feat: one output contract for errors, pages, help and examples

[MikeChenWM]

Summary

First step of the CLI design review: phases 0–1 of its rollout plan. Every change is additive: released fields, reason values and commands keep working.

Errors

• Every failure now carries command and a stable error object: code, message, server_code, http_status, retryable, and hint for usage errors.
• The released reason and detail fields are kept alongside.
• reason is always a category. Previously it could be a Python class name such as RuntimeError.
• Usage errors are JSON on stdout. Before, argparse printed text to stderr.
• Existing exit codes are unchanged: 0, 1, 2, 130. New ones: 3 not found, 4 authentication required, 5 conflict.

Pagination

• Paged reads add a normalized page_info. It covers the three page shapes domains return today: data.{items,total,…}, data.{items,pagination}, and data.data plus a top-level pagination.
• Read commands with --page take --all. It follows every page and reports page_info.complete. Hitting its cap of 100 pages or 10,000 records produces a warning instead of silent truncation.

Discovery

• Every flag prints help. Common flags and schema descriptions fill the gaps; before, 1,738 of 1,824 flags had none.
• Every command shows a runnable example generated from its required inputs. Before, 132 commands only showed museoncli schema <self>.
• schema accepts CLI paths, e.g. museoncli schema hireaicreator video +get, and reports resource and cli.

Fix

• ai-slideshow generation +create lost its run and frontend links in CLI 2.0: async detection and URL templates still named the retired generation.* / asset.* commands.

Conventions tests

The tests now enforce:

• runnable examples, parsed with the real parser
• help on every flag
• unique and reversible capability keys and CLI paths
• summaries that only reference existing shortcuts
• no command accepting both singular and plural spellings of one input

Verification

• uv run pytest -q: 1157 passed.
• ruff, the docs and contract --checks, wheel build, verify_public_artifacts.py and smoke_install.py all passed.
• Live read-only check: hireaicreator account +list --all on a real workspace fetched 9 pages, 877 records with no duplicates, matching manual paging.
• page_info is correct for both hireaicreator and ai-slideshow page shapes.

Follow-ups (separate PRs)

• Merge the two near-identical 3,500-line account modules.
• Aliases for the naming migration (<domain> <resource> +<verb>, fixed verb set, batch/bulk).
• Per-command output schemas, async --wait, and idempotency on the remaining writes.

🤖 Generated with Claude Code