@bongos/core 1.17.0

package/docs/modules-contract.md

@@ -0,0 +1,293 @@
+# The module plugin-API contract (`src/module-api.js` + `modules/*/`)
+
+> **Decision record:** [ADR 0083](adr/<redacted>.md) — the build plan.
+> **Live state:** the shipped modules under `modules/` are the four feature modules `dev-box`, `game`, `discord`, `art-pipeline` (+ `character-anim`, declaration-only; ADR 0088) and the carved core-domain modules `memory` (R72), `grading` (R73), `economy` (R77), `ideas` (R78), `security` (R79), `builder-settings` (R80), `onboarding` (R81), and `sessions` (R82) — see [ADR 0093](adr/<redacted>.md) for the remaining carve sequence.
+> **Author a new module:** jump to [the module-author recipe](#module-author-recipe).
+
+The module system turns optional features into self-contained directories. Adding a feature is "drop `modules/<key>/`"; the loader discovers, validates, and mounts it — no core file changes. The **one-way rule** is the load-bearing invariant:
+
+```
+module  ──require──▶  src/module-api.js  ──▶  kernel
+core    ──✗──────────────────────────────▶  module   (forbidden)
+module  ──✗──────────────────────────────▶  module   (forbidden; use a seam)
+```
+
+Two fitness checks enforce it on every build — a violation is a red CI gate, not a style note.
+
+---
+
+## The cut: core vs modules
+
+- **Core** is the trust kernel + the lifecycle state machine + the domains not yet carved: auth/identity/audit/rank (the kernel, [ADR 0091](adr/<redacted>.md) §1), the lifecycle (tasks, claims, versions, done-when, ship — never split), and the still-core domains (autonomy/MAS, the two web UIs) plus always-on infra (analytics, audit-log, gate-approvals, healthz, public). The remaining tranche-2 domains carve out per [ADR 0093](adr/<redacted>.md) §1; the lifecycle stays core. (Sessions/BFG — the `session_records` corpus + data plane + the BFG scorer + session-pulse — carved to `modules/sessions/` at R82; like `memory` it registers no port and core never calls back in. The per-claim `session_logs` ship LOG + `builder_sessions` auth tokens stay core.)
+- **Modules** are optional features an instance turns on via `config/modules.json` or env (the feature modules `dev-box`, `game`, `discord`, `art-pipeline`, `character-anim`), plus the **core-domain modules** that are `default: true` (always on unless disabled): `memory` (R72), `grading` (R73), `economy` — credits/cost/streaks/achievements/leaderboard (R77), `ideas` — inbox/capture/triage/blockers (R78), `security` — red-team reports + bounty (R79), `builder-settings` — wandering/skill/sound/render prefs + builder-needs (R80), `onboarding` — admission/onboarding-state/newcomer-restock (R81), and `sessions` — session_records corpus + BFG + session-pulse (R82). Each is a self-contained directory under `modules/<key>/`.
+
+---
+
+## The published doorway — `src/module-api.js`
+
+The **only** core file a module may `require`. It re-exports the kernel capabilities a module legitimately needs:
+
+| Export | What it gives a module |
+|---|---|
+| `requireBuilder` / `requireRank` / `rankMeetsThreshold` | Auth gates (ADR 0016). Modules self-gate per route: write routes call `api.requireRank(rank)`; authenticated read routes call `api.requireBuilder`; intentionally public read routes (e.g. leaderboard, claimable tasks) need no gate. The fitness check enforces the write-route rule; audit is composed at the kernel level before module routes mount. |
+| `requireBfgPrincipal` | Gate a route to the BFG agent principal. |
+| `allowBoxScope` | Opt a bootstrap route in to box-scoped session tokens. |
+| `pool` | The shared Postgres pool. A module owns its `<key>_*` tables via its migrations. |
+| `instanceDbName` | The resolved DB name (from branding). |
+| `db` | Kernel-managed DB helpers (`getBuilderById`, `setBuilderBoxBlocked`, `getBuilderGeminiKeyRow`, `setBuilderGeminiKey`, `clearBuilderGeminiKey`, `insertAuditLog`, `createTask`). Grow this additive-only. |
+| `branding` | The branding contract resolver — the resolved instance strings. |
+| `instanceConfig` | Module enablement config + env override resolution. |
+| `seams` | The seam registry (`registerProvider`, `hasProvider`, `resolve`, `resolveOptional`, `emit`, `on`) — how modules cooperate without importing each other. |
+| `buildInfo` | `{ version, commit, builtAt }` for `/health`-style routes. |
+| `validateOrRespond` / `LIMITS` / `parseId` | Route helpers (input validation, standard limits, numeric route-param parsing). |
+| `classifiers` | `LIVE_RANK_LADDER`, `VOTABLE_TASK_STATUSES`. |
+| `logger(key)` | Returns `{ info, warn, error }` — namespaced so module log lines are attributable. |
+| `CORE_VERSION` | The semver of THIS surface (see below). |
+
+### `CORE_VERSION` and semver compatibility
+
+`CORE_VERSION` is declared in `src/module-api.js`. It follows semver:
+- **MINOR bump** — adding an export (safe; existing modules keep working).
+- **MAJOR bump** — changing or removing an export (breaking; enabled modules must update their `coreVersion` range).
+
+A module's `module.json` declares `"coreVersion": "^1.4.0"` (a semver range). The loader silently skips any module whose range no longer satisfies `CORE_VERSION`. `bongos upgrade` reports this ahead-of-time and exits 1 on any enabled mismatch, so the silent drop is the last resort, not the first signal.
+
+**Current `CORE_VERSION`:** `1.8.0`
+
+| Bump | What it added |
+|---|---|
+| 1.0.0 | Initial doorway: auth gates, pool accessor, config/branding, seams. |
+| 1.1.0 | Contribution seam: `contribute`/`contributions`/`collectContributions`/`listContributionPoints`. |
+| 1.2.0 | dev-box needs: `auth.allowBoxScope`, `db.getBuilderById`/`setBuilderBoxBlocked`, `buildInfo`, `validateOrRespond`/`LIMITS`. |
+| 1.3.0 | art-pipeline needs: `db.getBuilderGeminiKeyRow`/`setBuilderGeminiKey`/`clearBuilderGeminiKey`. |
+| 1.4.0 | discord needs: `db.insertAuditLog`/`createTask`, `inbox.captureIdea`, `LIVE_RANK_LADDER`, `VOTABLE_TASK_STATUSES`. |
+| 1.5.0 | kernel-bounding (R68, ADR 0091): adds `withTx`; relocates `setBuilderBoxBlocked` → dev-box (lockstep-MINOR). |
+| 1.6.0 | grading carve (R73): adds the kernel trust classifiers `routeRankCheck`/`permissionPathCheck` + `llmCache` (domain leak). |
+| 1.7.0 | economy carve (R77): adds `llmPricing` (domain leak). |
+| 1.8.0 | ideas carve (R78, ADR 0093 §5): adds `parseId`; **retires** the `captureIdea` doorway leak → the `ideas.capture` kernel port (lockstep-MINOR). |
+
+---
+
+## The manifest schema — `module.json`
+
+Every module must have a `module.json` at its root (`modules/<key>/module.json`). The loader validates it against `src/module-loader/manifest-schema.js` before mounting.
+
+```jsonc
+{
+  "key":         "dev-box",           // REQUIRED. ^[a-z][a-z0-9-]*$ — must match the dir name.
+  "title":       "Dev boxes",         // REQUIRED. Human label.
+  "description": "…",                 // REQUIRED. One sentence.
+  "coreVersion": "^1.2.0",           // REQUIRED. semver range of CORE_VERSION this module supports.
+  "default":     false,               // OPTIONAL (default false). Fail-safe when no config names it.
+  "author":      "…",                 // OPTIONAL. Attribution (ADR 0107 §2) — portable, not a cross-GDS FK.
+  "origin":      "…",                 // OPTIONAL. Origin instance/project this module was built in.
+  "license":     "AGPL-3.0",          // OPTIONAL. License this module is offered under.
+  "maintainer":  "…",                 // OPTIONAL. Who to credit/contact if this module is upstreamed.
+  "contributes": {                    // REQUIRED object (may be empty {}).
+    "routes":      ["box"],           //   route-factory files in routes/ (one export = () => Router())
+    "rooms":       ["WorldRoom"],     //   Colyseus room classes (game module only)
+    "pollers":     ["box-lifecycle"], //   background pollers (start/stop lifecycle)
+    "disciplines": ["artist"],        //   builder disciplines this module adds
+    "skills":      ["otb-tile-generate"], // slash-command skills it ships
+    "uiSections":  ["boxes"],         //   hall/status UI sections gated by window.__MODULES__
+    "webSurfaces": [{ "host": "status.", "dir": "public" }], // host-routed static web surfaces (BV1.R84)
+    "migrations":  true               //   true → modules/<key>/migrations/*.sql applied if enabled
+  },
+  "provides": ["box.hasEverConnected"], // OPTIONAL. Seam PORTS this module registers a provider for.
+  "consumes": [],                       // OPTIONAL. Seam ports this module resolves (required caps).
+  "prerequisites": { "modules": [] }    // OPTIONAL. Other modules that must be enabled first.
+}
+```
+
+An unknown key throws at validate time — typos fail loud (top-level attribution fields have no closed allowlist; only `contributes` sub-keys do).
+
+**Attribution (`author`/`origin`/`license`/`maintainer`) is portable metadata, not a cross-GDS link** — each repo runs its own GDS with its own builder identities ([ADR 0100](adr/<redacted>.md) §3), so credit travels *with the module* rather than through a foreign key ([ADR 0107](adr/<redacted>.md) §2). `bongos module new` stamps all four as TODO placeholders (license defaults to `AGPL-3.0`) so a module carries its authorship from the day it's scaffolded, not bolted on later at upstream-submit time.
+
+**`bongos module check <key> [--sign-off "Name <email>"]`** ([ADR 0107](adr/<redacted>.md) §4) is the submit-time pre-check a module must clear before it can be upstreamed. It reuses (never re-types) the public-mirror publish denylist (`scripts/gds/publish-manifest.js`'s `matchesDeny`) to reject content that cannot ship under AGPL (game content, pixel art, copyrighted reference material) — deliberately the DENY half only, since a brand-new module is never on the publish ALLOWLIST until it's accepted into core (§6). It also requires `module.json`'s `license` to be AGPL-3.0 (inbound = outbound). On a pass, `--sign-off` records a lightweight DCO-style affirmation (own work, licensed AGPL-3.0 — never a copyright-assignment CLA) to `modules/<key>/.upstream-signoff.json`.
+
+---
+
+## The loader — `src/module-loader/loader.js`
+
+> **Two-root discovery ([ADR 0108](adr/<redacted>.md) §1, task 1881/W1 shipped):** `DEFAULT_ROOTS` resolves `modules/` off `resolveCoreRoot()` ([`src/instance-config.js`](../src/instance-config.js)), not a hardcoded `__dirname`-relative path. Today `resolveCoreRoot() === resolveInstanceRoot()` (both the repo root), so discovery is unchanged. Once a consumer installs the core as a package, an **instance-owned** `modules/` directory (host-authored modules, living in the instance repo, not the core package) becomes possible — the loader would then discover across both roots via `opts.roots`, same mechanism as below, no core-file change. That instance-root modules directory does not exist yet; this is the seam it will attach to.
+
+At boot the loader (called from `src/modules.js` and the route mounter) runs:
+
+1. **Discover** — scan `modules/*/module.json` (and any extra roots passed via `opts.roots`).
+2. **Validate** — run each manifest against the schema; invalid manifests are skipped with an error log, never a crash.
+3. **`coreVersion` check** — test the manifest's `coreVersion` range against `CORE_VERSION`; mismatch = skip with a warning.
+4. **Enablement filter** — check `isModuleEnabled(key)` (env override → `config/modules.json` → `config/modules.neutral.json` → `manifest.default`); disabled modules are skipped.
+5. **Mount routes** — for each `contributes.routes` key, `require(`modules/<key>/routes/<routeKey>.js`)` and call the factory. Audit is already composed at the kernel level (routes.js runs `auditMiddleware` before the loader mounts anything); each route self-gates at the appropriate rank via `api.requireBuilder` / `api.requireRank`. The fitness check (`BV1.R44`) ensures every write route is rank-gated.
+6. **Start pollers** — call each `contributes.pollers` file's `start()` on successful mount.
+7. **Serve web surfaces** — for each `contributes.webSurfaces` entry `{ host, dir }`, `serve-internal.js` (via `loader.moduleWebSurfaces`) serves `modules/<key>/<dir>/` on the matching Host prefix (the content-hash-stamped index + branding injection the status page always used). This is how the status dashboard (`status-ui`) reaches `status.<apex>` with no core edit (BV1.R84). A disabled module's surface is never built, so its host routes nowhere.
+8. **Apply migrations** — enabled-gated; `migrate.sh` discovers `modules/<key>/migrations/*.sql` only when the module is enabled.
+
+The loader is safe-by-construction: with no `modules/` dir it returns empty and all functions are no-ops — the instance behaves identically to before the module move.
+
+**Resolution precedence for enablement (highest wins):**
+
+```
+env override  →  config/modules.json  →  config/modules.neutral.json  →  manifest.default (false)
+```
+
+Env override key: `<envPrefix>_MODULE_<NAME>` (`NAME` = upper-snake of the key; `dev-box` → `DEV_BOX`). Example: `OTB_MODULE_DISCORD=0`.
+
+A fresh instance with **no** config resolves to **vanilla**: every module off (fail-to-vanilla).
+
+---
+
+## Seam registry — `src/module-seams.js`
+
+Modules cooperate through the kernel switchboard — never by importing each other. There are two seam types:
+
+### Ports (required capability — single provider)
+
+A provider module calls `api.seams.registerProvider(portName, fn)` at mount time. A consumer calls `api.seams.resolve(portName)` to get the function and call it. `resolve` throws if no provider is registered — a missing required capability is a fail-clear configuration error, not a silent no-op. `resolveOptional(portName, defaultFn)` returns `defaultFn` when nothing is registered (for graceful degradation on a module-less instance).
+
+### Events (optional reaction — zero-or-many listeners)
+
+A module calls `api.seams.emit(eventName, payload)` to broadcast. Any module that called `api.seams.on(eventName, listener)` at mount time reacts. `emit` isolates listener errors — one bad listener never breaks the emitter or other listeners.
+
+### Live seam registry
+
+| Port / Event | Provider | Consumer(s) | Contract |
+|---|---|---|---|
+| Port: `box.hasEverConnected` | `dev-box` | core `routes/me.js`, `routes/builders.js` | `(builderId) → Promise<bool>` — whether the builder's box has ever connected. Core reads via `resolveOptional(…, async () => false)` so onboarding degrades cleanly on a box-less instance. |
+| Port: `game.staticRoot` | `game` | `server.js` static-serve | `() → string` — absolute path to the game's static root. |
+| Port: `game.registerRooms` | `game` | `server.js` Colyseus setup | `(matchMaker) → void` — registers WorldRoom + QueueRoom. |
+| Port: `game.precreateWorldRoom` | `game` | `server.js` pre-create step | `(matchMaker) → Promise<void>` — pre-creates the singleton room. |
+| Port: `discord.isLinked` | `discord` | core `routes/me.js` | `(builderId) → Promise<bool>` — whether the builder has linked their Discord account. |
+| Port: `art.sharedKeyConfigured` | `art-pipeline` | core `routes/me.js` | `() → Promise<bool>` — whether a shared Gemini key is configured for the instance. |
+| Port: `grade` | `grading` (R73) | the lifecycle (`routes/tasks.js`, `routes/public.js`) | the quality-gate capability the ship path resolves instead of importing `grader.js` ([ADR 0091](adr/<redacted>.md) §4). |
+| Port: `reward` | `economy` (R77) | the lifecycle (`db.applyGrade`/`confirmTask`/…) + read routes (`me.js`/`public.js`/`builders.js`/`sessions.js`) | a **transaction-participant** port — credit/achievement writes take the caller's tx `client` ([ADR 0093](adr/<redacted>.md) §2). |
+| Port: `ideas.capture` | `ideas` (R78) | the `discord` module (`discord-inbound.js`) | `(idea) → Promise<row>` — file an `idea_inbox` row. The **first module→module port** (every other is consumed by core); retired the `captureIdea` doorway leak ([ADR 0093](adr/<redacted>.md) §5). |
+| Port: `security` | `security` (R79) | core `routes/public.js` (`/public/bounty-table`) | `{ bountyTableDetailed(), bountyTable() }` — the env-aware red-team bounty payout schedule. Core reads via `resolveOptional('security').bountyTableDetailed()` instead of importing the module (security is default-on; only <redacted> moved — [ADR 0093](adr/<redacted>.md) §1, [02-module-map §5](design/modular-architecture/02-module-map.md)). |
+| Port: `builder-settings` | `builder-settings` (R80) | core `routes/me.js` (`GET /me`) + `cascade-dispatch.js` | `{ getBuilderBehaviorPrefs, describeWandering, describeRender, computeNeeds, skillCeiling }` — the per-builder prefs read surface. The `GET /me` aggregator resolves it for its wandering/render/needs slices; the dormant cascade router for the skill ceiling. Default-on; degrades gracefully when off ([ADR 0093](adr/<redacted>.md) §1, [02-module-map §2](design/modular-architecture/02-module-map.md)). |
+| Port: `onboarding` | `onboarding` (R81) | the lifecycle (`db.js` claim/ship — transaction-participant `markStage`) + `auth.js` + `routes/me.js`/`builders.js`/`tasks.js`/`claims.js` | `{ getState, shapeForApi, safeMarkStage, markStage, broadcastGraduation, restockForClaim, restockAll, SOURCE_TAG }` — the onboarding state-machine + newcomer-restock surface. The FIRST core→module port the lifecycle ticks inside its own txn (alongside `reward`). Default-on; degrades to best-effort no-ops when off ([ADR 0093](adr/<redacted>.md) §1). |
+| Event: `builder.box-reconcile-needed` | core `db.js` (on rank change / deactivate / auto-graduation) | `dev-box` | `{ builderId, rank, status, actor }` — flags the box for reconciliation. |
+
+---
+
+## Rank-gate rule
+
+Every write route in a module **must** be rank-gated:
+
+```js
+router.post('/my-feature/thing', api.requireRank('metic'), (req, res) => { … });
+```
+
+The `BV1.R44` fitness check (`fitness.js`) walks `modules/**/routes/` with the same "unknown write = blocker" rule that covers the core routes. A module write route that bypasses rank fails the build — this is not advisory.
+
+Authenticated read routes call `api.requireBuilder`. Intentionally public read routes (leaderboard, version progress, claimable tasks list, etc.) need no gate — they are explicitly written without one.
+
+---
+
+## Module-owned migrations — `modules/<key>/migrations/`
+
+A module puts its SQL files under `modules/<key>/migrations/NNN_description.sql` and sets `"migrations": true` in its manifest. `scripts/migrate.sh` discovers and applies them **only when the module is enabled**. The `schema_migrations` table is stem-keyed, so relocating a migration between directories (e.g. from `migrations/game/` to `modules/game/migrations/`) never re-runs it on prod.
+
+Rules (enforced by the `BV1.R45` fitness check):
+- **Own your namespace** — every table must be prefixed `<key>_*`.
+- **Additive only** — `DROP TABLE`, `DROP COLUMN`, and destructive `ALTER` are rejected by the fitness check.
+- **Disable preserves data** — there is no down-migration; a disabled module's tables simply are never created (or are left untouched).
+
+---
+
+## Live module roster
+
+| Module | `contributes` | Seam ports | `coreVersion` |
+|---|---|---|---|
+| **`dev-box`** | routes: `box`; pollers: `box-lifecycle`; uiSections: `boxes` | provides `box.hasEverConnected`; listens `builder.box-reconcile-needed` | `^1.2.0` |
+| **`game`** | routes: `game`; rooms: `WorldRoom`/`QueueRoom` | provides `game.staticRoot`, `game.registerRooms`, `game.precreateWorldRoom` | `^1.4.0` |
+| **`discord`** | routes: `discord`, `bug-attachments`; pollers: `discord-bot` | provides `discord.isLinked`; consumes `ideas.capture` | `^1.4.0` |
+| **`art-pipeline`** | routes: `art-key`; disciplines: `artist`; skills: `otb-tile-generate` etc.; uiSections: `art` | provides `art.sharedKeyConfigured` | `^1.3.0` |
+| **`character-anim`** | skills: `otb-character-review` (prerequisite: `art-pipeline`) | — (declaration-only JS; runtime is the Python pipeline under `art/`) | `^1.4.0` |
+| **`memory`** *(core-domain, default-on; R72)* | routes: `memory`, `search`, `learnings` | — | `^1.5.0` |
+| **`grading`** *(core-domain, default-on; R73)* | routes: `grade` | provides `grade` | `^1.6.0` |
+| **`economy`** *(core-domain, default-on; R77)* | routes: `cost`, `leaderboard`, `reward` | provides `reward` | `^1.7.0` |
+| **`ideas`** *(core-domain, default-on; R78)* | routes: `inbox`, `blockers` | provides `ideas.capture` | `^1.8.0` |
+| **`security`** *(core-domain, default-on; R79)* | routes: `reports` | provides `security` | `^1.8.0` |
+| **`builder-settings`** *(core-domain, default-on; R80)* | routes: `settings` (the `/me/*-prefs` endpoints) | provides `builder-settings` | `^1.8.0` |
+| **`onboarding`** *(core-domain, default-on; R81)* | routes: `onboarding` (the `/access-requests` admission endpoints) | provides `onboarding` | `^1.9.0` |
+| **`sessions`** *(core-domain, default-on; R82)* | routes: `sessions` (the `/sessions` upload + cross-builder search/deep-dive) | — (registers NO port, like `memory`; *resolves* the economy `reward` port) | `^1.10.0` |
+| **`autonomy`** *(core-domain, default-on; R83)* | routes: `autonomy` (the `/autonomy/precheck`); pollers: `routine-timers` | — (registers NO port; reaches the lifecycle `tallyPeerVotes` via the doorway) | `^1.11.0` |
+| **`status-ui`** *(core-domain web surface, default-on; R84)* | webSurfaces: `{ host: "status.", dir: "public" }` (the status dashboard at `status.<apex>`) | — (registers NO port, NO routes; pure host-routed static surface) | `^1.11.0` |
+| **`hall-ui`** *(core-domain web surface, default-on; R85)* | webSurfaces: `{ host: "builders.", dir: "public" }` (the authenticated builders' hall) | — (registers NO port; keeps a DEDICATED serving block in `serve-internal.js`, unlike `status-ui`) | `^1.11.0` |
+| **`lifecycle`** *(core-domain, default-on; R86)* | routes: `tasks`, `claims`, `versions`, `done-when`, `goals`, `dependencies`, `gate-approvals`, `analytics` | provides `lifecycle` (createTask, classifyTaskKind, tallyPeerVotes, work-tracking reads); resolves `reward`, `onboarding` | `^1.12.0` |
+| **`provisioning`** *(default-off; [ADR 0111](adr/<redacted>.md))* | routes: `provisioning` (own+Archon rank-gated) | provides `provisioning.instanceState` | `^1.14.0` |
+
+Each module's `modules/<key>/CLAUDE.md` is the authoritative per-module reference (files, seams, tests, what is NOT in the module).
+
+> **Only <redacted> is the `security` module** ([ADR 0093](adr/<redacted>.md) §1, [02-module-map §5](design/modular-architecture/02-module-map.md)): the red-team / vulnerability reports + bounty (rank-gated Metic+). <redacted> — the `permission-path-check`/`route-rank-check` authz machinery AND the `/security/adr` threat-model reader + Archon-only `/security/docs` exploit-detail store (`src/bongos/routes/security.js`, backed by the core `db.js` `security_docs` queries) — stays kernel.
+
+> **`character-anim` is a declaration-only module** ([ADR 0088](adr/<redacted>.md)): consistent-character generative animation. Its manifest contributes the `otb-character-review` skill and declares the `art-pipeline` prerequisite; it has no routes/seams/migrations. The runtime — the contract entry point `art/pipeline/character_anim_module.py` (`animate(model-sheet + action-spec) → graded registered frame set + manifest`), with a config-driven rubric (a `character_anim` family) and a pluggable generator backend — lives under `art/` like the rest of the art pipeline, the same way `art-pipeline` keeps `art/` at the repo root.
+
+---
+
+## API surface — `src/modules.js`
+
+`src/modules.js` is now a **back-compat facade** over the loader. Its exports are stable and unchanged:
+
+| Export | Behaviour |
+|---|---|
+| `isModuleEnabled(name)` | Gate a mount or feature. Throws on an unknown name (programmer error). |
+| `enabledModules()` | The resolved on-set (an array of enabled module keys). |
+| `enabledDisciplines()` | The union of `contributes.disciplines` across enabled modules. |
+| `clientModules()` | `{ enabled: {…booleans}, disciplines: […] }` — injected into hall/status HTML as `window.__MODULES__` and served at `GET /api/gds/public/modules`. Front-ends read it to hide UI sections for off modules. |
+| `resolveModules(opts)` | The pure resolver (unit-tested, zero I/O). |
+
+---
+
+## Module-author recipe
+
+### 1. Scaffold
+
+```sh
+bongos module new <key>
+```
+
+This creates `modules/<key>/` with:
+- `module.json` — a valid manifest seeded for the current `CORE_VERSION`.
+- `routes/<key>.js` — a sample route factory with a health GET and a comment explaining the rank-gate rule.
+- `migrations/` — empty directory.
+- `ui/` — empty directory.
+- `CLAUDE.md` — per-module reference explaining the boundary, the seam pattern, and what to keep out of the module.
+
+### 2. Write the module
+
+- Reach core only through `require('../../../src/module-api')`. Never deep-import core internals.
+- Every write route: `api.requireRank('metic')` (or a higher rank). The fitness check enforces this.
+- Register seam ports/listeners in the route factory (guarded by `api.seams.hasProvider` to survive re-instantiation in tests).
+- Put DB tables in `modules/<key>/migrations/NNN_*.sql`, namespaced `<key>_*`.
+
+### 3. Declare
+
+Update `module.json`:
+- Set `coreVersion` to `^<CORE_VERSION>` (the current doorway version).
+- Declare everything the module contributes in `contributes`.
+- List ports under `provides`/`consumes`.
+
+### 4. Enable
+
+Add the module to `config/modules.json`:
+
+```json
+{ "modules": { "<key>": true } }
+```
+
+Or via env: `<PREFIX>_MODULE_<KEY>=1`. The loader discovers and mounts it on next boot — no core file changes.
+
+### 5. Verify
+
+Run `bongos upgrade` to confirm coreVersion compatibility, then `node scripts/gds/fitness.js` to confirm the boundary checks pass. The `unit` CI job runs fitness on every PR.
+
+## Carving an existing core domain (the `db.js` per-domain pattern)
+
+Most BONGOS-V1 module work is not scaffolding a *new* module — it's **carving an existing core domain out of the monolith** (ADR 0091, criterion C7). The reference carve is the kernel slice `src/bongos/db-kernel.js` (BV1.R69); the feature precedents are `modules/discord/db.js` + `modules/game/db.js`. Every later carve (memory R72, grading R73, …) copies this recipe. The invariant is **OTB byte-identical** at every step — you are *moving* code, not changing behavior.
+
+1. **Identify the slice.** The domain's files (`src/bongos/<domain>*.js`) + its query cluster inside `src/bongos/db.js`. Confirm cohesion: who reads/writes its tables, and does anything in *core* still need those queries (a reader that stays core ⇒ a vendored twin, below).
+2. **Create `modules/<key>/db.js`.** `require('../../src/module-api')` only; pull `pool` (and `withTx` for multi-statement writes) off the doorway. Move the domain's query functions verbatim. Re-export any **kernel** helper the module consumes (`insertAuditLog`, `getBuilderById`, `LIVE_RANK_LADDER`) straight off the doorway so a single `db.*` namespace serves both halves.
+3. **Delete from core.** Remove the moved functions from `src/bongos/db.js` so the monolith shrinks. If a function genuinely lives in the kernel (identity/audit/rank/tx), it goes to `src/bongos/db-kernel.js` and `db.js` re-exports it (so the 23 importers stay byte-identical) — that is the db-kernel reference carve, not a module carve.
+4. **Vendored twin when core still needs it.** If a core file *also* calls a moved query (e.g. `routes/me.js` reading a builder's art key), core keeps its own copy reading the same table and the module vendors its own — a module can never import core, and core can never import the module (the discord `getDiscordLink` precedent). Note the twin in the module's `CLAUDE.md`.
+5. **Capabilities the lifecycle invokes go behind a kernel PORT,** never a direct import: the providing module `registerProvider('<cap>', fn)` at boot; the lifecycle `resolve('<cap>')(…)` at call time (R73 does this for `grade`).
+6. **Verify byte-identical.** `node --check` each file; run the domain's `tests/*.mjs` + `tests/module_api.mjs` (the doorway surface contract) + `node scripts/gds/fitness.js`; regenerate the repo-map (`node scripts/gds/gen-repo-map.js`) since `db.js` exports changed.

package/docs/onboarding/browser-terminal-guide.md

@@ -0,0 +1,73 @@
+# Building from a Chromebook, iPad, or phone (the browser terminal)
+
+*Plain-language how-to for builders on a device that can't run the Claude Code desktop app.*
+
+Most builders run Claude Code in the **desktop app** (Mac or Windows). But you don't need it. If all you have is a **Chromebook, iPad, or phone** — anything with a web browser — you can still build, because your dev box serves its own **terminal in a browser tab**, and from there you switch to driving the box from the Claude app. This is the **Remote Control** path.
+
+You never install anything and you never touch SSH. It's two things: open a link, then sign in.
+
+> **On a Mac or Windows laptop?** You don't need this page — use the desktop app instead ([claude.com/download](https://claude.com/download)); it's the smoother path. This guide is only for browser-only devices.
+
+## What you'll do, at a glance
+
+1. Ask for your box and its terminal link (**`/builder-box`**).
+2. Open the link and sign in.
+3. Start Claude in the terminal and sign in once.
+4. Switch to **Remote Control** so you can work from the Claude app.
+
+That's it. Steps 1–3 are a one-time launchpad; after that you live in the Claude app.
+
+## Step 1 — Get your box and the terminal link
+
+In a Claude session, run **`/builder-box`**. It's your box's control panel — it will:
+
+- **wake or create your box** hands-off if it isn't already running (you never wait on an operator), and
+- give you your **terminal link** and a **one-time password** once the box is up.
+
+If the box was asleep, give it about a minute to come up, then run `/builder-box` again to read the link. (Under the hood `/builder-box` uses the box's own web terminal, published to the hall — you don't need any of that detail; just run the command.)
+
+## Step 2 — Open the link and sign in
+
+1. Open the **terminal link** in any browser tab.
+2. A small sign-in box appears. Enter:
+   - **Username:** `otb`
+   - **Password:** the one-time password `/builder-box` gave you.
+3. You're now looking at a terminal running on your box, already in your project folder.
+
+## Step 3 — Start Claude in the terminal
+
+In that terminal, type:
+
+```
+claude
+```
+
+and press Enter. The first time, it walks you through a normal browser sign-in (and may ask you to trust the folder once — say yes). When it finishes, you're in a real, interactive Claude Code session on your box. This first sign-in is the whole reason the browser terminal exists: a real person at a real browser can complete the login that a headless setup never could.
+
+## Step 4 — Switch to Remote Control (the daily surface)
+
+The terminal is a **launchpad, not where you'll live.** Once Claude is running in the terminal, run this **inside that session**:
+
+```
+/remote-control
+```
+
+It prints a **pairing link**. Open that link and you can now drive your box straight from the **Claude web or mobile app** — a much nicer surface than the terminal tab. From here on, that's where you work; the terminal was just where you logged in.
+
+> ⚠️ **Use the `/remote-control` slash command from inside a running Claude session — not a standalone `claude rc` command in the shell.** The standalone version mis-reads folder trust and fails; starting Remote Control from within an already-signed-in session is the path that works.
+
+## Good to know
+
+- **Closing the terminal tab ends the session and closes the box.** That's expected — it's how the session cleans up. Your work that's committed/shipped is safe; the box itself just shuts down.
+- **The box sleeps when idle and wakes on demand.** Next time, start again at Step 1 — `/builder-box` wakes it and hands you a fresh link.
+- **You also get a live game preview.** If your box is on the stable-hostname setup, your terminal link looks like `https://term-<you>.example.com`; your private game preview (the **sandbox**) is the same address with `term-` swapped for `sandbox-` — `https://sandbox-<you>.example.com`. Run **`/builder-stage`** to push your current edits there and review a change in a browser before you ship it. (See "Your own dev box" in the [primer](primer.md).)
+
+## If something isn't working
+
+- **No link yet?** The box may still be waking. Wait ~1 minute after `/builder-box` says it's starting, then run `/builder-box` again.
+- **Password rejected?** Re-run `/builder-box` to get a fresh link + password — the box republishes them when it restarts.
+- **Brand-new to the project on a browser-only device?** Getting the very first box onto a pure browser-only device can need a one-time assist (there's a known first-boot gap for a device with no terminal at all). If `/builder-box` can't hand you a link, ask an Archon to help seed your box once; after that the browser flow works on its own.
+
+---
+
+*Deeper detail (the systemd units, the Cloudflare tunnel, operator setup, and end-to-end verification) lives in the operator recipe [`docs/recipes/managed-settings-remote-control.md`](../recipes/managed-settings-remote-control.md) (Part 2) and [ADR 0038](../adr/<redacted>.md) / [ADR 0040](../adr/<redacted>.md). This page is the builder-facing summary of that flow.*

package/docs/onboarding/diagrams/01-task-lifecycle.mmd

@@ -0,0 +1,28 @@
+---
+title: Task lifecycle — from backlog to shipped  (AUTO-GENERATED from live facts — do not hand-edit; see scripts/gds/gen-diagrams.js)
+---
+stateDiagram-v2
+    [*] --> backlog: task created
+    backlog --> ready: deps shipped / promote
+    ready --> active: /builder-claim
+    active --> blocked: blocker filed
+    blocked --> active: blocker resolved
+    active --> ready: /builder-release (no credits)
+    active --> completed: /builder-ship: declared done + smoke tests
+    completed --> confirmed: grader passes  ◀ CREDITS AWARDED HERE
+    confirmed --> shipped: CI + gate-review → auto-merge + deploy
+    backlog --> abandoned: dropped
+    shipped --> [*]: live in production
+    note right of confirmed
+        Landing (confirmed→shipped): the PR must pass CI
+        (tests + secret scan + gate-review), then the server
+        auto-merges and main deploys — nobody pushes main by
+        hand. A stalled green PR is swept in ~5 min; /merge-mode
+        is the manual fallback.
+        --
+        What may AUTO-merge, by what the change touches:
+        - normal work (game / art / docs / tests): any rank
+        - a protected gate surface: Metic+ only;
+          Xenos / Thetes wait for an Archon
+        - the safety core (hard floor): always an Archon
+    end note

package/docs/onboarding/diagrams/02-rank-ladder.mmd

@@ -0,0 +1,54 @@
+---
+title: Builder rank ladder — live vs reserved  (AUTO-GENERATED from live facts — do not hand-edit; see scripts/gds/gen-diagrams.js)
+---
+flowchart TB
+    LEGEND["● LIVE (enforced by builders.rank)   ○ reserved (enum value, no wiring yet)"]
+    subgraph B_divine["Divine — above the system"]
+        direction TB
+        r_olympian["○ olympian — reserved"]
+        r_hermes["○ hermes — reserved"]
+        r_olympian --> r_hermes
+        r_oracle["○ oracle — reserved"]
+        r_hermes --> r_oracle
+        r_demigod["○ demigod — reserved"]
+        r_oracle --> r_demigod
+    end
+    subgraph B_citizen["Citizen — the working ladder"]
+        direction TB
+        r_archon["● archon — LIVE"]
+        r_strategos["○ strategos — reserved"]
+        r_archon --> r_strategos
+        r_boule["○ boule — reserved"]
+        r_strategos --> r_boule
+        r_aristoi["○ aristoi — reserved"]
+        r_boule --> r_aristoi
+        r_hippeis["○ hippeis — reserved"]
+        r_aristoi --> r_hippeis
+        r_zeugitai["○ zeugitai — reserved"]
+        r_hippeis --> r_zeugitai
+    end
+    B_divine --> B_citizen
+    subgraph B_outsider["Outsider / sub-citizen — sandboxed"]
+        direction TB
+        r_metic["● metic — LIVE"]
+        r_thetes["○ thetes — reserved"]
+        r_metic --> r_thetes
+        r_xenos["● xenos — default for new builders, LIVE"]
+        r_thetes --> r_xenos
+        r_periokoi["○ periokoi — reserved"]
+        r_xenos --> r_periokoi
+        r_doulos["○ doulos — reserved"]
+        r_periokoi --> r_doulos
+        r_helot["○ helot — reserved"]
+        r_doulos --> r_helot
+    end
+    B_citizen --> B_outsider
+    subgraph PERMS["Permissions — server-enforced (auth.requireRank, no caching; ADR 0016)"]
+        direction TB
+        P_archon["archon: create/promote/PATCH tasks · version close · grant ranks · override claims"]
+        P_metic["metic: claim any task · idea triage · blocker review · planning/priority · file red-team; CANNOT create tasks or grant ranks"]
+        P_default["xenos (default): claim ONLY newcomer_friendly tasks + ship/release OWN work · log cost · capture learnings · file blockers+ideas; CANNOT create/edit tasks or touch others' claims"]
+    end
+    r_archon -.-> P_archon
+    r_metic -.-> P_metic
+    r_xenos -.-> P_default

package/docs/onboarding/diagrams/03-drachmae-karma.mmd

@@ -0,0 +1,37 @@
+---
+title: Drachmae & karma — where each comes from, where each goes  (AUTO-GENERATED from live facts — do not hand-edit; see scripts/gds/gen-diagrams.js)
+---
+flowchart LR
+    subgraph CURRENCY["DRACHMAE  (the builder reward — equity / reputation, a stake, not a spendable currency)"]
+        direction TB
+        D_TOKEN["Ship a SESSION — the main reward\nround(true_cost_usd × 1.20) cents — cost-plus on real token spend\n(LIVE: priced server-side from token counts; ADR 0054, idempotent per session)"]
+        D_SHIP["Confirm a TASK\ncredits_reward × kind multiplier (0.8–1.5×)\n+ 25% idea-promotion bonus to the capturer\n(LIVE: ADR 0023)"]
+        D_ACH["Unlock an achievement\nachievements.credit_bonus (LIVE: 9 seeded)\n+ small net-negative-ship bonus"]
+        D_BOUNTY["Red-team / security bounty\ndrachmae payout by severity\n(rate card LIVE: R65 #284 — src/bongos/security.js + shown on /builders;\nawarding still PLANNED: R67 #286 + vulnerability_reports R63 #282)"]
+
+        D_BAL["builders.total_credits\n(running balance per builder)"]
+
+        D_TOKEN --> D_BAL
+        D_SHIP --> D_BAL
+        D_ACH --> D_BAL
+        D_BOUNTY -.PLANNED.-> D_BAL
+
+        D_SPEND["Spent on: nothing yet.\nDrachmae are EQUITY / reputation — a stake, not a\nspendable currency. They persist losslessly across exit (migration 025)."]
+        D_BAL --> D_SPEND
+    end
+
+    subgraph KARMA["KARMA  (separate signal — partially live)"]
+        direction TB
+        K_VOTE["Builder-on-builder upvote / downvote\non CONFIRMED work\n(LIVE: R25 #245, anti-self-vote)"]
+        K_PROP["Boost on criterion-proposal ratification\n(LIVE: R32 #248, cross-link C5→C2)"]
+        K_BAL["Per-builder karma score"]
+        K_SURF["Surfaced on profile + sortable\non leaderboard (LIVE: R26 #246)"]
+
+        K_VOTE --> K_BAL
+        K_PROP --> K_BAL
+        K_BAL --> K_SURF
+    end
+
+    note1["Drachmae measure OUTPUT (work shipped) — most of it now a cost-plus reward on real token spend.\nKarma measures PEER TRUST (how others rate your work); it does NOT gate rank promotions.\nBoth are reputation; neither is a spendable currency today.\nSeparately, an Archon can set a per-builder monthly budget cap to limit SPEND — but builders are uncapped by default (src/bongos/cost.js)."]
+    CURRENCY --- note1
+    KARMA --- note1

package/docs/onboarding/diagrams/04-architecture.mmd

@@ -0,0 +1,51 @@
+---
+title: The complete architecture — where your work runs and how it reaches production  (AUTO-GENERATED from live facts — do not hand-edit; see scripts/gds/gen-diagrams.js)
+config:
+  layout: elk
+---
+flowchart TB
+    subgraph DEVICE["YOUR DEVICE — only the screen lives here"]
+        APP["Claude desktop app or browser tab\n(shows files · sends your messages · holds NO code)"]
+    end
+
+    subgraph BOX["DEV BOX — a machine WE create on DigitalOcean (gated · revocable · audited; Metic+ may instead clone locally)"]
+        WORKER["Claude Code WORKER\n(opens files · runs commands · runs the /builder-* skills)"]
+        CODE["the code — git clone + per-builder worktrees (.claude/worktrees/*)\nfor sub-Metic builders it lives ONLY here · CLAUDE.md is DESCRIPTIVE only"]
+        LOCAL["local ~/.claude memory\nMAP = MEMORY.md — a one-line index loaded EVERY session\n(a guard + auto-tidy keep it light; ADR 0074)\n+ drawer of full notes, loaded only on demand"]
+        ORIGIN["credential-less git origin\n(NO GitHub push secret on the box — by design)"]
+        BOXTOK["box-scoped GDS token\n(deny-by-default: bootstrap endpoints only;\nrejected for branch upload → re-auth first — LIVE)"]
+        PREVIEW["sandbox preview server on :3000\n→ a per-builder sandbox URL (LIVE)"]
+        SWITCH["on / off + browser terminal\n(desktop app LIVE · ttyd-over-tunnel LIVE)"]
+    end
+
+    subgraph SERVER["THE SERVER — amazonprimea.com (the authority AND production)"]
+        API["/api/gds/* (same Node process as the game)"]
+        DB["Postgres — tasks · claims · versions · builders.rank\ncredit_log · grades · idea_inbox · builder_memory\n(KING for work-state + permissions; CLAUDE.md only describes it)"]
+        RANK["auth.requireRank — checked per request, NO caching\n(ADR 0016: a demotion takes effect on the next request)"]
+        SRVMEM["server-side builder_memory store\nLIVE: per-builder · isolated · Archon-audited forensic read\nyour memory follows you across machines & worktrees\n/recall fetches only the relevant subset (ADR 0060)\n(R54 / R55 / R56 / R57 — all shipped)"]
+        PUSHTOK["server-held push credential\n(GitHub App, short-lived tokens — the box never holds it)"]
+    end
+
+    subgraph GH["GITHUB — the code repository (github.com/lars589/amazonprimea)"]
+        MAIN["branch-protected main\n(no direct push; PR + required checks only)"]
+        ACTIONS["GitHub Actions — deploy-prod.yml"]
+    end
+
+    GAME["the live game — amazonprimea.com\n(same server · same Node process as /api/gds/*)"]
+
+    APP -->|"1 · toggle box on / open terminal"| SWITCH
+    SWITCH --> WORKER
+    WORKER -->|"2 · edit + commit"| CODE
+    WORKER -->|"3 · re-auth in browser"| API
+    WORKER -->|"4 · upload branch as a git bundle"| API
+    API -->|"5 · push + open PR + auto-merge (LIVE)"| MAIN
+    MAIN -->|"6 · merge triggers deploy (LIVE)"| ACTIONS
+    ACTIONS -->|"7 · deploy (no droplet key on any box)"| GAME
+    PUSHTOK -.-> API
+    ORIGIN -. "direct push blocked" .-> MAIN
+    API -. "claim / ship / cost" .-> WORKER
+    LOCAL -->|"sync on ship (push)"| SRVMEM
+    SRVMEM -->|"pull on session start"| LOCAL
+
+    NEXT["The whole box → production path is LIVE and hardware-verified end-to-end (1027 · 1028)."]
+    GAME --- NEXT

package/docs/onboarding/diagrams/05-versioning.mmd

@@ -0,0 +1,29 @@
+---
+title: Versioning + planning sessions  (AUTO-GENERATED from live facts — do not hand-edit; see scripts/gds/gen-diagrams.js)
+---
+flowchart TB
+    PS["/planning-session → done_when_criteria + tasks (with dependencies) + rank → seed the work pool"]
+    PS --> POOL["Version task pool (backlog/ready)"]
+    POOL --> VERSIONS
+    subgraph VERSIONS["Every task inherits its version; role/discipline is the work-type axis"]
+        direction TB
+        v_V1["V1 — shipped"]
+        v_PMS_V1["PMS-V1 — shipped"]
+        v_V1 --> v_PMS_V1
+        v_PMS_V2["PMS-V2 — shipped"]
+        v_PMS_V1 --> v_PMS_V2
+        v_GDS_V3["GDS-V3 — shipped"]
+        v_PMS_V2 --> v_GDS_V3
+        v_V2["V2 — planning"]
+        v_GDS_V3 --> v_V2
+        v_V3["V3 — planning"]
+        v_V2 --> v_V3
+        v_GDS_V4["GDS-V4 — frozen"]
+        v_V3 --> v_GDS_V4
+        v_BONGOS_V1["BONGOS-V1 — building"]
+        v_GDS_V4 --> v_BONGOS_V1
+    end
+    VERSIONS --> CLOSE["Version close — all done_when_criteria satisfied"]
+    CLOSE --> ARCHIVE["Archive scope to limitations/*.md; status=shipped"]
+    ARCHIVE --> REVIEW["Guided review before next version becomes king"]
+    REVIEW --> PS