Update AI Shell docs for 1.0-p2 (#299)

Author: sdwheeler

reference/docs-conceptual/AIShell/concepts/FAQ.md

@@ -1,7 +1,7 @@
 ---
 title: AI Shell FAQ
 description: Get answers to common questions about AI Shell.
-ms.date: 11/11/2024
+ms.date: 03/03/2025
 ms.topic: faq
 ---
 
@@ -61,7 +61,11 @@ Users interact with these agents using natural language in a conversational mann
 ## How do I create an agent?
 
 To create an agent, you need to implement the `IAgent` interface. For more information, see
-[Create an Ollama Agent][05] for the details of creating an agent.
+[Create an Ollama Agent][05] for the details of creating an agent. You can use this agent as a
+template to create your own agent.
+
+You can use the example code as written to interact with Ollama, or you can configure the OpenAI
+agent to interact with the Ollama using the OpenAI-compatible endpoint.
 
 ## How do I share my agent or find other community built agents?
 
@@ -74,4 +78,4 @@ recommend sharing it on the [discussions page][06] of the Project Mercury reposi
 [03]: ../how-to/agent-openai.md
 [04]: ../developer/agent-architecture.md
 [05]: ../developer/create-ollama-agent.md
-[06]: https://github.com/PowerShell/ProjectMercury/discussions/categories/agent-sharing
+[06]: https://github.com/PowerShell/AIShell/discussions/categories/agent-sharing

reference/docs-conceptual/AIShell/developer/create-ollama-agent.md

@@ -44,7 +44,7 @@ Within the newly created project, you need to install the [AIShell.Abstraction][
 NuGet gallery. Install the NuGet package using the following command:
 
 ```shell
-dotnet add package AIShell.Abstraction --version 1.0.0-preview.1
+dotnet add package AIShell.Abstraction --version 1.0.0-preview.2
 ```
 
 This command adds the package to your `.csproj` file. Your `.csproj` file should contain the
@@ -60,7 +60,7 @@ following XML:
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="AIShell.Abstraction" Version="1.0.0-preview.1" />
+    <PackageReference Include="AIShell.Abstraction" Version="1.0.0-preview.2" />
   </ItemGroup>
 </Project>
 ```
@@ -477,7 +477,7 @@ Copy the `.dll` files to agent folder you created. You should see the agent when
 
 ```shell
 AI Shell
-v1.0.0-preview.1
+v1.0.0-preview.2
 
 Please select an agent to use:
 
@@ -499,4 +499,4 @@ in the `agents` folder of the base directory of `aish.exe`, the agent will be lo
 [03]: https://github.com/PowerShell/ProjectMercury/discussions/categories/agent-sharing
 [04]: https://github.com/PowerShell/AIShell/tree/main/shell/agents/AIShell.Ollama.Agent
 [05]: https://github.com/PowerShell/AIShell/blob/main/shell/README.md
-[06]: https://www.nuget.org/packages/AIShell.Abstraction/1.0.0-preview.1
+[06]: https://www.nuget.org/packages/AIShell.Abstraction/1.0.0-preview.2

reference/docs-conceptual/AIShell/developer/ollama-agent-readme.md

@@ -1,12 +1,15 @@
 ---
 title: Ollama agent README
 description: Learn how to use the Ollama agent in AI Shell.
-ms.date: 11/11/2024
+ms.date: 03/03/2025
 ---
 # Ollama Plugin
 
 This agent is used to interact with a language model running locally by utilizing the Ollama API.
-Before using this agent you need to have Ollama installed and running.
+Before using this agent you need to have Ollama installed and running. To create an agent, you need
+to implement the `IAgent` interface.
+
+You can also use this example code as a template to create your own agent.
 
 ## Pre-requisites to using the agent
 
@@ -23,6 +26,9 @@ Currently to change the model you will need to modify the query in the code in t
 The default endpoint is `http://localhost:11434/api/generate` with `11434` being the default port.
 This can be changed in the code and eventually will be added to a configuration file.
 
+There is an updated version of the Ollama agent available in the AI Shell repository. See the
+[README][04] file for the Ollama plugin.
+
 ## Known Limitations
 
 - There is no history shared across queries so the model will not be able to remember previous
@@ -36,3 +42,4 @@ This can be changed in the code and eventually will be added to a configuration
 [01]: https://github.com/ollama/ollama
 [02]: https://github.com/ollama/ollama?tab=readme-ov-file#model-library
 [03]: https://github.com/ollama/ollama?tab=readme-ov-file#start-ollama
+[04]: https://github.com/PowerShell/AIShell/blob/v1.0.0-preview.2/shell/agents/AIShell.Ollama.Agent/README.md

reference/docs-conceptual/AIShell/how-to/agent-azure.md

@@ -1,7 +1,7 @@
 ---
 title: Copilot in Azure Agent
 description: Learn how to use the Copilot in Azure agent in AI Shell.
-ms.date: 11/18/2024
+ms.date: 03/03/2025
 ---
 # Copilot in Azure Agent
 
@@ -27,13 +27,14 @@ command from Azure CLI.
 - "What is Application Insights?"
 - "How to create a web app with Azure CLI?"
 
-## Known issues
+## Improvements in AI Shell v1.0.0-preview.2
 
-This preview release has some known issues with the Azure agent that we're actively working on
-addressing:
+The Preview 2 release includes the following enhancements:
 
-- The `Connect-AzAccount` command for authentication from Azure PowerShell isn't supported. You
-  must use the `az login` command from Azure CLI to sign in.
+- The Azure agent support authentication using either the `Connect-AzAccount` command from Azure
+  PowerShell or the `az login` command from Azure CLI.
+- The `/replace` command now supports Azure PowerShell. The agent walks you through replacement of
+  parameter values in generated Azure PowerShell responses.
 
 ## Telemetry and configuration
 

reference/docs-conceptual/AIShell/how-to/agent-openai.md

@@ -1,10 +1,10 @@
 ---
 title: OpenAI agent README
 description: Learn how to use the OpenAI agent in AI Shell.
-ms.date: 11/18/2024
+ms.date: 03/03/2025
 ms.topic: how-to
 ---
-# OpenAI Agent
+# OpenAI agent
 
 This agent is designed to provide a user-friendly platform for interacting with OpenAI services. It
 can connect to a public OpenAI service or a private deployment of the Azure OpenAI service. We
@@ -13,12 +13,12 @@ recommend using an Azure OpenAI deployment for enhanced security and privacy.
 ## Prerequisites
 
 - For OpenAI, you need the **Model Name** and **API Key** to use the agent.
-  - [OpenAI API Key][03]
-  - [OpenAI Model][04]
+  - [OpenAI API Key][09]
+  - [OpenAI Model][10]
 
 - For Azure OpenAI Service, you need the **Endpoint**, **Deployment Name**, **Model Name**, and
   **API Key** to use the agent.
-  - [Access to Azure OpenAI][02]
+  - [Access to Azure OpenAI][03]
   - [Create an Azure OpenAI deployment][01]
 
 ## Configuration
@@ -68,19 +68,20 @@ editor. Update the file based on the following example:
 ```
 
 > [!NOTE]
-> The endpoint for the Azure OpenAI configuration does not need a full endpoint including the deployment,
-> for example you can just use the following endpoint format, `https://<YourServiceName>.openai.azure.com`. 
+> The endpoint for the Azure OpenAI configuration does not need a full endpoint including the
+> deployment, for example you can just use the following endpoint format,
+> `https://<YourServiceName>.openai.azure.com`.
 
 ## GPT
 
-GPTs are tailored versions of base OpenAI models. You use a GPT to provide focused responses based on
-the system prompt you give the model. GPTs are configured in the agent's settings file. Each GPT
+GPTs are tailored versions of base OpenAI models. You use a GPT to provide focused responses based
+on the system prompt you give the model. GPTs are configured in the agent's settings file. Each GPT
 configuration includes the name, description, targeted OpenAI model, and system prompt for
 interaction. The system prompts can be customized to support specific scenarios. Each configuration
 allows you to create distinct GPTs tailored to a specific domain or scenario. Furthermore, you can
 select different OpenAI models for each GPT as required.
 
-## Command
+### Command
 
 The command `/gpt` is provided to make it easy to manage the GPTs.
 
@@ -105,8 +106,33 @@ Commands:
   use <GPT>   Specify a GPT to use, or choose one from the available GPTs.
 ```
 
+## Support for other OpenAI-compatible models
+
+With the release of AI Shell v1.0.0-preview.2, the `openai-gpt` agent extends support to third party
+models that follow the OpenAI API specifications, allowing for a more flexible AI experience. Many
+of these models are open source tools for running SLMs and LLMs locally. The `openai-gpt` agent nows
+supports the following additional models:
+
+- [**Ollama**][08]
+- [**LM Studio**][06]
+- [**Deepseek**][04]
+- [**LocalAI**][07]
+- [**Google Gemini**][02]
+- [**Grok**][05]
+
+To use these models, you only need to configure the `endpoint`, `key` and `model name` in the agent
+config file. The following `openai.agents.config` file contains example configurations for two of
+the new AI providers. For more information about endpoints and model names, see to the documentation
+for the specific model.
+
 <!-- link references -->
 [01]: /azure/ai-services/openai/how-to/create-resource?pivots=web-portal
-[02]: https://aka.ms/oai/access?azure-portal=true
-[03]: https://platform.openai.com/api-keys
-[04]: https://platform.openai.com/docs/models
+[02]: https://ai.google.dev/gemini-api/docs/openai
+[03]: https://aka.ms/oai/access?azure-portal=true
+[04]: https://api-docs.deepseek.com/
+[05]: https://docs.x.ai/docs/overview#migrating-from-another-llm-provider
+[06]: https://lmstudio.ai/docs/api/openai-api
+[07]: https://localai.io/
+[08]: https://ollama.com/blog/openai-compatibility
+[09]: https://platform.openai.com/api-keys
+[10]: https://platform.openai.com/docs/models

reference/docs-conceptual/AIShell/install-aishell.md

@@ -1,7 +1,7 @@
 ---
 title: Install AI Shell
 description: Learn how to install AI Shell on your system.
-ms.date: 11/18/2024
+ms.date: 03/03/2025
 ms.topic: install-set-up-deploy
 ---
 # Install AI Shell
@@ -29,13 +29,13 @@ AI Shell is supported on the following platforms:
 
 - macOS v13 Ventura or higher
 - PowerShell 7.4.6 or higher
-- iTerm2 (limited support)
+- iTerm2 preferred (no split-screen experience)
 
 ### [Linux](#tab/linux)
 
 - Ubuntu 20.04 or higher
 - PowerShell 7.4 or higher (recommended)
-- Any terminal emulator supported by the OS
+- Any terminal emulator supported by the OS (no split-screen experience)
 
   > [!NOTE]
   > The AI Shell module isn't supported on Linux.
@@ -72,7 +72,7 @@ To manually install AI Shell, follow the instructions for your platform:
 ### [Windows](#tab/windows)
 
 1. Download the latest version from the [GitHub releases page][03]. Choose the file that matches
-   your system architecture. For example, `AIShell-1.0.0-preview.1-win-x64.zip`.
+   your system architecture. For example, `AIShell-1.0.0-preview.2-win-x64.zip`.
 1. Extract the contents of the ZIP file to a location on your system.
 1. Add the extracted folder to your **PATH** environment variable.
 1. Install the AI Shell module from the PowerShell Gallery.
@@ -84,7 +84,7 @@ To manually install AI Shell, follow the instructions for your platform:
 ### [macOS](#tab/macos)
 
 1. Download the latest version from the [GitHub releases page][03]. Choose the file that matches
-   your system architecture. For example, `AIShell-1.0.0-preview.1-osx-x64.tar.gz`.
+   your system architecture. For example, `AIShell-1.0.0-preview.2-osx-x64.tar.gz`.
 1. Extract the contents of the TAR file to a location on your system.
 1. Add the extracted folder to your **PATH** environment variable.
 1. Install the AI Shell module from the PowerShell Gallery.
@@ -96,7 +96,7 @@ To manually install AI Shell, follow the instructions for your platform:
 ### [Linux](#tab/linux)
 
 1. Download the latest version from the [GitHub releases page][03]. Choose the file that matches
-   your system architecture. For example, `AIShell-1.0.0-preview.1-linux-x64.tar.gz`.
+   your system architecture. For example, `AIShell-1.0.0-preview.2-linux-x64.tar.gz`.
 1. Extract the contents of the TAR file to a location on your system.
 1. Add the extracted folder to your **PATH** environment variable.
 

reference/docs-conceptual/AIShell/overview.md

@@ -47,9 +47,8 @@ encourage you to share your experiences to help us improve AI Shell.
 This current release of AI Shell has some known issues that we're actively working on addressing:
 
 - The **AI Shell** module isn't supported on Linux.
-- The split-screen experience work best with Windows Terminal. There is limited support for the
-  split-screen experience on macOS with iTerm2. The `aish` executable can be run on Linux, but the
-  split-screen experience is not available.
+- The split-screen experience only works with Windows Terminal. The `aish` executable can be run on
+  macOS and Linux, but the split-screen experience isn't available.
 - If you have multiple versions of Windows Terminal installed, the `Start-AIShell` command opens a
   new terminal window running a different version of Windows Terminal.
 - If you started Window Terminal as an administrator, the `Start-AIShell` command opens a new

reference/docs-conceptual/AIShell/toc.yml

@@ -19,9 +19,9 @@ items:
     items:
       - name: AI Shell command reference
         href: how-to/aishell-reference.md
-      - name: Azure agent README
+      - name: Azure agent
         href: how-to/agent-azure.md
-      - name: OpenAI agent README
+      - name: OpenAI agent
         href: how-to/agent-openai.md
   - name: Developer guide
     items:

reference/ps-modules/AIShell/Resolve-Error.md

@@ -2,7 +2,7 @@
 external help file: AIShell.Integration.dll-Help.xml
 Module Name: AIShell
 online version:
-ms.date: 10/29/2024
+ms.date: 03/03/2025
 schema: 2.0.0
 ---
 
@@ -23,6 +23,9 @@ When an error occurs in the current session, this cmdlet sends the error to the
 resolution. The command sends the full error object to the current AIShell agent session, which
 attempts to provide a resolution.
 
+Beginning with theAI Shell v1.0.0-preview.2 release, the `Resolve-Error` cmdlet also works with
+error messages output from native commands.
+
 ## EXAMPLES
 
 ### Example 1 - Resolves the last error