docs: bring the README back in line with the code - #25
Merged
Conversation
An audit of every factual claim in the README against the repo. Fixes one outright error and several omissions that had accumulated over the recent refactors and features. Corrected: - "Run `npm run lint` (`tsc --noEmit`)" — wrong on both counts. `lint` is oxlint; `typecheck` is the tsc gate. The advice pointed at the wrong command entirely. Filled in: - File tree was missing rng.ts, stash.ts and particles.ts, and still listed ParticlePool under entities.ts (it moved to the render layer). - scripts/ listed only validate-data.mjs — smoke-test.mjs and headless.mjs were undocumented. - The components list omitted difficulty-modal, heat-modal and controls-modal. - storage.ts description now mentions the Daily Rift streak and BrowserStash. - `npm run verify` was described as five gates; it runs seven (headless and smoke were missing from both the one-liner and the "individually" list). - Table of contents didn't include the sim/host boundary subsection. Rewritten: - The Test suite section claimed the only automated coverage was Vitest unit tests and that everything else needed manual browser checking. There are now three layers — unit tests (node env, no jsdom), the headless sim boundary guard, and the Playwright smoke test — so it's a table explaining what each one actually catches, and why the UI layer having no unit harness is a deliberate choice rather than a gap. Verified against the code: grid dimensions, every named data file, every component, and both design docs (docs/fidchell.md's 7×7 board and every-7th- floor rule, docs/causeway-duel.md) are accurate and needed no changes. All ToC anchors resolve. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V6kP5vUAcNbxLK5EnPKAhv
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
2 participants
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.
An audit of every factual claim in the README against the actual repo, after the recent refactors and features. One outright error, several omissions, and one section that had become actively misleading.
Corrected
npm run buildgotcha pointed at the wrong command. It said "Runnpm run lint(tsc --noEmit)" — wrong on both counts.lintis oxlint;typecheckis the tsc gate. Anyone following that advice would have run the wrong tool and trusted an unchecked build.Filled in
rng.ts,stash.tsandparticles.ts, and still listedParticlePoolunderentities.ts(it moved to the render layer in the decoupling work).scripts/listed onlyvalidate-data.mjs—smoke-test.mjsandheadless.mjswere undocumented.difficulty-modal,heat-modalandcontrols-modal.storage.tsdescription now mentions the Daily Rift streak andBrowserStash.npm run verifywas described as five gates; it runs seven —headlessandsmokewere missing from both the one-liner and the "individually" list.Rewritten
The Test suite section claimed the only automated coverage was Vitest unit tests, and that everything else needed manual browser checking. That's now three layers, so it's a table explaining what each actually catches:
npm run headlessnpm run smoke…plus a note that the UI layer having no unit harness is a deliberate choice covered by the smoke test, not a gap.
Verified, no change needed
Checked against the code and found accurate: grid dimensions (10×25, 17px), every named data file exists, every component is now listed, and both design docs (
docs/fidchell.md's 7×7 brandub board and every-7th-non-boss-floor rule,docs/causeway-duel.md). All ToC anchors resolve to real headings.Verification
Docs-only change — no source touched.
npm run verifystill green: 456/456 tests, headless + build + smoke pass.🤖 Generated with Claude Code
Generated by Claude Code