docs(book): the four chapters — Phase 5 slice 2 #3

wtclaude · 2026-08-12T18:22:51Z

wtclaude commented

2026-08-12 18:22:51 +00:00

Phase 5 slice 2 (MODULE_SYSTEM.md §2.11.1). Docs half: docs#146. Either order.

The book, written out of the tree slice 1 proved. Four chapters in the order the work happens.

Chapter	Lines	What it is
1. Your first module in twenty minutes	243	Copy, rename, build, install, see a page. No theory.
2. The website module	484	The bulk: `module.json`, `register(ctx, api)`, the schema fragment, the client chunk, packaging, boundaries.
3. The sidecar	185	Why the website never talks to a game server; persist-before-forward; what thin means.
4. The game-side plugin	179	The least code, the highest stakes: never block the game thread.

The four decisions, all as recommended

template/README.md stays the reference; chapter 1 is the narration. The README travels with a copied template and CI holds it against the tree, so it keeps the tree diagram, the build commands and the rename checklist. Chapter 1 links to it and spends its length on what you should see — the log lines, the four URLs, the state you land in, the four ways it fails.
Chapters 3 and 4 cite by file and identifier, never by line. link/ and servuo-plugins/ move for their own reasons, and checkLinks.js already forbids commit permalinks, so a line number in this book is wrong the moment they do. The template stays the only code quoted verbatim.
A new check, scripts/checkChapterPaths.js.
One PR — the outline's status table and the link check are only coherent when the whole set lands.

The new check

Every path a chapter names in backticks must exist. None of those mentions is a markdown link, so checkLinks.js never looked at them; none is code, so nothing else did either. Renaming one template file would have left four chapters quietly pointing at nothing.

Its anchor list is stated, not derived from the tree — the same rule the template's own build guard states (API §3.6). A derived list cannot fail when what it derives from changes: rename template/ and a derived anchor set stops checking every template/… mention at exactly the moment they all became wrong. So the anchors are written down, and an anchor that matches nothing fails the build.

Eleven tests, and every "must not catch" case is a span that really appears in the book: a path in another repo, a placeholder shape, a command line, a fenced listing of the reader's own future tree. Proved to fire end-to-end as well as in its suite:

checkChapterPaths: 1 problem(s):
  - book/_probe.md:1: no such path — template/server/does-not-exist.js

stripFences moved to scripts/lib/markdown.js and both checks now use it — shared code, not a shared description.

Chapter 1 was run, not reasoned about

The template was copied into a real core on edge, booted against the dev database, and every claim in "What you should see" checked: the five log lines, /examplegame/status with its injected <script type="module" src="/modules/examplegame/entry.js">, the chunk served no-cache while module.json 404s, /api/v1/public/world/status, the capabilities in /api/v1/public/modules, and the route present in the merged /api/docs.json.

Then the three failures the chapter tells a reader to cause on purpose — because a chapter that predicts the wrong debugging heuristic is worse than one that predicts none:

Broken on purpose	What core actually printed
A prefix declared and never registered	stage `register`, "declared public/extra but never registered it" — routes `404`, absent from `/api/v1/public/modules`
A table without the id prefix	stage `schema`, at load time, before anything mounts
A throwing `onBoot`	after mounting: `503 Module unavailable`, not absent

All three came out exactly as written, and the chapter now quotes those messages. Two corrections fell out of the run: the log sample shows the real interleaving of core's three lines with the module's two, and the failure section gains the check that needs no login — a module disappears from /api/v1/public/modules in every failure case.

Cleaned up afterwards: module removed from website/modules/, smoke table dropped, website tree clean.

Checks

checkLinks:        56 link(s) across 15 markdown file(s) — OK
checkChapterPaths: 34 path(s) claimed across 15 markdown file(s) — all present
checkRenameSites:  OK — matches the template (21 files)
node --test scripts/checkChapterPaths.test.js   11 pass, 0 fail
node --test scripts/checkRenameSites.test.js    10 pass, 0 fail

The template job is untouched by this PR and should stay green against the pinned core.

AI-assisted: written with Claude Code (Opus 5), reviewed before opening.

**Phase 5 slice 2** (`MODULE_SYSTEM.md` §2.11.1). Docs half: docs#146. Either order. The book, written out of the tree slice 1 proved. Four chapters in the order the work happens. | Chapter | Lines | What it is | | --- | --- | --- | | 1. Your first module in twenty minutes | 243 | Copy, rename, build, install, see a page. No theory. | | 2. The website module | 484 | The bulk: `module.json`, `register(ctx, api)`, the schema fragment, the client chunk, packaging, boundaries. | | 3. The sidecar | 185 | Why the website never talks to a game server; persist-before-forward; what *thin* means. | | 4. The game-side plugin | 179 | The least code, the highest stakes: never block the game thread. | ## The four decisions, all as recommended 1. **`template/README.md` stays the reference; chapter 1 is the narration.** The README travels with a copied template and CI holds it against the tree, so it keeps the tree diagram, the build commands and the rename checklist. Chapter 1 links to it and spends its length on what you should *see* — the log lines, the four URLs, the state you land in, the four ways it fails. 2. **Chapters 3 and 4 cite by file and identifier, never by line.** `link/` and `servuo-plugins/` move for their own reasons, and `checkLinks.js` already forbids commit permalinks, so a line number in this book is wrong the moment they do. The template stays the only code quoted verbatim. 3. **A new check, `scripts/checkChapterPaths.js`.** 4. **One PR** — the outline's status table and the link check are only coherent when the whole set lands. ## The new check Every path a chapter names in backticks must exist. None of those mentions is a markdown link, so `checkLinks.js` never looked at them; none is code, so nothing else did either. Renaming one template file would have left four chapters quietly pointing at nothing. **Its anchor list is stated, not derived from the tree** — the same rule the template's own build guard states (API §3.6). A derived list cannot fail when what it derives from changes: rename `template/` and a derived anchor set stops checking every `template/…` mention at exactly the moment they all became wrong. So the anchors are written down, and **an anchor that matches nothing fails the build**. Eleven tests, and every "must not catch" case is a span that really appears in the book: a path in another repo, a placeholder shape, a command line, a fenced listing of the reader's own future tree. Proved to fire end-to-end as well as in its suite: ``` checkChapterPaths: 1 problem(s): - book/_probe.md:1: no such path — template/server/does-not-exist.js ``` `stripFences` moved to `scripts/lib/markdown.js` and both checks now use it — shared code, not a shared description. ## Chapter 1 was run, not reasoned about The template was copied into a real core on `edge`, booted against the dev database, and every claim in *"What you should see"* checked: the five log lines, `/examplegame/status` with its injected `<script type="module" src="/modules/examplegame/entry.js">`, the chunk served `no-cache` while `module.json` 404s, `/api/v1/public/world/status`, the capabilities in `/api/v1/public/modules`, and the route present in the merged `/api/docs.json`. Then the three failures the chapter tells a reader to cause on purpose — because **a chapter that predicts the wrong debugging heuristic is worse than one that predicts none**: | Broken on purpose | What core actually printed | | --- | --- | | A prefix declared and never registered | stage `register`, *"declared public/extra but never registered it"* — routes `404`, absent from `/api/v1/public/modules` | | A table without the id prefix | stage `schema`, at **load** time, before anything mounts | | A throwing `onBoot` | after mounting: `503 Module unavailable`, not absent | All three came out exactly as written, and the chapter now quotes those messages. Two corrections fell out of the run: the log sample shows the real interleaving of core's three lines with the module's two, and the failure section gains the check that needs no login — **a module disappears from `/api/v1/public/modules` in every failure case.** Cleaned up afterwards: module removed from `website/modules/`, smoke table dropped, `website` tree clean. ## Checks ``` checkLinks: 56 link(s) across 15 markdown file(s) — OK checkChapterPaths: 34 path(s) claimed across 15 markdown file(s) — all present checkRenameSites: OK — matches the template (21 files) node --test scripts/checkChapterPaths.test.js 11 pass, 0 fail node --test scripts/checkRenameSites.test.js 10 pass, 0 fail ``` The `template` job is untouched by this PR and should stay green against the pinned core. --- - [x] AI-assisted: written with Claude Code (Opus 5), reviewed before opening.

wtclaude added 1 commit 2026-08-12 18:22:52 +00:00

docs(book): the four chapters — Phase 5 slice 2

PR Checks / prose (pull_request) Successful in 8s

Details

PR Checks / template (pull_request) Successful in 27s

Details

f41ff92c67

The book, written out of the tree slice 1 proved. Four chapters in the order the
work happens: the first module in twenty minutes, the website module, the sidecar,
and the game-side plugin.

Shape, settled with the org lead:

  * template/README.md stays the REFERENCE — it travels with a copied template and
    CI holds it against the tree — and chapter 1 is the narration: what you should
    see after each step, the state your module lands in, and the four ways it fails.
    The chapter links to the checklist rather than restating it.
  * chapters 3 and 4 cite link/ and servuo-plugins/ by FILE AND IDENTIFIER, never by
    line. Those repositories move for their own reasons and checkLinks already
    forbids commit permalinks, so a line number in this book is wrong the moment
    they do. The template stays the only code quoted verbatim.
  * one PR: the outline's status table and the link check are only coherent when the
    whole set lands.

scripts/checkChapterPaths.js is the anti-rot half a machine can answer: every path
a chapter names in backticks must exist. None of those mentions is a markdown link,
so checkLinks never looked at them, and none is code, so nothing else did either —
renaming one template file would have left four chapters quietly pointing at
nothing. Its anchor list is STATED rather than derived from the tree, for the reason
the template's own build guard states it: a list derived from what exists cannot
fail when what exists changes, and an anchor that stops matching is a check that has
silently stopped checking. So each anchor must exist or the check fails. Eleven
tests, every "must not catch" case a span that really appears in the book.

stripFences moved to scripts/lib/markdown.js and both checks use it — shared code,
not a shared description.

CHAPTER 1 WAS RUN, NOT REASONED ABOUT. The template was copied into a real core on
edge, booted against the dev database, and every claim in "what you should see"
checked: the five log lines, /examplegame/status with its injected
<script type="module" src="/modules/examplegame/entry.js">, the chunk served
no-cache while module.json 404s, /api/v1/public/world/status, the capabilities in
/api/v1/public/modules, and the route in the merged /api/docs.json. Then the three
failures the chapter tells a reader to cause on purpose, because a chapter that
predicts the wrong debugging heuristic is worse than one that predicts none:

  * an undeclared prefix  -> stage `register`, "declared public/extra but never
    registered it", routes 404 and absent from /public/modules;
  * a table without the id prefix -> stage `schema`, at LOAD time, before mounting;
  * a throwing onBoot -> after mounting, so the same route answers 503 "Module
    unavailable" rather than vanishing.

All three came out exactly as written, and the messages in the chapter are that
core's own. Two small corrections fell out of the run: the log sample now shows the
real interleaving of core's three lines with the module's two, and the section on
failure adds that a module disappears from /api/v1/public/modules in every failure
case — a check that needs no login.

MODULE_SYSTEM.md 2.11.1 slice 2. Docs half: docs#146.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech merged commit d5a8520ce0 into main

2026-08-12 18:38:10 +00:00

whitlocktech deleted branch docs/book

2026-08-12 18:38:10 +00:00

whitlocktech referenced this issue from a commit

2026-08-12 18:38:12 +00:00

Merge pull request 'docs(book): the four chapters — Phase 5 slice 2' (#3) from docs/book into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/Integration-kit#3