feat(help): --help becomes two tiers — one line per flag, every disclosure one call away

`ripwire --help` printed 185,540 B / ~46,000 tokens in one flat document: every flag's purpose
AND every caveat that flag has ever earned, interleaved. On a tool whose pitch is token
efficiency that was the most expensive thing it could print.

The fix is a SPLIT, not a cull. Nothing was deleted; 133 opening lines were relocated.

  --help            one plain-speech line per flag   ~4,473 tokens  (was ~46,385)
  --help=--FLAG     that flag's whole entry, every disclosure intact
  --help=SECTION    one family at full detail
  --help=all        the entire former catalog

WHAT DECIDED THE DESIGN. Not length — reachability. test/legendcostcheck.sh records that an
outside evaluation (callstack/agent-device #2400) measured ripwire spending ~10% MORE tokens
than grep-and-read, traced it to the per-call legend, and that the fix (--legend=compact) was
ALREADY documented in --help: "buried four lines into a schema description, so nobody extracted
it." That sentence sits at line 1465 of 1597. An evaluator holding the exact question did not
find the answer they were standing on. The defect was not that the text was long; it was that a
fact inside it had no address. So the flags got addresses.

Measured here first: 156 entries, median 6 lines, mean 10, max 46; the top 30 carried 53% of the
bytes and 61 opening lines did not stand alone, so a "keep line 1, drop the rest" cull would have
shipped 61 broken fragments. Every rewritten line pushes its old text down one row rather than
replacing it, so tier 2 gained the summaries (+7.4%) and lost nothing.

ALSO: a missing <dir> no longer answers with the catalog. It printed all 185 KB to stderr —
~46,000 tokens for the likeliest first-run typo — while an unknown flag cost 32 bytes. Now 362 B
that names the four things you probably meant.

MACHINE CONSUMERS READ TIER 2. 52 invocations across 41 gates plus docs/docs_commands_build.py
now call --help=all: an assertion about DOCUMENTED CONTENT must not pass or fail on where a
sentence sits. clicheck keeps arm (e) on plain --help because that arm tests what a user types.

GATE FIRST (non-negotiable #1): test/helpbudgetcheck.sh was written and observed RED before any
of this. It holds tier 1 to a 7,000-token ceiling AND asserts tier 2 still carries every row —
opposite failure modes, so fixing one by breaking the other cannot pass. Arm (I) is deliberately
narrower than its name and says so: it proves a summary is not truncated (open bracket, dangling
punctuation, over-width), not that it reads well. An earlier draft flagged five complete
sentences ending in prepositions and would have made the prose worse to satisfy the checker.

RE-PINS, both legitimate and both checked before re-pinning:
- test/printffmtparitycheck.sh: the red set was confirmed to be exactly {help} (11 PASS, 1 FAIL,
  d9b77634 -> f066b2b8) before UPDATE_GOLDEN. The corpus gains `help_all` and `help_one` so both
  tiers and one addressed entry are fenced; pinning only one would let the other move silently.
- docs/COMMANDS.md regenerated from a --clean-first build, never hand-edited.

Gate count 570 -> 571 across its seven spellings.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: joyful-ii-V-I

README.md

@@ -791,6 +791,8 @@ Full retrieval tables — including the MRR figures behind the router numbers ab
 
 Around the core sit 179 long flags advertised in `--help`, across seven families — plus an MCP
 server, so a coding agent can call any of them mid-task instead of grepping and reading whole files.
+`--help` prints one line per flag (~4.5K tokens); `--help=--FLAG` prints that flag's full entry with
+every caveat, `--help=SECTION` one family, and `--help=all` the whole catalog.
 Not sure which of them fits the task in front of you? `ripwire . --help-task="<task in words>"`
 recommends ONE executable command with the evidence behind the pick — advice only, it never runs
 the recommendation — and abstains honestly when the evidence is too thin to name a winner.
@@ -1818,9 +1820,9 @@ wrong, and it has. These are the results that say so, all in-tree, all published
 ### In the tests
 
 <details>
-<summary><b>570 gate scripts</b>, five contracts no unit test can hold, and the house rule: write the gate before the code it measures</summary>
+<summary><b>571 gate scripts</b>, five contracts no unit test can hold, and the house rule: write the gate before the code it measures</summary>
 
-`test/regression.sh` names **570 gate scripts** and is the authoritative list;
+`test/regression.sh` names **571 gate scripts** and is the authoritative list;
 `python3 test/pargates.py . ./build/ripwire -j 6` runs the same set in parallel. On top of them sit the
 contracts that do not fit a unit test: two runs byte-identical, warm output identical to cold, output
 that pipes clean through `xmllint --noout`, a sanitizer build with `-fno-sanitize-recover=all`, and a

docs/COMMANDS.md

@@ -21,7 +21,7 @@ section, and it is not an afterthought.
 | **Co-change / known-item evals** | `--eval`, `--eval-retrieval` (see `bench/ANSWERQUALITY.md`) | Whether the tool surfaces the other files a real historical commit touched; and known-item retrieval across four rankers. |
 | **Ensemble calibration harness** | `bench/ensemblecal/` | Whether `--ensemble`'s four evidence families are actually orthogonal, how often each fires, how stable each is across commits — and the preset ladder derived from that (§9). |
 | **Differential argv harness** | `test/argvdiffcheck.sh` | That a refactor changed *nothing observable*: two binaries, every argv vector, stdout + stderr + exit code byte-identical. |
-| **The gate suite** | `test/regression.sh`, `test/pargates.py` | 570 gate scripts plus the determinism, cache-transparency and golden contracts. |
+| **The gate suite** | `test/regression.sh`, `test/pargates.py` | 571 gate scripts plus the determinism, cache-transparency and golden contracts. |
 | **`--quality-delta`** | `src/quality.h` | Ten measured code-quality failure modes, reported only where a change made them worse. |
 
 ### The labeling protocol (why the held-out eval is allowed to disagree with the ranker)
@@ -5579,7 +5579,7 @@ copy here would be exactly the dialect divergence that gate exists to catch. Com
 tags, wrap, stable-order defaults), seven individually invoked standalone gates (`g1freshcheck`,
 `skillscan`, `htmlexport`, `compresscheck`, `handoffcheck`, `releaseinstallcheck`,
 `taskroutecheck`), and a single loop
-naming **570 gate scripts**, all of which exist on disk.
+naming **571 gate scripts**, all of which exist on disk.
 
 `python3 test/pargates.py . ./build/ripwire -j 6` runs the same scripts in parallel so a full
 verification fits in one sitting. It does not modify `regression.sh`.
@@ -6491,7 +6491,7 @@ Listed because the reason is more useful than the silence.
   shipped**. See `bench/locbench/anchorhop_calib.json`. The mention anchor's reproducible numbers are
   the ablations in §4.
 - **A single round gate-count.** Two in-tree numbers disagree (`test/pargates.py`'s docstring says
-  ~210; `test/argvdiffcheck.sh` says 200+), while the loop in `test/regression.sh` names 570. The
+  ~210; `test/argvdiffcheck.sh` says 200+), while the loop in `test/regression.sh` names 571. The
   loop is the authority; the stale docstrings are a known drift. `test/manifestcheck.sh` asserts this
   very number against the loop's actual length, so it cannot go stale silently again.
 - **"282 argv vectors."** The gate asserts a floor of ≥250 assembled from five sources; 282 was a

docs/EVALS.md

@@ -162,7 +162,7 @@ def tool_name_of( binPath ):
 
 def help_text_of( binPath ):
     try:
-        run = subprocess.run( [ binPath, '--help' ], capture_output = True, text = True, timeout = 120 )
+        run = subprocess.run( [ binPath, '--help=all' ], capture_output = True, text = True, timeout = 120 )
     except OSError as exc:
         sys.exit( 'docs_commands_build: cannot run %s (%s)' % ( binPath, exc ) )
     if run.returncode != 0 and not run.stdout:

docs/docs_commands_build.py

@@ -708,7 +708,7 @@ function row(s, y, h, cols, opts={}){
   kicker(s, "// how it stays true", AMBER);
   title(s, "Proven, not promised");
   const cards = [
-    ["570 gate scripts", "the suite runs on every push — plus determinism, cache-transparency and golden contracts; the gate count itself is gated against the runner's own loop"],
+    ["571 gate scripts", "the suite runs on every push — plus determinism, cache-transparency and golden contracts; the gate count itself is gated against the runner's own loop"],
     ["byte-identical, always", "two runs over the same tree produce the same bytes; warm equals cold. Enforced in CI, twice — Release AND a plain flavour, because NDEBUG once blinded a whole class of checks"],
     ["differential refactoring", "a refactor must prove it changed nothing observable: two binaries, hundreds of argv vectors, stdout + stderr + exit codes byte-identical"],
     ["held-out labels, authored blind", "eval labels were written by reading source before the ranker ever ran on them — so the eval is allowed to say the ranker is wrong. It has."],
@@ -732,7 +732,7 @@ function row(s, y, h, cols, opts={}){
   title(s, "Claims you can trust, because we publish what failed", { size: 32 });
 
   card(s, MX, 1.72, 3.86, 1.72);
-  stat(s, "570", "gate scripts named by test/regression.sh — and the COUNT itself is gated against the runner's own loop, so it cannot go stale quietly",
+  stat(s, "571", "gate scripts named by test/regression.sh — and the COUNT itself is gated against the runner's own loop, so it cannot go stale quietly",
     MX+0.15, 1.86, 3.56, CYAN, { bsize: 42, bh: 0.66, lsize: 9.5 });
   card(s, 4.68, 1.72, 3.86, 1.72, CARD2);
   stat(s, "8", "registered NEGATIVES — changes built, gated green, measured against a band written before the code, and reverted rather than tuned",
@@ -971,7 +971,7 @@ function row(s, y, h, cols, opts={}){
     ["179 long flags · 29 slides",        "bash test/deckclaimcheck.sh"],
     ["every --flag named here exists",    "bash test/deckcheck.sh"],
     ["74.7% fewer element bytes",         "bash test/showcasecapturecheck.sh"],
-    ["570 gate scripts",                  "bash test/manifestcheck.sh"],
+    ["571 gate scripts",                  "bash test/manifestcheck.sh"],
     ["46 repos · 69 papers · 237 surveyed","bash test/readmedriftcheck.sh"],
     ["the ten moments, any row",          "ripwire . --callers=SYM | wc -c"],
     ["the head-to-head table",            "bench/headtohead/r4-2026-08-06/"],

present/deck5_ripwire_build.js

@@ -134,7 +134,7 @@ The always-loaded ripwire primer trains the READ verbs (`--for`/`--recall`/`--ca
   `ripwire <dir> --quality-panel[=strict|default|lenient]`, the six-family panel (→ **ripwire-fresh-eyes**).
   **It is a lens, not a gate** — always exits 0; `--quality-delta` above is the only pass here that gates.
 
-`ripwire --help` is the full flag catalog; every skill re-verifies its commands against the shipped binary.
+`ripwire --help` lists every flag on one line; `--help=--FLAG` prints one flag in full and `--help=all` the whole catalog. Every skill re-verifies its commands against the shipped binary.
 
 **Installing these skills:** `bash skills/install.sh` symlinks every `ripwire-*` skill into the Claude
 skill home (its codex mode targets `${AGENTS_HOME:-~/.agents}/skills`; `--codex-legacy` retains