[tommasobolis]

Closes #1447

Merge order: merge this PR last. #1447 is split across four PRs, and this one carries Closes plus the full item table below:

• docs: ledger recount, key-header row and review wording sweep (#1447) #1495: docs and ledger
• this PR: CLI, simulator and conformance
• fix(core): non-finite reset guards and docstring sweep (#1447) #1514: core, registry and tools docstrings, plus two small fixes
• the ADK PR (branch chore/1447-adk-bridged-classes, not yet opened): the ADK bridged classes

Summary

• CLI help text: each command docstring is now user-facing help, with no #N, BG §x.y or ADR NNNN references and no RST `` markup. Before, rich markup also swallowed the extras, so donkey doctor --help printed "Needs the ```` extra"; they now render as [llm], `[local]` and so on. The citations stay in the module docstrings. The generated `cli.mdx` block changes in one line (`verify` keeps "read-only").
• donkey verify and the gateway credential: when an asset needs a live read (an MCP server or an a2a_v1 agent) and there is no gateway credential, verify now exits 2 before any read. The message names DONKEY_LLM_PROXY_CLIENT_ID/_SECRET. In jwt/bearer mode the CLI has no token provider, so the message says so and points at DONKEY_LLM_PROXY_AUTH=client-id or Publication.verify() from code. Before, each asset failed on its own and the command exited 1. A plan with nothing to read live still needs no gateway credential. The module docstring and cli.mdx are updated.
• cli/_common.py: ci_source(), document() and print_issues() move here from publish.py, so expose and verify no longer import private helpers from .publish. expose has its own _runtime test seam.
• Conformance:
  • _fixture_responder(strip_budget=True) also drops x-llm-proxy-ratelimit (_wire.RATELIMIT_HEADER), the other header the token window is read from.
  • The [local] hint now covers all of server mode: the gateway fixture, --donkey-mode server and run_conformance(mode="server").
  • The correlation scenario's remediation points at the stable donkey.current_run.run_id instead of the Provisional core.telemetry.current_correlation_id(). The example page that prints the message is updated.
• nox: langgraph-demo and openai-agents-demo also run conformance with --donkey-mode=server. Both already install [local]; both modes pass 4/4 locally.
• Simulator: the CibaScenario docstring says its shapes were captured on an A2A message/send and an MCP tools/call, not on an LLM-proxy route. The simulator.mdx note is in docs: ledger recount, key-header row and review wording sweep (#1447) #1495.
• House-keeping:
  • removed the duplicate "mcp.*" mypy override and the stale if_changed vulture entry (if_changed is now a live option of donkey publish);
  • tests/conformance/suite.py now counts four tool-binding scenarios;
  • the wheel smoke tests skip on a Python without ensurepip.

Every #1447 item

Item	Outcome	Where
CLI help text: internal refs and RST in init	fixed	this PR
vulture: stale if_changed	fixed	this PR
vulture/session.py: dead _check_approvals, _bind_tool docstring	fixed	#1514
verify validates only the control plane	fixed (exit 2)	this PR
expose --path vs positional path	waived, see below	—
expose/verify import private helpers from .publish	fixed (cli/_common.py)	this PR
Action installs donkey-kit[cli] without a constraints lock	waived, see below	—
pyproject: duplicate "mcp.*" override	fixed	this PR
§8.3: litellm[mcp] a no-op below ~1.102	fixed (it is 1.100.0, from PyPI metadata)	#1495
_fixture_responder keeps x-llm-proxy-ratelimit	fixed	this PR
CibaScenario docstring and mock docs	fixed	this PR (docstring), #1495 (simulator.mdx)
ADK Governed*: ModelPrivateAttr marker, local classes	fixed	the ADK PR (branch chore/1447-adk-bridged-classes, not yet opened)
_LOCAL_EXTRA_HINT names only the gateway fixture	fixed	this PR
--donkey-mode server run in the demo sessions	fixed	this PR
correlation remediation points at Provisional current_correlation_id()	fixed	this PR
Ledger row for llm_proxy_key_header	fixed (UNVERIFIED row)	#1495
examples/openai_agents/collector.py duplicates LangGraph's	waived, see below	—
binding.mdx step-up exception	fixed	#1495
Discovery "no cache" docstrings	fixed	#1514
Non-finite reset headers	fixed	#1514
fraction_used overflow	fixed	#1514
PublicationAssetType docstring	fixed	#1514
ConfigWarning docstring	fixed	#1514
Local ensurepip	fixed	this PR
Version one-liner (donkey --version)	fixed	#1495
Conformance docstring "three" scenarios	fixed	this PR
warm() guard wording	fixed	#1514
ARCHITECTURE.md experimental	fixed	#1495
Rejections README "Blocked on #253"	fixed	#1495
Ledger §4 count	fixed (no number; every live shape listed)	#1495
Ledger content-safety 503 wording	fixed, maintainer to confirm	#1495
ADR 0013 citations	fixed	#1514
Redundant governed=True	fixed	#1495

None of the items had already been resolved by #1460–#1475 when this work started on 7bdaf455; each was re-checked on develop before it was fixed.

Waivers

• expose --path vs a positional path: expose/preflight take the optional service ID as their positional argument (donkey expose [SERVICE]). A second optional positional for the path would make donkey expose foo ambiguous between a service and a directory. Making them match means either moving the service to --service or the path to a positional, and either way the CLI surface changes. Maintainer call: keep --path, or redesign the expose arguments?
• The Action's constraints lock: action/action.yml installs donkey-kit[cli] into the Python the user's workflow chose (3.10+). A lock would need one constraints file per Python minor version, and it would pin users to versions they did not resolve themselves, against the floors-not-ceilings dependency policy. The donkey-kit input already lets a workflow pin the package. Maintainer call: is a lock wanted despite that?
• The duplicated example collector: each example directory runs in place (python -m examples.<dir>.main). Each is type-checked as its own package (mypy -p examples.<dir>) and smoke-tested against its own extra, and main.py loads collector.py from its own directory. A shared module would couple two examples that are meant to be copied out one at a time. The files differ only in their docstring.

Test plan

• nox -s typecheck-and-lint test-3.11 new-dependencies commit-identities (passed, after rebasing on 5af7d0e7)
• nox -s docs-site docs-llms-drift (passed)
• nox -s langgraph-demo openai-agents-demo (passed; conformance 4/4 in-process and 4/4 with --donkey-mode=server for both)
• New tests:
  • test_cli_verify.py: a missing gateway credential exits 2 before any read; bearer mode names the client-id pair; a plan with nothing to read live needs no credential.
  • test_conformance.py: strip_budget drops x-llm-proxy-ratelimit.
• nox (every session): not run locally; CI runs it
• python scripts/verify_frameworks.py: n/a, no adapters or extras changed

ADR needed?

• No: this PR changes none of those.

Acceptance-harness impact

• group3_public_surface/test_cli.py::test_verify_rejects_missing_version_before_reading is unaffected: a declaration issue still exits 1 before the credential check.
• A future acceptance test that runs donkey verify against a live proxy without DONKEY_LLM_PROXY_CLIENT_ID/_SECRET will now see exit 2 and "No gateway credential", not per-asset errors and exit 1. No current test does.
• No other acceptance test matches the reworded help text, hint or remediation.

Migration note

donkey verify exits 2, not 1, when an asset needs a live read and there is no gateway credential. That includes jwt/bearer mode, where the CLI has no token. Set DONKEY_LLM_PROXY_CLIENT_ID/DONKEY_LLM_PROXY_CLIENT_SECRET, or call Publication.verify() from code with Donkey(llm_auth=...).

Post-deploy steps

None.

[tommasobolis]

Held as draft by the 0.2.0 orchestrator: this PR carries Closes #1447 and must merge last, after #1495 and the two remaining #1447 PRs. Please do not mark ready or auto-merge.