From bb0e6a02feae2a0b335a3bf75473b9947d0c6640 Mon Sep 17 00:00:00 2001 From: wtclaude Date: Mon, 10 Aug 2026 14:10:41 -0500 Subject: [PATCH] docs(website): plan the Integration Kit, the module-builder's instruction book RunicGateway/Integration-kit -- empty today, exactly where Module-uo was at the start of Phase 0 -- becomes the book someone reads to build a module for a game that is not UO, starting from nothing. It is the only document in the project written for an audience outside the org. One book rather than a page in each repo, because the job spans all three layers of the data path: the website module (the bulk of it), the sidecar and WHY it exists -- the shard is never network-reachable, it dials out, the wire is a versioned contract -- and the game-side plugin that feeds it without ever letting a wedged sidecar stall the game. The rule that keeps it from rotting: it never re-specifies a contract. MODULE_API.md stays normative for the module surface and link/PLAN.md + INTEGRATION.md for the wire protocol; the kit teaches and links out for the authority. A guide that restates a contract diverges from it silently, and the reader who follows the divergent copy gets a module that fails validation for reasons the guide cannot explain. It trails the implementation rather than leading it -- scaffolded when Phase 2 lands, written against Phase 3's extraction with Module-uo as the worked example, finished alongside Phase 4 -- and it is a draft until someone builds a working module for a second game from it alone, without reading core's source. Adds 2.11, Phase 5 in 2.7, and settled decision 13. Co-Authored-By: Claude --- website/MODULE_SYSTEM.md | 59 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/website/MODULE_SYSTEM.md b/website/MODULE_SYSTEM.md index 06f676b..6ef2d52 100644 --- a/website/MODULE_SYSTEM.md +++ b/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//` 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 |