fix(cli): every --json failure answers with one envelope, and --json only where supported - #6622

What

Last of four stacked PRs (base: #6621). Fixes the --json finding:

• --json was accepted by every command (it was on the global allow list), so commands without JSON output took the flag and printed prose. Now a command supports --json by declaring a json arg, and every other command rejects it with exit 2 and the code json_unsupported.
• Failures under --json came back as a bare string ({"ok":false,"error":"Command failed",...} from lint), a command-specific shape, or nothing on stdout at all (info, compositions, render, snapshot, cloud get in an empty directory). Every failure is now {"ok": false, "error": {"code", "message", "hint"?}}.
• packages/cli/AGENTS.md (new) holds the CLI rules for agents: stdout is data, stderr is messages, never prompt without a TTY, exit 2 for usage errors, --json always returns an envelope, and define commands with the shared factory.

Why

An agent passing --json parses stdout. Empty stdout, a string where other commands put an object, or prose from a command that silently ignored the flag all break that parse, and none of them say which kind of failure happened.

Related work

Stack: #6616 → #6617 → #6621 → this PR.

How

• failureMessage(error) returns an error's own message, or for the generic Command failed / Invalid command usage a presented failure carries, its cause or the title the command reported through errorBox. Every command catch that writes a --json failure uses it, so lint --json and check --json in an empty directory now say No composition found in <dir>.

• Notices (telemetry disclosure, deprecation lines, diag progress) are never captured as the error message.

• utils/jsonError.ts: jsonFailure(code, message, hint?) builds the envelope. The 25 places that printed {ok: false, error: "<text>"} now use it and keep their extra fields (lint findings and counts, validate errors, layout issues, auth status configured). Transcribe uses its own TranscribeError.code.

• cli.ts: when --json is on the command line, watchOutput() notes whether anything reached stdout (stream and console, since Bun's console bypasses process.stdout.write) and keeps the tail of stderr. If the run fails and stdout is still empty, the boundary writes the envelope: a usage error carries its own code and hint (unknown_flag, unknown_command, json_unsupported, confirmation_required, prompt_unavailable, usage_error); anything else is runtime_error with the text the command printed on stderr as the message.

• A refused timeline edit printed its JSON to stderr. It now prints the envelope to stdout, and keeps its reason and fix fields next to error.

• reject-unknown-flags.ts: json left the global allow list.

Contract change for --json consumers: error is an object, not a string. Tests that read error as a string were updated (transcribe, models, capture, check, history, skills, timeline).

Test plan

• Unit tests added/updated; contract test now checks, for every registered command, that --json plus a bad flag (where --json is supported) or bare --json (where it is not) exits 2 with an envelope on stdout; plus info --json failing in an empty directory and an unknown command under --json
• CLI unit suite passes locally (422 files); typecheck, oxlint, oxfmt --check, fallow audit, comment ratchet pass
• Manual testing performed (below)
• Documentation updated: the error envelope in docs/packages/cli.mdx, plus packages/cli/AGENTS.md
• Comments follow CONTRIBUTING.md "Comments"

Manual runs of the built CLI, CLAUDECODE=1, stdin from /dev/null:

$ hyperframes info --json </dev/null        # in a project
# exit 0, stdout is the info object with _meta, stderr empty (unchanged)

$ hyperframes info --json </dev/null        # in an empty directory
# before: exit 1, stdout empty
# after:  exit 1, stdout:
{"ok":false,"error":{"code":"runtime_error","message":"No composition found in <dir> No index.html file found. Run npx hyperframes init to create a new composition."}}

$ hyperframes rendr --json </dev/null
# after: exit 2, stdout:
{"ok":false,"error":{"code":"unknown_command","message":"Unknown command: rendr","hint":"Did you mean 'hyperframes render'?"}}

🤖 Generated with Claude Code