[DRB-3] Reconcile CLI docs against parser and dispatch evidence

[metaphorics]

Residue family

CLI contract drift

Affected paths

• README.md:30-32,41,52-53,57,63-65 — quickstart examples, target flag limitations, CLI/doc links, diagnostics 'error limits' link text
• docs/tutorials/quickstart.md:65 — legacy command exclusion prose
• docs/reference/cli.md:41,51-58,65,67-79 — --init behavior, mode option tables, legacy command exclusion, exit codes
• docs/reference/diagnostics.md:28 — legacy --error-limit not public
• docs/explanation/architecture.md:50 — legacy command forms and internal --api parser
• .agents/developer-audience-context.md:77 — contradictory --init claim (flag for DRB-4 owner; no edit here)
• perf/benchmarks.toml:180-185 — cli-startup-empty fixture with argv = ["check", "{fixture}"]

Source of truth

• crates/bamts-cli/src/main.rs — public bamts binary dispatches through parse_tsc_args (tsc-compatible parser); --api and --lsp select non-CLI transports
• crates/bamts-cli/src/cli/tsc_args.rs — exact supported tsc options, removed options, response files, --init, --noEmit, --project, --build, --listFiles, --listFilesOnly, --pretty, --target (rejected with TS5108/TS5047), --help, --version
• crates/bamts-cli/src/driver.rs — dispatch for Check/Compile/Run, initialize_tsc_config (--init creates tsconfig.json via create_new, returns TS5054 if exists), native compile output
• crates/bamts-cli/src/args.rs — internal bamts subcommand parser (check, compile, run, explain, --target jit/aot, --error-limit) used by the --api server and tests, not the public binary
• crates/bamts-cli/src/cli/tsc_args.rs TscExitStatus 0-5 and crates/bamts-cli/src/cli.rs for command outcome formatting

Allowed edits

• Verify docs/reference/cli.md:41 against driver.rs::initialize_tsc_config and tsc_args.rs option tables; update only if source differs after integration.
• Replace docs/reference/cli.md:51-58 mode/option tables with a source-cited list of accepted options per dispatch mode (Direct, Project, Build); remove any option the parser rejects or does not consume.
• Ensure docs/reference/cli.md:65, docs/tutorials/quickstart.md:65, docs/explanation/architecture.md:50, and README.md:53,57 consistently state that check, run, compile, explain, --target jit, and --target aot are not public bamts binary commands and identify their internal owner (--api / src/args.rs test harness / compiler/explain RPC).
• Correct README.md:65 diagnostics link text so it does not promise 'error limits' that docs/reference/diagnostics.md does not cover, or add the missing error-limit/resource-budget coverage to docs/reference/diagnostics.md.
• Verify docs/reference/cli.md:67-79 exit-code table against TscExitStatus and driver.rs exit-code paths; fix any mismatch.
• Resolve perf/benchmarks.toml:180-185 cli-startup-empty fixture: if it runs through the public bamts binary, change argv to a tsc-compatible command; if it runs through the internal --api or parse_args harness, label the fixture group or add a harness field and keep the check subcommand. Do not leave an unlabeled public check subcommand.
• Verify README.md:30-32 quickstart examples and docs/tutorials/quickstart.md against the public bamts binary after integration; update only if the parser no longer accepts them.

Forbidden guessing

• Do not infer public CLI behavior from crates/bamts-cli/src/args.rs or crates/bamts-cli/src/cli.rs tests; those are internal/test surfaces.
• Do not add public commands or options that tsc_args.rs does not parse.
• Do not rewrite tsc_args.rs, driver.rs, or main.rs to match the docs.
• Do not decide the perf adapter without a recorded decision from Set performance budgets and trade-off authority #170 / the DRB-8 dual-performance-authority sibling.

Acceptance

• docs/reference/cli.md matches the public bamts binary parser and driver dispatch for every option, mode, and exit code it lists.
• README.md, quickstart.md, and architecture.md do not contradict the public CLI contract.
• README.md:65 no longer overpromises 'error limits' coverage, or docs/reference/diagnostics.md covers it.
• perf/benchmarks.toml:180-185 has a labeled harness and an argv accepted by that harness.
• The .agents/developer-audience-context.md:77 contradiction is filed as input to DRB-4 (agent-context reachability) and not silently edited here.
• Synchronize documentation with integrated behavior #185's sync-docs pass finds no CLI contract drift.

Related future issue

The perf/benchmarks.toml argv may also require the DRB-8 dual-performance-authority boundary issue (wayfinder:grilling child of #156) if the harness is not the public CLI.

[metaphorics]

Dependencies

This issue is blocked by:

• Audit documentation rules and build surfaces #163 — Audit documentation rules and build surfaces
• Decide the published product facade #168 — Decide the published product facade
• Integrate every refactor target #179 — Integrate every refactor target
• Set performance budgets and trade-off authority #170 — Set performance budgets and trade-off authority

Parent: #156. Feeds: #185.

The perf/benchmarks.toml argv may also require the DRB-8 dual-performance-authority boundary issue (#196, wayfinder:task child of #156) if the harness is not the public CLI.