docs(readme): the front page is a user's guide in controlled English

[heliocipher]

Rewrite the front page as a user's guide in controlled English.

The pitch, the pastiches and the three benchmark tables went. What remains is a plain user's guide: numbered sections, imperative steps, active voice, short sentences, and the benchmark claims point at docs/EVALS.md. The banner, the badges and the release title stay.

Every machine-checked anchor survives, because fifteen gates parse this file:

• 179 long flags advertised, 49 repositories and 70 papers, the 2026 recency counts
• the marked 602 gate count and the --max-tokens=3000 start-here line
• the nine ripwire wrap rows, the --callers example rows, 31 MCP verbs, 34 slides
• the three tokens the README alone carries: --scan-skillsdir, --code-only, --no-cluster

Verification on the commit:

• readmedriftcheck, readmeexamplecheck, manifestcheck, gatecountcheck, deckcheck, deckclaimcheck, agenttablecheck, mcpverbscheck, floormarkcheck, emittertruthcheck, ripwirepubliccheck, cudacheck, metalcheck, skillinstallcheck, docscommandscheck: all pass
• determinism (three same-argv pairs), warm equal to cold, and xmllint --noout: all pass
• docs-only diff: no source and no gate changed, so CI is the authority on the full suite

2,126 lines to 524.

[coderabbitai]

---

_{Comment @coderabbitai help to get the list of available commands.}

[joyful-ii-V-I]

Thank you, @heliocipher. This is genuinely useful help.

What you got right is the thing this README has never had: a reference. Numbered sections, one
instruction per sentence, and each question a reader brings to a manual answered where they would
look for it: how to install, which command, what the output means, which exit code, where the tool
stops being right. You also put the project's own rule in the second paragraph, where it belongs:
--help is the authority, and a guide that disagrees with it is the defect. The exit-code table,
the output-element table and the known-limits list collect in one place what the current page
spreads across two thousand lines.

The reason it is not replacing the front page is that this README serves many different readers,
and they came for different things:

• someone sharing it on X or LinkedIn
• an AI blog evaluator
• a serious coder
• a manager trying to cut token spend
• a developer looking for a fun project

One page has to serve all five, and the long form is carrying most of them today.

So your guide is going in as a reference section toward the bottom of the README, with a pointer
at the top for anyone who just wants the manual. Added, not replacing. Your commit is merged, not
squashed, so it stays in the history under your name.

Fitting it into the page meant three changes. We dropped your title and badge row, nested your headings
one level down, and took the gate count off two lines, since that number is generated and the page states
it in one place. Follow-up commits correct six places where the text and the current binary disagree.
For example, a corrupt --scip index falls back to the name-based edges with a warning instead of
refusing. The two timing rows in the performance table now link to the README's measured section,
rather than giving figures nothing in the tree measures. The --listen paragraph also now says the socket
carries no TLS, so a remote bind belongs behind a TLS-terminating proxy.

It is a work in progress. We will keep editing it to cut the wordiness and get each of those
readers to what they came for faster.

It's live now: Reference guide.

[joyful-ii-V-I]

Hi @heliocipher, a small follow-up on the reference guide.

We liked the question list in your section 1, the one that opens "ripwire reads a source tree and answers these questions", enough to expand it. It now lists forty-two questions, grouped by what you're trying to do: orient, navigate, change it safely, quality and structure, and setup and safety. Each one names the flag that answers it. Sections 4 and 6 also gained a short note that ripwire's output is written for coding agents today. That's in #204.

Thanks again. The structure you set up made this an easy addition.