docs(readme): rebuild the landing surface around commands that now run - #556
Merged
Conversation
The README opened with a menu, an architecture diagram and a link to a quickstart whose Step 1 invoked a script that does not exist. The working quickstart sat at line 227 of 389, behind a twenty-row Q and A accordion. Measured readership over the preceding fortnight: two unique visitors to the landing page. WHAT A STRANGER NOW SEES FIRST: a one-line positioning claim, one badge row, and an installable three-command block at line 16. Then the section that does the work. 'What just happened' quotes a REAL run of the published 1.3.0 in a container with nothing but Node -- 133 checked / 26 skipped / 0 errored, 37 blocking, exit 2 -- and then says the thing the numbers are for: NINE of those 37 blocking issues are rules that were SKIPPED. Not rules that failed; rules the engine could not decide, reported as failures because an undecided blocking rule is not a passing one. Backed by a named invariant test rather than by adjectives. Added 'Use it as a PR gate' with the copyable block. The README mentioned the GitHub Action NOWHERE, while action.yml has been Marketplace-shaped at the repository root for weeks. Added 'Why not ArchUnit, Conftest or dependency-cruiser?' -- which opens by telling the reader to use them. It also states what is NOT built: no command in the installed CLI reaches an LLM, so the 'LLM proposes, verifier disposes' half is a documented direction and is labelled as one. That paragraph exists because it is the first thing a skeptic greps for. The Q and A accordion moves below Quick Start and the hero diagram below the fold. Convince with the terminal; reward with the diagram. NUMBERS, AND I HAD TWO OF THEM WRONG. The README claimed '137 ADRs, 163 rulesets, 45 schemas' and '47 tools, 9 resources'. My own first count said 103 core ADRs and 382 rules. An independent measurement replicating the production loader corrected both: the normalizer reads , so the corpus is 412 rules and not 382, and 142 is the ADR count once README/adr-matrix/authoring-standard are excluded. Now: 142 ADRs, 181 ruleset files carrying 412 rules, 50 schemas, 52 tools, 12 resources. It also caught a contradiction I had introduced: 412 is the corpus the Core carries, 159 is what one satellite's run selected. The README now says which is which, because a report that blurred two denominators is the exact defect this project exists to stop. QUICKSTART REWRITTEN. It made booting a Core API a mandatory Step 1 via ./.harness/scripts/run-core-local.sh -- a file that does not exist -- and promised a server on :30080 that no service in the compose file defines. It is now the three commands that work, plus what the numbers mean and the exit-code taxonomy. The server material moved to a new 'Self-hosting the Core API' guide that opens by saying you do not need it, and that records the dead instruction rather than quietly deleting it. Also fixed the dead 'Onboarding by role' table row -- plain text where a link belonged.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
📊 Bilingual Coverage ImpactPR Changes
Repository Coverage
✅ Good: All EN changes have ES counterparts. Generated by GitHub Actions |
This was referenced Aug 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request Summary
The README opened with a menu, an architecture diagram, and a link to a quickstart whose Step 1 invoked a script that does not exist. The working quickstart sat at line 227 of 389, behind a twenty-row Q&A accordion. Measured readership over the preceding fortnight: two unique visitors to the landing page.
What a stranger now sees first
A one-line positioning claim, one badge row, and an installable three-command block at line 16.
Then the section that does the work. "What just happened" quotes a real run of the published
1.3.0in a container with nothing but Node —133 checked / 26 skipped / 0 errored, 37 blocking, exit 2 — and then says what the numbers are for:Backed by a named invariant test rather than by adjectives:
blocking-skipped-invariant.spec.ts.Two sections that did not exist
"Use it as a PR gate" with the copyable
uses:block. The README mentioned the GitHub Action nowhere, whileaction.ymlhas been Marketplace-shaped at the repository root for weeks."Why not ArchUnit, Conftest or dependency-cruiser?" — which opens by telling the reader to use them, and includes a column for where the neighbour is equal or better. It also states what is not built: no command in the installed CLI reaches an LLM, so the "LLM proposes, verifier disposes" half is labelled a documented direction. That paragraph exists because it is the first thing a skeptic greps for.
Numbers, and I had two of them wrong
The README claimed "137 ADRs, 163 rulesets, 45 schemas" and "47 tools, 9 resources". My own first count said 103 core ADRs and 382 rules. An independent measurement replicating the production loader corrected both:
The 382 → 412 correction is the interesting one: the normalizer reads
rules ?? principles, so four principle-shaped packs contribute 30 rules my naive count missed.It also caught a contradiction I had introduced. 412 is the corpus the Core carries; 159 is what one satellite's run selected. The README now says which is which — a report that blurred two denominators would be the exact defect this project exists to stop.
Quickstart rewritten
It made booting a Core API a mandatory Step 1 via
./.harness/scripts/run-core-local.sh— a file that does not exist — and promised a server on:30080that no service in the compose file defines. It is now the three commands that work, plus what the numbers mean and the exit-code taxonomy (1and3are not weaker forms of2; they mean nothing was evaluated).The server material moved to a new Self-hosting the Core API guide that opens by saying you do not need it, and that records the dead instruction rather than quietly deleting it.
Also: the Q&A accordion moves below Quick Start, the hero diagram below the fold, and the dead "Onboarding by role" table row is now a link.
Still open from the W4 plan
The asciinema demo is not in this PR. Everything it would record is now real and reproducible, but recording it needs a terminal capture I cannot produce here.
Before you submit
docs(readme): …README,README.es, both quickstarts and both new guides — 19/19 headings matched, guard 04 green