The README is held honest the way the guide is, and readable again: a test on its paths, and its module tour cut to size #112

src/engine/GUIDE.md cannot go stale: src/engine/guide.test.ts reads it and fails when it names a file that does not exist, quotes a line a source does not have, or misses a name the door exports. README.md — 516 lines, the app's front door, the thing a person reads before anything else — has no test at all, and 361 of those lines are one ## Shape heading that retells the module tour the guide already tells better. It is the one document here that can lie silently, and by the repository's own standard that is a gap, not a style preference.

Done looks like

• [ ] A test reads the README the way guide.test.ts reads the guide, and reports offences with their line rather than failing bare: every src/... and scripts/... path it names exists; every directory under src/ is named somewhere in it; every fenced block whose first line names a source quotes lines that file actually has; every command it tells a person to run exists in forge.json or package.json. Where it sits — beside it at the root or under src/ — is the builder's call, said in the pull.
• [ ] It checks paths, quotes and commands and never wording: a test that argues with prose is a test somebody deletes.
• [ ] The README gets shorter by getting truer. How to run it, how to play, what is real and what is simulated, and who a score belongs to stay up front and readable; the module tour keeps roughly a paragraph a directory and sends a reader to src/engine/GUIDE.md for the door instead of retelling it; the pull states the new line count.
• [ ] Every stale or now-wrong claim the work turns up is fixed in the same pull and listed in it — expect several: which modules are behind the door today, what the range does and does not do yet, and the measured numbers. A claim that cannot be checked in ten minutes is cut rather than left standing.
• [ ] No line of it is a changelog: what a pull changed belongs to that pull. The test would otherwise pin history and the file would keep growing by one paragraph a merge, which is how it got to 516 lines.
• [ ] bun test green, and the README still answers the three questions the forge's bar asks of it: how to use the app, what is real versus simulated, and how it runs.

Files I expect to change

README.md, one new test file, and AGENTS.md only if it turns out to promise something the README no longer does.

Risks

Cutting prose is the easiest way to delete something true; the pull lists what went and why, so a reviewer can put a paragraph back. The engine's story is now in two places and the guide is the one with a test, so the README must point at it rather than summarise it — a summary is a second copy that drifts.

Suggested: Vesper — the pages and the words have been Vesper's, and this is the same care applied to the front door.