fix(cli): make the documented invocation the real one; regenerate CLI reference; release 0.6.0

[imran-siddique]

Stacked on #237. Merge that one first; this branch contains its two commits and the diff collapses once it lands.

The bug

Every CLI command was attached to a redundant second manifest group. The real invocation was:

manifest manifest verify signed.json

while the README, the docs site, the PyPI long description, and cli.py's own module docstring all printed:

manifest verify signed.json

Anyone following the published quickstart hit Error: No such command 'keygen' on step one. tests/test_cli.py invoked the nested form, which is why CI stayed green over a CLI nobody could drive as documented.

What changed

Commands are top level, as documented. The nested spelling still resolves, is hidden from --help, and prints a deprecation warning (removal in 1.0), so any script written against 0.5.0 keeps working. test_documented_commands_are_top_level and test_deprecated_nested_invocation_still_works pin both halves.

The CLI reference is generated, not written. docs/api-reference/cli.md had drifted into fiction: it documented keygen --out/--print-pub, verify --revocation-url/--min-slsa-level, create --agent-id/--issuer/--model/--ttl-hours, and revoke --crl-file/--key-file, none of which exist, while omitting the options that do. It now renders from click's own help via scripts/gen_cli_reference.py, following the same committed-generated-file pattern as tests/vectors. test_cli_reference.py fails if the committed page drifts from the code.

Help output is readable. \b markers stop click rewrapping the example blocks onto a single line, and -o/--output, --enforce-hitl, --enforce-attestation have help text instead of appearing bare.

Two more examples that could not have worked. docs/operations/key-rotation.md used the non-existent manifest keygen --out ... --print-pub. docs/index.md and python/README.md printed manifest verify without --public-key next to a # VALID comment, but with no trusted key the verifier fails closed as UNVERIFIABLE and exits 1.

Release

Version bumped to 0.6.0. Minor rather than patch: the crypto-profile check from #237 can turn a previously VALID manifest into MISMATCH (a post-quantum profile carrying a classical-only signature), and the command surface moved.

Publishing is tag-driven (python-v* -> OIDC trusted publish), so after merge: git tag python-v0.6.0 && git push origin python-v0.6.0.

Verification

Not argued from reading the code. The documented quickstart was run verbatim against a clean venv with the built 0.6.0 wheel installed from dist/:

manifest --version                  -> manifest, version 0.6.0
manifest keygen -d ./keys/          -> Generated key pair in keys/
manifest create config.json -o draft.json
manifest sign draft.json --key keys/private.hex -o signed.json
manifest verify signed.json --public-key keys/public.hex   -> "result": "VALID", exit 0

manifest revoke, manifest attest, and manifest keygen -d keys/new/ were run the same way.

• pytest: 617 passed, 18 skipped; coverage 84.55% (gate 80%)
• mypy src/agent_manifest: clean, 20 files
• ruff check src/ tests/ --select E,F,W --ignore E501: clean
• bandit: 0 findings
• python -m build + twine check dist/*: both artifacts PASSED