docs: the command table becomes two tables because it was two audiences, and the page that answers "is this for me" is asked before the install (#591)

[stephrobert]

The rest of #591, reduced by a maintainer decision: file size is not a
problem. Two of the audit's recommendations fall with that premise and were
not smuggled back under another name:

• no docs/ restructure — the argument was "at twenty files a flat directory
  stops working", which is an argument about mass;
• no summary of docs/limits.md — the argument was "3950 lines is
  unreadable". That file is a register: nobody reads it whole, they look a
  section up, and its length is the evidence it is doing its job.

What survives, survives on other grounds.

1. The command table was two audiences

	before	after
command rows, README.md	26, one table	16 + 10, two tables
command rows, README.fr.md	26, one table	16 + 10
verbs in the dispatch	26	26

Someone who came to test their Terraform met feint proxy, feint corpus,
feint evidence and feint shapes in the same table as feint up, with nothing
telling them the last four are not theirs. Same 26 rows, same wording, two
headings, each with one sentence saying who it is for.

The brief's split was wrong and the dispatch said so. It listed 24 verbs;
checking against the switch TestEveryDispatchedCommandIsInTheHelp already
parses found serve and images missing — both everyday, serve being
the foreground emulator the quick-start banner shows and images building what a
--vm user needs. Neither table is generated, so the READMEs were the right
files to edit; that was checked, not assumed.

2. confidence.md was not where it is looked for

Probably the best page here: 73 lines answering "what can I reasonably test
against this emulator?", every verdict pointing at its proof, held by
TestEveryConfidenceRowCarriesItsProof. It was cited twice, in a nav strip and
in prose after the demo, and in neither table of contents.

A new section — "Is this the right tool for your test?" — sits before
## Install in both pages, in both tables of contents.

And it copies nothing. The argument matters more than the section.

The obvious move was a six-row extract in the README. It was refused, for three
reasons in order of weight:

1. A generator producing an extract would have to select rows, and selection
   is a judgement. internal/cli/docs_confidence.go says in its own header
   that the counts are generated and "what stays hand-written is the table,
   because a verdict is a judgement and this file has none to offer". Any rule —
   first N, rows by verdict class — either moves when someone reorders the table
   or needs a new marker in the source. The generator would silently own an
   editorial decision.
2. The FR/EN axis makes it worse. The source table is English prose;
   injecting it into README.fr.md is finding 4 of The documentation's next wave: the code simplified use faster than the documentation simplified its story #591 restated, and feat(docs): the promise on line 41 is derived from a matrix that asks the doorstep, and the quick start is four commands a reader can run (#592, #593) #595 has
   just paid to undo exactly that.
3. The README already carries two early generated blocks answering nearby
   questions — the safety callout and the promise block derived from The README promises Terraform on the three clouds while feint up refuses one of them: a capability claim owned by nobody, and the doc gates check numbers #592's
   matrix. A third statement of the same thing is the one fact in two places
   class this repository keeps paying for.

The section states the framing and links. No verdict, no count, no capability
pair is duplicated.

And its own first draft was corrected: it cited "a sentence on line 41",
which is true today and false after the next paragraph anybody inserts above it.
It names #592 instead (d50d620).

3. An index, because four paths guide and a listing does not

docs/README.md: run something · does it answer my question · what "proven"
means · change it. Every claim in it was checked against the page it
describes, and one was wrong: docs/install.md has no "from source" section —
that route is in the README.

The guards, and a weakness they close

Two new tests, and the first closes something that predates this branch:
TestEveryCommandIsNamedInTheReadmes accepts a mention anywhere on the page,
which is why stop and restart once read as documented while both were folded
into one entry about start.

• TestEveryCommandHasExactlyOneRowUnderAnAudience asserts the partition:
  every dispatched verb has exactly one row across every group, every row names a
  dispatched verb, and the rows sit under at least two headings each holding at
  least three.
• TestTheDocsIndexResolvesEveryPathItOffers — every link resolves, and a
  #fragment resolves to a heading that really produces it. It deliberately does
  not assert completeness: that would turn the index back into the listing
  GitHub already renders, which is where the maintainer's refusal is written down
  in code.

command-tables-two-audiences.json, 6 mutations, all 6 bite, none dropping an
identifier:

the second heading dissolves into prose            → red
a verb loses its row, still named in prose         → red
a verb described under both audiences              → red
a row survives the verb it described               → red
an index path stops arriving at a file             → red
an index path arrives at the page, not the section → red

A hand witness was planted on docs/README.md#quick-start before the spec was
written, to prove the anchor reader can fail at all rather than passing
vacuously.

What docs:check cannot see, said plainly

feint docs --check compares only the marker blocks. Neither command table,
neither new section, neither ToC entry and none of docs/README.md sits inside
one — docs:check is silent about every line this branch adds. What covers
them is the two new Go tests plus the two pre-existing ones, all running under
mise run check inside prepush.

Gates

prepush 0, twice, the second on the final diff · docs:check 0 ·
falsify 6/6 · falsify:lint 968 mutations over 150 specs.

limits:check is 2 and pre-existing — three docs/limits.md sections cite
#365, #570 and #571, all closed 2026-08-28, before this branch.
git diff origin/main -- docs/limits.md docs/limits-acks.json is empty.

What was not obtained

• No docs/README.fr.md. The index names the French pages where they exist
  and states that English is the source, but it is itself English. A translated
  index is a fifth page to keep in step.
• No conformance run: no route, response shape or error changed.
• One tension left for the maintainer: docs/routes.md opens with "Is your
  resource emulated? This page answers it without installing anything." — very
  close to the new section's framing. They are complementary (capability versus
  operation) and the section links both, but if only one front-page signpost is
  wanted, that is the tension to resolve.

Where testplan was slightly wrong

It named limits:check because docs/README.md matched "prose, including what
this project says it does not do" — but that gate reads only docs/limits.md,
which this diff does not touch. Over-trigger, not a false green, and it cost a run
that exits 2 for somebody else's reason.