docs: overhaul Handler documentation

README.md

@@ -4,75 +4,78 @@
 [![A2A Protocol](https://img.shields.io/badge/A2A_Protocol-v0.3.0-blue)](https://a2a-protocol.org/latest/)
 [![PyPI version](https://img.shields.io/pypi/v/a2a-handler)](https://pypi.org/project/a2a-handler/)
 [![PyPI - Status](https://img.shields.io/pypi/status/a2a-handler)](https://pypi.org/project/a2a-handler/)
-[![PyPI monthly downloads](https://img.shields.io/pypi/dm/a2a-handler)](https://pypi.org/project/a2a-handler/)
 [![Pepy total downloads](https://img.shields.io/pepy/dt/a2a-handler?label=total%20downloads)](https://pepy.tech/projects/a2a-handler)
 [![GitHub stars](https://img.shields.io/github/stars/alDuncanson/handler)](https://github.com/alDuncanson/handler/stargazers)
 
-![Handler TUI](https://github.com/alDuncanson/Handler/blob/main/assets/handler-tui.png?raw=true)
+Handler is an open-source [A2A protocol](https://github.com/a2aproject/A2A)
+client for software engineers building, testing, and operating agentic systems.
+It provides an interactive TUI, a scriptable CLI with structured output, and an
+MCP server that lets other agents integrate with A2A services directly. Handler
+also supports global and repo-scoped A2A server configuration with bearer,
+API key, mTLS, and OAuth2 client credentials auth.
 
-Handler is an open-source [A2A protocol](https://github.com/a2aproject/A2A) client for your terminal.
-
-Use the TUI or CLI to send messages, manage tasks, and inspect agent cards.
-An included MCP server lets your AI assistant talk to A2A agents too.
+![Handler TUI connected to the built-in Handler Agent, showing the agent card and a completed assistant response](https://raw.githubusercontent.com/alDuncanson/Handler/73915875903b60dad6e4e404aa7ed91b6d94559f/assets/tui.png)
 
 ## Install
 
+Install Handler from the [PyPI package](https://pypi.org/project/a2a-handler/) as a `uv` tool:
+
 ```bash
 uv tool install a2a-handler
 ```
 
-Or with [pipx](https://pipx.pypa.io/) / pip:
+Or with [pipx](https://pipx.pypa.io/):
 
 ```bash
-pipx install a2a-handler   # or: pip install a2a-handler
+pipx install a2a-handler
 ```
 
-## Quick Start
+Or with pip:
 
 ```bash
-handler tui                              # launch the interactive TUI
-handler message send URL "hello"         # send a message from the CLI
-handler card get URL                     # fetch an agent card
-handler mcp                              # start the MCP server
-handler server run agent                 # run the bundled embedded agent
-handler docs                             # open the hosted documentation
-handler update                           # upgrade Handler to the latest release
+pip install a2a-handler
 ```
 
-## Run Without Installing
+## Quick Start
+
+Open the interactive terminal UI:
 
 ```bash
-uvx --from a2a-handler handler           # or: pipx run a2a-handler
+handler tui
 ```
 
-## Servers
+Inspect an A2A server's agent card:
+
+```bash
+handler card get --url http://localhost:8000
+```
 
-Handler supports named servers in `$XDG_CONFIG_HOME/handler/servers.toml`
-(global) and `.handler/servers.toml` (repo-local).
+Send a message from the CLI:
 
-```toml
-version = 1
+```bash
+handler message send --url URL --text "hello"
+```
 
-[servers.local]
-url = "http://localhost:8000"
+Open the full documentation:
 
-[servers.local.auth]
-type = "bearer"
-env = "HANDLER_LOCAL_TOKEN"
+```bash
+handler docs
 ```
 
-See [docs/](docs) for the full auth reference covering bearer, API key, mTLS,
-and OAuth2.
+## Run Without Installing
+
+Run Handler with `uvx`:
 
-## Development
+```bash
+uvx --from a2a-handler handler
+```
 
-A [hermetic](https://zero-to-nix.com/concepts/hermeticity/) dev environment
-is available via [Nix](https://zero-to-nix.com/concepts/nix/):
+Run Handler with `pipx`:
 
 ```bash
-nix develop
+pipx run a2a-handler
 ```
 
-The Mintlify docs source lives in `docs/`.
+## Documentation
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Read the documentation at <https://handler.alduncanson.com>.

docs/docs.json

@@ -23,29 +23,47 @@
   "navigation": {
     "tabs": [
       {
-        "tab": "Docs",
+        "tab": "Get started",
         "groups": [
           {
             "group": "Getting started",
             "pages": [
               "index",
               "quickstart"
             ]
-          },
+          }
+        ]
+      },
+      {
+        "tab": "Guides",
+        "groups": [
           {
-            "group": "Workflows",
+            "group": "Core workflows",
             "pages": [
               "guides/tui",
               "guides/messages-tasks",
+              "guides/servers",
+              "guides/authentication"
+            ]
+          },
+          {
+            "group": "Agent and MCP workflows",
+            "pages": [
               "guides/mcp",
+              "guides/agent-docs-mcp",
+              "guides/enterprise-a2a",
               "guides/local-servers"
             ]
-          },
+          }
+        ]
+      },
+      {
+        "tab": "Reference",
+        "groups": [
           {
-            "group": "Configuration",
+            "group": "CLI",
             "pages": [
-              "guides/servers",
-              "guides/authentication"
+              "reference/cli"
             ]
           }
         ]

docs/guides/agent-docs-mcp.mdx

@@ -0,0 +1,78 @@
+---
+title: "Documentation MCP"
+description: "Use Handler's hosted documentation MCP server so agents can discover Handler commands and structured CLI workflows."
+---
+
+# Give agents current Handler docs
+
+Handler's documentation is available through a hosted MCP server at:
+
+```text
+https://handler.alduncanson.com/mcp
+```
+
+Connect an agent to this MCP endpoint when you want it to use Handler reliably
+instead of guessing command names or output shapes from model memory.
+
+## When this is useful
+
+- an AI coding assistant needs to call A2A agents from a shell
+- an internal agent should generate `handler --output json ...` commands
+- a workflow needs up-to-date examples for sessions, tasks, and server configuration
+- you want agents to discover Handler docs through MCP rather than a web browser
+
+## Recommended agent instruction
+
+Give the agent a short, operational instruction like this:
+
+```text
+Use Handler to send A2A protocol messages, inspect agent cards, and manage A2A
+tasks. Prefer structured output with `handler --output json` or
+`handler --output ndjson` when another program or agent will consume the result.
+```
+
+## Agent-friendly CLI pattern
+
+For single responses, prefer JSON:
+
+```bash
+handler --output json message send \
+  --server production-agent \
+  --text "Summarize the current task state"
+```
+
+For streaming responses, prefer newline-delimited JSON:
+
+```bash
+handler --output ndjson message stream \
+  --server production-agent \
+  --text "Run the long workflow and stream progress"
+```
+
+## Discover commands programmatically
+
+Handler also exposes its own CLI shape for agents and automation:
+
+```bash
+handler --output json schema
+```
+
+```bash
+handler --output json describe message send
+```
+
+```bash
+handler --output json describe task get
+```
+
+Use these commands when an agent needs to construct invocations dynamically.
+They are also useful for validating wrapper tools, command palettes, and
+generated documentation.
+
+## Built-in local agent behavior
+
+The bundled local agent uses the same hosted docs MCP endpoint by default:
+
+```bash
+handler server run agent
+```

docs/guides/authentication.mdx

@@ -3,9 +3,9 @@ title: "Authentication"
 description: "Configure bearer, API key, mTLS, and OAuth2 client credentials authentication for Handler servers."
 ---
 
-# Authentication
+# Configure server authentication
 
-Handler supports four auth types for named servers:
+Handler supports four auth types for configured servers:
 
 - bearer tokens
 - API keys
@@ -98,7 +98,7 @@ key = "/path/to/client.key"
 ca_cert = "/path/to/ca.crt"
 ```
 
-Handler checks that the certificate and key files exist before use, and it also
+Handler checks that the certificate and key files exist before use, and
 verifies private key permissions.
 
 ## OAuth2 client credentials

docs/guides/enterprise-a2a.mdx

@@ -0,0 +1,109 @@
+---
+title: "Enterprise A2A setup"
+description: "Configure Handler for OAuth-authenticated, gateway-fronted, and team-shared A2A services."
+---
+
+# Connect to production A2A services
+
+Handler is designed to work with production A2A services, including agents
+behind API gateways, OAuth2 token endpoints, private clusters, and internal
+developer platforms.
+
+## Recommended production pattern
+
+Use repo-scoped server configuration for shared server shape and
+environment variables for secrets:
+
+```toml
+version = 1
+
+[servers.apigee-gke-agent]
+url = "https://agents.example.com/a2a/my-agent"
+
+[servers.apigee-gke-agent.auth]
+type = "oauth2"
+token_url = "https://login.example.com/oauth2/token"
+client_id_env = "HANDLER_APIGEE_CLIENT_ID"
+client_secret_env = "HANDLER_APIGEE_CLIENT_SECRET"
+scopes = ["a2a.invoke"]
+```
+
+Commit `.handler/servers.toml` if the URL and auth shape are safe to share.
+Keep client IDs, client secrets, bearer tokens, API keys, and certificate paths
+in each developer or CI environment.
+
+## Validate before sending traffic
+
+Validate server configuration and auth references first:
+
+```bash
+handler server validate
+```
+
+```bash
+handler card validate --server apigee-gke-agent
+```
+
+```bash
+handler card get --server apigee-gke-agent
+```
+
+This catches invalid TOML, missing environment variables, auth file problems,
+and agent-card issues before you debug task execution.
+
+## Use structured output in automation
+
+Human-readable text is best in a terminal. JSON is better for CI, scripts, and
+other agents:
+
+```bash
+handler --output json message send \
+  --server apigee-gke-agent \
+  --text "Run the readiness check"
+```
+
+For long-running tasks, stream newline-delimited JSON:
+
+```bash
+handler --output ndjson message stream \
+  --server apigee-gke-agent \
+  --text "Execute the deployment analysis"
+```
+
+## Tune network timeouts for gateway-fronted services
+
+Long-running A2A tasks may sit behind proxies, service meshes, or load
+balancers. Handler exposes timeout controls as global flags and environment
+variables:
+
+```bash
+handler \
+  --connect-timeout 120 \
+  --read-timeout 120 \
+  --write-timeout 120 \
+  --pool-timeout 120 \
+  --stream-read-timeout none \
+  message stream --server apigee-gke-agent --text "Run the workflow"
+```
+
+The streaming read timeout defaults to `none` so idle gaps between server-sent
+events do not abort long tasks.
+
+## Production-readiness checklist
+
+- Use configured servers instead of hard-coded URLs in scripts.
+- Store secrets in environment variables, not TOML files.
+- Prefer OAuth2 client credentials, bearer tokens, API keys, or mTLS according
+  to your gateway policy.
+- Validate agent cards and server configuration during onboarding and CI checks.
+- Use `--output json` or `--output ndjson` when another system consumes results.
+- Use `handler task resubscribe` for recoverable streaming interruptions.
+- Run the local webhook receiver before integrating push notifications with a
+  real webhook consumer.
+
+## Current gaps to plan around
+
+Handler is production-ready as a terminal and MCP client, but it intentionally
+does not replace enterprise platform controls. Plan to provide external secret
+management, audit logging, network policy, and centralized distribution through
+your existing infrastructure.