Azure · sajeetharan · Jun 15, 2026 · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,33 +1,119 @@
-# Contributing
-
-This project welcomes contributions and suggestions. Most contributions require you to
-agree to a Contributor License Agreement (CLA) declaring that you have the right to,
-and actually do, grant us the rights to use your contribution. For details, visit
-the [CLA site](https://cla.microsoft.com).
-
-When you submit a pull request, a CLA-bot will automatically determine whether you need to
-provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
-instructions provided by the bot. You will only need to do this once across all repositories
-using our CLA.
-
-There are several ways you can contribute to the CosmosDBShell project:
-
-- **Ideas, feature requests and bugs**: We are open to all ideas, and we want to get rid of bugs! Use the [Issues](../../issues) section to report a new issue, provide your ideas or contribute to existing threads.
-
-- **Documentation**: Found a typo or strangely worded sentences? Submit a PR!
-
-- **Code**: Contribute bug fixes, features or design changes:
-  - **Prerequisites**: [.NET SDK 10.0+](https://dotnet.microsoft.com/download)
-  - Clone the repository and open it in VS Code or your preferred IDE.
-  - Restore dependencies: `dotnet restore CosmosDBShell.sln`
-  - Build: `dotnet build CosmosDBShell.sln` (or use the VS Code build task with Ctrl+Shift+B).
-  - Run tests: `dotnet test CosmosDBShell.sln`
-  - Run tests with code coverage: `./tools/coverage.ps1` (or the VS Code `coverage` task). Generates an HTML report under `TestResults/coverage` and prints a per-namespace summary; use the report's "Group by" selector for namespace-level coverage.
-  - Run the tool locally: `dotnet run --project CosmosDBShell/CosmosDBShell.csproj`
-  - GitHub Actions runs CI and uploads NuGet package artifacts from [.github/workflows/validate-and-package.yml](.github/workflows/validate-and-package.yml).
-  - Local builds and GitHub Actions use the default NuGet sources (nuget.org). The Azure DevOps pipeline uses [.pipelines/nuget.config](.pipelines/nuget.config) to restrict restores to the internal feed.
-  - Azure Pipelines runs from [.pipelines/CosmosDB-Shell-Official.yml](.pipelines/CosmosDB-Shell-Official.yml) for signed builds and publishing from the `main` branch (and any manual runs configured there).
-
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
-or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+# Contributing to Azure Cosmos DB Shell
+
+We welcome contributions and suggestions! Whether it's a bug fix, new feature, documentation improvement, or just a question — we'd love to hear from you.
+
+## Contributor License Agreement (CLA)
+
+Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit the [CLA site](https://cla.microsoft.com).
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
+
+## Ways to Contribute
+
+### Ideas, Feature Requests, and Bugs
+
+We are open to all ideas and we want to get rid of bugs! Use the [Issues](https://github.com/Azure/CosmosDBShell/issues) section to:
+
+- Report a bug
+- Suggest a new feature or enhancement
+- Ask a question or start a discussion
+
+Look for issues labeled [`good first issue`](https://github.com/Azure/CosmosDBShell/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) if you're looking for a place to start.
+
+### Documentation
+
+Found a typo or strangely worded sentences? Submit a PR! Documentation lives in the `docs/` folder and the root `README.md`.
+
+### Code
+
+Contribute bug fixes, features, or design changes by following the development setup below.
+
+## Development Setup
+
+### Prerequisites
+
+- [.NET SDK 10.0+](https://dotnet.microsoft.com/download) (verify with `dotnet --list-sdks`)
+- [Git](https://git-scm.com/)
+- A code editor (VS Code recommended — the repo includes a build task)
+
+### Getting Started
+
+```bash
+# Clone the repository
+git clone https://github.com/Azure/CosmosDBShell.git
+cd CosmosDBShell
+
+# Restore dependencies
+dotnet restore CosmosDBShell.sln
+
+# Build the solution
+dotnet build CosmosDBShell.sln
+
+# Run the shell locally
+dotnet run --project CosmosDBShell/CosmosDBShell.csproj
+
+# Run tests
+dotnet test CosmosDBShell.sln
+
+# Run tests with code coverage (or use the VS Code `coverage` task)
+./tools/coverage.ps1
+```
+
+In VS Code, you can also build with **Ctrl+Shift+B** (Windows/Linux) or **Cmd+Shift+B** (macOS) (uses the predefined build task).
+
+### Project Architecture
+
+```
+CosmosDBShell/
+├── Azure.Data.Cosmos.Shell.ArgumentParser/  # CLI argument parsing
+├── Azure.Data.Cosmos.Shell.Commands/        # Each shell command (ls, cd, query, etc.)
+├── Azure.Data.Cosmos.Shell.Core/            # Interpreter, state machine, command runner
+├── Azure.Data.Cosmos.Shell.Parser/          # Lexer and AST for shell syntax
+├── Azure.Data.Cosmos.Shell.States/          # Shell state (connected, in database, etc.)
+├── Azure.Data.Cosmos.Shell.Mcp/             # MCP (Model Context Protocol) server
+├── Azure.Data.Cosmos.Shell.Lsp/             # LSP server for editor integration
+├── Azure.Data.Cosmos.Shell.Lsp.Semantics/   # Semantic analysis for the LSP server
+├── Azure.Data.Cosmos.Shell.Util/            # Shared utilities and helpers
+├── Azure.Data.Cosmos.Shell.KeyBindings/     # Key binding definitions
+├── lang/                                    # Localization files (Fluent .ftl)
+└── Program.cs                               # Entry point and CLI option parsing
+
+CosmosDBShell.Tests/                         # Unit and integration tests
+docs/                                        # User-facing documentation
+```
+
+### Key Conventions
+
+- **Commands** are classes in `Azure.Data.Cosmos.Shell.Commands/` using `[CosmosCommand]`, `[CosmosExample]`, `[CosmosOption]`, and `[CosmosParameter]` attributes.
+- **Localization** strings live in `lang/en.ftl` (Fluent format). Keep help text aligned with actual CLI behavior.
+- **Tests** live in `CosmosDBShell.Tests/`. Add or update tests when changing behavior.
+- Match the existing C# style. Prefer clear names over abbreviations.
+
+### Running Against the Emulator
+
+You can develop and test without an Azure subscription by using the [Azure Cosmos DB Emulator](https://learn.microsoft.com/azure/cosmos-db/emulator):
+
+```bash
+dotnet run --project CosmosDBShell/CosmosDBShell.csproj -- --connect "https://localhost:8081"
+```
+
+## Submitting a Pull Request
+
+1. Fork the repository and create a feature branch from `main`.
+2. Make your changes — keep them focused and minimal.
+3. Add or update tests for any behavior changes.
+4. Update documentation (`README.md`, `docs/`) if the change is user-visible.
+5. Ensure the build passes: `dotnet build CosmosDBShell.sln`
+6. Ensure tests pass: `dotnet test CosmosDBShell.sln`
+7. Open a pull request against `main` with a clear description of what and why.
+
+### CI Pipelines
+
+- **GitHub Actions** ([.github/workflows/validate-and-package.yml](.github/workflows/validate-and-package.yml)) runs validation on pull requests, and on branch pushes also builds NuGet tool packages.
+- **Azure Pipelines** ([.pipelines/CosmosDB-Shell-Official.yml](.pipelines/CosmosDB-Shell-Official.yml)) handles signed builds and publishing from `main`.
+
+Local builds use the default NuGet sources (nuget.org).
+
+## Code of Conduct
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
 # Azure Cosmos DB Shell
 
-Lightweight CLI for Azure Cosmos DB.
+A terminal-native shell for Azure Cosmos DB — navigate databases like a filesystem, query interactively, and script with variables, loops, and functions. Supports Entra ID, MCP for AI tool integration, and works with the local emulator.
+
+![Azure Cosmos DB Shell Demo](docs/cosmosdbshell-demo.gif)
 
 ## Features
 
@@ -38,7 +40,41 @@ cd MyContainer
 query "SELECT * FROM c"
 ```
 
-## Install from NuGet package artifacts
+## Build from Source
+
+```bash
+git clone https://github.com/Azure/CosmosDBShell.git
+cd CosmosDBShell
+dotnet build CosmosDBShell.sln
+dotnet run --project CosmosDBShell/CosmosDBShell.csproj
+```
+
+Run the tests:
+
+```bash
+dotnet test CosmosDBShell.sln
+```
+
+## Architecture
+
+| Folder | Purpose |
+| ------ | ------- |
+| `CosmosDBShell/Azure.Data.Cosmos.Shell.ArgumentParser/` | Command-line argument parsing |
+| `CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/` | Each shell command is a class (`ls`, `cd`, `query`, `mkitem`, etc.) |
+| `CosmosDBShell/Azure.Data.Cosmos.Shell.Core/` | Interpreter, state machine, command runner |
+| `CosmosDBShell/Azure.Data.Cosmos.Shell.Parser/` | Lexer and AST for shell syntax |
+| `CosmosDBShell/Azure.Data.Cosmos.Shell.States/` | Shell states (disconnected, connected, in database, in container) |
+| `CosmosDBShell/Azure.Data.Cosmos.Shell.Mcp/` | MCP server for AI/tool integration |
+| `CosmosDBShell/Azure.Data.Cosmos.Shell.Lsp/` | LSP server for editor integration |
+| `CosmosDBShell/Azure.Data.Cosmos.Shell.Lsp.Semantics/` | Semantic analysis for the LSP server |
+| `CosmosDBShell/Azure.Data.Cosmos.Shell.Util/` | Shared utilities (localization, pattern matching, etc.) |
+| `CosmosDBShell/Azure.Data.Cosmos.Shell.KeyBindings/` | Key binding definitions |
+| `CosmosDBShell/lang/` | Localization files (Fluent `.ftl` format) |
+| `CosmosDBShell.Tests/` | Unit and integration tests |
+| `docs/` | User-facing documentation |
+
+<details>
+<summary><strong>Install from NuGet package artifacts</strong></summary>
 
 When consuming build artifacts (`*.nupkg`) from this repo, install as a .NET global tool.
 
@@ -47,7 +83,7 @@ When consuming build artifacts (`*.nupkg`) from this repo, install as a .NET glo
 1. Download the base tool package (`CosmosDBShell.<version>.nupkg`) and the package for your runtime to the same local folder.
 2. Install from that folder with `--add-source` using the base package ID `CosmosDBShell`.
 
-### Runtime-specific package files
+#### Runtime-specific package files
 
 - Linux x64: `CosmosDBShell.linux-x64.<version>.nupkg`
 - Linux ARM64: `CosmosDBShell.linux-arm64.<version>.nupkg`
@@ -56,7 +92,7 @@ When consuming build artifacts (`*.nupkg`) from this repo, install as a .NET glo
 - Windows x64: `CosmosDBShell.win-x64.<version>.nupkg`
 - Windows ARM64: `CosmosDBShell.win-arm64.<version>.nupkg`
 
-### Install command
+#### Install command
 
 After placing the base package and the matching runtime package in the same folder, install with the base package ID:
 
@@ -70,7 +106,7 @@ Windows PowerShell example:
 dotnet tool install --global CosmosDBShell --add-source C:\path\to\nupkgs --version <version>
 ```
 
-### Use, update, uninstall
+#### Use, update, uninstall
 
 Run the tool:
 
@@ -86,18 +122,13 @@ dotnet tool update --global <package-id> --add-source /path/to/nupkgs --version
 
 Uninstall:
 
-List the installed global tools first so you can identify the exact package ID:
-
 ```bash
 dotnet tool list --global
-```
-
-Then uninstall the tool by its package ID:
-
-```bash
 dotnet tool uninstall --global CosmosDBShell
 ```
 
+</details>
+
 ## Documentation
 
 - [Connection](docs/connect.md) - Authentication and connection options
@@ -223,11 +254,10 @@ CS > theme reload                       # rescan the user themes directory
 
 ## How to Contribute
 
-This project welcomes contributions and suggestions. To contribute, see these documents:
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for ways to help, project architecture, and PR guidelines.
 
 - [Code of Conduct](./CODE_OF_CONDUCT.md)
 - [Security](./SECURITY.md)
-- [Contributing](./CONTRIBUTING.md)
 
 ## Telemetry
 

diff --git a/docs/cosmosdbshell-demo.gif b/docs/cosmosdbshell-demo.gif