[alDuncanson]

Summary

Brings the docs site, README, and two in-code docstrings up to date with everything that landed after v0.2.0 (#98, #111–#118, #120) and with the seven fix branches queued for 0.3.0 (fix/attachments-dropped, fix/credentials-scoped-to-origin, fix/push-config-get-without-id, fix/push-receiver-v1-payloads, fix/protocol-version-mixed-cards, fix/tui-streaming-widget-collision, chore/widen-uv-build-pin). Every flag and TOML key was checked against handler <cmd> --help and the branch diffs; nothing is documented that the code does not do.

Docs-only apart from two docstrings. No behaviour changes.

What changed

docs/guides/messages-tasks.mdx (largest change)

• New sections: send files and structured data (--file local inline / URL by reference, 10 MiB inline limit, --data, text optional, how received parts render, integers in data parts), shape the request (--accept, --history-length, --no-wait), request A2A extensions (-e/--extension, required-extension warning), list an agent's tasks (task list, --status labels with hyphen tolerance, 100-task page cap, truncation reporting).
• Card section covers card get --extended and how it fails when not offered.
• Streaming section explains transport negotiation (JSON-RPC, HTTP+JSON, gRPC via the extra) and the no-common-binding error.
• Push notifications cover message send --push-url/--push-token, notification get without --config-id (single-config lookup), notification list, notification remove.
• Notes that warnings print by default and that --continue is how you answer input-required.

docs/guides/authentication.mdx

• Six schemes now: adds HTTP Basic (--basic-username/--basic-password-env, type = "basic") and OpenID Connect (--oidc-*, type = "oidc", issuer discovery).
• New "Where credentials go" section: credentials and custom headers are bound to the configured URL's origin, loopback aliases and default ports count as one origin, and Handler warns when a card routes elsewhere.
• Documents the per-call --bearer-env/--api-key-env overrides, the IAM identity-token pattern, the HTTPS rule for token/issuer URLs, and that server show prints only env var names.

docs/guides/servers.mdx

• Real config locations: platformdirs user config dir (macOS ~/Library/Application Support/handler, Linux $XDG_CONFIG_HOME/handler), plus .handler/servers.toml; points at server validate for the resolved path.
• New extensions = [...] key.

docs/guides/local-servers.mdx

• server run push --token, the v1.0 delivery shapes (statusUpdate/artifactUpdate/task/message) and the state field in the listing, and an end-to-end test that uses --push-url.

docs/guides/tui.mdx

• Streaming replies, STOP/cancel semantics, the input-required placeholder, ATTACH button and palette command, badges (protocol version, transport, auth), extended card on connect, all six Auth tab schemes, session resume/forget, the fuller keybinding list.

docs/guides/mcp.mdx

• The thirteen tools the server actually exposes, grouped; removes the "credential storage" area (set_agent_credentials/clear_agent_credentials no longer exist); notes per-tool auth arguments, list_tasks truncation, and get_task_notification lookup.

docs/reference/cli.mdx

• Full option lists for message send/stream, new task list, task notification list/remove sections, card get --extended, server add Basic/OIDC flags, server run push --token, logging-default note.

docs/index.mdx, docs/quickstart.mdx, docs/guides/enterprise-a2a.mdx, README.md

• Feature lists and quick examples refreshed (six auth schemes, attachments, task listing, push receiver, origin rule, gRPC extra). assets/tui.png untouched (Retake the README screenshot (shows the removed built-in agent) #109).

src/a2a_handler/cli/mcp.py

• handler mcp --help lists the real tools instead of two removed ones, and adds list_tasks, list_task_notifications, delete_task_notification.

src/a2a_handler/servers.py

• Module docstring no longer claims the global file is only at $XDG_CONFIG_HOME.

Also drafted (not in this PR): release-notes-0.3.0.md in the session scratchpad, ready to paste into the GitHub release.

Verification

• uv run ruff check ., uv run ruff format --check ., uv run ty check: clean.
• uv run pytest -q: 596 passed (this branch is off main; the fix branches add their own tests).
• Every documented flag checked against handler <cmd> --help on this branch, and --token on server run push against the fix/push-receiver-v1-payloads diff.
• A script walked docs/docs.json: all 11 nav pages exist, every page has title/description front matter, code fences are balanced, and all relative links resolve.
• Could not run a Mintlify build locally (no mint CLI in this environment); the deploy preview on this PR is the real check.

Review notes

• The Windows config path is described as "the local AppData directory" rather than a literal path, because platformdirs nests handler\handler there and I did not want to state a path I could not verify on Windows.
• Merge after the seven fix branches, since several sections describe their behaviour (--token, single-config lookup, origin-bound credentials, protocol version badge).

🤖 Generated with Claude Code

[alDuncanson]

Release notes draft for v0.3.0 (for the GitHub release once everything is merged; PR numbers for the seven fix branches are #125–#131):

# v0.3.0

The A2A v1.0 parity release. Handler now implements every protocol method on every surface it has, sends and receives non-text parts, negotiates its transport, and supports six security schemes. It also closes a credential-handling gap found while testing all of that end to end.

## Highlights

- **Streaming in the TUI** with a STOP control, input-required handling, and replies that render as they arrive (#98)
- **Files and structured data** go out with `--file` and `--data` (or the TUI's ATTACH button) and come back readable (#111)
- **Every A2A v1.0 method**: `ListTasks` (#112, #120), `ListTaskPushNotificationConfigs` and `DeleteTaskPushNotificationConfig` (#113), `GetExtendedAgentCard` (#114)
- **Transport negotiation**: JSON-RPC and HTTP+JSON built in, gRPC via `a2a-handler[grpc]`, chosen from the agent card (#116)
- **HTTP Basic and OpenID Connect** join bearer, API key, mTLS, and OAuth2 client credentials (#117)
- **Credentials stay on the origin you configured**, never on a host an agent card happens to name (fix/credentials-scoped-to-origin)

## Features

- `handler task list` with `--context-id`, `--status`, `--page-size`, `--history-length`, `--include-artifacts`; follows pagination to the end and reports truncation; MCP `list_tasks` (#112, #120)
- `handler task notification list` and `remove`; MCP `list_task_notifications` and `delete_task_notification` (#113)
- `handler card get --extended`; the TUI shows the extended card on connect; MCP `get_agent_card` takes `extended` and auth arguments (#114)
- `SendMessageConfiguration` on every send: `--accept`, `--history-length`, `--no-wait`; push config rides on the message with `--push-url`/`--push-token` (#115)
- Transport badge in the TUI, `A2AService.negotiated_transport`, a clear error when no binding is shared (#116)
- `type = "basic"` and `type = "oidc"` in `servers.toml`, `server add --basic-*` and `--oidc-*` flags, and both schemes in the TUI Auth tab (#117)
- A2A extensions: `-e/--extension`, per-server `extensions = [...]`, declared extensions on the card, and a warning when a required extension is not requested (#118)
- `handler server run push --token` rejects deliveries without the matching `X-A2A-Notification-Token` (fix/push-receiver-v1-payloads)
- Whole numbers in data parts render as integers (fix/attachments-dropped)

## Fixes

- Attachments were built but never left the client on `send` or `stream`; `--file`, `--data`, and TUI attachments now reach the agent (fix/attachments-dropped)
- The second message of a TUI session could crash the send worker with a duplicate widget id and lock the composer (fix/tui-streaming-widget-collision)
- `task notification get` without `--config-id` failed with a server-side validation error; it now uses the task's single config and names the choices when there are several (#121, fix/push-config-get-without-id)
- The push receiver read only the v0.3 payload shape, so v1.0 deliveries showed no task ID or state (fix/push-receiver-v1-payloads)
- Cards that mix a v0.3 top-level `protocolVersion` with versionless v1.0 interfaces reported "A2A vunknown"; the served JSON now answers (fix/protocol-version-mixed-cards)
- When both well-known card paths fail, the error names the standard path, not the legacy fallback (fix/protocol-version-mixed-cards)
- `task list` hardened against servers that repeat or cycle page tokens, with a 100-task page cap from the spec (#120)
- `uv_build` pin widened to current releases; deprecated license classifier dropped (#110, chore/widen-uv-build-pin)

## Security

- Auth headers, API keys, Basic credentials, and custom headers are bound to the origin (scheme, host, port) of the configured agent URL. A card that advertises a different host no longer receives them, and Handler warns when a card routes requests away from the configured origin. Loopback aliases and default ports count as one origin. (fix/credentials-scoped-to-origin)
- The CLI's default log level moves from ERROR to WARNING so the warnings above, and the required-extension warning, are visible without `-v`.
- The push receiver can require a notification token, so a receiver bound beyond loopback cannot be fed forged notifications.

## Docs

- Guides and the CLI reference cover attachments, request configuration, task listing, push notifications end to end, extended cards, transport negotiation, extensions, all six auth schemes, the origin rule, and the real configuration file locations (docs/0.3.0-features)
- `handler mcp --help` and the MCP guide list the thirteen tools the server actually exposes
- README feature list refreshed

## Upgrading

`uv tool install --force a2a-handler --refresh` (or `pipx upgrade a2a-handler`). No configuration changes are required. If you relied on an agent card redirecting authenticated requests to a different host, configure that host as the server URL instead.