website/MODULE_SYSTEM.md

@@ -479,6 +479,11 @@ Acceptance, all four required:
 `startup_failed` with its recorded reason) and the Docker-environment path from §2.5. Deliberately
 last, so loader, packaging, schema and chunk-loading problems are not all being debugged at once.
 
+**Phase 5 — The Integration Kit.** `RunicGateway/Integration-kit`, the instruction book for building
+a module for a game that is not UO — the website module, the sidecar and why it exists, and the
+game-side plugin that feeds it. Scaffolded when Phase 2 lands, written against Phase 3's extraction,
+finished alongside Phase 4. Full shape and its acceptance test in §2.11.
+
 ### 2.8 SPA URL namespacing — a deliberate break
 
 **Decision: module pages are namespaced, and old paths are not redirected.** The site is not public
@@ -543,6 +548,59 @@ merely regenerated) and `npm test`, and carries a matching edit to `BACKEND_DESI
 documentation aggregates in this repo under `docs/modules/<id>/` rather than living in module repos.
 Conventional Commits, the AI-disclosure trailer, branches cut from an up-to-date `main`.
 
+### 2.11 The Integration Kit — the instruction book for building a module
+
+**`RunicGateway/Integration-kit`** — `https://gitea.whitlocktech.com/RunicGateway/Integration-kit.git`,
+**empty as of 2026-08-10**: no branches, no initial commit, exactly where `Module-uo` was at the start
+of Phase 0. Its first commit needs the same scaffolding as any other repo here — `README.md`,
+`LICENSE.md` (GPL-3.0-or-later), `CONTRIBUTING.md` with the AI-disclosure clause, the PR template.
+
+**Who it is for.** Everything else in this plan is written for someone changing *this* system. The kit
+is written for someone building a **new** one: a person who wants Runic Gateway to front a game that
+is not Ultima Online, starting from nothing. It is the only document in the project whose audience is
+outside the org, and that changes how it is written — it explains and motivates rather than records
+decisions.
+
+The job spans all three layers of the data path, which is why it is one book and not a page in each
+repo:
+
+1. **The website module.** `module.json`, the server entry point and what `ctx` hands you, the
+   `register*` calls, the schema fragment, the prebuilt client chunk and the shared-dependency rule,
+   packaging and release CI. The bulk of it.
+2. **The sidecar** — what it is and, more importantly, *why*. The shard is never network-reachable;
+   the shard dials **out** and the sidecar is the listener; the wire is a versioned compatibility
+   contract rather than a build dependency; only the website's backend talks to it. A new game needs
+   its own sidecar or an adapter into the existing one, and neither can be designed by someone who has
+   been handed the message list and none of the reasoning.
+3. **The game-side plugin** — how a shard feeds the sidecar without ever letting the sidecar stall the
+   game: the bounded drop-oldest queue, the dedicated writer thread, world reads only on the game's
+   own thread. `servuo-plugins/` is the worked example; the constraints are general, and a plugin that
+   ignores them takes the game down when the sidecar wedges.
+
+**The rule that keeps it from rotting: the kit never re-specifies a contract.**
+[`MODULE_API.md`](MODULE_API.md) stays normative for the module surface, and
+[`../link/PLAN.md`](../link/PLAN.md) + [`../link/INTEGRATION.md`](../link/INTEGRATION.md) for the wire
+protocol. The kit *teaches* — worked examples, the reasoning, the order to do things in, the mistakes
+that cost time — and links out for the authority. Where it must show a member list it quotes with a
+pointer, never a copy. A guide that restates a contract diverges from it silently, and a reader who
+follows the divergent copy gets a module that fails validation for reasons the guide cannot explain.
+
+**It cannot be written before the contract is proven**, so it trails the implementation rather than
+leading it:
+
+- **Scaffolded once Phase 2 lands** — repo, license, CI, and an outline. By then a loader exists to
+  describe and a real module to point at.
+- **Written against Phase 3's extraction**, using `Module-uo` as the worked example throughout. A kit
+  whose examples are invented is a kit whose examples do not compile.
+- Phase 3's fourth acceptance criterion, the written `module-rust` dry run, is really this book's
+  first chapter — and doubles as the honest test that the contract generalises past its first module.
+
+**Acceptance:** someone builds a trivial working module for a second game by following the kit alone,
+without reading core's source. Until that has happened it is a draft, however finished it looks.
+
+The org landing page (`RunicGateway/.profile`) and the workspace's `CLAUDE.md` repo table both gain a
+row for it — when it has content, not while it is an empty repo.
+
 ---
 
 ## Part 3 — Settled decisions
@@ -564,3 +622,4 @@ Conventional Commits, the AI-disclosure trailer, branches cut from an up-to-date
 | 10 | Client half loads as a prebuilt ESM chunk with React shared via a core global | §2.6 |
 | 11 | Website work lands on `edge` and reaches `main` as one cutover at the end | §2.9 |
 | 12 | The module repo is `RunicGateway/Module-uo`; the module id is `uo` | §2.3 |
+| 13 | `RunicGateway/Integration-kit` is the module-builder's instruction book — module + sidecar + game plugin, teaching only, never re-specifying a contract | §2.11 |