PowerShell
diff --git a/Diff for: ‎LICENSE
+2-2 b/Diff for: ‎LICENSE
+2-2
diff --git a/Diff for: ‎README.md
+90-66 b/Diff for: ‎README.md
+90-66
diff --git a/Diff for: ‎docs/CODE_OF_CONDUCT.md
+11 b/Diff for: ‎docs/CODE_OF_CONDUCT.md
+11
diff --git a/Diff for: ‎docs/CONTRIBUTING.md
+30 b/Diff for: ‎docs/CONTRIBUTING.md
+30
diff --git a/Diff for: ‎docs/FAQ.md
+47 b/Diff for: ‎docs/FAQ.md
+47
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Steve Lee
+Copyright (c) 2023 Microsoft Corporation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.
@@ -1,100 +1,124 @@
-# AISH
+# Welcome to the AISH repository
 
-This is a repository of various **AI** + **Sh**ell prototypes we have created to test out experiences and
-features. **AISH** is the latest and most finished prototype. It is a CLI tool that creates
-an interactive chat session with a registered Large Language Model. Currently we are in a **Private Preview** state and everything is subject to change.
+**AISH** is our latest CLI tool that provides an interactive shell session to chat with large
+language models. Users can use _agents_ to interact with different AI models, or other assistance
+providers, in a conversational manner. **AISH** also provides a framework for creating AI agents.
 
-![GIF showing demo of AISH](./docs/media/ShellCopilotDemo.gif)
+This project is currently in an **alpha** 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.
 
-## Installing and Using AISH
+![GIF showing demo of AISH][04]
+
+## Installing AISH
 
 Some prerequisites for building AISH
-- Build script requires PowerShell v7.2 or newer versions. [PowerShell v7.4](https://learn.microsoft.com/powershell/scripting/install/installing-powershell?view=powershell-7.4) is recommended.
-- [.NET SDK 8](https://dotnet.microsoft.com/en-us/download) is required to build the project.
+
+- Build script requires PowerShell v7.2 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 AISH.
-1. Clone this repository, `git clone https://github.com/PowerShell/ShellCopilot`;
-2. Run `./build.ps1` in the repository's root directory to build the project;
-3. After the build is complete, you can find the produced executable `aish` in the `out\debug` folder within the repository's root directory. You can add it to the `PATH` environment variable for easy access.
 
-> Note: Depending on your OS directory paths may be `\` on Windows or `/` on Mac.
+1. Clone this repository, `git clone https://github.com/PowerShell/AISH`
+2. Run `./build.ps1` in the repository's root directory to build the project
+3. 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.
 
-## Agent Concept
+## AI Agents
 
-AISH has a concept of different AI Agents, these can be thought of like modules that users can use to interact with different AI models. Right now there are three supported agents
-- `az-cli`
-- `az-ps`
-- `openai-gpt`
+AISH 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, there are four
+supported agents in this repository.
 
-If you run `aish` you will get prompted to choose between the two.
+Agent README files:
 
-### Az-CLI Agent
+- [`az-cli` & `az-ps`][06]
+- [`openai-gpt`][08]
+- [`interpreter`][07]
 
-This agent is for talking specifically to an Az CLI endpoint tailored to helping users with Azure CLI questions.
+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.
 
-Prerequisites:
-- Have [Azure CLI installed](https://learn.microsoft.com/cli/azure/install-azure-cli)
-- Login with an Azure account within the Microsoft tenant with `az login` command
+## How to use AISH
 
-### Az-PS Agent
+To start a chat session with the LLM, run `aish`, which starts a new session in your current window.
+Choose the agent you would like to use. Once you select an agent you can begin your conversation.
 
-This agent is for talking specifically to an Az PowerShell endpoint tailored to helping users with Azure PowerShell questions.
+We suggest using a split pane approach with the terminal of choice. In Windows Terminal, use the
+following command to start `aish` in a new split pane:
 
-Prerequisites:
-- Have [Azure PowerShell installed](https://learn.microsoft.com/powershell/azure/install-azure-powershell)
-- Login with an Azure account within the Microsoft tenant with `Connect-AzAccount` command
+```shell
+wt -w 0 sp aish
+```
 
+You can bind this command to a key like `F3` in your PowerShell session. Add the following code to
+your `$PROFILE` script:
 
-### OpenAI-GPT Agent
+```powershell
+$PSReadLineSplat = @{
+    Chord = 'F3'
+    ScriptBlock = {
+        wt -w 0 sp --tabColor '#345beb'--size 0.4 -p $env:WT_PROFILE_ID --title 'AISH' <full-path-to-aish.exe>
+    }
+}
+Set-PSReadLineKeyHandler @PSReadLineSplat
+```
 
-This is a more generalized agent that users can bring their own instance of Azure OpenAI (or the public OpenAI) and a completely customizable system prompt.
-Right now, it is defaulted to an internal Azure OpenAI endpoint with a prompt to be an assistant for PowerShell commands. This is for internal private preview purposes only.
+### `/` commands
 
-## Getting an Azure OpenAI Endpoint Key
+By default, `aish` provides a base set of chat `/` commands used to interact with the responses from
+the AI model. To get a list of commands, use the `/help` command in the chat session.
 
-All the configuration is already included by default and on the first run of this agent you will be prompted to include a API key to be able to use this endpoint.
+```
+  Name       Description
+────────────────────────────────────────────────────────────
+  /agent     Command for agent management.
+  /cls       Clear the screen.
+  /code      Command to interact with the code generated.
+  /dislike   Dislike the last response and send feedback.
+  /exit      Exit the interactive session.
+  /help      Show all available commands.
+  /like      Like the last response and send feedback.
+  /refresh   Refresh the chat session.
+  /retry     Regenerate a new response for the last query.
+```
 
-Guide for Signing Up For API Key
-1.  Navigate to <https://pscopilot.developer.azure-api.net>
-2.  Click `Sign Up` located on the top right corner of the page.
-3.  Sign up for a subscription by filling in the fields (email, password, first name, last name).
-4.  Verify the account (An email should have been sent from
-    <[email protected]> to your email)
-5.  Click `Sign In` located on the top right corner of the page.
-6.  Enter the email and password used when signing up.
-7.  Click `Products` located on the top right corner of the page
-8.  In the field stating `Your new product subscription name`, Enter `Azure OpenAI Service API`.
-9.  Click `Subscribe` to be subscribed to the product.
+Also, agents can implement their own commands. Some commands, such as `/like` and `/dislike`, are
+commands that sends feedback to the agents. It is up to the agents to consume the feedback.
 
-In order to view your subscription/API key,
-1.  Click `Profile` located on the top right corner of the page.
-2.  Your Key should be located under the `Subscriptions` section. Click on `Show` to view the
-    primary or secondary key.
+## Agent development
 
-Once you have a key you can always edit your endpoint configuration by running `/agent config openai-gpt` within AISH. This opens up a JSON file with all the configuration options. 
+To learn more about how to create an agent for yourself please see, [Creating an Agent][03].
 
-If you have separate Azure OpenAI endpoint you can use that instead of the one above. Read more at
-[Create and deploy an Azure OpenAI Service resource](https://learn.microsoft.com/azure/ai-services/openai/how-to/create-resource?pivots=ps).
+## Contributing to the project
 
-## Using AISH
+Please see [CONTRIBUTING.md][02] for more details.
 
-To start a chat session with the LLM, simply run `aish` and it will open up a new session in your current window.
-We suggest using a split pane approach with the terminal of choice.
-Windows Terminal offers an easy pane option by running:
+## Support
 
-```shell
-wt -w 0 sp aish
-```
+For support, see our [Support][05] statement.
 
-If you use Windows Terminal and would like to tie this command to a key like `F3` in your PowerShell session,
-you can add the following code to your `$PROFILE`:
+## Code of Conduct
 
-```powershell
-Set-PSReadLineKeyHandler -Chord F3 -ScriptBlock { wt -w 0 sp --tabColor '#345beb'--size 0.4 -p "<your-default-WT-profile-guid>" --title 'AISH' <full-path-to-aish.exe> }
-```
+The project follows the Microsoft Open Source Code of Conduct. For more information, see the
+[Code of Conduct FAQ][01].
 
 ## Feedback
 
-We still in development and value any and all feedback! Please file an [issue in this repository](https://github.com/PowerShell/ShellCopilot/issues) for
-any bugs, suggestions and feedback. Any additional feedback can be sent to
-[email protected].
+We're still in development and value your feedback! Please file [issues][10] in this repository for
+bugs, suggestions, or feedback.
+
+<!-- link references -->
+[01]: ./docs/CODE_OF_CONDUCT.md
+[02]: ./docs/CONTRIBUTING.md
+[03]: ./docs/development/CreatingAnAgent.md
+[04]: ./docs/media/ShellCopilotDemo.gif
+[05]: ./docs/SUPPORT.md
+[06]: ./shell/ShellCopilot.Azure.Agent/README.md
+[07]: ./shell/ShellCopilot.Interpreter.Agent/README.md
+[08]: ./shell/ShellCopilot.OpenAI.Agent/README.md
+[09]: https://dotnet.microsoft.com/en-us/download
+[10]: https://github.com/PowerShell/AISH/issues
+[11]: https://learn.microsoft.com/powershell/scripting/install/installing-powershell
@@ -0,0 +1,11 @@
+# Microsoft Open Source Code of Conduct
+
+This project has adopted the
+[Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+
+Resources:
+
+- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
+- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
+- Contact [[email protected]](mailto:[email protected]) with questions or concerns
+- Employees can reach out at [aka.ms/opensource/moderation-support](https://aka.ms/opensource/moderation-support)
@@ -0,0 +1,30 @@
+# Contributing to AISH
+
+Thank you for your interest in contributing to AISH! We aren't currently accepting pull requests,
+but we highly value your contributions in other forms.
+
+## Reporting Issues
+
+Issues are a great way to contribute to the project. By creating a detailed report, you help us
+understand and prioritize what needs attention. Whether it's a bug or a feature request, your
+reports play a crucial role in improving AISH.
+
+### How to Report an Issue
+
+Before creating an issue, please do the following:
+
+1. **Search for existing issues.** To avoid duplicates, please check to see if someone else has
+   reported the same issue.
+2. **Check if the issue has been fixed.** Try to reproduce the issue using the latest `main` branch
+   to see if it has already been addressed.
+
+If you've determined that your issue is unique and current, you can proceed to create a new issue.
+Please follow the issue templates provided.
+
+## Other Ways to Contribute
+
+While we aren't accepting pull requests, there are other ways to contribute:
+
+- Reviewing documentation for typos or clarity
+- Participating in discussions on issues
+- Providing use cases or additional information on existing issues
@@ -0,0 +1,47 @@
+# Frequently Asked Questions
+
+This page provides help with common questions about the AISH platform.
+
+## What is AISH?
+
+**AISH** is an AI shell platform that provides a framework for developers to build their own AI
+Agents and assistance providers. **AISH** agents provide the user experience for the LLM and are
+deeply connected to PowerShell 7. For more about the architecture of **AISH**, see the
+[shell/README][01].
+
+## What are agents?
+
+An agent is a library that implements the user interface that talks to a specific large language
+model or other assistance provider. Users can interact with these agents in a conversational manner,
+using natural language, to get the desired output or assistance. Currently, there are four supported
+agents in this repository.
+
+Agent README files:
+
+- [`az-cli` & `az-ps`][02]
+- [`openai-gpt`][04]
+- [`interpreter`][03]
+
+An assistance provider is an agent that provides user assistance without using a large language
+model or AI engine.
+
+## What operating systems are supported?
+
+We have tested **AISH** on macOS and Windows operating systems. **AISH** may work on linux but we
+haven't tested it can't guarantee that all features will work as expected.
+
+## How do I get a split pane experience in my Terminal?
+
+The ability to run `aish` in a split pane depends on the capabilities of your terminal. For example,
+Windows Terminal can be split by running the following command: `wt -w 0 sp`. Refer to the
+documentation for your terminal application to see if it supports this feature.
+
+> [!NOTE]
+> Information the user should notice even if skimmingNot all terminal applications support this
+> feature.
+
+<!-- link references -->
+[01]: ../shell/README.md
+[02]: ./shell/ShellCopilot.Azure.Agent/README.md
+[03]: ./shell/ShellCopilot.Interpreter.Agent/README.md
+[04]: ./shell/ShellCopilot.OpenAI.Agent/README.md