Tracing what a brand-new user actually experiences.

1. The global --json help text is a 380-char paragraph about one noun

src/commands/mod.rs:30-35 documents requirement-specific internals (“applicability list”, “seed”, “matrix”, the {"ok":true, …} envelope) on a global flag. Because it is global = true, clap reprints it verbatim on every subcommand help screen.

On anvil update --help the --json text is longer than the rest of the help combined — and update ignores --json entirely (#32). It is also the first thing a new user sees, since bare anvil prints full help.

It is wrong in both directions: it implies JSON is a requirement-only feature, when label, board, milestone, issue, pr, ci, agent, repo, branch, commit, epic all honor it — and release, deploy, registry, ssh-key, auth, update honor it nowhere.

2. anvil auth status always exits 0

auth.rs:299-316 returns Ok(()) in both branches, so there is no scriptable way to test whether the CLI is authenticated. It also ignores --json.

3. anvil repo set-default is undiscoverable

It is the setup step that makes ~120 subcommands work outside a git checkout, and it is mentioned in no top-level help, in no error message, and not in the auth login success output. It is only findable by reading the fifth entry of anvil repo --help. Compare runner configure, which does tell you what to run next (runner.rs:515).

4. Two env vars silently override the config file and are documented nowhere in help

ANVIL_SERVER_URL and ANVIL_TOKEN take precedence over config.json (config.rs:42-51). A stale exported ANVIL_TOKEN makes auth login appear to succeed and then every command 401s, while auth status reports the env token as if it were the saved one. (ANVIL_RUNNER_TOKEN at least appears in runner configure --help.)

5. Bare anvil prints help to stderr with exit 2

Reasonable for a usage error, but it means anvil | less shows nothing.

6. Nothing in the onboarding path mentions anvil ssh-key add

Without a key, anvil repo clone (SSH-only, repo.rs:242-266) cannot work.

Also: doc-comment accuracy

• src/output.rs:4-5 says JSON mode is “Set once at program start by main.rs” — main.rs never touches it; commands::run does (mod.rs:87).
• src/commands/requirement.rs:155 hardcodes “204 requirements across 16 domains” in help; the seed creates 16 domain parents + 204 children and will drift on any edit.
• src/commands/requirement.rs:241-243 leaks (#257) and Hits GET /api/v1/<org>/standards/strict into user-facing --help.
• src/commands/requirement.rs:1111 returns the user-facing error --parent-id is not supported for standards in Phase 2 — “Phase 2” means nothing to a user and suggests no alternative.

Found during a CLI-wide consistency audit.