feat(cli): add --json output for agent readers

[Jamie-BitFlight]

Stacked on #312. The base is claude/pr-289-rebase-conflicts-xuyr0w, so the diff shows only this change (14 commits). Retarget to main after #312 merges.

What this adds

An additive --json option on the commands agents run. With --json, stdout is exactly one line of compact JSON built from frozen Pydantic models (responses.py, Rich-free), diagnostics go to stderr, and no Rich-rendered output reaches either stream.

• Commands: check (including --tokens-only), rules, rule, the six docs commands, and --version at the root. The flag is per command. A root --json is valid only with --version.
• Exit codes: results (0 or 1) are JSON on stdout. Usage errors (2) are plain text on stderr with empty stdout. Under --json, check with no paths or a bad path no longer prints help to stdout and exits 2.
• check JSON carries an omitted block (passed_files, passed_validators, info_issues, retrieve_with) that names the flags restoring what was left out.
• docs sections, docs section and docs verify report file_exists, so a missing file differs from an empty one.
• --record keeps working. With --json the file is written first, then the JSON carries record_path (absolute, resolved). A failed write exits 2 with nothing on stdout.
• A non-UTF-8 path prints as ? under --json, the same way the text path shows it.
• Rich is declared as an explicit runtime dependency (rich>=15.0.0). The built wheel imports it in cli_docs, output, plugin_validator, record_export and reporting.

What does not change

Without --json, stdout, stderr and exit codes stay byte-identical to the base (2edc05d), apart from two differences accepted up front:

• --help screens gain one --json option line.
• A mistyped option such as check --jsn now ends with (Possible options: --json). This is Click's suggestion for the new option, and a test pins it.

action.yml, .pre-commit-hooks.yaml and other callers are not edited, because nothing in the repository passes --json. --no-color, --show-summary and the reporters are untouched.

Evidence

Test-first. f97babe adds 266 golden outputs (106 cases, captured from the real executable in nine environment profiles), a test that replays them, 125 strict-xfail --json probes, and a parity test between the text and JSON visibility rules. The goldens are unchanged since that commit. Each later commit removes the xfail markers it satisfies.

Reported by the implementing agent, run on Linux in a worktree:

• uv run prek run --all-files passes.
• uv run pytest: 2,450 passed, 14 skipped.
• A built wheel has Requires-Dist: rich>=15.0.0 and scripts/assert_installed_artifact.py --wheel exits 0.

An independent review ran the base and this branch side by side over about 30 default-path invocations. It found no stdout or exit-code difference. It found the mistyped-option suggestion above and the non-UTF-8 crash, which are fixed in 0fb71c0 and a5fbaff.

I ran --version --json, check <invalid SKILL.md> --json and check --json by hand. They gave one JSON line, the failed validator with its issues and an omitted block, and exit 2, as expected.

Not verified

• No GitHub workflow has run on this branch yet.
• The sdist, macOS and Windows are untested. The non-UTF-8 test needs a file system that accepts such names.
• check --json is not measured on the 1,000-skill fixture.
• docs verify <directory> --json still ends in an IsADirectoryError traceback, exit 1, which is the existing behaviour tracked in docs sections crashes with a traceback when given a directory #315.

Known follow-ups, not in this PR

• Pre-existing defects --record raises a traceback for an unsupported extension or an unwritable target #314 to The "clean" benchmark fixture fails validation on all 1000 files #318 are untouched.
• Reviewer notes left open: responses.py (730 lines) could split by command family, the probe harness has no subprocess timeout, and _run_validation_command returns a three-way union.
• A second PR is planned to default the scripts/ maintenance tools to compact JSON.

🤖 Generated with Claude Code

https://claude.ai/code/session_01K5rAHJfvZyEEaUQghV7hCQ

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 7eccd29f-375c-49b8-bda8-4770fb06a540

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Jamie-BitFlight]

Applied the follow-up review improvements on this branch:

• --show-progress --json now exposes passed validator records instead of reporting an omitted count with no restoring flag.
• JSON serialization now preserves POSIX surrogateescape path identity via JSON escapes; distinct non-UTF-8 filenames no longer collapse to the same ? path.
• Added a collision/round-trip regression test for distinct non-UTF-8 paths.
• docs sections|section|verify <directory> --json now classifies the directory as a usage error (exit 2, stderr, empty stdout) instead of leaking an IsADirectoryError traceback.

I am not merging this PR yet. Its head is still not mergeable with current main, and GitHub has not produced fresh workflow runs for the amended head. Current main has also moved through #321/#322/#323/#329, including overlapping changes in plugin_validator.py, test_cli.py, pyproject.toml, and uv.lock. Those need a real reconciliation/rebase rather than forcing the stale 310-file branch over current architecture.

[Jamie-BitFlight]

Superseded by #330, rebuilt from current main with the reviewed JSON-contract fixes and without the stale stacked/baseline history. Closing this PR so review and CI continue on the clean replacement.