docs(website): plan the Integration Kit — the module-builder's instruction book #126

wtclaude · 2026-08-10T19:11:02Z

wtclaude commented

2026-08-10 19:11:02 +00:00

Stacks on RunicGateway/docs#125 (same branch line) — merge that one first and this diff reduces to its single commit.

Plans RunicGateway/Integration-kit into the module system as a named deliverable. The repo is empty today — no branches, no initial commit — exactly where Module-uo was at the start of Phase 0.

What it is

The book someone reads to build a module for a game that is not UO, starting from nothing. Everything else in the plan is written for people changing this system; this is the only document whose audience is 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 — module.json, the entry point and ctx, the register* calls, the schema fragment, the prebuilt client chunk and the shared-dependency rule, packaging and release CI. The bulk of it.
The sidecar, and why it exists — the shard is never network-reachable, it dials out and the sidecar listens, the wire is a versioned compatibility contract rather than a build dependency. A new game needs its own sidecar or an adapter into this one, and neither can be designed by someone handed the message list and none of the reasoning.
The game-side plugin — feeding the sidecar without ever letting a wedged sidecar stall the game: the bounded drop-oldest queue, the writer thread, world reads only on the game's own thread. servuo-plugins/ is the worked example; the constraints are general.

The rule that keeps it from rotting

It never re-specifies a contract. MODULE_API.md stays normative for the module surface, link/PLAN.md + link/INTEGRATION.md for the wire protocol. The kit teaches — worked examples, reasoning, ordering, 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 the reader who follows the divergent copy gets a module that fails validation for reasons the guide cannot explain.

When

It trails the implementation rather than leading it, because it cannot be written before the contract is proven:

scaffolded when Phase 2 lands (repo, license, CI, outline);
written against Phase 3's extraction, with 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 its first chapter.

Acceptance: someone builds a trivial working module for a second game following the kit alone, without reading core's source. Until then it is a draft however finished it looks.

Changes

MODULE_SYSTEM.md only: new §2.11, a Phase 5 entry in §2.7, and settled decision 13. The landing page (.profile) and the workspace CLAUDE.md get their rows when the repo has content, not while it is empty — noted in §2.11.

AI-assisted: written with Claude Code (Claude Opus 5)

🤖 Generated with Claude Code

**Stacks on RunicGateway/docs#125** (same branch line) — merge that one first and this diff reduces to its single commit. Plans [`RunicGateway/Integration-kit`](https://gitea.whitlocktech.com/RunicGateway/Integration-kit.git) into the module system as a named deliverable. The repo is **empty today** — no branches, no initial commit — exactly where `Module-uo` was at the start of Phase 0. ## What it is The book someone reads to build a module for a game that is **not** UO, starting from nothing. Everything else in the plan is written for people changing *this* system; this is the only document whose audience is outside the org. One book rather than a page in each repo, because the job spans all three layers of the data path: 1. **The website module** — `module.json`, the entry point and `ctx`, 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, and *why* it exists** — the shard is never network-reachable, it dials **out** and the sidecar listens, the wire is a versioned compatibility contract rather than a build dependency. A new game needs its own sidecar or an adapter into this one, and neither can be designed by someone handed the message list and none of the reasoning. 3. **The game-side plugin** — feeding the sidecar without ever letting a wedged sidecar stall the game: the bounded drop-oldest queue, the writer thread, world reads only on the game's own thread. `servuo-plugins/` is the worked example; the constraints are general. ## The rule that keeps it from rotting **It never re-specifies a contract.** `MODULE_API.md` stays normative for the module surface, `link/PLAN.md` + `link/INTEGRATION.md` for the wire protocol. The kit teaches — worked examples, reasoning, ordering, 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 the reader who follows the divergent copy gets a module that fails validation for reasons the guide cannot explain. ## When It trails the implementation rather than leading it, because it cannot be written before the contract is proven: - **scaffolded when Phase 2 lands** (repo, license, CI, outline); - **written against Phase 3's extraction**, with `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 its first chapter. **Acceptance:** someone builds a trivial working module for a second game following the kit alone, without reading core's source. Until then it is a draft however finished it looks. ## Changes `MODULE_SYSTEM.md` only: new §2.11, a Phase 5 entry in §2.7, and settled decision 13. The landing page (`.profile`) and the workspace `CLAUDE.md` get their rows when the repo has content, not while it is empty — noted in §2.11. --- - [x] AI-assisted: written with Claude Code (Claude Opus 5) 🤖 Generated with [Claude Code](https://claude.com/claude-code)

wtclaude added 1 commit 2026-08-10 19:11:04 +00:00

docs(website): plan the Integration Kit, the module-builder's instruction book bb0e6a02fe

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 <noreply@anthropic.com>

whitlocktech merged commit d7054fd1f2 into main

2026-08-10 21:30:31 +00:00

whitlocktech deleted branch docs/module-integration-kit

2026-08-10 21:30:32 +00:00

whitlocktech referenced this issue from a commit

2026-08-10 21:30:33 +00:00

Merge pull request 'docs(website): plan the Integration Kit — the module-builder's instruction book' (#126) from docs/module-integration-kit into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#126