diff --git a/.gitignore b/.gitignore
index 7a12ef8..9b25ba9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,6 +12,9 @@ __temp__/
 ## VS Code
 .vscode/
 
+## macOS
+.DS_Store
+
 
 # vvvvvvv  Default Python Ignore vvvvvvvv
 # Byte-compiled / optimized / DLL files
diff --git a/README.md b/README.md
index 9890844..18fa1b3 100644
--- a/README.md
+++ b/README.md
@@ -2,49 +2,36 @@
 
 ![Hatch Logo](https://raw.githubusercontent.com/CrackingShells/Hatch/refs/heads/main/docs/resources/images/Logo/hatch_wide_dark_bg_transparent.png)
 
-## Introduction
+Hatch is a CLI tool for configuring MCP servers across AI host platforms. Adding a server to Claude Desktop, Cursor, VS Code, and others normally means editing separate JSON config files in different locations. Hatch does it from one command.
 
-Hatch is the package manager for managing Model Context Protocol (MCP) servers with environment isolation, multi-type dependency resolution, and multi-host deployment. Deploy MCP servers to Claude Desktop, VS Code, Cursor, Kiro, Codex, and other platforms with automatic dependency management.
+It also has a package system for managing MCP servers with dependency isolation, though that part is still being developed — see [Getting Started](./docs/articles/users/GettingStarted.md) for the current state.
 
-The canonical documentation is at `docs/index.md` and published at <https://hatch.readthedocs.io/en/latest/>.
+**Current status:** suitable for development and trusted environments. Not hardened for production or multi-tenant use yet — see [Security and Trust](./docs/articles/users/SecurityAndTrust.md).
 
-## Key Features
+## What it does
 
-- **Environment Isolation** — Create separate, isolated workspaces for different projects without conflicts
-- **Multi-Type Dependency Resolution** — Automatically resolve and install system packages, Python packages, Docker containers, and Hatch packages
-- **Multi-Host Deployment** — Configure MCP servers on multiple host platforms
-- **Package Validation** — Ensure packages meet schema requirements before distribution
-- **Development-Focused** — Optimized for rapid development and testing of MCP server ecosystems
+- Configure MCP servers on one or more AI host platforms at once
+- Discover which host platforms are installed on your machine
+- List and inspect server registrations across all your tools
+- Manage MCP server packages with dependency isolation (system, Python, Docker)
 
 ## Supported MCP Hosts
 
-Hatch supports deployment to the following MCP host platforms:
+Claude Desktop, Claude Code, VS Code, Cursor, Kiro, Codex, LM Studio, Google Gemini CLI, Mistral Vibe, OpenCode, Augment Code (Auggie CLI and Intent)
 
-- **Claude Desktop** — Anthropic's desktop application for Claude with native MCP support
-- **Claude Code** — Claude integration for VS Code with MCP capabilities
-- **VS Code** — Visual Studio Code with the MCP extension for tool integration
-- **Cursor** — AI-first code editor with built-in MCP server support
-- **Kiro** — Kiro IDE with MCP support
-- **Codex** — OpenAI Codex with MCP server configuration support
-- **LM Studio** — Local LLM inference platform with MCP server integration
-- **Google Gemini CLI** — Command-line interface for Google's Gemini model with MCP support
-- **Mistral Vibe** — Mistral Vibe CLI coding agent
-
-## Quick Start
-
-### Install from PyPI
+## Install
 
 ```bash
 pip install hatch-xclam
 ```
 
-Verify installation:
+Verify:
 
 ```bash
 hatch --version
 ```
 
-### Install from source
+Or install from source:
 
 ```bash
 git clone https://github.com/CrackingShells/Hatch.git
@@ -52,76 +39,72 @@ cd Hatch
 pip install -e .
 ```
 
-### Create your first environment and *Hatch!* MCP server package
+## Usage
 
-```bash
-# Create an isolated environment
-hatch env create my_project
+### Configure MCP servers on your hosts
 
-# Switch to it
-hatch env use my_project
+```bash
+# Local server via npx — register it on VS Code
+hatch mcp configure context7 --host vscode \
+  --command npx --args "-y @upstash/context7-mcp"
 
-# Create a package template
-hatch create my_mcp_server --description "My MCP server"
+# Remote server with an auth header — register it on Gemini CLI
+export GIT_PAT_TOKEN=your_github_personal_access_token
+hatch mcp configure github-mcp --host gemini \
+  --httpUrl https://api.github.com/mcp \
+  --header Authorization="Bearer $GIT_PAT_TOKEN"
 
-# Validate the package
-hatch validate ./my_mcp_server
+# Register the same server on multiple hosts at once
+hatch mcp configure my-server --host claude-desktop,cursor,vscode \
+  --command python --args "-m my_server"
 ```
 
-### Deploy MCP servers to your tools
-
-**Package-First Deployment (Recommended)** — Add a Hatch package and automatically configure it on Claude Desktop and Cursor:
+### Inspect what is configured
 
 ```bash
-hatch package add ./my_mcp_server --host claude-desktop,cursor
+# See all servers across all hosts
+hatch mcp list servers
+
+# See all hosts a specific server is registered on
+hatch mcp show servers --server "context7"
+
+# Detect which MCP host platforms are installed
+hatch mcp discover hosts
 ```
 
-**Direct Configuration (Advanced)** — Configure arbitrary MCP servers on your hosts:
+### Package management (in development)
 
-```bash
-# Remote server example: GitHub MCP Server with authentication
-export GIT_PAT_TOKEN=your_github_personal_access_token
-hatch mcp configure github-mcp --host gemini \
-  --httpUrl https://api.github.com/mcp \
-  --header Authorization="Bearer $GIT_PAT_TOKEN"
+The package system lets you install MCP servers with automatic dependency resolution and environment isolation. It is functional but being reworked for better integration with MCP registries.
 
-# Local server example: Context7 via npx
-hatch mcp configure context7 --host vscode \
-  --command npx --args "-y @upstash/context7-mcp"
+```bash
+hatch env create my_project
+hatch env use my_project
+hatch package add ./my_mcp_server
 ```
 
 ## Documentation
 
-- **[Full Documentation](https://hatch.readthedocs.io/en/latest/)** — Complete reference and guides
-- **[Getting Started](./docs/articles/users/GettingStarted.md)** — Quick start for users
-- **[CLI Reference](./docs/articles/users/CLIReference.md)** — All commands and options
-- **[Tutorials](./docs/articles/users/tutorials/)** — Step-by-step guides from installation to package authoring
-- **[MCP Host Configuration](./docs/articles/users/MCPHostConfiguration.md)** — Deploy to multiple platforms
-- **[Developer Docs](./docs/articles/devs/)** — Architecture, implementation guides, and contribution guidelines
-- **[Troubleshooting](./docs/articles/users/Troubleshooting/ReportIssues.md)** — Common issues and solutions
+- **[Full Documentation](https://hatch.readthedocs.io/en/latest/)**
+- **[Getting Started](./docs/articles/users/GettingStarted.md)**
+- **[CLI Reference](./docs/articles/users/CLIReference.md)**
+- **[MCP Host Configuration](./docs/articles/users/MCPHostConfiguration.md)**
+- **[Tutorials](./docs/articles/users/tutorials/)**
+- **[Troubleshooting](./docs/articles/users/Troubleshooting/ReportIssues.md)**
 
 ## Contributing
 
-We welcome contributions! See the [How to Contribute](./docs/articles/devs/contribution_guides/how_to_contribute.md) guide for details.
-
-### Quick start for developers
-
-1. **Fork and clone** the repository
-2. **Install dependencies**: `pip install -e .` and `npm install`
-3. **Create a feature branch**: `git checkout -b feat/your-feature`
-4. **Make changes** and add tests
-5. **Use conventional commits**: `npm run commit` for guided commits
-6. **Run tests**: `wobble`
-7. **Create a pull request**
-
-We use [Conventional Commits](https://www.conventionalcommits.org/) for automated versioning. Use `npm run commit` for guided commit messages.
+We welcome contributions. See [How to Contribute](./docs/articles/devs/contribution_guides/how_to_contribute.md) for details.
 
-## Getting Help
+Quick setup:
 
-- Search existing [GitHub Issues](https://github.com/CrackingShells/Hatch/issues)
-- Read [Troubleshooting](./docs/articles/users/Troubleshooting/ReportIssues.md) for common problems
-- Check [Developer Onboarding](./docs/articles/devs/development_processes/developer_onboarding.md) for setup help
+1. Fork and clone the repository
+2. Install dependencies: `pip install -e .` and `npm install`
+3. Create a feature branch: `git checkout -b feat/your-feature`
+4. Make changes and add tests
+5. Use conventional commits: `npm run commit`
+6. Run tests: `wobble`
+7. Open a pull request
 
 ## License
 
-This project is licensed under the GNU Affero General Public License v3 — see `LICENSE` for details.
+GNU Affero General Public License v3 — see `LICENSE` for details.
diff --git a/docs/articles/api/cli/mcp.md b/docs/articles/api/cli/mcp.md
index 252c9dd..1162c74 100644
--- a/docs/articles/api/cli/mcp.md
+++ b/docs/articles/api/cli/mcp.md
@@ -22,9 +22,11 @@ This module provides handlers for:
 - vscode: Visual Studio Code with Copilot
 - kiro: Kiro IDE
 - codex: OpenAI Codex
-- lm-studio: LM Studio
+- lmstudio: LM Studio
 - gemini: Google Gemini
 - mistral-vibe: Mistral Vibe CLI coding agent
+- opencode: OpenCode AI coding assistant
+- augment: Augment Code AI assistant
 
 ## Handler Functions
 
diff --git a/docs/articles/appendices/LimitsAndKnownIssues.md b/docs/articles/appendices/LimitsAndKnownIssues.md
index 516ab05..0fdbbf5 100644
--- a/docs/articles/appendices/LimitsAndKnownIssues.md
+++ b/docs/articles/appendices/LimitsAndKnownIssues.md
@@ -1,34 +1,14 @@
 # Limits and Known Issues
 
-This appendix documents current limitations and known issues in Hatch v0.4.2, organized by impact severity and architectural domain.
+This appendix documents current limitations and known issues in Hatch v0.8.1, organized by impact severity and architectural domain.
 
 ## Critical Limitations (High Impact)
 
-### Non-Interactive Environment Handling
-
-**Issue**: The dependency installation orchestrator can block indefinitely in non-TTY environments.
-
-**Code Location**: `hatch/installers/dependency_installation_orchestrator.py:501` (`_request_user_consent`)
-
-**Symptoms**:
-
-- Hangs in CI/CD pipelines when TTY is unavailable
-- Docker container execution may hang indefinitely
-- Programmatic integration requires foreknowledge of `--auto-approve` parameter
-
-**Workaround**: Use `--auto-approve` flag for automated scenarios
-
-```bash
-hatch package add my-package --auto-approve
-```
-
-**Root Cause**: Blocking `input()` call without TTY detection or environment variable fallback mechanisms.
-
 ### System Package Version Constraint Simplification
 
 **Issue**: Complex version constraints for system packages are reduced to "install latest" with only warning messages.
 
-**Code Location**: `hatch/installers/system_installer.py:332-365` (`_build_apt_command`)
+**Code Location**: `hatch/installers/system_installer.py:366-403` (`_build_apt_command`)
 
 **Symptoms**:
 
@@ -46,8 +26,9 @@ hatch package add my-package --auto-approve
 
 **Code Locations**:
 
-- `hatch/environment_manager.py:85-90`
-- `hatch/package_loader.py:80-85`
+- `hatch/environment_manager.py:172-179` (`_save_environments`)
+- `hatch/environment_manager.py:220` (`set_current_environment`, `current_env` file write)
+- `hatch/package_loader.py:139-145` (cache write in `download_package`)
 
 **Symptoms**:
 
@@ -63,25 +44,25 @@ hatch package add my-package --auto-approve
 
 ### Registry Fetch Fragility
 
-**Issue**: Registry fetching uses date-based URL construction with limited fallback robustness.
+**Issue**: Registry fetching has no retry logic for transient network failures.
 
-**Code Location**: `hatch/registry_retriever.py:45-65`
+**Code Location**: `hatch/registry_retriever.py:200-231` (`_fetch_remote_registry`)
 
 **Symptoms**:
 
-- Package discovery breaks when registry publishing is delayed
+- A single transient network error causes the fetch to fail immediately with no retry
 - Poor error messages during network connectivity issues
-- Development workflow disruption during registry maintenance
+- Development workflow disruption during registry unavailability
 
 **Workaround**: Use local packages (`hatch package add ./local-package`) when registry is unavailable
 
-**Root Cause**: Registry URL construction assumes daily publishing schedule without robust fallback strategies.
+**Root Cause**: Network requests are single-attempt with no retry strategy or back-off logic.
 
 ### Package Integrity Verification Gap
 
 **Issue**: Downloaded packages are not cryptographically verified for integrity.
 
-**Code Location**: `hatch/package_loader.py:75-125` (`download_package`)
+**Code Location**: `hatch/package_loader.py:56-157` (`download_package`)
 
 **Symptoms**:
 
@@ -95,25 +76,25 @@ hatch package add my-package --auto-approve
 
 ### Cross-Platform Python Environment Detection
 
-**Issue**: Hard-coded path assumptions limit Python environment detection across different platforms and installations.
+**Issue**: Hard-coded path assumptions limit Python environment detection for non-standard conda/mamba installations.
 
-**Code Location**: `hatch/python_environment_manager.py:85-120` (`_detect_conda_mamba`)
+**Code Location**: `hatch/python_environment_manager.py:65-125` (`_detect_manager`)
 
 **Symptoms**:
 
-- Inconsistent behavior across different conda installations
-- Silent feature degradation when Python environments unavailable
-- User confusion about Python integration capabilities
+- Inconsistent behavior with custom conda/mamba installation locations
+- Silent feature degradation when conda/mamba is not in a standard path
+- User confusion about Python integration capabilities on non-standard setups
 
-**Workaround**: Ensure conda/mamba are in system PATH or use explicit paths
+**Workaround**: Set the `CONDA_EXE` or `MAMBA_EXE` environment variable to point to your conda/mamba executable, or ensure it is in your system PATH
 
-**Root Cause**: Platform-specific path assumptions and limited environment variable checking.
+**Root Cause**: Hard-coded fallback paths cover only common installation locations (`~/miniconda3`, `~/anaconda3`, `/opt/conda`). `PATH` and `CONDA_EXE`/`MAMBA_EXE` environment variables are checked first but may not cover all installation scenarios.
 
 ### Error Recovery and Rollback Gaps
 
 **Issue**: Limited transactional semantics during multi-dependency installation.
 
-**Code Location**: `hatch/installers/dependency_installation_orchestrator.py:550-580` (`_execute_install_plan`)
+**Code Location**: `hatch/installers/dependency_installation_orchestrator.py:605-681` (`_execute_install_plan`)
 
 **Symptoms**:
 
@@ -147,7 +128,7 @@ hatch package add my-package --auto-approve
 
 **Issue**: Templates assume specific MCP server structure and dependencies.
 
-**Code Location**: `hatch/template_generator.py:130-140`
+**Code Location**: `hatch/template_generator.py` (particularly `generate_mcp_server_py:33`, `generate_hatch_mcp_server_entry_py:63`, `generate_metadata_json:87`)
 
 **Symptoms**:
 
@@ -163,17 +144,17 @@ hatch package add my-package --auto-approve
 
 **Issue**: Limited handling of circular dependencies and complex version constraints.
 
-**Code Location**: `hatch/installers/dependency_installation_orchestrator.py:290-320`
+**Code Location**: `hatch/installers/dependency_installation_orchestrator.py:337-358` (`_get_install_ready_hatch_dependencies`)
 
 **Symptoms**:
 
-- Potential infinite loops during dependency resolution
+- Potential failures during dependency resolution for circular or deeply nested graphs
 - Unclear error messages for complex dependency conflicts
 - Unexpected behavior with deeply nested dependency trees
 
 **Workaround**: Simplify dependency structures and avoid circular dependencies
 
-**Root Cause**: Dependency graph builder lacks edge case handling for complex scenarios.
+**Root Cause**: Dependency graph resolution is delegated to `hatch_validator.utils.hatch_dependency_graph.HatchDependencyGraphBuilder`; edge case robustness depends on that external library.
 
 ## Minor Limitations (Quality of Life)
 
@@ -181,7 +162,7 @@ hatch package add my-package --auto-approve
 
 **Issue**: System package installation assumes `sudo` availability without proper validation.
 
-**Code Location**: `hatch/installers/system_installer.py:365-380`
+**Code Location**: `hatch/installers/system_installer.py:382-403` (`_build_apt_command`, `install`)
 
 **Symptoms**:
 
@@ -192,53 +173,45 @@ hatch package add my-package --auto-approve
 
 ### Simulation and Dry-Run Gaps
 
-**Issue**: Inconsistent simulation mode implementation across installers.
+**Issue**: Simulation mode infrastructure exists but is not yet wired through the orchestrator.
 
-**Code Locations**: Various installer modules
+**Code Locations**:
+
+- `hatch/installers/dependency_installation_orchestrator.py:635` (`simulation_mode=False`, marked "Future enhancement")
+- `hatch/installers/system_installer.py:152` (simulation mode fully implemented at installer level)
 
 **Symptoms**:
 
-- No unified dry-run capability across all dependency types
+- No dry-run capability reachable through normal `hatch package add` flow
+- `SystemInstaller` has full `apt-get --dry-run` support ready but not yet exposed
 - Limited preview capabilities for complex installation plans
 
 **Workaround**: Test installations in isolated environments first
 
+**Root Cause**: Planned feature not yet implemented. `InstallationContext` supports `simulation_mode` and individual installers handle it, but the orchestrator does not yet accept or pass through a simulation flag.
+
 ### Cache Management Strategy
 
 **Issue**: Basic TTL-based caching without intelligent invalidation or size limits.
 
 **Code Locations**:
 
-- `hatch/package_loader.py:40-50`
-- `hatch/registry_retriever.py:35-45`
+- `hatch/registry_retriever.py:37` (24-hour TTL constant)
+- `hatch/package_loader.py` (presence-only caching, no TTL or size limits)
 
 **Symptoms**:
 
-- Fixed 24-hour TTL regardless of registry update frequency
+- Fixed 24-hour TTL for registry data regardless of registry update frequency
+- Package cache never expires — only invalidated by `force_download=True`
 - No automatic cache cleanup for disk space management
 - Force refresh only available at operation level
 
 **Workaround**: Manually clear cache directory when needed:
 
 ```bash
-rm -rf ~/.hatch/cache/*
+rm -rf ~/.hatch/packages/*
 ```
 
-### External Dependency Coupling
-
-**Issue**: Validator dependency fetched via git URL with network requirements.
-
-**Code Location**: `pyproject.toml:24`
-
-**Details**: `hatch_validator @ git+https://github.com/CrackingShells/Hatch-Validator.git@v0.6.3`
-
-**Symptoms**:
-
-- Build-time network access required
-- Dependency on repository and tag availability
-
-**Workaround**: Ensure network access during installation or consider local installation methods
-
 ### Documentation and Schema Evolution
 
 **Issue**: Limited handling of package schema version transitions.
@@ -257,20 +230,19 @@ rm -rf ~/.hatch/cache/*
 
 | Severity | Automation | Reliability | Development |
 |----------|------------|-------------|-------------|
-| **Critical** | Non-interactive handling | Concurrent access, System constraints | - |
+| **Critical** | - | Concurrent access, System constraints | - |
 | **Significant** | Registry fragility, Error recovery | Package integrity, Python detection | - |
 | **Moderate** | - | - | Observability, Templates, Dependency resolution |
-| **Minor** | Simulation gaps | Security context, Cache strategy | External coupling, Schema evolution |
+| **Minor** | Simulation gaps | Security context, Cache strategy | Schema evolution |
 
 ## Recommended Mitigation Strategies
 
 ### For Production Use
 
-1. **Always use `--auto-approve`** for automated deployments
-2. **Avoid concurrent operations** until race conditions are resolved
-3. **Use exact version constraints** for system packages when possible
-4. **Implement external monitoring** for installation operations
-5. **Regularly backup environment configurations**
+1. **Avoid concurrent operations** until race conditions are resolved
+2. **Use exact version constraints** for system packages when possible
+3. **Implement external monitoring** for installation operations
+4. **Regularly backup environment configurations**
 
 ### For Development
 
@@ -290,7 +262,7 @@ rm -rf ~/.hatch/cache/*
 
 The Hatch team is aware of these limitations and they are prioritized for future releases:
 
-**Phase 1 (Stability)**: Address concurrent access, non-interactive handling, and error recovery
+**Phase 1 (Stability)**: Address concurrent access and error recovery
 **Phase 2 (Security)**: Implement package integrity verification and security context validation
 **Phase 3 (Robustness)**: Improve cross-platform consistency and system package handling
 **Phase 4 (Quality)**: Enhance observability, caching, and template flexibility
diff --git a/docs/articles/devs/architecture/mcp_host_configuration.md b/docs/articles/devs/architecture/mcp_host_configuration.md
index 42de522..2784e51 100644
--- a/docs/articles/devs/architecture/mcp_host_configuration.md
+++ b/docs/articles/devs/architecture/mcp_host_configuration.md
@@ -10,7 +10,7 @@ This article covers:
 
 ## Overview
 
-The MCP host configuration system manages Model Context Protocol server configurations across multiple host platforms (Claude Desktop, VS Code, Cursor, Gemini, Kiro, Codex, LM Studio). It uses the **Unified Adapter Architecture**: a single data model with host-specific adapters for validation and serialization.
+The MCP host configuration system manages Model Context Protocol server configurations across multiple host platforms (Claude Desktop, Claude Code, VS Code, Cursor, LM Studio, Gemini, Kiro, Codex, Mistral Vibe, OpenCode, Augment). It uses the **Unified Adapter Architecture**: a single data model with host-specific adapters for validation and serialization.
 
 > **Adding a new host?** See the [Implementation Guide](../implementation_guides/mcp_host_configuration_extension.md) for step-by-step instructions.
 
diff --git a/docs/articles/users/CLIReference.md b/docs/articles/users/CLIReference.md
index 09ee038..527c61c 100644
--- a/docs/articles/users/CLIReference.md
+++ b/docs/articles/users/CLIReference.md
@@ -1,1117 +1,972 @@
-# CLI Reference
-
-This document is a compact reference of all Hatch CLI commands and options implemented in the `hatch/cli/` package, presented as tables for quick lookup.
-
-## Table of Contents
-
-```
-- [Global options](#global-options)
-- [Commands](#commands)
-  - [hatch create](#hatch-create)
-  - [hatch validate](#hatch-validate)
-  - [hatch env](#hatch-env-environment-management)
-    - [hatch env create](#hatch-env-create)
-    - [hatch env remove](#hatch-env-remove)
-    - [hatch env list](#hatch-env-list)
-    - [hatch env use](#hatch-env-use)
-    - [hatch env current](#hatch-env-current)
-    - [hatch env python](#hatch-env-python-advanced-python-environment-subcommands)
-      - [hatch env python init](#hatch-env-python-init)
-      - [hatch env python info](#hatch-env-python-info)
-      - [hatch env python add-hatch-mcp](#hatch-env-python-add-hatch-mcp)
-      - [hatch env python remove](#hatch-env-python-remove)
-      - [hatch env python shell](#hatch-env-python-shell)
-  - [hatch package](#hatch-package-package-management)
-    - [hatch package add](#hatch-package-add)
-    - [hatch package remove](#hatch-package-remove)
-    - [hatch package list](#hatch-package-list)
-    - [hatch package sync](#hatch-package-sync)
-  - [hatch mcp](#hatch-mcp)
-    - [hatch mcp configure](#hatch-mcp-configure)
-    - [hatch mcp sync](#hatch-mcp-sync)
-    - [hatch mcp remove server](#hatch-mcp-remove-server)
-    - [hatch mcp remove host](#hatch-mcp-remove-host)
-    - [hatch mcp list hosts](#hatch-mcp-list-hosts)
-    - [hatch mcp list servers](#hatch-mcp-list-servers)
-    - [hatch mcp discover hosts](#hatch-mcp-discover-hosts)
-    - [hatch mcp discover servers](#hatch-mcp-discover-servers)
-    - [hatch mcp backup list](#hatch-mcp-backup-list)
-    - [hatch mcp backup restore](#hatch-mcp-backup-restore)
-    - [hatch mcp backup clean](#hatch-mcp-backup-clean)
-```
-
-## Global options
-
-These flags are accepted by the top-level parser and apply to all commands unless overridden.
-
-| Flag | Type | Description | Default |
-|------|------|-------------|---------|
-| `--version` | flag | Show program version and exit | n/a |
-| `--envs-dir` | path | Directory to store environments | `~/.hatch/envs` |
-| `--cache-ttl` | int | Cache time-to-live in seconds | `86400` (1 day) |
-| `--cache-dir` | path | Directory to store cached packages | `~/.hatch/cache` |
-| `--log-level` | choice | Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR` | `WARNING` |
-
-Example:
-
-```bash
-hatch --version
-# Output: hatch 0.6.1
-```
-
-## Commands
-
-Each top-level command has its own table. Use the Syntax line before the table to see how to call it.
-
-### `hatch create`
-
-Create a new package template.
-
-Syntax:
-
-`hatch create <name> [--dir DIR] [--description DESC]`
-
-| Argument / Flag | Type | Description | Default |
-|---:|---|---|---|
-| `name` | string (positional) | Package name (required) | n/a |
-| `--dir`, `-d` | path | Target directory for the template | current directory |
-| `--description`, `-D` | string | Package description | empty string |
-
-Examples:
-
-`hatch create my_package`
-
-`hatch create my_package --dir ./packages --description "My awesome package"`
-
----
-
-### `hatch validate`
-
-Validate a package structure and metadata.
-
-Syntax:
-
-`hatch validate <package_dir>`
-
-| Argument | Type | Description |
-|---:|---|---|
-| `package_dir` | path (positional) | Path to package directory to validate (required) |
-
-Examples:
-
-`hatch validate ./my_package`
-
----
-
-### `hatch env` (environment management)
-
-Top-level syntax: `hatch env <create|remove|list|use|current|python> ...`
-
-#### `hatch env create`
-
-Create a new Hatch environment bootstrapping a Python/conda environment.
-
-Syntax:
-
-`hatch env create <name> [--description DESC] [--python-version VER] [--no-python] [--no-hatch-mcp-server] [--hatch_mcp_server_tag TAG]`
-
-| Argument / Flag | Type | Description | Default |
-|---:|---|---|---|
-| `name` | string (positional) | Environment name (required) | n/a |
-| `--description`, `-D` | string | Human-readable environment description | empty string |
-| `--python-version` | string | Python version to create (e.g., `3.11`) | none (manager default) |
-| `--no-python` | flag | Do not create a Python environment (skip conda/mamba) | false |
-| `--no-hatch-mcp-server` | flag | Do not install `hatch_mcp_server` wrapper | false |
-| `--hatch-mcp-server-tag` | string | Git tag/branch for wrapper installation (e.g., `dev`, `v0.1.0`) | none |
-
-#### `hatch env remove`
-
-Syntax:
-
-`hatch env remove <name>`
-
-| Argument | Type | Description |
-|---:|---|---|
-| `name` | string (positional) | Environment name to remove (required) |
-
-#### `hatch env list`
-
-List all environments with package counts.
-
-Syntax:
-
-`hatch env list [--pattern PATTERN] [--json]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--pattern` | string | Filter environments by name using regex pattern | none |
-| `--json` | flag | Output in JSON format | false |
-
-**Example Output**:
-
-```bash
-$ hatch env list
-Environments:
-  Name             Python        Packages
-  ───────────────────────────────────────
-  * default        3.14.2               0
-    test-env       3.11.5               3
-```
-
-**Key Details**:
-- Header: `"Environments:"` only
-- Columns: Name (width 15), Python (width 10), Packages (width 10, right-aligned)
-- Current environment marked with `"* "` prefix
-- Packages column shows COUNT only
-- Separator: `"─"` character (U+2500)
-
-#### `hatch env list hosts`
-
-List environment/host/server deployments from environment data.
-
-Syntax:
-
-`hatch env list hosts [--env PATTERN] [--server PATTERN] [--json]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--env`, `-e` | string | Filter by environment name using regex pattern | none |
-| `--server` | string | Filter by server name using regex pattern | none |
-| `--json` | flag | Output in JSON format | false |
-
-**Example Output**:
-
-```bash
-$ hatch env list hosts
-Environment Host Deployments:
-  Environment      Host                Server              Version
-  ─────────────────────────────────────────────────────────────────
-  default          claude-desktop      weather-server      1.0.0
-  default          cursor              weather-server      1.0.0
-```
-
-**Description**:
-Lists environment/host/server deployments from environment data. Shows only Hatch-managed packages and their host deployments.
-
-#### `hatch env list servers`
-
-List environment/server/host deployments from environment data.
-
-Syntax:
-
-`hatch env list servers [--env PATTERN] [--host PATTERN] [--json]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--env`, `-e` | string | Filter by environment name using regex pattern | none |
-| `--host` | string | Filter by host name using regex pattern (use '-' for undeployed) | none |
-| `--json` | flag | Output in JSON format | false |
-
-**Example Output**:
-
-```bash
-$ hatch env list servers
-Environment Servers:
-  Environment      Server              Host                Version
-  ─────────────────────────────────────────────────────────────────
-  default          weather-server      claude-desktop      1.0.0
-  default          weather-server      cursor              1.0.0
-  test-env         utility-pkg         -                   2.1.0
-```
-
-**Description**:
-Lists environment/server/host deployments from environment data. Shows only Hatch-managed packages. Undeployed packages show '-' in Host column.
-
-#### `hatch env show`
-
-Display detailed hierarchical view of a specific environment.
-
-Syntax:
-
-`hatch env show <name>`
-
-| Argument | Type | Description |
-|---:|---|---|
-| `name` | string (positional) | Environment name to show (required) |
-
-**Example Output**:
-
-```bash
-$ hatch env show default
-Environment: default (active)
-  Description: My development environment
-  Created: 2026-01-15 10:30:00
-
-  Python Environment:
-    Version: 3.14.2
-    Executable: /path/to/python
-    Conda env: N/A
-    Status: Active
-
-  Packages (2):
-    weather-server
-      Version: 1.0.0
-      Source: registry (https://registry.example.com)
-      Deployed to: claude-desktop, cursor
-
-    utility-pkg
-      Version: 2.1.0
-      Source: local (/path/to/package)
-      Deployed to: (none)
-```
-
-**Key Details**:
-- Header shows `"(active)"` suffix if current environment
-- Hierarchical structure with 2-space indentation
-- No separator lines between sections
-- Packages section shows count in header
-- Each package shows version, source, and deployed hosts
-
-#### `hatch env use`
-
-Syntax:
-
-`hatch env use <name>`
-
-| Argument | Type | Description |
-|---:|---|---|
-| `name` | string (positional) | Environment name to set as current (required) |
-
-#### `hatch env current`
-
-Syntax:
-
-`hatch env current`
-
-Description: Print the name of the current environment.
-
----
-
-### `hatch env python` (advanced Python environment subcommands)
-
-Top-level syntax: `hatch env python <init|info|add-hatch-mcp|remove|shell> ...`
-
-#### `hatch env python init`
-
-Initialize or recreate a Python environment inside a Hatch environment.
-
-Syntax:
-
-`hatch env python init [--hatch_env NAME] [--python-version VER] [--force] [--no-hatch-mcp-server] [--hatch_mcp_server_tag TAG]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--hatch_env` | string | Hatch environment name (defaults to current env) | current environment |
-| `--python-version` | string | Desired Python version (e.g., `3.12`) | none |
-| `--force` | flag | Force recreation if it already exists | false |
-| `--no-hatch-mcp-server` | flag | Skip installing `hatch_mcp_server` wrapper | false |
-| `--hatch_mcp_server_tag` | string | Git tag/branch for wrapper installation | none |
-
-#### `hatch env python info`
-
-Show information about the Python environment for a Hatch environment.
-
-Syntax:
-
-`hatch env python info [--hatch_env NAME] [--detailed]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--hatch_env` | string | Hatch environment name (defaults to current) | current environment |
-| `--detailed` | flag | Show additional diagnostics and package listing | false |
-
-When available this command prints: status, python executable, python version, conda env name, environment path, creation time, package count and package list. With `--detailed` it also prints diagnostics from the manager.
-
-#### `hatch env python add-hatch-mcp`
-
-Install the `hatch_mcp_server` wrapper into the Python environment of a Hatch env.
-
-Syntax:
-
-`hatch env python add-hatch-mcp [--hatch_env NAME] [--tag TAG]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--hatch_env` | string | Hatch environment name (defaults to current) | current environment |
-| `--tag` | string | Git tag/branch for wrapper install | none |
-
-#### `hatch env python remove`
-
-Remove the Python environment associated with a Hatch environment.
-
-Syntax:
-
-`hatch env python remove [--hatch_env NAME] [--force]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--hatch_env` | string | Hatch environment name (defaults to current) | current environment |
-| `--force` | flag | Skip confirmation prompt and force removal | false |
-
-#### `hatch env python shell`
-
-Launch a Python REPL or run a single command inside the Python environment.
-
-Syntax:
-
-`hatch env python shell [--hatch_env NAME] [--cmd CMD]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--hatch_env` | string | Hatch environment name (defaults to current) | current environment |
-| `--cmd` | string | Command to execute inside the Python shell (optional) | none |
-
----
-
-### `hatch package` (package management)
-
-Top-level syntax: `hatch package <add|remove|list|sync> ...`
-
-#### `hatch package add`
-
-Add a package (local path or registry name) into an environment.
-
-Syntax:
-
-`hatch package add <package_path_or_name> [--env NAME] [--version VER] [--force-download] [--refresh-registry] [--auto-approve]`
-
-| Argument / Flag | Type | Description | Default |
-|---:|---|---|---|
-| `package_path_or_name` | string (positional) | Path to package directory or registry package name (required) | n/a |
-| `--env`, `-e` | string | Target Hatch environment name (defaults to current) | current environment |
-| `--version`, `-v` | string | Version for registry packages | none |
-| `--force-download`, `-f` | flag | Force fetching even if cached | false |
-| `--refresh-registry`, `-r` | flag | Refresh registry metadata before resolving | false |
-| `--auto-approve` | flag | Automatically approve dependency installation prompts | false |
-| `--host` | string | Comma-separated list of MCP host platforms to configure (e.g., claude-desktop,cursor) | none |
-
-**Note:** Dependency installation prompts are also automatically approved in non-TTY environments (such as CI/CD pipelines) or when the `HATCH_AUTO_APPROVE` environment variable is set. See [Environment Variables](#environment-variables) for details.
-
-**MCP Host Integration:** When adding a package, if the `--host` flag is specified, Hatch will automatically configure the package's MCP servers on the specified hosts. This includes analyzing package dependencies and configuring all related MCP servers.
-
-**MCP Host Integration Examples:**
-
-```bash
-# Add package and automatically configure MCP servers on specific hosts
-hatch package add ./my_package --host claude-desktop,cursor
-
-# Add package for all available hosts
-hatch package add ./my_package --host all
-
-# Skip host configuration (no MCP servers configured)
-hatch package add ./my_package
-
-# Add with other flags and MCP configuration
-hatch package add registry_package --version 1.0.0 --env dev-env --host gemini --auto-approve
-```
-
-Examples:
-
-`hatch package add ./my_package`
-
-`hatch package add registry_package --version 1.0.0 --env dev-env --auto-approve`
-
-#### `hatch package remove`
-
-Remove a package from a Hatch environment.
-
-Syntax:
-
-`hatch package remove <package_name> [--env NAME]`
-
-| Argument / Flag | Type | Description | Default |
-|---:|---|---|---|
-| `package_name` | string (positional) | Name of the package to remove (required) | n/a |
-| `--env`, `-e` | string | Hatch environment name (defaults to current) | current environment |
-
-#### `hatch package list`
-
-**⚠️ DEPRECATED**: This command is deprecated. Use `hatch env list` to see packages inline with environment information, or `hatch env show <name>` for detailed package information.
-
-List packages installed in a Hatch environment.
-
-Syntax:
-
-`hatch package list [--env NAME]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--env`, `-e` | string | Hatch environment name (defaults to current) | current environment |
-
-**Example Output**:
-
-```bash
-$ hatch package list
-Warning: 'hatch package list' is deprecated. Use 'hatch env list' instead, which shows packages inline.
-Packages in environment 'default':
-weather-server (1.0.0)	Hatch compliant: True	source: https://registry.example.com	location: /path/to/package
-```
-
-**Migration Guide**:
-- For package counts: Use `hatch env list` (shows package count per environment)
-- For detailed package info: Use `hatch env show <name>` (shows full package details)
-- For deployment info: Use `hatch env list hosts` or `hatch env list servers`
-
-#### `hatch package sync`
-
-Synchronize package MCP servers to host platforms.
-
-Syntax:
-
-`hatch package sync <package_name> --host <hosts> [--env ENV] [--dry-run] [--auto-approve] [--no-backup]`
-
-| Argument / Flag | Type | Description | Default |
-|---:|---|---|---|
-| `package_name` | string (positional) | Name of package whose MCP servers to sync | n/a |
-| `--host` | string | Comma-separated list of host platforms or 'all' | n/a |
-| `--env`, `-e` | string | Target Hatch environment name (defaults to current) | current environment |
-| `--dry-run` | flag | Preview changes without execution | false |
-| `--auto-approve` | flag | Skip confirmation prompts | false |
-| `--no-backup` | flag | Disable default backup behavior of the MCP host's config file | false |
-
-Examples:
-
-`hatch package sync my-package --host claude-desktop`
-
-`hatch package sync weather-server --host claude-desktop,cursor --dry-run`
-
-# Multi-package synchronization examples
-# Sync main package AND all its dependencies:
-hatch package sync my-package --host all
-
-# Sync without creating backups
-hatch package sync my-package --host claude-desktop --no-backup
-
----
-
-## Environment Variables
-
-Hatch recognizes the following environment variables to control behavior:
-
-| Variable | Description | Accepted Values | Default |
-|----------|-------------|-----------------|---------|
-| `HATCH_AUTO_APPROVE` | Automatically approve dependency installation prompts in non-interactive environments | `1`, `true`, `yes` (case-insensitive) | unset |
-
-### `HATCH_AUTO_APPROVE`
-
-When set to a truthy value (`1`, `true`, or `yes`, case-insensitive), this environment variable enables automatic approval of dependency installation prompts. This is particularly useful in CI/CD pipelines and other automated environments where user interaction is not possible.
-
-**Behavior:**
-
-- In TTY environments: User is still prompted for consent unless this variable is set
-- In non-TTY environments: Installation is automatically approved regardless of this variable
-- When set in any environment: Installation is automatically approved without prompting
-
-**Examples:**
-
-```bash
-# Enable auto-approval for the current session
-export HATCH_AUTO_APPROVE=1
-hatch package add my_package
-
-# Enable auto-approval for a single command
-HATCH_AUTO_APPROVE=true hatch package add my_package
-
-# CI/CD pipeline usage
-HATCH_AUTO_APPROVE=yes hatch package add production_package
-```
-
-**Note:** This environment variable works in conjunction with the `--auto-approve` CLI flag. Either method will enable automatic approval of installation prompts.
-
----
-
-## MCP Host Configuration Commands
-
-### `hatch mcp`
-
-Commands subset to manage non-hatch package MCP servers.
-Top level syntax: `<hatch mcp configure|sync|remove|list|discover|backup> ...`
-
-#### `hatch mcp configure`
-
-Configure an MCP server on a specific host platform.
-
-Syntax:
-
-`hatch mcp configure <server-name> --host <host> (--command CMD | --url URL) [--args ARGS] [--env-var ENV] [--header HEADER] [--dry-run] [--auto-approve] [--no-backup]`
-
-| Argument / Flag | Hosts | Type | Description | Default |
-|---:|---|---|---|---|
-| `server-name` | all | string (positional) | Name of the MCP server to configure | n/a |
-| `--host` | all | string | Target host platform (claude-desktop, cursor, etc.) | n/a |
-| `--command` | all | string | Command to execute for local servers (mutually exclusive with --url) | none |
-| `--url` | all except Claude Desktop/Code | string | URL for remote MCP servers (mutually exclusive with --command) | none |
-| `--http-url` | gemini | string | HTTP streaming endpoint URL | none |
-| `--args` | all | string | Arguments for MCP server command (only with --command) | none |
-| `--env-var` | all | string | Environment variables format: KEY=VALUE (can be used multiple times) | none |
-| `--header` | all except Claude Desktop/Code | string | HTTP headers format: KEY=VALUE (only with --url) | none |
-| `--timeout` | gemini | int | Request timeout in milliseconds | none |
-| `--trust` | gemini | flag | Bypass tool call confirmations | false |
-| `--cwd` | gemini, codex | string | Working directory for stdio transport | none |
-| `--include-tools` | gemini, codex | multiple | Tool allowlist / enabled tools. Space-separated values. | none |
-| `--exclude-tools` | gemini, codex | multiple | Tool blocklist / disabled tools. Space-separated values. | none |
-| `--env-file` | cursor, vscode, lmstudio | string | Path to environment file | none |
-| `--input` | vscode | multiple | Input variable definitions format: type,id,description[,password=true] | none |
-| `--disabled` | kiro | flag | Disable the MCP server | false |
-| `--auto-approve-tools` | kiro | multiple | Tool names to auto-approve. Can be used multiple times. | none |
-| `--disable-tools` | kiro | multiple | Tool names to disable. Can be used multiple times. | none |
-| `--env-vars` | codex | multiple | Environment variable names to whitelist/forward. Can be used multiple times. | none |
-| `--startup-timeout` | codex | int | Server startup timeout in seconds (default: 10) | none |
-| `--tool-timeout` | codex | int | Tool execution timeout in seconds (default: 60) | none |
-| `--enabled` | codex | flag | Enable the MCP server | false |
-| `--bearer-token-env-var` | codex | string | Name of env var containing bearer token for Authorization header | none |
-| `--env-header` | codex | multiple | HTTP header from env var format: KEY=ENV_VAR_NAME. Can be used multiple times. | none |
-| `--dry-run` | all | flag | Preview configuration without applying changes | false |
-| `--auto-approve` | all | flag | Skip confirmation prompts | false |
-| `--no-backup` | all | flag | Skip backup creation before configuration | false |
-
-**Behavior**:
-
-The command now displays a **conversion report** showing exactly what fields will be configured on the target host. This provides transparency about which fields are supported by the host and what values will be set.
-
-The conversion report shows:
-- **UPDATED** fields: Fields being set with their new values (shown as `None --> value`)
-- **UNSUPPORTED** fields: Fields not supported by the target host (automatically filtered out)
-- **UNCHANGED** fields: Fields that already have the specified value (update operations only)
-
-Note: Internal metadata fields (like `name`) are not shown in the field operations list, as they are used for internal bookkeeping and are not written to host configuration files. The server name is displayed in the report header for context.
-
-**Example - Local Server Configuration**:
-
-```bash
-$ hatch mcp configure my-server --host claude-desktop --command python --args server.py --env API_KEY=secret
-
-Server 'my-server' created for host 'claude-desktop':
-  command: UPDATED None --> 'python'
-  args: UPDATED None --> ['server.py']
-  env: UPDATED None --> {'API_KEY': 'secret'}
-
-Configure MCP server 'my-server' on host 'claude-desktop'? [y/N]: y
-[SUCCESS] Successfully configured MCP server 'my-server' on host 'claude-desktop'
-```
-
-**Example - Remote Server Configuration**:
-
-```bash
-$ hatch mcp configure api-server --host claude-desktop --url https://api.example.com --header Auth=token
-
-Server 'api-server' created for host 'claude-desktop':
-  name: UPDATED None --> 'api-server'
-  command: UPDATED None --> None
-  args: UPDATED None --> None
-  env: UPDATED None --> {}
-  url: UPDATED None --> 'https://api.example.com'
-  headers: UPDATED None --> {'Auth': 'token'}
-
-Configure MCP server 'api-server' on host 'claude-desktop'? [y/N]: y
-[SUCCESS] Successfully configured MCP server 'api-server' on host 'claude-desktop'
-```
-
-**Example - Advanced Gemini Configuration**:
-
-```bash
-$ hatch mcp configure my-server --host gemini --command python --args server.py --timeout 30000 --trust --include-tools weather,calculator
-
-Server 'my-server' created for host 'gemini':
-  name: UPDATED None --> 'my-server'
-  command: UPDATED None --> 'python'
-  args: UPDATED None --> ['server.py']
-  timeout: UPDATED None --> 30000
-  trust: UPDATED None --> True
-  include_tools: UPDATED None --> ['weather', 'calculator']
-
-Configure MCP server 'my-server' on host 'gemini'? [y/N]: y
-[SUCCESS] Successfully configured MCP server 'my-server' on host 'gemini'
-```
-
-**Example - Kiro Configuration**:
-
-```bash
-$ hatch mcp configure my-server --host kiro --command python --args server.py --auto-approve-tools weather,calculator --disable-tools debug
-
-Server 'my-server' created for host 'kiro':
-  name: UPDATED None --> 'my-server'
-  command: UPDATED None --> 'python'
-  args: UPDATED None --> ['server.py']
-  autoApprove: UPDATED None --> ['weather', 'calculator']
-  disabledTools: UPDATED None --> ['debug']
-
-Configure MCP server 'my-server' on host 'kiro'? [y/N]: y
-[SUCCESS] Successfully configured MCP server 'my-server' on host 'kiro'
-```
-
-**Example - Kiro with Disabled Server**:
-
-```bash
-$ hatch mcp configure my-server --host kiro --command python --args server.py --disabled
-
-Server 'my-server' created for host 'kiro':
-  name: UPDATED None --> 'my-server'
-  command: UPDATED None --> 'python'
-  args: UPDATED None --> ['server.py']
-  disabled: UPDATED None --> True
-
-Configure MCP server 'my-server' on host 'kiro'? [y/N]: y
-[SUCCESS] Successfully configured MCP server 'my-server' on host 'kiro'
-```
-
-**Example - Codex Configuration with Timeouts and Tool Filtering**:
-
-```bash
-$ hatch mcp configure context7 --host codex --command npx --args "-y" "@upstash/context7-mcp" --env-vars PATH --env-vars HOME --startup-timeout 15 --tool-timeout 120 --enabled --include-tools read write --exclude-tools delete
-
-Server 'context7' created for host 'codex':
-  name: UPDATED None --> 'context7'
-  command: UPDATED None --> 'npx'
-  args: UPDATED None --> ['-y', '@upstash/context7-mcp']
-  env_vars: UPDATED None --> ['PATH', 'HOME']
-  startup_timeout_sec: UPDATED None --> 15
-  tool_timeout_sec: UPDATED None --> 120
-  enabled: UPDATED None --> True
-  enabled_tools: UPDATED None --> ['read', 'write']
-  disabled_tools: UPDATED None --> ['delete']
-
-Configure MCP server 'context7' on host 'codex'? [y/N]: y
-[SUCCESS] Successfully configured MCP server 'context7' on host 'codex'
-```
-
-**Example - Codex HTTP Server with Authentication**:
-
-```bash
-$ hatch mcp configure figma --host codex --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN --env-header "X-Figma-Region=FIGMA_REGION" --header "X-Custom=static-value"
-
-Server 'figma' created for host 'codex':
-  name: UPDATED None --> 'figma'
-  url: UPDATED None --> 'https://mcp.figma.com/mcp'
-  bearer_token_env_var: UPDATED None --> 'FIGMA_OAUTH_TOKEN'
-  env_http_headers: UPDATED None --> {'X-Figma-Region': 'FIGMA_REGION'}
-  http_headers: UPDATED None --> {'X-Custom': 'static-value'}
-
-Configure MCP server 'figma' on host 'codex'? [y/N]: y
-[SUCCESS] Successfully configured MCP server 'figma' on host 'codex'
-```
-
-**Example - Remote Server Configuration**:
-
-```bash
-$ hatch mcp configure api-server --host vscode --url https://api.example.com --header Auth=token
-
-Server 'api-server' created for host 'vscode':
-  name: UPDATED None --> 'api-server'
-  url: UPDATED None --> 'https://api.example.com'
-  headers: UPDATED None --> {'Auth': 'token'}
-
-Configure MCP server 'api-server' on host 'vscode'? [y/N]: y
-[SUCCESS] Successfully configured MCP server 'api-server' on host 'vscode'
-```
-
-**Example - Dry Run Mode**:
-
-```bash
-$ hatch mcp configure my-server --host gemini --command python --args server.py --dry-run
-
-[DRY RUN] Would configure MCP server 'my-server' on host 'gemini':
-[DRY RUN] Command: python
-[DRY RUN] Args: ['server.py']
-[DRY RUN] Backup: Enabled
-[DRY RUN] Preview of changes for server 'my-server':
-  command: UPDATED None --> 'python'
-  args: UPDATED None --> ['server.py']
-
-No changes were made.
-```
-
-**Host-Specific Field Support**:
-
-Different MCP hosts support different configuration fields. The conversion report automatically filters unsupported fields:
-
-- **Claude Desktop / Claude Code**: Supports universal fields only (command, args, env, url, headers, type)
-- **Cursor / LM Studio**: Supports universal fields + envFile
-- **VS Code**: Supports universal fields + envFile, inputs
-- **Gemini CLI**: Supports universal fields + 14 additional fields (cwd, timeout, trust, OAuth settings, etc.)
-- **Codex**: Supports universal fields + Codex-specific fields for URL-based servers (http_headers, env_http_headers, bearer_token_env_var, enabled, startup_timeout_sec, tool_timeout_sec, env_vars)
-
-When configuring a server with fields not supported by the target host, those fields are marked as UNSUPPORTED in the report and automatically excluded from the configuration.
-
-#### `hatch mcp sync`
-
-Synchronize MCP configurations across environments and hosts.
-
-The sync command displays a preview of servers to be synced before requesting confirmation, giving visibility into which servers will be affected.
-
-Syntax:
-
-`hatch mcp sync [--from-env ENV | --from-host HOST] --to-host HOSTS [--servers SERVERS | --pattern PATTERN] [--dry-run] [--auto-approve] [--no-backup]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--from-env` | string | Source Hatch environment (mutually exclusive with --from-host) | none |
-| `--from-host` | string | Source host platform (mutually exclusive with --from-env) | none |
-| `--to-host` | string | Target hosts (comma-separated or 'all') | n/a |
-| `--servers` | string | Specific server names to sync (mutually exclusive with --pattern) | none |
-| `--pattern` | string | Regex pattern for server selection (mutually exclusive with --servers) | none |
-| `--dry-run` | flag | Preview synchronization without executing changes | false |
-| `--auto-approve` | flag | Skip confirmation prompts | false |
-| `--no-backup` | flag | Skip backup creation before synchronization | false |
-
-**Example Output (pre-prompt)**:
-
-```
-hatch mcp sync:
-  [INFO] Servers: weather-server, my-tool (2 total)
-  [SYNC] environment 'dev' → 'claude-desktop'
-  [SYNC] environment 'dev' → 'cursor'
-  Proceed? [y/N]:
-```
-
-When more than 3 servers match, the list is truncated: `Servers: srv1, srv2, srv3, ... (7 total)`
-
-**Error Output**:
-
-Sync failures use standardized error formatting with structured details:
-
-```
-[ERROR] Synchronization failed
-  claude-desktop: Config file not found
-```
-
-#### `hatch mcp remove server`
-
-Remove an MCP server from one or more hosts.
-
-Syntax:
-
-`hatch mcp remove server <server-name> --host <hosts> [--env ENV] [--dry-run] [--auto-approve] [--no-backup]`
-
-| Argument / Flag | Type | Description | Default |
-|---:|---|---|---|
-| `server-name` | string (positional) | Name of the server to remove | n/a |
-| `--host` | string | Target hosts (comma-separated or 'all') | n/a |
-| `--env`, `-e` | string | Hatch environment name (reserved for future use) | none |
-| `--dry-run` | flag | Preview removal without executing changes | false |
-| `--auto-approve` | flag | Skip confirmation prompts | false |
-| `--no-backup` | flag | Skip backup creation before removal | false |
-
-#### `hatch mcp remove host`
-
-Remove complete host configuration (all MCP servers from the specified host).
-
-Syntax:
-
-`hatch mcp remove host <host-name> [--dry-run] [--auto-approve] [--no-backup]`
-
-| Argument / Flag | Type | Description | Default |
-|---:|---|---|---|
-| `host-name` | string (positional) | Name of the host to remove | n/a |
-| `--dry-run` | flag | Preview removal without executing changes | false |
-| `--auto-approve` | flag | Skip confirmation prompts | false |
-| `--no-backup` | flag | Skip backup creation before removal | false |
-
-#### `hatch mcp list hosts`
-
-List host/server pairs from host configuration files.
-
-**Purpose**: Shows ALL servers on hosts (both Hatch-managed and third-party) with Hatch management status.
-
-Syntax:
-
-`hatch mcp list hosts [--server PATTERN] [--json]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--server` | string | Filter by server name using regex pattern | none |
-| `--json` | flag | Output in JSON format | false |
-
-**Example Output**:
-
-```bash
-$ hatch mcp list hosts
-MCP Hosts:
-  Host                Server              Hatch     Environment
-  ─────────────────────────────────────────────────────────────────
-  claude-desktop      weather-server      ✅        default
-  claude-desktop      third-party-tool    ❌        -
-  cursor              weather-server      ✅        default
-```
-
-**Key Details**:
-- Header: `"MCP Hosts:"`
-- Columns: Host (width 18), Server (width 18), Hatch (width 8), Environment (width 15)
-- Hatch column: `"✅"` for Hatch-managed, `"❌"` for third-party
-- Shows ALL servers on hosts (both Hatch-managed and third-party)
-- Environment column: environment name if Hatch-managed, `"-"` otherwise
-- Sorted by: host (alphabetically), then server
-
-#### `hatch mcp list servers`
-
-List server/host pairs from host configuration files.
-
-**Purpose**: Shows ALL servers on hosts (both Hatch-managed and third-party) with Hatch management status.
-
-Syntax:
-
-`hatch mcp list servers [--host PATTERN] [--json]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--host` | string | Filter by host name using regex pattern | none |
-| `--json` | flag | Output in JSON format | false |
-
-**Example Output**:
-
-```bash
-$ hatch mcp list servers
-MCP Servers:
-  Server              Host                Hatch     Environment
-  ─────────────────────────────────────────────────────────────────
-  third-party-tool    claude-desktop      ❌        -
-  weather-server      claude-desktop      ✅        default
-  weather-server      cursor              ✅        default
-```
-
-**Key Details**:
-- Header: `"MCP Servers:"`
-- Columns: Server (width 18), Host (width 18), Hatch (width 8), Environment (width 15)
-- Hatch column: `"✅"` for Hatch-managed, `"❌"` for third-party
-- Shows ALL servers on hosts (both Hatch-managed and third-party)
-- Environment column: environment name if Hatch-managed, `"-"` otherwise
-- Sorted by: server (alphabetically), then host
-
-#### `hatch mcp show hosts`
-
-Show detailed hierarchical view of all MCP host configurations.
-
-**Purpose**: Displays comprehensive configuration details for all hosts with their servers.
-
-Syntax:
-
-`hatch mcp show hosts [--server PATTERN] [--json]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--server` | string | Filter by server name using regex pattern | none |
-| `--json` | flag | Output in JSON format | false |
-
-**Example Output**:
-
-```bash
-$ hatch mcp show hosts
-═══════════════════════════════════════════════════════════════════════════════
-MCP Host: claude-desktop
-  Config Path: /Users/user/.config/claude/claude_desktop_config.json
-  Last Modified: 2026-02-01 15:30:00
-  Backup Available: Yes (3 backups)
-
-  Configured Servers (2):
-    weather-server (Hatch-managed: default)
-      Command: python
-      Args: ['-m', 'weather_server']
-      Environment Variables:
-        API_KEY: ****** (hidden)
-        DEBUG: true
-      Last Synced: 2026-02-01 15:30:00
-      Package Version: 1.0.0
-
-    third-party-tool (Not Hatch-managed)
-      Command: node
-      Args: ['server.js']
-
-═══════════════════════════════════════════════════════════════════════════════
-MCP Host: cursor
-  Config Path: /Users/user/.cursor/mcp.json
-  Last Modified: 2026-02-01 14:20:00
-  Backup Available: No
-
-  Configured Servers (1):
-    weather-server (Hatch-managed: default)
-      Command: python
-      Args: ['-m', 'weather_server']
-      Last Synced: 2026-02-01 14:20:00
-      Package Version: 1.0.0
-```
-
-**Key Details**:
-- Separator: `"═" * 79` (U+2550) between hosts
-- Host and server names highlighted (bold + amber when colors enabled)
-- Hatch-managed servers show: `"(Hatch-managed: {environment})"`
-- Third-party servers show: `"(Not Hatch-managed)"`
-- Sensitive environment variables shown as `"****** (hidden)"`
-- Hierarchical structure with 2-space indentation per level
-
-#### `hatch mcp show servers`
-
-Show detailed hierarchical view of all MCP server configurations across hosts.
-
-**Purpose**: Displays comprehensive configuration details for all servers across their host deployments.
-
-Syntax:
-
-`hatch mcp show servers [--host PATTERN] [--json]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--host` | string | Filter by host name using regex pattern | none |
-| `--json` | flag | Output in JSON format | false |
-
-**Example Output**:
-
-```bash
-$ hatch mcp show servers
-═══════════════════════════════════════════════════════════════════════════════
-MCP Server: weather-server
-  Hatch Managed: Yes (default)
-  Package Version: 1.0.0
-
-  Host Configurations (2):
-    claude-desktop:
-      Command: python
-      Args: ['-m', 'weather_server']
-      Environment Variables:
-        API_KEY: ****** (hidden)
-        DEBUG: true
-      Last Synced: 2026-02-01 15:30:00
-
-    cursor:
-      Command: python
-      Args: ['-m', 'weather_server']
-      Last Synced: 2026-02-01 14:20:00
-
-═══════════════════════════════════════════════════════════════════════════════
-MCP Server: third-party-tool
-  Hatch Managed: No
-
-  Host Configurations (1):
-    claude-desktop:
-      Command: node
-      Args: ['server.js']
-```
-
-**Key Details**:
-- Separator: `"═" * 79` between servers
-- Server and host names highlighted (bold + amber when colors enabled)
-- Hatch-managed servers show: `"Hatch Managed: Yes ({environment})"`
-- Third-party servers show: `"Hatch Managed: No"`
-- Hierarchical structure with 2-space indentation per level
-
-#### `hatch mcp discover hosts`
-
-Discover available MCP host platforms on the system.
-
-**Purpose**: Shows ALL host platforms (both available and unavailable) with system detection status.
-
-Syntax:
-
-`hatch mcp discover hosts [--json]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--json` | flag | Output in JSON format | false |
-
-**Example Output**:
-
-```bash
-$ hatch mcp discover hosts
-Available MCP Host Platforms:
-  Host                Status           Config Path
-  ─────────────────────────────────────────────────────────────────
-  claude-desktop      ✓ Available      /Users/user/.config/claude/...
-  cursor              ✓ Available      /Users/user/.cursor/mcp.json
-  vscode              ✗ Not Found      -
-  mistral-vibe        ✓ Available      /Users/user/.config/mistral/mcp.toml
-```
-
-**Key Details**:
-- Header: `"Available MCP Host Platforms:"`
-- Columns: Host (width 18), Status (width 15), Config Path (width "auto")
-- Status: `"✓ Available"` or `"✗ Not Found"`
-- Shows ALL host types (MCPHostType enum), not just available ones
-
-Syntax:
-
-`hatch mcp discover hosts`
-
-**Example Output**:
-
-```text
-Available MCP host platforms:
-  claude-desktop: ✓ Available
-    Config path: ~/.claude/config.json
-  cursor: ✓ Available
-    Config path: ~/.cursor/config.json
-  vscode: ✗ Not detected
-    Config path: ~/.vscode/config.json
-  mistral-vibe: ✓ Available
-    Config path: ~/.config/mistral/mcp.toml
-```
-
-#### `hatch mcp discover servers`
-
-Discover MCP servers in Hatch environments.
-
-Syntax:
-
-`hatch mcp discover servers [--env ENV]`
-
-| Flag | Type | Description | Default |
-|---:|---|---|---|
-| `--env` | string | Specific environment to discover servers in | current environment |
-
-#### `hatch mcp backup list`
-
-List available configuration backups for a specific host.
-
-Syntax:
-
-`hatch mcp backup list <host> [--detailed]`
-
-| Argument / Flag | Type | Description | Default |
-|---:|---|---|---|
-| `host` | string (positional) | Host platform to list backups for (e.g., claude-desktop, cursor) | n/a |
-| `--detailed`, `-d` | flag | Show detailed backup information | false |
-
-#### `hatch mcp backup restore`
-
-Restore host configuration from a backup file.
-
-Syntax:
-
-`hatch mcp backup restore <host> [--backup-file FILE] [--dry-run] [--auto-approve]`
-
-| Argument / Flag | Type | Description | Default |
-|---:|---|---|---|
-| `host` | string (positional) | Host platform to restore (e.g., claude-desktop, cursor) | n/a |
-| `--backup-file`, `-f` | string | Specific backup file to restore (defaults to latest) | latest backup |
-| `--dry-run` | flag | Preview restore without executing changes | false |
-| `--auto-approve` | flag | Skip confirmation prompts | false |
-
-#### `hatch mcp backup clean`
-
-Clean old backup files for a specific host based on retention criteria.
-
-Syntax:
-
-`hatch mcp backup clean <host> [--older-than-days DAYS] [--keep-count COUNT] [--dry-run] [--auto-approve]`
-
-| Argument / Flag | Type | Description | Default |
-|---:|---|---|---|
-| `host` | string (positional) | Host platform to clean backups for (e.g., claude-desktop, cursor) | n/a |
-| `--older-than-days` | integer | Remove backups older than specified days | none |
-| `--keep-count` | integer | Keep only the most recent N backups | none |
-| `--dry-run` | flag | Preview cleanup without executing changes | false |
-| `--auto-approve` | flag | Skip confirmation prompts | false |
-
-**Note:** At least one of `--older-than-days` or `--keep-count` must be specified.
-
----
-
-## Exit codes
-
-| Code | Meaning |
-|---:|---|
-| `0` | Success |
-| `1` | Error or failure |
-
-## Notes
-
-- The CLI is implemented in the `hatch/cli/` package with modular handler modules. Use `hatch --help` to inspect available commands and options.
-- This reference mirrors the command names and option names implemented in the CLI handlers. If you change CLI arguments in code, update this file to keep documentation in sync.
+# CLI Reference
+
+This document is a compact reference of all Hatch CLI commands and options implemented in the `hatch/cli/` package, presented as tables for quick lookup.
+
+## Table of Contents
+
+- [Global options](#global-options)
+- [Commands](#commands)
+  - [hatch create](#hatch-create)
+  - [hatch validate](#hatch-validate)
+  - [hatch env](#hatch-env-environment-management)
+    - [hatch env create](#hatch-env-create)
+    - [hatch env remove](#hatch-env-remove)
+    - [hatch env list](#hatch-env-list)
+    - [hatch env use](#hatch-env-use)
+    - [hatch env current](#hatch-env-current)
+    - [hatch env show](#hatch-env-show)
+    - [hatch env python](#hatch-env-python-advanced-python-environment-subcommands)
+      - [hatch env python init](#hatch-env-python-init)
+      - [hatch env python info](#hatch-env-python-info)
+      - [hatch env python add-hatch-mcp](#hatch-env-python-add-hatch-mcp)
+      - [hatch env python remove](#hatch-env-python-remove)
+      - [hatch env python shell](#hatch-env-python-shell)
+  - [hatch package](#hatch-package-package-management)
+    - [hatch package add](#hatch-package-add)
+    - [hatch package remove](#hatch-package-remove)
+    - [hatch package list](#hatch-package-list)
+    - [hatch package sync](#hatch-package-sync)
+  - [hatch mcp](#hatch-mcp)
+    - [hatch mcp discover hosts](#hatch-mcp-discover-hosts)
+    - [hatch mcp discover servers](#hatch-mcp-discover-servers)
+    - [hatch mcp list hosts](#hatch-mcp-list-hosts)
+    - [hatch mcp list servers](#hatch-mcp-list-servers)
+    - [hatch mcp show hosts](#hatch-mcp-show-hosts)
+    - [hatch mcp show servers](#hatch-mcp-show-servers)
+    - [hatch mcp configure](#hatch-mcp-configure)
+    - [hatch mcp sync](#hatch-mcp-sync)
+    - [hatch mcp remove server](#hatch-mcp-remove-server)
+    - [hatch mcp remove host](#hatch-mcp-remove-host)
+    - [hatch mcp backup list](#hatch-mcp-backup-list)
+    - [hatch mcp backup restore](#hatch-mcp-backup-restore)
+    - [hatch mcp backup clean](#hatch-mcp-backup-clean)
+
+## Global options
+
+These flags are accepted by the top-level parser and apply to all commands unless overridden.
+
+| Flag | Type | Description | Default |
+|------|------|-------------|---------|
+| `--version` | flag | Show program version and exit | n/a |
+| `--envs-dir` | path | Directory to store environments | `~/.hatch/envs` |
+| `--cache-ttl` | int | Cache time-to-live in seconds | `86400` (1 day) |
+| `--cache-dir` | path | Directory to store cached packages | `~/.hatch/cache` |
+| `--log-level` | choice | Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR` | `WARNING` |
+
+Example:
+
+```bash
+hatch --version
+# Output: hatch 0.6.1
+```
+
+## Commands
+
+Each top-level command has its own table. Use the Syntax line before the table to see how to call it.
+
+### `hatch create`
+
+
+Create a new package template.
+
+Syntax:
+
+`hatch create <name> [--dir DIR] [--description DESC]`
+
+
+| Argument / Flag | Type | Description | Default |
+|---:|---|---|---|
+| `name` | string (positional) | Package name (required) | n/a |
+| `--dir`, `-d` | path | Target directory for the template | current directory |
+| `--description`, `-D` | string | Package description | empty string |
+
+Examples:
+
+`hatch create my_package`
+
+`hatch create my_package --dir ./packages --description "My awesome package"`
+
+
+---
+
+
+### `hatch validate`
+
+
+Validate a package structure and metadata.
+
+Syntax:
+
+`hatch validate <package_dir>`
+
+
+| Argument | Type | Description |
+|---:|---|---|
+| `package_dir` | path (positional) | Path to package directory to validate (required) |
+
+Examples:
+
+`hatch validate ./my_package`
+
+---
+
+### `hatch env` (environment management)
+
+
+Top-level syntax: `hatch env <create|remove|list|use|current|show|python> ...`
+
+
+#### `hatch env create`
+
+
+Create a new Hatch environment bootstrapping a Python/conda environment.
+
+Syntax:
+
+`hatch env create <name> [--description DESC] [--python-version VER] [--no-python] [--no-hatch-mcp-server] [--hatch-mcp-server-tag TAG]`
+
+
+| Argument / Flag | Type | Description | Default |
+|---:|---|---|---|
+| `name` | string (positional) | Environment name (required) | n/a |
+| `--description`, `-D` | string | Human-readable environment description | empty string |
+| `--python-version` | string | Python version to create (e.g., `3.11`) | none (manager default) |
+| `--no-python` | flag | Do not create a Python environment (skip conda/mamba) | false |
+| `--no-hatch-mcp-server` | flag | Do not install `hatch_mcp_server` wrapper | false |
+| `--hatch-mcp-server-tag` | string | Git tag/branch for wrapper installation | none |
+
+---
+
+#### `hatch env remove`
+
+
+Syntax:
+
+`hatch env remove <name>`
+
+
+| Argument | Type | Description |
+|---:|---|---|
+| `name` | string (positional) | Environment name to remove (required) |
+
+---
+
+#### `hatch env list`
+
+
+List all environments with package counts.
+
+**Example Output**:
+
+```bash
+$ hatch env list
+Environments:
+  Name             Python        Packages
+  ───────────────────────────────────────
+  * default        3.14.2               0
+    test-env       3.11.5               3
+```
+
+**Key Details**:
+- Header: `"Environments:"` only
+- Columns: Name (width 15), Python (width 10), Packages (width 10, right-aligned)
+- Current environment marked with `"* "` prefix
+- Packages column shows COUNT only
+- Separator: `"─"` character (U+2500)
+
+Syntax:
+
+`hatch env list [--pattern PATTERN] [--json]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--pattern` | string | Filter environments by name using regex pattern | none |
+| `--json` | flag | Output in JSON format | false |
+
+---
+
+#### `hatch env use`
+
+Syntax:
+
+`hatch env use <name>`
+
+
+| Argument | Type | Description |
+|---:|---|---|
+| `name` | string (positional) | Environment name to set as current (required) |
+
+---
+
+#### `hatch env current`
+
+Syntax:
+
+`hatch env current`
+
+
+Description: Print the name of the current environment.
+
+---
+
+#### `hatch env show`
+
+
+Display detailed hierarchical view of a specific environment.
+
+Syntax:
+
+`hatch env show <name>`
+
+
+| Argument | Type | Description |
+|---:|---|---|
+| `name` | string (positional) | Environment name to show (required) |
+
+**Example Output**:
+
+```bash
+$ hatch env show default
+Environment: default (active)
+  Description: My development environment
+  Created: 2026-01-15 10:30:00
+
+  Python Environment:
+    Version: 3.14.2
+    Executable: /path/to/python
+    Conda env: N/A
+    Status: Active
+
+  Packages (2):
+    weather-server
+      Version: 1.0.0
+      Source: registry (https://registry.example.com)
+      Deployed to: claude-desktop, cursor
+
+    utility-pkg
+      Version: 2.1.0
+      Source: local (/path/to/package)
+      Deployed to: (none)
+```
+
+**Key Details**:
+- Header shows `"(active)"` suffix if current environment
+- Hierarchical structure with 2-space indentation
+- No separator lines between sections
+- Packages section shows count in header
+- Each package shows version, source, and deployed hosts
+
+---
+
+### `hatch env python` (advanced Python environment subcommands)
+
+Top-level syntax: `hatch env python <init|info|add-hatch-mcp|remove|shell> ...`
+
+
+#### `hatch env python init`
+
+Initialize or recreate a Python environment inside a Hatch environment.
+
+Syntax:
+
+`hatch env python init [--hatch_env NAME] [--python-version VER] [--force] [--no-hatch-mcp-server] [--hatch_mcp_server_tag TAG]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--hatch_env` | string | Hatch environment name (defaults to current env) | current environment |
+| `--python-version` | string | Desired Python version (e.g., `3.12`) | none |
+| `--force` | flag | Force recreation if it already exists | false |
+| `--no-hatch-mcp-server` | flag | Skip installing `hatch_mcp_server` wrapper | false |
+| `--hatch_mcp_server_tag` | string | Git tag/branch for wrapper installation | none |
+
+---
+
+#### `hatch env python info`
+
+Show information about the Python environment for a Hatch environment.
+
+Syntax:
+
+`hatch env python info [--hatch_env NAME] [--detailed]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--hatch_env` | string | Hatch environment name (defaults to current) | current environment |
+| `--detailed` | flag | Show additional diagnostics and package listing | false |
+
+When available this command prints: status, python executable, python version, conda env name, environment path, creation time, package count and package list. With `--detailed` it also prints diagnostics from the manager.
+
+
+---
+
+#### `hatch env python add-hatch-mcp`
+
+
+Install the `hatch_mcp_server` wrapper into the Python environment of a Hatch env.
+
+
+Syntax:
+
+`hatch env python add-hatch-mcp [--hatch_env NAME] [--tag TAG]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--hatch_env` | string | Hatch environment name (defaults to current) | current environment |
+| `--tag` | string | Git tag/branch for wrapper install | none |
+
+---
+
+#### `hatch env python remove`
+
+
+Remove the Python environment associated with a Hatch environment.
+
+
+Syntax:
+
+`hatch env python remove [--hatch_env NAME] [--force]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--hatch_env` | string | Hatch environment name (defaults to current) | current environment |
+| `--force` | flag | Skip confirmation prompt and force removal | false |
+
+---
+
+#### `hatch env python shell`
+
+Launch a Python REPL or run a single command inside the Python environment.
+
+
+Syntax:
+
+`hatch env python shell [--hatch_env NAME] [--cmd CMD]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--hatch_env` | string | Hatch environment name (defaults to current) | current environment |
+| `--cmd` | string | Command to execute inside the Python shell (optional) | none |
+
+---
+
+### `hatch package` (package management)
+
+Top-level syntax: `hatch package <add|remove|list|sync> ...`
+
+
+#### `hatch package add`
+
+Add a package (local path or registry name) into an environment.
+
+Syntax:
+
+`hatch package add <package_path_or_name> [--env NAME] [--version VER] [--force-download] [--refresh-registry] [--auto-approve] [--host HOSTS]`
+
+
+| Argument / Flag | Type | Description | Default |
+|---:|---|---|---|
+| `package_path_or_name` | string (positional) | Path to package directory or registry package name (required) | n/a |
+| `--env`, `-e` | string | Target Hatch environment name (defaults to current) | current environment |
+| `--version`, `-v` | string | Version for registry packages | none |
+| `--force-download`, `-f` | flag | Force fetching even if cached | false |
+| `--refresh-registry`, `-r` | flag | Refresh registry metadata before resolving | false |
+| `--auto-approve` | flag | Automatically approve dependency installation prompts | false |
+| `--host` | string | Comma-separated list of MCP host platforms to configure (e.g., claude-desktop,cursor) | none |
+
+**Note:** Dependency installation prompts are also automatically approved in non-TTY environments (such as CI/CD pipelines) or when the `HATCH_AUTO_APPROVE` environment variable is set.
+
+**MCP Host Integration:** When adding a package, if the `--host` flag is specified, Hatch will automatically configure the package's MCP servers on the specified hosts.
+
+Examples:
+
+`hatch package add ./my_package`
+
+`hatch package add registry_package --version 1.0.0 --env dev-env --host gemini --auto-approve`
+
+---
+
+#### `hatch package remove`
+
+Remove a package from a Hatch environment.
+
+Syntax:
+
+`hatch package remove <package_name> [--env NAME]`
+
+
+| Argument / Flag | Type | Description |
+|---:|---|---|
+| `package_name` | string (positional) | Name of the package to remove (required) | n/a |
+| `--env`, `-e` | string | Hatch environment name (defaults to current) | current environment |
+
+---
+
+#### `hatch package list`
+
+**⚠️ DEPRECATED**: This command is deprecated. Use `hatch env list` to see packages inline with environment information, or `hatch env show <name>` for detailed package information.
+
+List packages installed in a Hatch environment.
+
+Syntax:
+
+`hatch package list [--env NAME]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--env`, `-e` | string | Target Hatch environment name (defaults to current) | current environment |
+
+**Example Output**:
+
+```bash
+$ hatch package list
+Warning: 'hatch package list' is deprecated. Use 'hatch env list' instead, which shows packages inline.
+Packages in environment 'default':
+weather-server (1.0.0)  Hatch compliant: True  source: https://registry.example.com  location: /path/to/package
+```
+
+**Migration Guide**:
+- For package counts: Use `hatch env list` (shows package count per environment)
+- For detailed package info: Use `hatch env show <name>` (shows full package details)
+
+---
+
+#### `hatch package sync`
+
+Synchronize package MCP servers to host platforms.
+
+Syntax:
+
+`hatch package sync <package_name> --host <hosts> [--env ENV] [--dry-run] [--auto-approve] [--no-backup]`
+
+
+| Argument / Flag | Type | Description | Default |
+|---:|---|---|---|
+| `package_name` | string (positional) | Name of package whose MCP servers to sync | n/a |
+| `--host` | string | Comma-separated list of host platforms or 'all' | n/a |
+| `--env`, `-e` | string | Target Hatch environment name (defaults to current) | current environment |
+| `--dry-run` | flag | Preview changes without execution | false |
+| `--auto-approve` | flag | Skip confirmation prompts | false |
+| `--no-backup` | flag | Disable default backup behavior of the MCP host's config file | false |
+
+Examples:
+
+`hatch package sync my-package --host claude-desktop`
+
+`hatch package sync weather-server --host claude-desktop,cursor --dry-run --no-backup`
+
+
+---
+
+## Environment Variables
+
+Hatch recognizes the following environment variables to control behavior:
+
+| Variable | Description | Accepted Values | Default |
+|----------|-------------|-----------------|---------|
+| `HATCH_AUTO_APPROVE` | Automatically approve dependency installation prompts in non-interactive environments | `1`, `true`, `yes` (case-insensitive) | unset |
+
+### `HATCH_AUTO_APPROVE`
+
+When set to a truthy value (`1`, `true`, or `yes`, case-insensitive), this environment variable enables automatic approval of dependency installation prompts. This is particularly useful in CI/CD pipelines and other automated environments where user interaction is not possible.
+
+**Behavior:**
+
+- In TTY environments: User is still prompted for consent unless this variable is set
+- In non-TTY environments: Installation is automatically approved regardless of this variable
+- When set in any environment: Installation is automatically approved without prompting
+
+
+Examples:
+
+```bash
+# Enable auto-approval for the current session
+export HATCH_AUTO_APPROVE=1
+hatch package add my_package
+
+# Enable auto-approval for a single command
+HATCH_AUTO_APPROVE=true hatch package add my_package
+
+# CI/CD pipeline usage
+HATCH_AUTO_APPROVE=yes hatch package add production_package
+```
+
+---
+
+## MCP Host Configuration Commands
+
+### `hatch mcp`
+
+
+Commands subset to manage non-hatch package MCP servers.
+Top level syntax: `<hatch mcp discover|list|show|configure|sync|remove|backup> ...`
+
+
+#### `hatch mcp discover hosts`
+
+
+Discover available MCP host platforms on the system.
+
+**Purpose**: Shows ALL host platforms (both available and unavailable) with system detection status.
+
+
+Syntax:
+
+`hatch mcp discover hosts [--json]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--json` | flag | Output in JSON format | false |
+
+
+**Example Output**:
+
+```bash
+$ hatch mcp discover hosts
+Available MCP Host Platforms:
+  Host                Status           Config Path
+  ─────────────────────────────────────────────────────────────────
+  claude-desktop      ✓ Available      /Users/user/.config/claude/...
+  cursor              ✓ Available      /Users/user/.cursor/mcp.json
+  vscode              ✗ Not Found      -
+  mistral-vibe        ✓ Available      /Users/user/.config/mistral/mcp.toml
+```
+
+**Key Details**:
+- Header: `"Available MCP Host Platforms:"`
+- Columns: Host (width 18), Status (width 15), Config Path (width "auto")
+- Status: `"✓ Available"` or `"✗ Not Found"`
+- Shows ALL host types (MCPHostType enum), not just available ones
+
+---
+
+#### `hatch mcp discover servers`
+
+
+Discover MCP servers in Hatch environments.
+
+
+Syntax:
+
+`hatch mcp discover servers [--env ENV]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--env` | string | Specific environment to discover servers in | current environment |
+
+---
+
+#### `hatch mcp list hosts`
+
+
+List host/server pairs from host configuration files.
+
+
+**Purpose**: Shows ALL servers on hosts (both Hatch-managed and third-party) with Hatch management status.
+
+
+Syntax:
+
+`hatch mcp list hosts [--server PATTERN] [--json]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--server` | string | Filter by server name using regex pattern | none |
+| `--json` | flag | Output in JSON format | false |
+
+
+**Example Output**:
+
+```bash
+$ hatch mcp list hosts
+MCP Hosts:
+  Host                Server              Hatch     Environment
+  ─────────────────────────────────────────────────────────────────
+  claude-desktop      weather-server      ✅        default
+  claude-desktop      third-party-tool    ❌        -
+  cursor              weather-server      ✅        default
+```
+
+**Key Details**:
+- Header: `"MCP Hosts:"`
+- Columns: Host (width 18), Server (width 18), Hatch (width 8), Environment (width 15)
+- Hatch column: `"✅"` for Hatch-managed, `"❌"` for third-party
+- Shows ALL servers on hosts (both Hatch-managed and third-party)
+- Environment column: environment name if Hatch-managed, `"-"` otherwise
+- Sorted by: host (alphabetically), then server
+
+---
+
+#### `hatch mcp list servers`
+
+
+List server/host pairs from host configuration files.
+
+**Purpose**: Shows ALL servers on hosts (both Hatch-managed and third-party) with Hatch management status.
+
+Syntax:
+
+`hatch mcp list servers [--host PATTERN] [--json]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--host` | string | Filter by host name using regex pattern | none |
+| `--json` | flag | Output in JSON format | false |
+
+**Example Output**:
+
+```bash
+$ hatch mcp list servers
+MCP Servers:
+  Server              Host                Hatch     Environment
+  ─────────────────────────────────────────────────────────────────
+  third-party-tool    claude-desktop      ❌        -
+  weather-server      claude-desktop      ✅        default
+  weather-server      cursor              ✅        default
+```
+
+**Key Details**:
+- Header: `"MCP Servers:"`
+- Columns: Server (width 18), Host (width 18), Hatch (width 8), Environment (width 15)
+- Hatch column: `"✅"` for Hatch-managed, `"❌"` for third-party
+- Shows ALL servers on hosts (both Hatch-managed and third-party)
+- Environment column: environment name if Hatch-managed, `"-"` otherwise
+- Sorted by: server (alphabetically), then host
+
+---
+
+#### `hatch mcp show hosts`
+
+
+Show detailed hierarchical view of all MCP host configurations.
+
+**Purpose**: Displays comprehensive configuration details for all hosts with their servers.
+
+Syntax:
+
+`hatch mcp show hosts [--server PATTERN] [--json]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--server` | string | Filter by server name using regex pattern | none |
+| `--json` | flag | Output in JSON format | false |
+
+**Example Output**:
+
+```bash
+$ hatch mcp show hosts
+═══════════════════════════════════════════════════════════════════════════════
+MCP Host: claude-desktop
+  Config Path: /Users/user/.config/claude/claude_desktop_config.json
+  Last Modified: 2026-02-01 15:30:00
+  Backup Available: Yes (3 backups)
+
+  Configured Servers (2):
+    weather-server (Hatch-managed: default)
+      Command: python
+      Args: ['-m', 'weather_server']
+      Environment Variables:
+        API_KEY: ****** (hidden)
+        DEBUG: true
+      Last Synced: 2026-02-01 15:30:00
+      Package Version: 1.0.0
+
+    third-party-tool (Not Hatch-managed)
+      Command: node
+      Args: ['server.js']
+
+═══════════════════════════════════════════════════════════════════════════════
+MCP Host: cursor
+  Config Path: /Users/user/.config/cursor/mcp.json
+  Last Modified: 2026-02-01 14:20:00
+  Backup Available: No
+
+  Configured Servers (1):
+    weather-server (Hatch-managed: default)
+      Command: python
+      Args: ['-m', 'weather_server']
+      Last Synced: 2026-02-01 14:20:00
+      Package Version: 1.0.0
+```
+
+**Key Details**:
+- Separator: `"═" * 79` (U+2550) between hosts
+- Host and server names highlighted (bold + amber when colors enabled)
+- Hatch-managed servers show: `"(Hatch-managed: {environment})"`
+- Third-party servers show: `"(Not Hatch-managed)"`
+- Sensitive environment variables shown as `"****** (hidden)"`
+- Hierarchical structure with 2-space indentation per level
+
+---
+
+#### `hatch mcp show servers`
+
+
+Show detailed hierarchical view of all MCP server configurations across hosts.
+
+**Purpose**: Displays comprehensive configuration details for all servers across their host deployments.
+
+Syntax:
+
+`hatch mcp show servers [--host PATTERN] [--json]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--host` | string | Filter by host name using regex pattern | none |
+| `--json` | flag | Output in JSON format | false |
+
+**Example Output**:
+
+```bash
+$ hatch mcp show servers
+═══════════════════════════════════════════════════════════════════════════════
+MCP Server: weather-server
+  Hatch Managed: Yes (default)
+  Package Version: 1.0.0
+
+  Host Configurations (2):
+    claude-desktop:
+      Command: python
+      Args: ['-m', 'weather_server']
+      Environment Variables:
+        API_KEY: ****** (hidden)
+        DEBUG: true
+      Last Synced: 2026-02-01 15:30:00
+
+    cursor:
+      Command: python
+      Args: ['-m', 'weather_server']
+      Last Synced: 2026-02-01 14:20:00
+
+═══════════════════════════════════════════════════════════════════════════════
+MCP Server: third-party-tool
+  Hatch Managed: No
+
+  Host Configurations (1):
+    claude-desktop:
+      Command: node
+      Args: ['server.js']
+```
+
+**Key Details**:
+- Separator: `"═" * 79` between servers
+- Server and host names highlighted (bold + amber when colors enabled)
+- Hatch-managed servers show: `"Hatch Managed: Yes ({environment})"`
+- Third-party servers show: `"Hatch Managed: No"`
+- Hierarchical structure with 2-space indentation per level
+
+---
+
+#### `hatch mcp configure`
+
+
+Configure an MCP server on a specific host platform.
+
+
+Syntax:
+
+`hatch mcp configure <server-name> --host <host> (--command CMD | --url URL) [--args ARGS] [--env-var ENV] [--header HEADER] [--http-url URL] [--timeout MS] [--trust] [--cwd DIR] [--include-tools TOOLS] [--exclude-tools TOOLS] [--env-file FILE] [--input INPUTS] [--disabled] [--auto-approve-tools TOOLS] [--disable-tools TOOLS] [--env-vars VARS] [--startup-timeout SEC] [--tool-timeout SEC] [--enabled] [--bearer-token-env-var VAR] [--env-header HEADERS] [--dry-run] [--auto-approve] [--no-backup]`
+
+
+| Argument / Flag | Hosts | Type | Description | Default |
+|---:|---:|---|---|---|
+| `server-name` | all | string (positional) | Name of the MCP server to configure | n/a |
+| `--host` | all | string | Target host platform (claude-desktop, cursor, etc.) | n/a |
+| `--command` | all | string | Command to execute for local servers (mutually exclusive with --url) | none |
+| `--url` | all except Claude Desktop/Code | string | URL for remote MCP servers (mutually exclusive with --command) | none |
+| `--http-url` | gemini | string | HTTP streaming endpoint URL | none |
+| `--args` | all | string list | Arguments for MCP server command (only with --command) | none |
+| `--env-var` | all | string | Environment variables format: KEY=VALUE (can be used multiple times) | none |
+| `--header` | all except Claude Desktop/Code | string | HTTP headers format: KEY=VALUE (only with --url) | none |
+| `--timeout` | gemini | int | Request timeout in milliseconds | none |
+| `--trust` | gemini | flag | Bypass tool call confirmations | false |
+| `--cwd` | gemini, codex | string | Working directory for stdio transport | none |
+| `--include-tools` | gemini, codex | multiple | Tool allowlist / enabled tools. Space-separated values. | none |
+| `--exclude-tools` | gemini, codex | multiple | Tool blocklist / disabled tools. Space-separated values. | none |
+| `--env-file` | cursor, vscode, lmstudio | string | Path to environment file | none |
+| `--input` | vscode | multiple | Input variable definitions format: type,id,description[,password=true] | none |
+| `--disabled` | kiro | flag | Disable the MCP server | false |
+| `--auto-approve-tools` | kiro | multiple | Tool names to auto-approve. Can be used multiple times. | none |
+| `--disable-tools` | kiro | multiple | Tool names to disable. Can be used multiple times. | none |
+| `--env-vars` | codex | multiple | Environment variable names to whitelist/forward. Can be used multiple times. | none |
+| `--startup-timeout` | codex | int | Server startup timeout in seconds (default: 10) | 10 |
+| `--tool-timeout` | codex | int | Tool execution timeout in seconds (default: 60) | 60 |
+| `--enabled` | codex | flag | Enable the MCP server | false |
+| `--bearer-token-env-var` | codex | string | Name of env var containing bearer token for Authorization header | none |
+| `--env-header` | codex | multiple | HTTP header from env var format: KEY=ENV_VAR_NAME. Can be used multiple times. | none |
+| `--dry-run` | all | flag | Preview configuration without applying changes | false |
+| `--auto-approve` | all | flag | Skip confirmation prompts | false |
+| `--no-backup` | all | flag | Skip backup creation before configuration | false |
+
+**Behavior**:
+
+The command displays a **conversion report** showing exactly what fields will be configured on the target host. This provides transparency about which fields are supported by the host and what values will be set.
+
+The conversion report shows:
+- **UPDATED** fields: Fields being set with their new values (shown as `None --> value`)
+- **UNSUPPORTED** fields: Fields not supported by the target host (automatically filtered out)
+
+
+Note: Internal metadata fields (like `name`) are not shown in the field operations list.
+
+---
+
+#### `hatch mcp sync`
+
+
+Synchronize MCP configurations across environments and hosts.
+
+The sync command displays a preview of servers to be synced before requesting confirmation, giving visibility into which servers will be affected.
+
+Syntax:
+
+`hatch mcp sync [--from-env ENV | --from-host HOST] --to-host HOSTS [--servers SERVERS | --pattern PATTERN] [--dry-run] [--auto-approve] [--no-backup]`
+
+
+| Flag | Type | Description | Default |
+|---:|---|---|---|
+| `--from-env` | string | Source Hatch environment (mutually exclusive with --from-host) | none |
+| `--from-host` | string | Source host platform (mutually exclusive with --from-env) | none |
+| `--to-host` | string | Target hosts (comma-separated or 'all') | n/a |
+| `--servers` | string | Specific server names to sync (mutually exclusive with --pattern) | none |
+| `--pattern` | string | Regex pattern for server selection (mutually exclusive with --servers) | none |
+| `--dry-run` | flag | Preview synchronization without executing changes | false |
+| `--auto-approve` | flag | Skip confirmation prompts | false |
+| `--no-backup` | flag | Skip backup creation before synchronization | false |
+
+**Example Output (pre-prompt)**:
+
+```
+hatch mcp sync:
+  [INFO] Servers: weather-server, my-tool (2 total)
+  [SYNC] environment 'dev' → 'claude-desktop'
+  [SYNC] environment 'dev' → 'cursor'
+  Proceed? [y/N]:
+```
+
+When more than 3 servers match, the list is truncated: `Servers: srv1, srv2, srv3, ... (7 total)`
+
+
+---
+
+#### `hatch mcp remove server`
+
+
+Remove an MCP server from one or more hosts.
+
+Syntax:
+
+`hatch mcp remove server <server-name> --host <hosts> [--env ENV] [--dry-run] [--auto-approve] [--no-backup]`
+
+
+| Argument / Flag | Type | Description | Default |
+|---:|---|---|---|
+| `server-name` | string (positional) | Name of the server to remove | n/a |
+| `--host` | string | Target hosts (comma-separated or 'all') | n/a |
+| `--env`, `-e` | string | Hatch environment name (reserved for future use) | none |
+| `--dry-run` | flag | Preview removal without executing changes | false |
+| `--auto-approve` | flag | Skip confirmation prompts | false |
+| `--no-backup` | flag | Skip backup creation before removal | false |
+
+---
+
+#### `hatch mcp remove host`
+
+
+Remove complete host configuration (all MCP servers from the specified host).
+
+Syntax:
+
+`hatch mcp remove host <host-name> [--dry-run] [--auto-approve] [--no-backup]`
+
+
+| Argument / Flag | Type | Description | Default |
+|---:|---|---|---|
+| `host-name` | string (positional) | Name of the host to remove | n/a |
+| `--dry-run` | flag | Preview removal without executing changes | false |
+| `--auto-approve` | flag | Skip confirmation prompts | false |
+| `--no-backup` | flag | Skip backup creation before removal | false |
+
+---
+
+#### `hatch mcp backup list`
+
+
+List available configuration backups for a specific host.
+
+Syntax:
+
+`hatch mcp backup list <host> [--detailed]`
+
+
+| Argument / Flag | Type | Description | Default |
+|---:|---|---|---|
+| `host` | string (positional) | Host platform to list backups for (e.g., claude-desktop, cursor) | n/a |
+| `--detailed`, `-d` | flag | Show detailed backup information | false |
+
+---
+
+#### `hatch mcp backup restore`
+
+
+Restore host configuration from a backup file.
+
+Syntax:
+
+`hatch mcp backup restore <host> [--backup-file FILE] [--dry-run] [--auto-approve]`
+
+
+| Argument / Flag | Type | Description | Default |
+|---:|---|---|---|
+| `host` | string (positional) | Host platform to restore (e.g., claude-desktop, cursor) | n/a |
+| `--backup-file`, `-f` | string | Specific backup file to restore (defaults to latest) | latest backup |
+| `--dry-run` | flag | Preview restore without executing changes | false |
+| `--auto-approve` | flag | Skip confirmation prompts | false |
+
+---
+
+#### `hatch mcp backup clean`
+
+
+Clean old backup files for a specific host based on retention criteria.
+
+Syntax:
+
+`hatch mcp backup clean <host> [--older-than-days DAYS] [--keep-count COUNT] [--dry-run] [--auto-approve]`
+
+
+| Argument / Flag | Type | Description | Default |
+|---:|---|---|---|
+| `host` | string (positional) | Host platform to clean backups for (e.g., claude-desktop, cursor) | n/a |
+| `--older-than-days` | integer | Remove backups older than specified days | none |
+| `--keep-count` | integer | Keep only the most recent N backups | none |
+| `--dry-run` | flag | Preview cleanup without executing changes | false |
+| `--auto-approve` | flag | Skip confirmation prompts | false |
+
+**Note:** At least one of `--older-than-days` or `--keep-count` must be specified.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|---:|---|
+| `0` | Success |
+| `1` | Error or failure |
+
+## Notes
+
+- The CLI is implemented in the `hatch/cli/` package with modular handler modules. Use `hatch --help` to inspect available commands and options.
+- This reference mirrors the command names and option names implemented in the CLI handlers. If you change CLI arguments in code, update this file to keep documentation in sync.
diff --git a/docs/articles/users/MCPHostConfiguration.md b/docs/articles/users/MCPHostConfiguration.md
index 47adab5..9af7204 100644
--- a/docs/articles/users/MCPHostConfiguration.md
+++ b/docs/articles/users/MCPHostConfiguration.md
@@ -24,6 +24,8 @@ Hatch currently supports configuration for these MCP host platforms:
 - **LM Studio** - Local language model interface
 - **Gemini** - Google's AI development environment
 - **Mistral Vibe** - Mistral Vibe CLI coding agent
+- **OpenCode** - OpenCode AI coding assistant
+- **Augment** - Augment Code AI assistant
 
 ## Hands-on Learning
 
diff --git a/docs/articles/users/tutorials/04-mcp-host-configuration/01-host-platform-overview.md b/docs/articles/users/tutorials/04-mcp-host-configuration/01-host-platform-overview.md
index ec98fe2..479a521 100644
--- a/docs/articles/users/tutorials/04-mcp-host-configuration/01-host-platform-overview.md
+++ b/docs/articles/users/tutorials/04-mcp-host-configuration/01-host-platform-overview.md
@@ -58,6 +58,8 @@ Hatch currently supports configuration for these MCP host platforms:
 - [**LM Studio**](https://lmstudio.ai/) - Local language model interface
 - [**Gemini**](https://github.com/google-gemini/gemini-cli) - Google's AI Command Line Interface
 - [**Mistral Vibe**](https://mistral.ai/vibe) - Mistral Vibe CLI coding agent
+- [**OpenCode**](https://opencode.ai) - OpenCode AI coding assistant
+- [**Augment**](https://www.augmentcode.com/) - Augment Code AI assistant
 
 ## Configuration Management Workflow
 
diff --git a/docs/index.md b/docs/index.md
index 78eb741..379db89 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,21 +1,26 @@
 # Hatch Documentation
 
-Welcome to the documentation for Hatch, the official package manager for the Hatch! ecosystem.
-
 ## Overview
 
-Hatch provides powerful tools for managing MCP server packages, environments, and interacting with the Hatch registry. It serves as the package management foundation for [Hatchling](https://github.com/CrackingShells/Hatchling) and other projects in the ecosystem.
+Hatch is a CLI tool for configuring MCP servers across AI host platforms. Instead of editing JSON config files for each tool separately, you register servers from the command line — once, on as many hosts as you need.
+
+```bash
+hatch mcp configure context7 --host claude-desktop,cursor,vscode \
+  --command npx --args "-y @upstash/context7-mcp"
+```
+
+Hatch also has a package system for installing MCP servers with dependency isolation (Python, system packages, Docker). That part is still being developed and will eventually integrate with MCP registries.
 
-Hatch also supports MCP host configuration across popular platforms including Claude Desktop/Code, VS Code, Cursor, Kiro, Codex, LM Studio, and Gemini.
+Supported hosts: Claude Desktop, Claude Code, VS Code, Cursor, Kiro, Codex, LM Studio, Google Gemini CLI, Mistral Vibe, OpenCode, Augment Code (Auggie CLI and Intent).
 
 ## Documentation Sections
 
 ### For Users
 
-- **[Getting Started](./articles/users/GettingStarted.md)** - Quick start guide for using Hatch
-- **[Command Reference](./articles/users/CLIReference.md)** - Complete CLI command documentation
-- **[MCP Host Configuration](./articles/users/MCPHostConfiguration.md)** - Configure MCP servers across different host platforms
-- **[Tutorials Start](./articles/users/tutorials/01-getting-started/01-installation.md)** - Step-by-step guides for your journey from installation to authoring Hatch packages for MCP server easy sharing.
+- **[Getting Started](./articles/users/GettingStarted.md)** - Installation and first steps
+- **[MCP Host Configuration](./articles/users/MCPHostConfiguration.md)** - Configure MCP servers across host platforms
+- **[Command Reference](./articles/users/CLIReference.md)** - Complete CLI reference
+- **[Tutorials](./articles/users/tutorials/01-getting-started/01-installation.md)** - Step-by-step guides, including package authoring
 
 ### For Developers
 
diff --git a/docs/stylesheets/brand.css b/docs/stylesheets/brand.css
new file mode 100644
index 0000000..e408c0e
--- /dev/null
+++ b/docs/stylesheets/brand.css
@@ -0,0 +1,199 @@
+/* =============================================================
+   CrackingShells Brand Themes
+   Two custom MkDocs Material palette schemes:
+     - egg-shell  (light)  — custom scheme, fully standalone
+     - slate      (dark)   — Material built-in base + brand overrides
+   ============================================================= */
+
+/* ── Light: Egg Shell ──────────────────────────────────────── */
+[data-md-color-scheme="egg-shell"] {
+
+  /* Primary — egg yolk amber nav/header, dark green text on it */
+  --md-primary-fg-color:              #E8B84B;
+  --md-primary-fg-color--light:       #F0D060;
+  --md-primary-fg-color--dark:        #D4952A;
+  --md-primary-bg-color:              #1D3328;
+  --md-primary-bg-color--light:       rgba(29, 51, 40, 0.7);
+
+  /* Accent — warm amber */
+  --md-accent-fg-color:               #D4952A;
+  --md-accent-fg-color--transparent:  rgba(212, 149, 42, 0.15);
+  --md-accent-bg-color:               #F0E8C8;
+  --md-accent-bg-color--light:        #f5f0e0;
+
+  /* Page & surface backgrounds — warm cream */
+  --md-default-bg-color:              #F7F3EA;
+  --md-default-bg-color--light:       #EDE8DC;
+  --md-default-bg-color--lighter:     #F0EBE0;
+  --md-default-bg-color--lightest:    #faf7f2;
+
+  /* Body text — deep dark green */
+  --md-default-fg-color:              #1D3328;
+  --md-default-fg-color--light:       #3D5148;
+  --md-default-fg-color--lighter:     #4A6B58;
+  --md-default-fg-color--lightest:    rgba(29, 51, 40, 0.12);
+
+  /* Links */
+  --md-typeset-a-color:               #D4952A;
+
+  /* Code blocks */
+  --md-code-fg-color:                 #1D3328;
+  --md-code-bg-color:                 #EDE5CE;
+
+  /* Admonitions */
+  --md-admonition-fg-color:           #1D3328;
+  --md-admonition-bg-color:           #f3edd8;
+
+  /* Footer */
+  --md-footer-fg-color:               #F0E8C8;
+  --md-footer-fg-color--light:        rgba(240, 232, 200, 0.7);
+  --md-footer-fg-color--lighter:      rgba(240, 232, 200, 0.45);
+  --md-footer-bg-color:               #1D3328;
+  --md-footer-bg-color--dark:         #111D18;
+
+  /* Keyboard key */
+  --md-typeset-kbd-color:             #EDE8DC;
+  --md-typeset-kbd-accent-color:      #D4952A;
+  --md-typeset-kbd-border-color:      #C8B898;
+
+  /* Tables */
+  --md-typeset-table-color:           rgba(29, 51, 40, 0.12);
+  --md-typeset-table-color--light:    rgba(29, 51, 40, 0.035);
+
+  /* Sidebar scroll track */
+  --md-scrollbar-thumb-bg-color:      rgba(61, 81, 72, 0.35);
+}
+
+/* Override logo for light scheme */
+[data-md-color-scheme="egg-shell"] .md-header__button.md-logo img {
+  content: url(https://raw.githubusercontent.com/CrackingShells/.github/main/resources/images/hatch_wide_light_bg_transparent.png);
+}
+
+
+/* ── Dark: Hatch Night (scheme: slate) ────────────────────── */
+[data-md-color-scheme="slate"] {
+
+  /* Primary — deep green nav/header */
+  --md-primary-fg-color:              #2A3D32;
+  --md-primary-fg-color--light:       #3D5148;
+  --md-primary-fg-color--dark:        #1D2B24;
+  --md-primary-bg-color:              #F0E8C8;
+  --md-primary-bg-color--light:       rgba(240, 232, 200, 0.7);
+
+  /* Accent — golden amber */
+  --md-accent-fg-color:               #E8B84B;
+  --md-accent-fg-color--transparent:  rgba(232, 184, 75, 0.15);
+  --md-accent-bg-color:               #1D2B24;
+  --md-accent-bg-color--light:        #243525;
+
+  /* Page & surface backgrounds — near-black green */
+  --md-default-bg-color:              #111D18;
+  --md-default-bg-color--light:       #1D2B24;
+  --md-default-bg-color--lighter:     #162318;
+  --md-default-bg-color--lightest:    rgba(255, 255, 255, 0.05);
+
+  /* Body text — warm off-white */
+  --md-default-fg-color:              #E8DFC8;
+  --md-default-fg-color--light:       rgba(232, 223, 200, 0.75);
+  --md-default-fg-color--lighter:     rgba(232, 223, 200, 0.45);
+  --md-default-fg-color--lightest:    rgba(232, 223, 200, 0.12);
+
+  /* Links */
+  --md-typeset-a-color:               #E8B84B;
+
+  /* Code blocks */
+  --md-code-fg-color:                 #F0E8C8;
+  --md-code-bg-color:                 #1A2B22;
+
+  /* Admonitions */
+  --md-admonition-fg-color:           #E8DFC8;
+  --md-admonition-bg-color:           #1D2B24;
+
+  /* Footer */
+  --md-footer-fg-color:               #F0E8C8;
+  --md-footer-fg-color--light:        rgba(240, 232, 200, 0.7);
+  --md-footer-fg-color--lighter:      rgba(240, 232, 200, 0.45);
+  --md-footer-bg-color:               #0D1710;
+  --md-footer-bg-color--dark:         #080F0A;
+
+  /* Keyboard key */
+  --md-typeset-kbd-color:             #1D2B24;
+  --md-typeset-kbd-accent-color:      #E8B84B;
+  --md-typeset-kbd-border-color:      #3D5148;
+
+  /* Tables */
+  --md-typeset-table-color:           rgba(232, 184, 75, 0.12);
+  --md-typeset-table-color--light:    rgba(232, 184, 75, 0.035);
+
+  /* Sidebar scroll track */
+  --md-scrollbar-thumb-bg-color:      rgba(232, 184, 75, 0.25);
+}
+
+/* Override logo for dark scheme */
+[data-md-color-scheme="slate"] .md-header__button.md-logo img {
+  content: url(https://raw.githubusercontent.com/CrackingShells/.github/main/resources/images/hatch_wide_dark_bg_transparent.png);
+}
+
+/* Explicit link/nav/toc overrides — variables alone lose to Material's slate defaults */
+
+/* Body content links */
+[data-md-color-scheme="slate"] .md-typeset a {
+  color: #E8B84B;
+}
+[data-md-color-scheme="slate"] .md-typeset a:hover,
+[data-md-color-scheme="slate"] .md-typeset a:focus {
+  color: #F0D060;
+}
+
+/* Left sidebar nav — active, hover, focus states */
+[data-md-color-scheme="slate"] .md-nav__link:focus,
+[data-md-color-scheme="slate"] .md-nav__link:hover,
+[data-md-color-scheme="slate"] .md-nav__link--active,
+[data-md-color-scheme="slate"] .md-nav__item--active > .md-nav__link {
+  color: #E8B84B;
+}
+
+/* Right TOC — active / focused section */
+[data-md-color-scheme="slate"] .md-nav--secondary .md-nav__link:focus,
+[data-md-color-scheme="slate"] .md-nav--secondary .md-nav__link:hover,
+[data-md-color-scheme="slate"] .md-nav--secondary .md-nav__link--active {
+  color: #E8B84B;
+}
+
+/* Top navigation tabs — inactive, active, hover */
+[data-md-color-scheme="slate"] .md-tabs__link {
+  color: rgba(240, 232, 200, 0.65);
+  opacity: 1;
+}
+[data-md-color-scheme="slate"] .md-tabs__link--active,
+[data-md-color-scheme="slate"] .md-tabs__link:hover {
+  color: #F0D060;
+  opacity: 1;
+}
+
+
+/* ── Shared tweaks ─────────────────────────────────────────── */
+
+/* Slightly reduce logo height in the header so it sits comfortably */
+.md-header__button.md-logo img {
+  height: 1.8rem;
+  width: auto;
+}
+
+/* Admonition title bars — use brand green for note, amber for warning/tip */
+[data-md-color-scheme="egg-shell"] .admonition.note > .admonition-title,
+[data-md-color-scheme="egg-shell"] .admonition.info > .admonition-title {
+  background-color: rgba(61, 81, 72, 0.18);
+}
+[data-md-color-scheme="egg-shell"] .admonition.warning > .admonition-title,
+[data-md-color-scheme="egg-shell"] .admonition.tip > .admonition-title {
+  background-color: rgba(212, 149, 42, 0.2);
+}
+[data-md-color-scheme="slate"] .admonition.note > .admonition-title,
+[data-md-color-scheme="slate"] .admonition.info > .admonition-title {
+  background-color: rgba(61, 81, 72, 0.45);
+}
+[data-md-color-scheme="slate"] .admonition.warning > .admonition-title,
+[data-md-color-scheme="slate"] .admonition.tip > .admonition-title {
+  background-color: rgba(232, 184, 75, 0.22);
+}
diff --git a/mkdocs.yml b/mkdocs.yml
index 1a044b2..b5752f4 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -7,8 +7,28 @@ docs_dir: docs
 
 theme:
   name: material
+  custom_dir: overrides
+  logo: https://raw.githubusercontent.com/CrackingShells/.github/main/resources/images/hatch_wide_light_bg_transparent.png
+  favicon: https://raw.githubusercontent.com/CrackingShells/.github/main/resources/images/hatch_icon_light_bg_transparent.png
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: egg-shell
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
   features:
     - content.code.copy
+    - navigation.tabs
+    - navigation.top
+    - toc.follow
+
+extra_css:
+  - stylesheets/brand.css
 
 plugins:
   - search
@@ -31,6 +51,13 @@ markdown_extensions:
   - admonition
   - tables
   - fenced_code
+  - attr_list
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+  - pymdownx.inlinehilite
   - toc:
       permalink: true
 
diff --git a/overrides/main.html b/overrides/main.html
new file mode 100644
index 0000000..47cd516
--- /dev/null
+++ b/overrides/main.html
@@ -0,0 +1,31 @@
+{% extends "base.html" %}
+
+{% block scripts %}
+  {{ super() }}
+  <script>
+    /* Swap the header logo src whenever the color scheme changes. */
+    (function () {
+      var LOGOS = {
+        "egg-shell":   "https://raw.githubusercontent.com/CrackingShells/.github/main/resources/images/hatch_wide_light_bg_transparent.png",
+        "slate":        "https://raw.githubusercontent.com/CrackingShells/.github/main/resources/images/hatch_wide_dark_bg_transparent.png"
+      };
+
+      function applyLogo() {
+        var scheme = document.body.getAttribute("data-md-color-scheme") || "egg-shell";
+        var src = LOGOS[scheme] || LOGOS["egg-shell"];
+        var imgs = document.querySelectorAll(".md-header__button.md-logo img");
+        imgs.forEach(function (img) { if (img.src !== src) img.src = src; });
+      }
+
+      /* Run on load */
+      document.addEventListener("DOMContentLoaded", applyLogo);
+
+      /* Watch for scheme attribute changes (theme toggle click) */
+      var observer = new MutationObserver(applyLogo);
+      observer.observe(document.body, {
+        attributes: true,
+        attributeFilter: ["data-md-color-scheme"]
+      });
+    })();
+  </script>
+{% endblock %}