refactor(cli-schema): derive the flag tail of usage synopses

[thymikee]

Summary

A --help synopsis restated the options its command already declared. #2421 made the flag declaration own the option; this removes the last copy.

A synopsis is now grammar plus a generated [label] tail, and the two rendering rules sit on the declaration: the tail names an option with its declared usageLabel, alias included — the token Command flags: already shows; and usageHidden: true keeps a cross-cutting opt-in out of every synopsis (--record today, still documented under Command flags:).

usageFlags is the one addition a command may state: the options its synopsis names, defaulting to allowedFlags, [] when the synopsis is pure grammar or writes its own mutually-exclusive brackets. So adding an option updates --help on its own unless that command said its synopsis stays short — the curation is now a declaration instead of an unstated property of a prose string.

$ agent-device snapshot --help
Usage:
  agent-device snapshot [--diff] [-i] [--depth, -d <depth>] [--scope, -s <scope>] [--raw] [--actions] [--force-full] [--timeout <ms>]

snapshot and proxy drop their usageOverride; five more drop only the flag brackets. is loses [--record]; the other 67 synopses are byte-identical, verified by generating all of them before and after. commands.md moves to the generated line and its byte-for-byte doc test stays green. 27 files. Closes #2444.

Validation

pnpm check:affected --run green on 7240ef1db9 (format, lint, typecheck, layering, fallow, build, related Vitest, command-docs, agent-guidance); check:fallow --base origin/main clean. Replay, web-smoke and device lanes stay GitHub-authoritative: only synopsis strings changed.

Guards verified by planting: a forgotten usageFlags: [] renders [--settle] [--settle] and fails; a tail naming an unaccepted option fails; an added option reaches snapshot and prepare with no override edit; a terse synopsis keeps it in Command flags: only.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-10 14:32 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	4.53 MB	4.53 MB	+100 B
Package (unpacked)	4.53 MB	4.53 MB	+100 B
Package (download)	1.34 MB	1.34 MB	-57 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.5 ms	28.1 ms	+0.6 ms
CLI --help	75.9 ms	76.4 ms	+0.5 ms

[thymikee]

Rebased onto main (805ffb4690) and simplified the design in 7240ef1db9. No review comments had landed, so this is self-inflicted.

The first shape added deriveUsageFlagTail and kept the 19 hand-written synopses that show only some options honest through a guard table listing ~90 flag keys per command. That table was itself a restatement of the option lists — the thing this change exists to delete — and it reconstructed per-command facts inside a test.

The new shape states them where the parser and help already read them: usageFlags (default allowedFlags) is the option set a synopsis names, so the tail is always generated and the ~23 commands that keep a terse synopsis say usageFlags: [] at their own descriptor. Removed: deriveUsageFlagTail, the waiver table, and the prose-matching that had to guess whether a synopsis "mentioned" a flag. Two guards remain, both structural: a tail may not name an option outside allowedFlags, and a generated tail may not repeat a bracket the grammar already wrote. Diff is 224 added lines against 492.

Behaviour is unchanged from the previous head: all 69 synopses regenerate byte-identically, still only snapshot and is moving.

[thymikee]

No code findings at 7240ef1. The shared renderer derives the flag tail, keeps intentional short forms explicit, and preserves the documented help output apart from the declared alias and record changes. Current checks are green; package growth is 100 B.