docs: make walkthrough citations checkable, and point new readers at START_HERE

[HomenShum]

A cold reader was given only this repository and asked to run it and trace nine stages. They succeeded. These are the things that cost them time, plus the guard that should have caught one of them.

The citation guard proved anchor stability, not anchor correctness

scripts/validate-tours.mjs checked that a cited line NUMBER was inside the file. That proves the anchor is stable. It does not prove it is correct — a citation that has drifted onto a different symbol is still in range, and the check passes it.

Two holes:

• pattern was optional on a tour step. A step with no pattern got a range check and nothing else.
• docs/START_HERE.md has line citations into live source and no guard at all.

Demonstrated before fixing — delete pattern from tour step 1 and move its line from main.tsx:156 to 157 (a real line, the wrong symbol):

--- OLD guard on this mutation:
All 27 tour steps resolve.
OLD exit=0
--- HARDENED guard on the same mutation:
01-primary-user-flow.tour step 1 (apps/web/src/main.tsx:157) — no "pattern"; a line
number alone proves the anchor is stable, not that it points at the right symbol
HARDENED exit=1

Now:

• a tour step without pattern is rejected rather than range-checked;
• every path:line citation in START_HERE.md is written path:line — text on that line, and the guard asserts the cited line contains that text;
• bare "line N" prose references are rejected, because nothing can check them. The eight in START_HERE.md are deleted rather than rewritten — each already named the symbol beside it, which is what a reader greps anyway.

Proven on three mutations, each restored afterwards:

Mutation	Result
A START_HERE citation moved to a wrong but in-range line	fails, naming the text it expected and the text actually there
A tour step's pattern deleted and its line drifted	fails (old guard: passes)
A bare "line N" prose ref re-added	fails

Clean tree: All 37 citations resolve and match their anchors.

Wired so it actually runs — npm run docs:check, plus a step in the CI Typecheck job placed before npm install, since it needs no dependencies and fails in about a second.

grep -c START_HERE on CLAUDE.md and AGENTS.md returned 0 and 0

Both now point at docs/START_HERE.md in their first paragraph.

Step 11's Playwright rows did not say they need a backend

docs/codebase/TESTING.md said it under "Browser checks need a running app". The table a reader reaches first did not, and the cold reader burned a run finding out.

Re-measured 2026-08-13 from a fresh clone, vite serving the frontend with no VITE_CONVEX_URL and BASE_URL pointed at it:

Spec	Result	Failing on
one-flow-regression.spec.ts	6 failed / 0 passed (2 tests x chromium, firefox, webkit)	getByTestId('one-surface-workspace') never found
redesign-runtime-route-ownership.spec.ts	3 failed / 1 passed (chromium)	right-inspector, reports-runtime-inspector, exact-web-chat-stream

Root cause, confirmed by reading the rendered page rather than inferring it: with no deployment URL main.tsx renders MissingConvexUrlScreen, so the page under every one of those failures was the "Convex backend not configured" card and no product element can ever mount.

What was deliberately not built

No local fixture backend. Steps 5–10 are Convex server code and this repo ships no substitute for Convex; a canned redesignChatRuns / redesignChatStreamEvents source needs a fake reactive client and an auth shim, which is a subsystem rather than a documentation fix. START_HERE.md now says so plainly instead of leaving a reader to discover it.

Tests

app-vitest 22 failed / 1426 passed / 20 skipped, measured both at clean HEAD and with this change — identical, and identical to the figure docs/codebase/TESTING.md already records. The full npm run test:run is red at HEAD for the pre-existing reasons that document lists. This change touches four markdown files, one script nothing imports, package.json (one added key) and ci.yml.

The four vitest rows of Step 11 that do run from a clean clone: 61 passed.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
nodebench-ai	Ignored	Preview	Aug 13, 2026 9:43pm

[HomenShum]

CI: the new step passes; the job's failure predates this branch

The Walkthrough citations step added to the Typecheck job passed in CI:

Set up job: success
Run actions/checkout@v6: success
Run actions/setup-node@v6: success
Walkthrough citations: success        <- this PR
Install dependencies: success
Convex bundle analysis (codegen): failure
App typecheck: skipped
Convex typecheck: skipped

Convex bundle analysis (codegen) fails identically on main at 8e74f08, the commit this branch is cut from — same job, same step, before any of these changes existed:

Install dependencies: success
Convex bundle analysis (codegen): failure
App typecheck: skipped

(run 31735762685, main @ 8e74f08). It needs CONVEX_DEPLOY_KEY. Nothing here touches Convex.

Worth noting the step ordering is deliberate: Walkthrough citations runs before npm install because it uses only node:fs, so it fails in about a second rather than after a multi-minute install. Proven cold — clone this branch, run it with no node_modules present:

$ ls node_modules
no node_modules (as expected)
$ node scripts/validate-tours.mjs
All 37 citations resolve and match their anchors.
exit=0

[HomenShum]

Correction, found by an adversarial pass on my own first commit

docs/SIMPLIFICATION_REPORT.md records a deliberate decision with a stated reason:

it is deliberately not wired to a 199th npm script in a repository whose script count is itself a documented problem (CONCERNS C5)

My first commit added docs:check anyway — taking the count to 199 while leaving that report asserting the opposite, and giving one command two names (the three .tour descriptions already say node scripts/validate-tours.mjs).

Reverted in 840bb38. Script count back to 198, verified on the branch:

$ gh api repos/HomenShum/NodeBenchAI/contents/package.json?ref=<branch> ... | node -e '...scripts).length'
198
$ grep -c "docs:check" CLAUDE.md
0

All four documents now name the same command the tours do. Nothing about the wiring changed — what makes the guard run is the CI step, which is untouched and already confirmed green (Walkthrough citations: success).

Also footnoted the report's 27 / 27 row: the validator has since grown to cover START_HERE.md citations, so the same command now reports 37, of which 27 are still the tour steps that row counted. The historical number is left alone rather than edited to match today's run.