first pass at README edits

README.md

@@ -1,48 +1,70 @@
-# Welcome to Project Mercury
+# ![logo][]AI Shell (a.k.a Project Mercury)
 
-**Project Mercury** contains our latest CLI tool that provides an interactive shell session to chat
-with language models, creating an *AI Shell*. Users can use _agents_ to interact with different AI models, or other
-assistance providers, in a conversational manner. **Project Mercury** also provides a framework for
-creating AI agents.
+Welcome to the **AI Shell** repository! AI Shell is a CLI tool that brings the power of artificial
+intelligence directly to your command line! Designed to help you get command assistance from various
+AI assistants, AIShell is a versatile tool to help you become more productive in the command line.
+We call these various AI asssitant providers _agents_. You can use agents to interact with different
+generative AI models or other AI/ML/assistant providers in a conversational manner. This repo
+contains the code of the AI Shell engine, agents and details on how to create your own agent.
 
-Why the name **Project Mercury**? The name is inspired both by the Roman god of messages and the
-first human spaceflight by the US. This project is our first step into the new world of AI powered
-assistance and focuses on being the connection (or messenger) between the user and the AI model.
+Why the name **Project Mercury**? This was the original code name of the project and was inspired
+both by the Roman god of messages and the first human spaceflight by the US. This project is our
+first step into the new world of AI powered assistance and focuses on being the connection (or
+messenger) between the user and the AI model.
 
-This project is currently in the **alpha** phase. Expect many significant changes to the code as we
-experiment and refine the user experiences of this tool. We appreciate your feedback and patience as
-we continue our development.
+This project is currently in a very early **public preview** state. Expect many significant changes
+to the code as we experiment and refine the user experiences of this tool. We appreciate your
+feedback and patience as we continue our development.
 
 ![GIF showing demo of the AI Shell][04]
 
-## Installation
+## New to AI Shell?
+
+To learn more about AI Shell, we recommend you check out the overview page of the AI Shell
+documentation.
+
+There are two modes to use AI Shell, standalone and a side-by-side, integrated experience with
+PowerShell 7. For more information see,
+- [Get Started with AI Shell in PowerShell][15]
+- [Get Started with AI Shell (standalone)][16]
+
+## Getting AI Shell
+
+AI Shell is supported on Windows, MacOS and Linux, however the best experience you can have is with
+Windows, [PowerShell 7][11] and [Windows Terminal][14]. For more information see,
+[Installing AI Shell][13].
+
+## Locally Building AI Shell
 
 Some prerequisites for building an AI Shell:
 
-- Build script requires PowerShell v7.2 or newer versions
+- Build script requires PowerShell v7.4 or newer versions
 - [PowerShell v7.4][11] is recommended
 - [.NET SDK 8][09] is required to build the project
 
 Here are the steps to install and use.
 
 1. Clone this repository, `git clone https://github.com/PowerShell/ProjectMercury`
 2. Import the `build.psm1` module by running `import-module ./build.psm1` 
-3. Run the `Start-Build` command 
+3. Run the `Start-Build` command (You can specify which agents build with the `-AgentsToInclude`
+   parameter)
 4. After the build is complete, you can find the produced executable `aish` in the `out\debug\app`
    folder within the repository's root directory. You can add the location to the `PATH` environment
    variable for easy access. The full path is copied to your clipboard after successful build.
 
 ## AI Agents
 
 Project Mercury provides a framework for creating and registering multiple AI Agents. The agents are
-libraries that you use to interact with different AI models or assistance providers. Currently,
-these are the supported agents:
+libraries that you use to interact with different AI models or assistance providers. AI Shell
+releases with two agents, the `openai-gpt` and `azure` agent. However there are additional ones
+supported if you locally build the project: 
 
 Agent README files:
 
-- [`openai-gpt`][08]
+- [`openai-gpt`][08] (shipped with AI Shell)
 - [`ollama`][06]
 - [`interpreter`][07]
+- [`azure`][17] (shipped with AI Shell)
 
 When you run `aish`, you are prompted to choose an agent. For more details about each agent, see the
 README in the each agent folder.
@@ -165,8 +187,14 @@ bugs, suggestions, or feedback.
 [05]: ./docs/SUPPORT.md
 [06]: ./shell/agents/AIShell.Ollama.Agent/README.md
 [07]: ./shell/agents/AIShell.Interpreter.Agent/README.md
-[08]: ./shell/agents/AIShell.OpenAI.Agent/README.md
+[08]: https://learn.microsoft.com/command-line/aishell/agent-openai
 [09]: https://dotnet.microsoft.com/en-us/download
 [10]: https://github.com/PowerShell/ProjectMercury/issues
 [11]: https://learn.microsoft.com/powershell/scripting/install/installing-powershell
 [12]: ./docs/SECURITY.md
+[13]: https://learn.microsoft.com/command-line/aishell/install
+[14]: https://learn.microsoft.com/windows/terminal/
+[15]: https://learn.microsoft.com/command-line/aishell/get-started-powershell
+[16]: https://learn.microsoft.com/command-line/aishell/get-started-standalone
+[17]: https://learn.microsoft.com/command-line/aishell/agent-azure
+[logo]: <TODO>

shell/agents/AIShell.OpenAI.Agent/README.md

@@ -4,96 +4,7 @@ This agent is designed to provide a flexible and user-friendly platform for inte
 services, either the public OpenAI service or a private deployment of the Azure OpenAI service,
 through one or more customly defined GPT instances.
 
-## GPT
-
-GPTs are configured in the agent's settings file, which is in JSON format. Each GPT configuration
-includes the name, description, the targeted OpenAI model, and the system prompt for interaction.
-This allows for the creation of distinct GPTs, each tailored to a specific domain or scenario, whose
-system prompts can be customized to suit these individual scenarios. Furthermore, you have the
-flexibility to select different OpenAI models for each GPT as required.
-
-## Command
-
-The command `/gpt` is provided to make it easy to manage the GPTs.
-
-- Run `/gpt use <gpt-name>` to switch to another GPT instance, or run `/gpt use` to simply choose
-  from the available ones.
-- Run `/gpt list <gpt-name>` to view the details of a GPT definition, or run `/gpt list` to list all
-  available GPTs.
-
-```shell
-aish:1> /gpt --help
-Description:
-  Command for GPT management within the 'openai-gpt' agent.
-
-Usage:
-  gpt [command] [options]
-
-Options:
-  -h, --help  Show help and usage information
-
-Commands:
-  list <GPT>  List a specific GPT, or all available GPTs.
-  use <GPT>   Specify a GPT to use, or choose one from the available GPTs.
-```
-
-## Prerequisites
-
-- For OpenAI, you need the **Model Name** and **API Key** to use the agent.
-  - [OpenAI API Key][03]
-  - [OpenAI Model][04]
-
-- For Azure OpenAI Service, you need the **Endpoint**, **Deployment Name**, **Model Name**, and **API Key** to use the agent.
-  - [Access to Azure OpenAI][01]
-  - [Create an Azure OpenAI deployment][02]
-
-## Configuration
-
-To configure the agent, run `/agent config openai-gpt` to open up the setting file in your default editor,
-and then update the file based on the following example.
-
-```jsonc
-{
-  // Declare GPT instances.
-  "GPTs": [
-    // To use the Azure OpenAI service:
-    // - Set `Endpoint` to the endpoint of your Azure OpenAI service,
-    //     or the endpoint to the Azure API Management service if you are using it as a gateway.
-    // - Set `Deployment` to the deployment name of your Azure OpenAI service.
-    // - Set `ModelName` to the name of the model used for your deployment, e.g. "gpt-4-0613".
-    // - Set `Key` to the access key of your Azure OpenAI service,
-    //     or the key of the Azure API Management service if you are using it as a gateway.
-    {
-      "Name": "ps-az-gpt4",
-      "Description": "A GPT instance with expertise in PowerShell scripting and command line utilities. Use gpt-4 running in Azure.",
-      "Endpoint": "<insert your Azure OpenAI endpoint>",
-      "Deployment": "<insert your deployment name>",
-      "ModelName": "<insert the model name>",   // required field to infer properties of the service, such as token limit.
-      "Key": "<insert your key>",
-      "SystemPrompt": "1. You are a helpful and friendly assistant with expertise in PowerShell scripting and command line.\n2. Assume user is using the operating system `Windows 11` unless otherwise specified.\n3. Use the `code block` syntax in markdown to encapsulate any part in responses that is code, YAML, JSON or XML, but not table.\n4. When encapsulating command line code, use '```powershell' if it's PowerShell command; use '```sh' if it's non-PowerShell CLI command.\n5. When generating CLI commands, never ever break a command into multiple lines. Instead, always list all parameters and arguments of the command on the same line.\n6. Please keep the response concise but to the point. Do not overexplain."
-    },
-
-    // To use the public OpenAI service:
-    // - Ignore the `Endpoint` and `Deployment` keys.
-    // - Set `ModelName` to the name of the model to be used.
-    // - Set `Key` to be the OpenAI access token.
-    // For example:
-    {
-        "Name": "ps-gpt4o",
-        "Description": "A GPT instance with expertise in PowerShell scripting and command line utilities. Use gpt-4o running in OpenAI.",
-        "ModelName": "gpt-4o",
-        "Key": "<insert your key>",
-        "SystemPrompt": "1. You are a helpful and friendly assistant with expertise in PowerShell scripting and command line.\n2. Assume user is using the operating system `Windows 11` unless otherwise specified.\n3. Use the `code block` syntax in markdown to encapsulate any part in responses that is code, YAML, JSON or XML, but not table.\n4. When encapsulating command line code, use '```powershell' if it's PowerShell command; use '```sh' if it's non-PowerShell CLI command.\n5. When generating CLI commands, never ever break a command into multiple lines. Instead, always list all parameters and arguments of the command on the same line.\n6. Please keep the response concise but to the point. Do not overexplain."
-    }
-  ],
-
-  // Specify the default GPT instance to use for user query.
-  "Active": "ps-az-gpt4"
-}
-```
+For more infromation about this agent, see the [OpenAI Agent][01] documentation.
 
 <!-- link references -->
-[01]: https://aka.ms/oai/access?azure-portal=true
-[02]: https://learn.microsoft.com/azure/ai-services/openai/how-to/create-resource?pivots=web-portal
-[03]: https://platform.openai.com/api-keys
-[04]: https://platform.openai.com/docs/models
+[01]: https://learn.microsoft.com/command-line/aishell/agent-openai

shell/agents/Microsoft.Azure.Agent/README.md

@@ -0,0 +1,5 @@
+# Copilot in Azure Agent
+
+For more details about this agent please see, [Copilot in Azure Agent][01].
+
+[01]: https://learn.microsoft.com/command-line/aishell/agent-azure