@bongos/core 1.17.0 → 1.17.2

package/docs/file-map.md

@@ -147,7 +147,7 @@
 │       ├── gen-file-map.js      ← ADR 0066 ([#1276](https://example.com/builders#/task/1276)): generates the `.claude/skills/` + `.claude/scheduled-tasks/` sections of docs/file-map.md from disk; per-entry notes come from docs/file-map.notes.json; `--check` fails on drift OR a skill/routine with no note (CI gate via fitness.js); regenerated on deploy by ship.js regenerateFileMap()
 │       ├── fitness.js           ← Path C (ADR 0062 §9, [#1225](https://example.com/builders#/task/1225)): architecture fitness functions — core↔host import boundary (zero grandfathered exceptions as of R52/#1191), CLAUDE.md budget + nested-doc presence (ADR 0061), no route bypasses rank checks (reuses route-rank-check), repo-map freshness. Enforced in CI via tests/fitness.mjs (the `unit` gate). `node scripts/gds/fitness.js`
 │       ├── ship.js              ← resolve claim as shipped, award credits (`/builder-ship`); also uploads a secret-scrubbed session digest to the corpus (6D.1, ADR 0027); on a dev box runs the sandbox-first review gate before resolving (#927, ADR 0046)
-│       ├── package-core.js      ← package the core as a versioned, installable artifact + pin manifest (`bongos package-core`; R84, ADR 0100 §1, [#1688](https://example.com/builders#/task/1688)): isPublishable() selection + mirror redaction + fail-closed no-leak gate → dist/cloudbongos-core-<version>.{tgz,manifest.json}; version = src/module-api CORE_VERSION. Recipe: docs/recipes/packaging-the-core.md
+│       ├── package-core.js      ← package the core as a versioned, installable artifact + pin manifest (`bongos package-core`; R84, ADR 0100 §1, [#1688](https://example.com/builders#/task/1688)): isPublishable() selection + mirror redaction + fail-closed no-leak gate → dist/bongos-core-<version>.{tgz,manifest.json}; version = src/module-api CORE_VERSION. Recipe: docs/recipes/packaging-the-core.md
 │       ├── sandbox-stage.js     ← stage the working tree on the live game preview (box OR local) for browser review before ship; resolvePreviewContext picks the context (`/builder-stage`; #927, ADR 0046; local: task 1056)
 │       ├── local-preview.js     ← builder CLI for the LOCAL sandbox: start/stop/status/restart/logs/url of the game-only preview at http://localhost:3100 (`npm run preview`; task 1056)
 │       ├── local-preview-lib.js ← core of the local sandbox launcher (detached `node src/preview-server.js`, pid/health/port mgmt); shared by local-preview.js + sandbox-stage.js (task 1056)
@@ -170,7 +170,7 @@
 │       ├── gen-api-docs.js      ← ADR 0109: generates `docs/api/openapi.json` + `docs/api-reference.md` from the live route files via `route-rank-check.js` introspection, so the API reference cannot drift from what the server actually mounts
 │       ├── architect-audit.js   ← MAS Phase 5 (ADR 0024): the Architect's bounded first-principles `--scope`/`--paths` audit CLI → `docs/audits/`
 │       ├── module.js            ← `bongos module new <key>` scaffolder + module CLI utilities (ADR 0083)
-│       ├── upgrade.js           ← `bongos upgrade` — bump the installed `@cloudbongos/core` package version with doorway/coreVersion pre-checks (ADR 0108)
+│       ├── upgrade.js           ← `bongos upgrade` — bump the installed `@bongos/core` package version with doorway/coreVersion pre-checks (ADR 0108)
 │       └── newcomer-floor.js    ← deterministic on-claim replenisher for the evergreen newcomer chores (engineer/artist/ideator floor); no cron, restocks when one is claimed (task 1168)
 │
 ├── src/
@@ -364,23 +364,24 @@ tests/
 <!-- BEGIN GENERATED FILE-MAP .claude/scheduled-tasks/ (scripts/gds/gen-file-map.js — do not hand-edit; notes live in docs/file-map.notes.json) -->
 ```
 .claude/scheduled-tasks/
-├── bfg/SKILL.md                     ← (MAS Phase 6, ADR 0026) BFG hygiene + read-the-room + steward routine: doc-vs-reality checks, memory hygiene, cross-builder learning. Read-mostly.
-├── bfg-session-eval/SKILL.md        ← (6D.3, ADR 0027) BFG session-inefficiency evaluator: search the session corpus, deep-dive wasteful sessions (ceremony-vs-work + footguns), file systemic findings. Read-only.
-├── box-dormant-reclaim/SKILL.md     ← (#598/ADR 0031) daily: deprovision dev boxes parked past the dormant threshold (pings the builder). Drives `box.js sweep-dormant --apply`. Control-plane only.
-├── box-idle-suspend/SKILL.md        ← (#598/ADR 0031) every 15 min: snapshot-and-park dev boxes idle past the idle threshold. Drives `box.js sweep-idle --apply`. Control-plane only.
-├── dep-audit-nightly/SKILL.md       ← autonomous nightly dependency-vulnerability scan on the droplet (`scripts/security/dep-audit.js --report-mode=nightly`) across npm + the devbox app
-├── diagram-drift/SKILL.md           ← belt-and-braces backstop for the onboarding diagrams — all five auto-regenerate on deploy, so this only flags any residual staleness
-├── idea-triage-nightly/SKILL.md     ← nightly autonomous walk of the idea_inbox; promotes high-confidence bugs/cleanups, discards obvious noise, defers ambiguous ideas
-├── main-audit/SKILL.md              ← (SEC #863 / ADR 0043) nightly post-push audit of `main` — flags commits where a sub-Metic builder edited a permission-sensitive surface
-├── newcomer-floor/SKILL.md          ← deterministic on-claim replenisher for the three evergreen newcomer chores (engineer/artist/ideator) — no cron; restocks when one is claimed (task 1168)
-├── newcomer-generator/SKILL.md      ← keep the newcomer_friendly task queue populated (C1) — deterministic generator tops the queue back up to its floor
-├── overnight-builder/SKILL.md       ← (#358) autonomous overnight session-runner: claims the highest-priority autonomous-fit task, works it in a fresh sub-agent, ships, re-polls. Archon-only. Runbook: docs/recipes/overnight-builder.md
-├── overnight-code-review/SKILL.md   ← nightly read-only code review; routes each finding into the idea_inbox (one row per finding; title prefix `[review YYYY-MM-DD]`)
-├── peer-vote-tally/SKILL.md         ← (V3.R25 / #245, C2) weekly tally of builder-on-builder peer votes into karma; folds votes ≥7 days old into karma_log
-├── repo-simplify-sweep/SKILL.md     ← weekly autonomous repo-cleanliness janitor: runs repo-metrics, files dead-code findings to the idea_inbox, auto-fixes the narrow safe class (unused vars/imports)
-├── security-review-weekly/SKILL.md  ← (V3.R69 / #288) autonomous weekly security-state review — surfaces stale vulnerability_reports + other stale-security signals
-├── skill-usage-review/SKILL.md      ← nightly skill-usage feedback loop: aggregates 24h of skill invocations, detects friction (over-invocation, errors), files findings
-└── stale-claim-release/SKILL.md     ← auto-release GDS claims whose session_pulses heartbeat went silent ≥ GDS_STALE_CLAIM_HOURS (default 6h); runs every 15 min on the droplet
+├── bfg/SKILL.md                       ← (MAS Phase 6, ADR 0026) BFG hygiene + read-the-room + steward routine: doc-vs-reality checks, memory hygiene, cross-builder learning. Read-mostly.
+├── bfg-session-eval/SKILL.md          ← (6D.3, ADR 0027) BFG session-inefficiency evaluator: search the session corpus, deep-dive wasteful sessions (ceremony-vs-work + footguns), file systemic findings. Read-only.
+├── box-dormant-reclaim/SKILL.md       ← (#598/ADR 0031) daily: deprovision dev boxes parked past the dormant threshold (pings the builder). Drives `box.js sweep-dormant --apply`. Control-plane only.
+├── box-idle-suspend/SKILL.md          ← (#598/ADR 0031) every 15 min: snapshot-and-park dev boxes idle past the idle threshold. Drives `box.js sweep-idle --apply`. Control-plane only.
+├── core-update-subscription/SKILL.md  ← (task 2150 / ADR 0136) daily: patch-only auto-upgrade of subscribed consumer instances (config/update-subscriptions.json) via `bongos upgrade --registry` with auto-rollback. Deterministic; opt-in + autonomy-gated (default OFF). Control-plane only.
+├── dep-audit-nightly/SKILL.md         ← autonomous nightly dependency-vulnerability scan on the droplet (`scripts/security/dep-audit.js --report-mode=nightly`) across npm + the devbox app
+├── diagram-drift/SKILL.md             ← belt-and-braces backstop for the onboarding diagrams — all five auto-regenerate on deploy, so this only flags any residual staleness
+├── idea-triage-nightly/SKILL.md       ← nightly autonomous walk of the idea_inbox; promotes high-confidence bugs/cleanups, discards obvious noise, defers ambiguous ideas
+├── main-audit/SKILL.md                ← (SEC #863 / ADR 0043) nightly post-push audit of `main` — flags commits where a sub-Metic builder edited a permission-sensitive surface
+├── newcomer-floor/SKILL.md            ← deterministic on-claim replenisher for the three evergreen newcomer chores (engineer/artist/ideator) — no cron; restocks when one is claimed (task 1168)
+├── newcomer-generator/SKILL.md        ← keep the newcomer_friendly task queue populated (C1) — deterministic generator tops the queue back up to its floor
+├── overnight-builder/SKILL.md         ← (#358) autonomous overnight session-runner: claims the highest-priority autonomous-fit task, works it in a fresh sub-agent, ships, re-polls. Archon-only. Runbook: docs/recipes/overnight-builder.md
+├── overnight-code-review/SKILL.md     ← nightly read-only code review; routes each finding into the idea_inbox (one row per finding; title prefix `[review YYYY-MM-DD]`)
+├── peer-vote-tally/SKILL.md           ← (V3.R25 / #245, C2) weekly tally of builder-on-builder peer votes into karma; folds votes ≥7 days old into karma_log
+├── repo-simplify-sweep/SKILL.md       ← weekly autonomous repo-cleanliness janitor: runs repo-metrics, files dead-code findings to the idea_inbox, auto-fixes the narrow safe class (unused vars/imports)
+├── security-review-weekly/SKILL.md    ← (V3.R69 / #288) autonomous weekly security-state review — surfaces stale vulnerability_reports + other stale-security signals
+├── skill-usage-review/SKILL.md        ← nightly skill-usage feedback loop: aggregates 24h of skill invocations, detects friction (over-invocation, errors), files findings
+└── stale-claim-release/SKILL.md       ← auto-release GDS claims whose session_pulses heartbeat went silent ≥ GDS_STALE_CLAIM_HOURS (default 6h); runs every 15 min on the droplet
 ```
 <!-- END GENERATED FILE-MAP .claude/scheduled-tasks/ -->
 

package/docs/handoff-template.md

@@ -65,9 +65,9 @@ If even one of these is false, the claim is `[verified-smoke]` or `[implemented-
 
 ### Diagram backstop (task [#357](https://example.com/builders#/task/357); conceptual diagrams auto-generated [#436](https://example.com/builders#/task/436))
 
-If your change touched anything the onboarding diagrams describe — the **rank enum or which ranks are wired** (`requireRank`, `builders.rank` default, exit/assign paths), the **task-status set**, the **versions** (id/track/status), or the **complete-architecture** (the ADR 0024 memory chain + the dev-box → production ship flow) **/ drachmae-karma** models (which now flip per the **shipped** status of their backing tasks) — then before shipping:
+If your change touched anything the onboarding diagrams describe — the **rank enum or which ranks are wired** (`requireRank`, `builders.rank` default, exit/assign paths), the **task-status set**, the **versions** (id/track/status), or the **complete-architecture** (the ADR 0024 memory chain + the dev-box → production ship flow) **/ example-karma** models (which now flip per the **shipped** status of their backing tasks) — then before shipping:
 
-- **All five diagrams are auto-generated** by `scripts/gds/gen-diagrams.js` — run it (`node scripts/gds/gen-diagrams.js`) and confirm the result looks right; **do not hand-edit any `.mmd`**. The mechanical three (`01-task-lifecycle`, `02-rank-ladder`, `05-versioning`) regenerate from migrations + the public version API. The conceptual two (`03-drachmae-karma`, `04-architecture`) regenerate from the **authenticated** `/tasks/:id` status of their backing tasks (and 03's seeded-achievement count); if no session is present the generator skips them cleanly. Rendering produces both `.svg` (the pannable viewer asset) and `.png` (fallback).
+- **All five diagrams are auto-generated** by `scripts/gds/gen-diagrams.js` — run it (`node scripts/gds/gen-diagrams.js`) and confirm the result looks right; **do not hand-edit any `.mmd`**. The mechanical three (`01-task-lifecycle`, `02-rank-ladder`, `05-versioning`) regenerate from migrations + the public version API. The conceptual two (`03-example-karma`, `04-architecture`) regenerate from the **authenticated** `/tasks/:id` status of their backing tasks (and 03's seeded-achievement count); if no session is present the generator skips them cleanly. Rendering produces both `.svg` (the pannable viewer asset) and `.png` (fallback).
 - To change a diagram's **layout or wording**, edit the matching template function in `gen-diagrams.js` — not the `.mmd`. `assertions.json` is rebuilt by the generator in lockstep, so you don't hand-maintain it.
 
 The `diagram-drift` routine is a belt-and-braces backstop (it should find nothing once the generator has run), but the point is not to rely on it — running `gen-diagrams.js` is part of the change.

package/docs/modules-contract.md

@@ -95,16 +95,23 @@ Every module must have a `module.json` at its root (`modules/<key>/module.json`)
   },
   "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.
+  "prerequisites": { "modules": [] },   // OPTIONAL. Other modules that must be enabled first.
+  "dependencies": { "discord.js": "^14.26.4" } // OPTIONAL. External npm deps this module needs at runtime.
 }
 ```
 
 An unknown key throws at validate time — typos fail loud (top-level attribution fields have no closed allowlist; only `contributes` sub-keys do).
 
+### `dependencies` — a module's own npm deps ([ADR 0138](adr/<redacted>.md))
+
+`@bongos/core` ships lean — its synthesized `package.json` declares only `express` + `pg` ([ADR 0108](adr/<redacted>.md)). A bundled module that needs an external npm package at runtime (e.g. `discord` → `discord.js`) declares it in its own `module.json` `dependencies` (`{ "<npm-name>": "<semver-range>" }`, schema-validated). **Core does not carry it**, so the *consumer* must — greenfield `bongos init` composes the ENABLED modules' declared deps into the instance `package.json` (`enabledModuleDeps` → `buildInstancePackageJson`; an explicit pre-existing pin wins, `@bongos/core` is always set), and the R89 cutover preserves the monolith's existing dependency closure. If a module needs a dep and neither declares it nor is it in the consumer's closure, an instance that enables the module crashes at boot — so **declare it here**.
+
 **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`.
 
+**`bongos module submit <key> [--sign-off "Name <email>"]`** ([ADR 0107](adr/<redacted>.md) §1) re-runs the §4 pre-check + requires a sign-off, then packages the module (manifest + a full file snapshot + the sign-off) and files it into the rank-gated (metic+archon) upstreaming review queue via `POST /modules/:key/submit` — the same route the hall "Modules" tab's submit button calls. Refuses (exit 1) if the pre-check fails or no sign-off can be found/recorded. The queue currently lives in **this instance's own DB**, not a live call to the extracted core repo — see [ADR 0135](adr/<redacted>.md) for why, and `GET /modules/submissions` to read it back.
+
 ---
 
 ## The loader — `src/module-loader/loader.js`

package/docs/onboarding/diagrams/README.md

@@ -11,7 +11,7 @@ Five flowcharts that explain the Game Development System (GDS) to a new builder
 | Diagram | What drives its state |
 |---|---|
 | `01-task-lifecycle` · `02-rank-ladder` · `05-versioning` (**mechanical**) | The task-status set + rank enum/wiring (read from `migrations/` + `src/bongos/`) and the live version set (production API). No auth needed — always regenerate. |
-| `03-drachmae-karma` · `04-architecture` (**conceptual**) | Each feature-piece is **LIVE iff its backing GDS task is `shipped`**, plus 03's "N seeded" count from the achievements seed in `migrations/`. These read the **authenticated** `/tasks/:id` status, so when no GDS session is available (headless run, no creds) the generator **skips** 03/04 and leaves them untouched rather than emit wrong data. (04's device/box/server/GitHub *topology* is structural; only its LIVE/PLANNED markers — the memory chain + the box→prod ship-flow legs — are task-gated.) |
+| `03-example-karma` · `04-architecture` (**conceptual**) | Each feature-piece is **LIVE iff its backing GDS task is `shipped`**, plus 03's "N seeded" count from the achievements seed in `migrations/`. These read the **authenticated** `/tasks/:id` status, so when no GDS session is available (headless run, no creds) the generator **skips** 03/04 and leaves them untouched rather than emit wrong data. (04's device/box/server/GitHub *topology* is structural; only its LIVE/PLANNED markers — the memory chain + the box→prod ship-flow legs — are task-gated.) |
 
 The mechanical diagrams regenerate **on every deploy** (`ship.js` / `/merge-mode` run `gen-diagrams.js` before deploying; a changed diagram is committed and shipped automatically). The conceptual diagrams regenerate the same way whenever a session is present (the deploy host has one). The `diagram-drift` routine remains as a belt-and-braces backstop. So `/builders/diagrams` is never more than one deploy behind the live architecture.
 
@@ -28,7 +28,7 @@ The GDS is mid-build. These diagrams deliberately distinguish **what exists toda
 ## The five diagrams
 
 ### 1. Task lifecycle — backlog → shipped
-How a task moves from creation to production, and the exact edge where **credits/drachmae are awarded** (`completed → confirmed`, *not* at ship).
+How a task moves from creation to production, and the exact edge where **credits/example are awarded** (`completed → confirmed`, *not* at ship).
 
 ![Task lifecycle](01-task-lifecycle.png)
 
@@ -41,12 +41,12 @@ The 16-value reserved rank enum (migration 023) in three Greek bands, which rank
 
 Source: [`02-rank-ladder.mmd`](02-rank-ladder.mmd)
 
-### 3. Drachmae & karma — sourcing and spending
-Where each comes from and where each goes. Key facts: **drachmae = credits** (same thing, in-world name), they are **equity, not a spendable currency**, and the **primary source is now a cost-plus reward on each shipped session** — `round(true_cost × 1.20)` ([ADR 0054](../../adr/<redacted>.md)) — alongside per-task `credits_reward × kind multiplier` ([ADR 0023](../../adr/<redacted>.md)), achievements, and the (rate-card-live) security bounty. Karma is a separate peer-trust signal that does **not** gate rank promotions; its LIVE/PLANNED state tracks its backing tasks (R25/R32/R26). The full write-up is [`docs/onboarding/drachmae-and-karma.md`](../drachmae-and-karma.md).
+### 3. Example & karma — sourcing and spending
+Where each comes from and where each goes. Key facts: **example = credits** (same thing, in-world name), they are **equity, not a spendable currency**, and the **primary source is now a cost-plus reward on each shipped session** — `round(true_cost × 1.20)` ([ADR 0054](../../adr/<redacted>.md)) — alongside per-task `credits_reward × kind multiplier` ([ADR 0023](../../adr/<redacted>.md)), achievements, and the (rate-card-live) security bounty. Karma is a separate peer-trust signal that does **not** gate rank promotions; its LIVE/PLANNED state tracks its backing tasks (R25/R32/R26). The full write-up is [`docs/onboarding/example-and-karma.md`](../example-and-karma.md).
 
-![Drachmae and karma](03-drachmae-karma.png)
+![Example and karma](03-example-karma.png)
 
-Source: [`03-drachmae-karma.mmd`](03-drachmae-karma.mmd)
+Source: [`03-example-karma.mmd`](03-example-karma.mmd)
 
 ### 4. The complete architecture — where your work runs and how code reaches production
 One map of the whole system, merging the old "server ↔ repo ↔ memory" three-layer view with the dev-box → production ship flow. The four places Claude Code splits across — your **device** (screen only) · the **dev box** (the worker, the code, *and* your local memory dir) · the **server/droplet** (authority *and* production: Postgres, the server-side memory store, the push credential) · **GitHub** (branch-protected main + Actions) — plus two flows woven through it: the **per-builder memory layer** (ADR 0024 — local ↔ server, sync-on-ship / pull-on-start) and the **box → prod ship path** (a credential-less box re-auths and uploads its branch as a git bundle; the server pushes it with a GitHub App credential; the PR auto-merges and GitHub Actions deploys — no droplet key on any box). Every feature-piece + flow edge is LIVE/solid iff its backing task is `shipped`. Backing tasks: memory chain [#273](https://example.com/builders#/task/273)–[#276](https://example.com/builders#/task/276); dev box [#904](https://example.com/builders#/task/904)/[#774](https://example.com/builders#/task/774)/[#897](https://example.com/builders#/task/897)/[#919](https://example.com/builders#/task/919); box→prod [#1025](https://example.com/builders#/task/1025)/[#859](https://example.com/builders#/task/859)/[#1028](https://example.com/builders#/task/1028)/[#1027](https://example.com/builders#/task/1027) (all shipped → the map reads all-LIVE today). See [ADR 0024](../../adr/<redacted>.md) (cloneable memory), [ADR 0055](../../adr/<redacted>.md) (server-mediated publish), [ADR 0053](../../adr/0053-scoped-dev-box-session.md) (scoped box token), [ADR 0042](../../adr/<redacted>.md) (CI self-deploy), [ADR 0016](../../adr/<redacted>.md) (trust boundary).
@@ -78,7 +78,7 @@ Two mechanisms keep these honest as the system changes (added under [#356](https
    node .claude/scheduled-tasks/diagram-drift/check.js --file-idea
    ```
 
-`assertions.json` is the machine-readable record of what these diagrams claim about the live system (rank enum + wired ranks, task-status set, live versions, and the conceptual `architecture` + `drachmae_karma` piece→task slices). It is **rebuilt by `gen-diagrams.js` in lockstep with the diagrams**, so you no longer hand-maintain it; it stays as the drift checker's reference.
+`assertions.json` is the machine-readable record of what these diagrams claim about the live system (rank enum + wired ranks, task-status set, live versions, and the conceptual `architecture` + `example_karma` piece→task slices). It is **rebuilt by `gen-diagrams.js` in lockstep with the diagrams**, so you no longer hand-maintain it; it stays as the drift checker's reference.
 
 ## Regenerating the diagrams by hand
 

package/docs/onboarding/drachmae-and-karma.md

@@ -1,28 +1,28 @@
-# Drachmae & karma — how you get paid, and how you earn trust
+# Example & karma — how you get paid, and how you earn trust
 
 *The complete reference for the two reputation tracks in the GDS. The [primer](primer.md) gives you the one-paragraph version; this is the full picture, kept honest against the live system. ~8 minutes.*
 
-> **Source of truth.** The numbers live in the production database (`builders.total_credits`, `builders.karma`) and the rules live in code (`src/bongos/db.js`, `src/bongos/cost.js`). This doc *describes* them; where they disagree, the code wins. The two diagrams that visualize this — [task lifecycle](diagrams/01-task-lifecycle.png) and [drachmae & karma](diagrams/03-drachmae-karma.png) — are auto-generated from the same live facts.
+> **Source of truth.** The numbers live in the production database (`builders.total_credits`, `builders.karma`) and the rules live in code (`src/bongos/db.js`, `src/bongos/cost.js`). This doc *describes* them; where they disagree, the code wins. The two diagrams that visualize this — [task lifecycle](diagrams/01-task-lifecycle.png) and [example & karma](diagrams/03-example-karma.png) — are auto-generated from the same live facts.
 
 ---
 
 ## The 30-second version
 
-- **Drachmae** (the code calls them *credits*) are your **equity** in Off the Boats. You earn them by shipping work, and they only ever go up. They are a score and a stake — **not** a currency you spend on anything in-game.
-- The **headline change (June 2026):** most of your drachmae now come from a **cost-plus reward on each shipped session** — we pay you the real API cost of the work you did, **plus 20%**. Expensive, real work pays more than declaring a big number ever did.
+- **Example** (the code calls them *credits*) are your **equity** in Example. You earn them by shipping work, and they only ever go up. They are a score and a stake — **not** a currency you spend on anything in-game.
+- The **headline change (June 2026):** most of your example now come from a **cost-plus reward on each shipped session** — we pay you the real API cost of the work you did, **plus 20%**. Expensive, real work pays more than declaring a big number ever did.
 - **Karma** is a *separate* signal. It measures **peer trust** — how other trusted builders rate your work — not how much you shipped. It is surfaced on your profile and the leaderboard, and it feeds your "builder strength" score. It is **not** a gate on rank promotions.
 - A **monthly budget cap** ($50 by default) limits how much you can *spend*; it's the cost side of the same coin the reward is computed from.
 
 ---
 
-## Part 1 — Drachmae (credits)
+## Part 1 — Example (credits)
 
 ### What they are
 
-Drachmae are the in-world name for the `total_credits` counter on your builder row. The owner's framing ([ADR 0054](../adr/<redacted>.md)) is that **drachmae are equity** — units of ownership in the thing you're helping build. Practically, today, they are:
+Example are the in-world name for the `total_credits` counter on your builder row. The owner's framing ([ADR 0054](../adr/<redacted>.md)) is that **example are equity** — units of ownership in the thing you're helping build. Practically, today, they are:
 
 - **Append-only.** Every award is a row in `credit_log`; the `total_credits` counter is maintained by a database trigger. History is never rewritten — a correction is a new (sometimes negative) row, never an edit.
-- **Persistent across exit.** If you leave and come back, your drachmae are still there (migration 025). They are reputation, not a session balance.
+- **Persistent across exit.** If you leave and come back, your example are still there (migration 025). They are reputation, not a session balance.
 - **Not spendable.** There is no shop, no sink, nothing to buy with them. They are a *score and a stake*. (This may change in a future version; today it does not.)
 - **Public.** Your total is visible on the [builders' hall](https://example.com/builders) leaderboard.
 
@@ -35,7 +35,7 @@ There are several sources. They all land in the same `credit_log` and roll up in
 When you **ship** a session, the server looks at the LLM tokens that session actually burned, prices them, and pays you:
 
 ```
-drachmae = round( true_cost_usd × 1.20 )            // whole drachmae (1 drachma = $1)
+example = round( true_cost_usd × 1.20 )            // whole example (1 drachma = $1)
                                   └─ REWARD_MARGIN_PCT = 20 (a code constant in src/bongos/db.js)
 ```
 
@@ -47,7 +47,7 @@ The important details, because they're designed to be fair *and* un-gameable:
 - **Idempotent per session.** Re-shipping or retrying the same session is a true no-op — keyed on `session_id`, you can't get paid twice.
 - **Reversible.** A bad award is undone with a compensating negative `credit_log` row; the trigger nets it out. History stays intact.
 
-> **Why pay for cost at all — doesn't that reward waste?** It can, and that was accepted on purpose ([ADR 0054](../adr/<redacted>.md)). The guardrails are: you only get paid for sessions that *ship*; drachmae are *equity*, so padding your own cost dilutes a pool you hold (early builders self-police); and the [BFG session-inefficiency evaluator](../adr/<redacted>.md) already flags wasteful sessions, so a future version can discount the reward by an efficiency factor. The stated direction is to move toward market/bidding pricing once there's a real multi-builder pool.
+> **Why pay for cost at all — doesn't that reward waste?** It can, and that was accepted on purpose ([ADR 0054](../adr/<redacted>.md)). The guardrails are: you only get paid for sessions that *ship*; example are *equity*, so padding your own cost dilutes a pool you hold (early builders self-police); and the [BFG session-inefficiency evaluator](../adr/<redacted>.md) already flags wasteful sessions, so a future version can discount the reward by an efficiency factor. The stated direction is to move toward market/bidding pricing once there's a real multi-builder pool.
 
 #### 2. Per-task credits, adjusted by *kind* ([ADR 0023](../adr/<redacted>.md))
 
@@ -80,11 +80,11 @@ A ship whose committed diff **removes more lines than it adds** earns a small `s
 
 #### 6. Red-team / security bounty *(rate card live; awarding still landing)*
 
-There's a published payout rate-card by severity for red-team / security findings (shown on the hall, `src/bongos/security.js`). The **automatic** drachmae payout for a filed-and-confirmed vulnerability is still being wired up (tracked by [#286](https://example.com/builders#/task/286) + [#282](https://example.com/builders#/task/282)); the rates are real, the auto-pay isn't switched on yet.
+There's a published payout rate-card by severity for red-team / security findings (shown on the hall, `src/bongos/security.js`). The **automatic** example payout for a filed-and-confirmed vulnerability is still being wired up (tracked by [#286](https://example.com/builders#/task/286) + [#282](https://example.com/builders#/task/282)); the rates are real, the auto-pay isn't switched on yet.
 
 ### Where in the lifecycle credits land
 
-Drachmae are awarded at the **`completed → confirmed`** edge — when verification (smoke tests, and the grader when it's enabled) passes — **not** at the final ship/deploy. Releasing a task with `/builder-release` pays nothing.
+Example are awarded at the **`completed → confirmed`** edge — when verification (smoke tests, and the grader when it's enabled) passes — **not** at the final ship/deploy. Releasing a task with `/builder-release` pays nothing.
 
 ```
 active ──▶ completed ──▶ confirmed ──▶ shipped
@@ -103,7 +103,7 @@ We knowingly run two conventions on the same ledger ([ADR 0054](../adr/<redacted
 
 ## Part 2 — The monthly budget cap (the cost side)
 
-Drachmae are what you *earn*; the budget cap limits what you *spend*. They're linked, because the reward is computed from the same true cost the cap meters.
+Example are what you *earn*; the budget cap limits what you *spend*. They're linked, because the reward is computed from the same true cost the cap meters.
 
 Defined in `src/bongos/cost.js` (criterion C3, [#302](https://example.com/builders#/task/302)):
 
@@ -126,21 +126,21 @@ If a cap is set and you hit `over`, you're not in trouble — you've just reache
 
 ## Part 3 — Karma
 
-Karma (added in migration 040) is a **completely separate** counter from drachmae. Where drachmae measure *output* (work shipped), karma measures **peer trust** — how other builders, and the project's good-citizenship signals, rate the *way* you work.
+Karma (added in migration 040) is a **completely separate** counter from example. Where example measure *output* (work shipped), karma measures **peer trust** — how other builders, and the project's good-citizenship signals, rate the *way* you work.
 
 ### How karma is earned (and lost)
 
 - **Peer votes on confirmed work.** Builders upvote/downvote each other's confirmed tasks. Only **Metic-and-above** can cast a vote (`POST /api/gds/tasks/:id/vote` is rank-gated). Votes are **tallied weekly** into one net `peer_vote_weekly` karma entry per builder. There's an **anti-self-vote** guard and an anti-retaliation rule (a downvote can't dent your karma within the same week).
 - **Proposal ratification.** When a criterion-proposal you made is ratified, you get **+3 karma** (`proposal_ratified`).
 - **Idea promotion.** Promoting an idea into a real task awards karma to the capturer.
-- **It can go down.** The [BFG](../adr/<redacted>.md) good-citizenship corrections can apply a *non-positive* karma delta. Karma is a slower, more reflective signal than drachmae — you can ship fast and still lose karma if you break things.
+- **It can go down.** The [BFG](../adr/<redacted>.md) good-citizenship corrections can apply a *non-positive* karma delta. Karma is a slower, more reflective signal than example — you can ship fast and still lose karma if you break things.
 
 > Discord cheers don't count. Reaction "applause" in Discord is cosmetic and **never** mints karma — only rank-gated peer votes do ([ADR 0033](../adr/<redacted>.md)). Unranked enthusiasm can't manufacture trust.
 
 ### Where karma shows up
 
 - **Your profile card** on the hall shows your karma and its **30-day trend**, plus your recent karma feed (last 10 entries).
-- **The leaderboard** is sortable by karma (it still defaults to drachmae order).
+- **The leaderboard** is sortable by karma (it still defaults to example order).
 - **Builder strength.** Karma is one input (weight ~0.15) into the BFG's 0–100 "builder strength" score (`src/bongos/bfg.js`), alongside ship volume, grader pass-rate, and reliability.
 
 ### What karma is *not*
@@ -154,9 +154,9 @@ Karma is evidence an Archon *can weigh* when deciding a discretionary promotion,
 
 ---
 
-## Drachmae vs karma, side by side
+## Example vs karma, side by side
 
-| | **Drachmae** (credits) | **Karma** |
+| | **Example** (credits) | **Karma** |
 |---|---|---|
 | Measures | Output — work shipped | Peer trust — how others rate your work |
 | Earned by | Shipping (cost-plus reward, per-task credits, bonuses) | Metic+ peer votes, ratification, idea promotion |
@@ -173,6 +173,6 @@ Both are reputation. Neither is a spendable currency today. You don't have to *d
 ## See it / dig deeper
 
 - **Your numbers:** [builders' hall](https://example.com/builders) (profile card + leaderboard), or `/builder-start` (shows your credit total).
-- **The diagram:** [`diagrams/03-drachmae-karma.png`](diagrams/03-drachmae-karma.png) — sources and sinks at a glance.
+- **The diagram:** [`diagrams/03-example-karma.png`](diagrams/03-example-karma.png) — sources and sinks at a glance.
 - **The decisions:** [ADR 0054](../adr/<redacted>.md) (cost-plus reward), [ADR 0023](../adr/<redacted>.md) (kind multipliers + idea bonus), [ADR 0028](../adr/<redacted>.md) (token→USD pricing).
 - **The code:** `src/bongos/db.js` (`REWARD_MARGIN_PCT`, `KIND_MULTIPLIERS`, `computeSessionTokenReward`), `src/bongos/llm-pricing.js` (pricing), `src/bongos/cost.js` (budget cap), `src/bongos/bfg.js` (builder strength).

package/docs/onboarding/primer.md

@@ -2,15 +2,15 @@
 
 *Read this before you claim your first work. ~10 minutes.*
 
-You're about to build inside Off the Boats, a project that runs on a small purpose-built dev system. This primer is the one document that gives you enough context to ask Claude smart questions and ship your first task without getting lost. Read it linearly — it's short on purpose.
+You're about to build inside Example, a project that runs on a small purpose-built dev system. This primer is the one document that gives you enough context to ask Claude smart questions and ship your first task without getting lost. Read it linearly — it's short on purpose.
 
 When you're done, open [/builders](https://example.com/builders) and run `/builder-start`. There's no separate "I have read it" step anymore — reading the primer is on your honor, and the work queue is already open to you.
 
 ---
 
-## What Off the Boats is
+## What this project is
 
-Off the Boats is a web experience that drops visitors into a single, persistent, playable digital world set in ancient Greece. Inside the world, players can spend real money to buy **physical goods** (fulfilled by a third-party logistics company called Example) and **digital assets** that develop the shared world. The world is never wiped — every interaction is permanent. The brand is mythic and underground: prices feel like a discovered secret, and the world reads as ancient even though the inciting object is a literal shipping container washed ashore. Visit [example.com](https://example.com) to see it.
+This primer teaches the **platform** — how you claim work and ship it, the same on every Cloud Bongos instance. *What* you're building here — the product, its world, and its visual style — is specific to this instance and lives in **[`docs/project-context.md`](../project-context.md)**. Read that first for the product; everything below is the build system you'll use to make it.
 
 ## What the GDS is
 
@@ -66,13 +66,13 @@ Four ranks, in ancient-Greek-civilization order:
 
 So the sandbox is short: ship three small `newcomer_friendly` tasks and the city opens the whole queue to you on its own (the jump to **Metic** — with its triage/trust powers — is still a deliberate Archon promotion). Rank lives on the `builders.rank` column in the production database and is checked server-side on every privileged request — **with no caching**. A demotion takes effect on your next request. You cannot escalate your own rank by editing local files; the server is the source of truth. See [ADR 0016](../adr/<redacted>.md) and [ADR 0034](../adr/<redacted>.md) for the full trust model.
 
-## Drachmae and karma
+## Example and karma
 
-Two parallel reputation tracks. You don't need to *do* anything special to earn either — claim a task, do good work, ship it, and the system tracks both. The full mechanics (formulas, the kind table, the budget cap, every karma source) live in **[Drachmae & karma — how you get paid](drachmae-and-karma.md)**; here's the shape of it.
+Two parallel reputation tracks. You don't need to *do* anything special to earn either — claim a task, do good work, ship it, and the system tracks both. The full mechanics (formulas, the kind table, the budget cap, every karma source) live in **[Example & karma — how you get paid](example-and-karma.md)**; here's the shape of it.
 
-- **Drachmae** (called "credits" in code) are your **equity** in the project — a score and a stake, *not* a currency you spend on anything. They only go up, and they persist if you leave and come back. Most of your drachmae now come from a **cost-plus reward on each shipped session**: the server prices the LLM tokens your work actually burned and pays you that real cost **plus 20%** ([ADR 0054](../adr/<redacted>.md)). On top of that, each task pays its `credits_reward` adjusted by the *kind* of work (a captured learning or a resolved blocker is worth 1.5×; cleanup 0.8×), and capturing an idea that someone else then ships earns you a 25% bonus ([ADR 0023](../adr/<redacted>.md)). Credits land at the `completed → confirmed` edge — when verification passes, not at deploy. See the standings on [/builders](https://example.com/builders).
+- **Example** (called "credits" in code) are your **equity** in the project — a score and a stake, *not* a currency you spend on anything. They only go up, and they persist if you leave and come back. Most of your example now come from a **cost-plus reward on each shipped session**: the server prices the LLM tokens your work actually burned and pays you that real cost **plus 20%** ([ADR 0054](../adr/<redacted>.md)). On top of that, each task pays its `credits_reward` adjusted by the *kind* of work (a captured learning or a resolved blocker is worth 1.5×; cleanup 0.8×), and capturing an idea that someone else then ships earns you a 25% bonus ([ADR 0023](../adr/<redacted>.md)). Credits land at the `completed → confirmed` edge — when verification passes, not at deploy. See the standings on [/builders](https://example.com/builders).
 
-- **Karma** is a *separate* signal that measures **peer trust** — how other builders rate the *way* you work, not how much you ship. It's earned when Metic-and-above builders upvote your confirmed work (tallied weekly), when a proposal of yours is ratified, and when you capture ideas; it can also go *down* if you break things. Karma shows up on your profile (with a 30-day trend) and as a sortable column on the leaderboard, and it feeds your "builder strength" score. **It does not gate rank promotions** — those happen automatically by ship count (Xenos → Thetes after three ships) or by an Archon's deliberate decision. A builder who ships fast but breaks things gains drachmae and loses karma; a builder who ships thoughtfully gains both.
+- **Karma** is a *separate* signal that measures **peer trust** — how other builders rate the *way* you work, not how much you ship. It's earned when Metic-and-above builders upvote your confirmed work (tallied weekly), when a proposal of yours is ratified, and when you capture ideas; it can also go *down* if you break things. Karma shows up on your profile (with a 30-day trend) and as a sortable column on the leaderboard, and it feeds your "builder strength" score. **It does not gate rank promotions** — those happen automatically by ship count (Xenos → Thetes after three ships) or by an Archon's deliberate decision. A builder who ships fast but breaks things gains example and loses karma; a builder who ships thoughtfully gains both.
 
 One more thing worth knowing: builders are **uncapped by default** — your spend is tracked (it's the cost side of the same coin the reward is computed from) but never blocks you. There's no default budget. An Archon *can* set a per-builder **monthly budget cap** as a manual brake on a runaway; if one is set for you, you get a warning at 80% and `/builder-ship` pauses at 100% until it's raised ([ADR 0085](../adr/<redacted>.md)).
 
@@ -111,7 +111,7 @@ The whole project's source-of-truth index is [`CLAUDE.md`](../../CLAUDE.md). Two
 
 Other depth, in roughly the order you'll need it:
 
-- [`docs/onboarding/drachmae-and-karma.md`](drachmae-and-karma.md) — the full reward economy: how drachmae and karma are earned, the cost-plus session reward, and the monthly budget cap
+- [`docs/onboarding/example-and-karma.md`](example-and-karma.md) — the full reward economy: how example and karma are earned, the cost-plus session reward, and the monthly budget cap
 - [`docs/architecture.md`](../architecture.md) — live system: droplet, stack, schema, API surface
 - [`docs/modules-contract.md`](../modules-contract.md) — the product is built as a small core plus swappable `modules/<key>/` (dev boxes, the game, Discord, art, and more); this is the live roster and how a task lands inside one
 - [`docs/canonical-permissions.md`](../canonical-permissions.md) — who can do what (rank gates)
@@ -190,7 +190,7 @@ If a `/builder-*` command ever says "no GDS session," just run `/builder-setup`
 
 Run `/builder-start` to see what you can claim — no acknowledgment step needed, the queue is open. New builders see only `newcomer_friendly` tasks — small, well-scoped, easy to finish in one sitting. Pick one that looks interesting, claim it with `/builder-claim N`, do the work, and ship it with `/builder-ship`.
 
-When you ship your **first** task, drachmae land in your column and you're inducted as a citizen of Example. Ship your **third** and you graduate to **Thetes** — the one-claim limit lifts and the whole general queue opens to you. Welcome.
+When you ship your **first** task, example land in your column and you're inducted as a citizen of Example. Ship your **third** and you graduate to **Thetes** — the one-claim limit lifts and the whole general queue opens to you. Welcome.
 
 ## Your own dev box
 

package/docs/recipes/audit-replay.md

@@ -15,7 +15,7 @@ Run by an Archon when investigating an incident, a suspected compromise, or a "w
 |---|---|---|
 | `CLAIM` | `claims.claimed_at` | Builder claimed a task — task locked to this session. |
 | `CLAIM_END` | `claims.released_at` + `outcome` | Claim resolved — `outcome` says whether the work shipped, was abandoned, partially completed, or expired. |
-| `CREDIT` | `credit_log.recorded_at` | Drachmae moved (`task.confirmed`, `ship.net_negative`, rank-change audit, etc.) — `delta` is the integer amount. |
+| `CREDIT` | `credit_log.recorded_at` | Example moved (`task.confirmed`, `ship.net_negative`, rank-change audit, etc.) — `delta` is the integer amount. |
 | `COST` | `cost_log.recorded_at` | The builder logged a USD spend — `category` (api / compute / infra / domain / art / other) + `source`. |
 | `SESSION_START` / `SESSION_END` | `session_logs.started_at` / `ended_at` | Claim-scoped working session boundaries. Pair with `outcome` for "shipped / partial / abandoned." |
 | `HTTP_<METHOD>` | `audit_log.recorded_at` | Every authenticated POST / PATCH / PUT / DELETE the builder made — route, status, IP. The forensic fine-grain. |
@@ -23,7 +23,7 @@ Run by an Archon when investigating an incident, a suspected compromise, or a "w
 Notably absent — and worth knowing about so you can ask follow-up questions if needed:
 
 - **GET requests** are not in `audit_log` (by design; high volume, low signal). Read patterns aren't part of this replay.
-- **Builder rank changes** show up as `HTTP_PATCH route=/api/gds/builders/:id/rank` rows and as `CREDIT` rows when the rank change carries a drachmae adjustment. The new rank value lives in `audit_log.request_body_redacted`.
+- **Builder rank changes** show up as `HTTP_PATCH route=/api/gds/builders/:id/rank` rows and as `CREDIT` rows when the rank change carries a example adjustment. The new rank value lives in `audit_log.request_body_redacted`.
 - **Game-server WebSocket events** (movement, world state) live in `world_events` and are NOT included here — this script is GDS-scoped. If a game-side investigation is needed, query `world_events` separately.
 
 ## Running the script

package/docs/recipes/builder-box-lifecycle.md

@@ -105,7 +105,7 @@ Put these in `/etc/example/box.env` (chmod 600 — **secrets never go in the rep
 
 ## Cost (Criterion C1 / cost)
 
-A box accrues compute cost **only while `active`**. At park/deprovision the CLI computes `active hours × the size's hourly rate` and writes it to both the `box_events` ledger and `cost_log` (category `compute`, builder-attributed) — so the public status dashboard's per-builder split sees real box spend. `box.js status` prints the active monthly run-rate + total spent. The **rebill to drachmae/earnings** (org-funded starter → self-fund) is a separate task, [#602](https://example.com/builders#/task/602).
+A box accrues compute cost **only while `active`**. At park/deprovision the CLI computes `active hours × the size's hourly rate` and writes it to both the `box_events` ledger and `cost_log` (category `compute`, builder-attributed) — so the public status dashboard's per-builder split sees real box spend. `box.js status` prints the active monthly run-rate + total spent. The **rebill to example/earnings** (org-funded starter → self-fund) is a separate task, [#602](https://example.com/builders#/task/602).
 
 ## Going live (one-time operator steps)
 
@@ -143,7 +143,7 @@ These spend money and are intentionally manual.
 - **[#596](https://example.com/builders#/task/596)** (done) — the devcontainer (box-as-code) this provisions.
 - **[#599](https://example.com/builders#/task/599)** — Claude Desktop managed-settings + the stable-hostname cutover the lifecycle records. (The browser-on-ramp is now the ttyd web terminal over a Cloudflare Tunnel — [#760](https://example.com/builders#/task/760)/[ADR 0038](../adr/<redacted>.md) — not the retired `claude rc` Remote-Control service.)
 - **[#600](https://example.com/builders#/task/600)** — rank-gated **source access**: the scoped GitHub credential the box holds, granted/revoked by rank. [#598](https://example.com/builders#/task/598) records `scope`; [#600](https://example.com/builders#/task/600) enforces it.
-- **[#602](https://example.com/builders#/task/602)** — cost passthrough (org-funded starter → self-fund via the `costs`/drachmae system). [#598](https://example.com/builders#/task/598) logs the cost; [#602](https://example.com/builders#/task/602) rebills it.
+- **[#602](https://example.com/builders#/task/602)** — cost passthrough (org-funded starter → self-fund via the `costs`/example system). [#598](https://example.com/builders#/task/598) logs the cost; [#602](https://example.com/builders#/task/602) rebills it.
 
 ## Safety properties
 

package/docs/recipes/claude-design-loop.md

@@ -61,7 +61,7 @@ node scripts/gds/design-sync.js --surface hall-ui
 Use the DesignSync MCP tool in your Claude Code session:
 
 ```
-list_projects      → pick the OTB project (or create "Off the Boats — Design System")
+list_projects      → pick the OTB project (or create "Example — Design System")
 finalize_plan      → stage all files from manifest.files, rooted at bundlePath
 write_files        → push the bundle
 ```

package/docs/recipes/instance-deploy.md

@@ -1,12 +1,12 @@
 # Recipe — deploying a Cloud Bongos instance on a pinned core (`git reset` → `npm ci`)
 
-> ADR [0108](../adr/<redacted>.md) §4 (configurable-root W4, task [#1884](https://example.com/builders#/task/1884)). How a **consumer instance** — one that installs `@cloudbongos/core` as a versioned npm dependency rather than living in the monorepo — deploys. This is the target the live droplet deploy converts to; the reference implementation is [`scripts/deploy/deploy-instance.sh`](../../scripts/deploy/deploy-instance.sh).
+> ADR [0108](../adr/<redacted>.md) §4 (configurable-root W4, task [#1884](https://example.com/builders#/task/1884)). How a **consumer instance** — one that installs `@bongos/core` as a versioned npm dependency rather than living in the monorepo — deploys. This is the target the live droplet deploy converts to; the reference implementation is [`scripts/deploy/deploy-instance.sh`](../../scripts/deploy/deploy-instance.sh).
 
 ## The two models
 
 | | Pre-split (today, `example`) | Post-split (consumer instance) |
 |---|---|---|
-| Core code | in-tree (the monorepo) | `node_modules/@cloudbongos/core` (a pinned version) |
+| Core code | in-tree (the monorepo) | `node_modules/@bongos/core` (a pinned version) |
 | Deploy | [`deploy-prod.sh`](../../scripts/deploy/deploy-prod.sh): `git reset --hard origin/main` on a shared checkout | [`deploy-instance.sh`](../../scripts/deploy/deploy-instance.sh): `git pull` the instance repo → `npm ci` → migrate → restart |
 | Upgrade the core | (n/a — one tree) | bump the pin in `package.json` → `npm ci` → migrate → restart (ADR 0108 §4; the R86 channel, task [#1690](https://example.com/builders#/task/1690)) |
 | `cloudbongos.com` | a 2nd service on the **same** checkout (why it ran stale) | its **own** consumer repo + its own `deploy-instance.sh` |
@@ -14,7 +14,7 @@
 ## The flow (`deploy-instance.sh`)
 
 1. **`git pull --ff-only origin main`** the *instance* repo — host content only: `config/`, `migrations/instance/`, and the pinned core version in `package.json`.
-2. **`npm ci --omit=dev`** — installs the pinned `@cloudbongos/core` + instance deps. This is what replaces `git reset --hard`: the core is a dependency, so an upgrade is a pin bump + `npm ci`, not a source merge.
+2. **`npm ci --omit=dev`** — installs the pinned `@bongos/core` + instance deps. This is what replaces `git reset --hard`: the core is a dependency, so an upgrade is a pin bump + `npm ci`, not a source merge.
 3. **`bash <core>/scripts/migrate.sh`** — the core's **three-root** migrate (W5 / ADR 0108 §5) merges `<core>/migrations` + `<instance>/migrations/instance` + each enabled module's migrations, keyed by namespaced filename stems (`core_NNN_`, `<key>_NNN_`, bare instance) so the two repos never collide. It resolves core-root vs instance-root via `src/instance-config.js`.
 4. **restart the platform** — a systemd unit runs `node <core>/src/platform-server.js` (GDS-only) with `WorkingDirectory` = the instance root (so `resolveInstanceRoot()` resolves to the instance) + `PORT`/`HOST` env; then poll `/healthz`.
 
@@ -32,6 +32,6 @@
 ## Wiring it on a consumer host (R85/R89)
 
 1. Install the script as the droplet's `~/deploy.sh` (the CI deploy key is forced-command-locked to `~/deploy.sh` — ADR 0043 — so it stays hand-installed, like `deploy-prod.sh`).
-2. Create a systemd unit for the instance: `ExecStart=/usr/bin/node <instanceRoot>/node_modules/@cloudbongos/core/src/platform-server.js`, `WorkingDirectory=<instanceRoot>`, `Environment=PORT=… HOST=127.0.0.1 <PREFIX>_INSTANCE_ROOT=<instanceRoot>`.
+2. Create a systemd unit for the instance: `ExecStart=/usr/bin/node <instanceRoot>/node_modules/@bongos/core/src/platform-server.js`, `WorkingDirectory=<instanceRoot>`, `Environment=PORT=… HOST=127.0.0.1 <PREFIX>_INSTANCE_ROOT=<instanceRoot>`.
 3. Set `INSTANCE_SERVICE=<unit>` + `PORT=<port>` in the deploy environment.
 4. Front it with TLS and point the origins at the real domain (see [self-host.md](self-host.md)).

package/docs/recipes/instance-first-run.md

@@ -0,0 +1,51 @@
+# First run: clone → working instance
+
+> The one-shot path from `git clone` of a **standalone Cloud Bongos instance repo**
+> (ADR 0108 — a repo that pins `@cloudbongos/core` as a dependency, e.g. `example-owner/demo`)
+> to a session that can actually claim + ship work. This is for a **builder joining an
+> existing instance**; standing up a *new* instance is `/new-project` (`bongos onboard`).
+
+## Why this recipe exists
+
+A cloned instance repo ships `config/` + `package.json` + a vendored core tarball, but
+**not** the installed engine. Until you install it there is no `bongos` binary and no
+`scripts/gds/…`, so every `/builder-*` skill fails. An agent that presses on in that
+state has no tools of its own and can fall back on whatever *other* Cloud Bongos instance
+the machine is signed in to — which is how a `demo` clone once offered to write a task
+into the wrong live backlog (2026-07-08). The session-start hook now prints these same
+steps when it detects an uninstalled instance (task 2105); the wrong-instance write it
+used to risk is refused outright (task 2102).
+
+## The steps
+
+From the repo root, in order:
+
+```bash
+# 1. Install the engine (the vendored core → node_modules + the `bongos` bin).
+#    No registry auth needed: the dependency is a local file: tarball.
+npm install
+
+# 2. Sign in to THIS instance (one browser click — no code to paste).
+#    Use the instance's own origin — the one in config/branding.json → domains.publicOrigin.
+npx bongos login https://<this-instance-origin>
+
+# 3. Confirm you're wired up: this lists what you can claim right now.
+npx bongos start
+```
+
+That's it — `bongos claim <id>` / `bongos ship` now work, scoped to this instance.
+
+## Notes
+
+- **Sign in to the RIGHT instance.** `bongos login <url>` writes a per-instance session
+  (`session.api_base`), and the CLI **refuses to act** if the session it would use belongs
+  to a different instance than this repo is configured for (task 2102). If you see that
+  refusal, re-run `bongos login` with *this* instance's origin.
+- **Which origin?** `config/branding.json` → `domains.publicOrigin`. `GET <origin>/api/bongos`
+  also re-advertises an instance's own hall/status/docs origins (the docs-discovery contract,
+  ADR 0114).
+- **Invite-only by default.** A brand-new GitHub account isn't admitted until an Archon
+  approves it; `bongos login` files the request and waits, then finishes sign-in.
+- **The engine lives in the package, not the repo.** `bongos` resolves the heavy CLI inside
+  `node_modules/@cloudbongos/core`; that's why step 1 must come first. On a machine with the
+  core installed globally you can drop the `npx`.

package/docs/recipes/ops-gotchas.md

@@ -119,7 +119,7 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 
 - **Symptom:** Visitor clicks "Sign in with GitHub" on /builders, GitHub renders its red "Be careful!" warning page or returns `?error=redirect_uri_mismatch`, and the visitor never lands back on the hall.
 - **Root cause:** The GitHub OAuth app's **Authorization callback URL** field must match exactly what the server tells GitHub. Our server sends `${publicOrigin}/api/gds/auth/web/callback` — easy to misconfigure as just `https://example.com/` or `/auth/callback` when registering a fresh OAuth app.
-- **Fix:** In github.com → Settings → Developer settings → OAuth Apps → (the Off the Boats app) → **Authorization callback URL**, set:
+- **Fix:** In github.com → Settings → Developer settings → OAuth Apps → (the Example app) → **Authorization callback URL**, set:
   ```
   https://example.com/api/gds/auth/web/callback
   ```

package/docs/recipes/packaging-the-core.md

@@ -2,7 +2,7 @@
 
 > Implements [ADR 0100 §1](../adr/<redacted>.md) (the two-repo instance model). This is **R84**, the first step of the `R84 → R85 → R86` spine: package the core → stand a downstream instance up on a pinned core → make `bongos upgrade` a real update channel. Tooling: [`scripts/gds/package-core.js`](../../scripts/gds/package-core.js) (`bongos package-core`).
 >
-> **Real installable npm package ([ADR 0108](../adr/<redacted>.md) §2, task 1882/W2, shipped):** the artifact is `package/`-rooted (the npm convention `npm install ./x.tgz` requires) and carries a synthesized `package.json` — `name: "@cloudbongos/core"`, `version` = `CORE_VERSION`, `main: "src/platform-server.js"`, `exports` for the default entry (`buildPlatformApp`) plus `./serve-internal` (`mountInternalSurfaces`) and `./module-api`, `bin: "bongos"` — and a **pruned** `package-lock.json` (express + pg's own transitive closure only, resolved offline from the source lockfile — no colyseus/phaser/sharp/discord.js). Both files are synthesized fresh, never copied verbatim from the source repo's game-heavy `package.json`. `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js), W1/task 1881) are what a consumer's own code routes through once installed.
+> **Real installable npm package ([ADR 0108](../adr/<redacted>.md) §2, task 1882/W2, shipped):** the artifact is `package/`-rooted (the npm convention `npm install ./x.tgz` requires) and carries a synthesized `package.json` — `name: "@bongos/core"`, `version` = `CORE_VERSION`, `main: "src/platform-server.js"`, `exports` for the default entry (`buildPlatformApp`) plus `./serve-internal` (`mountInternalSurfaces`) and `./module-api`, `bin: "bongos"` — and a **pruned** `package-lock.json` (express + pg's own transitive closure only, resolved offline from the source lockfile — no colyseus/phaser/sharp/discord.js). Both files are synthesized fresh, never copied verbatim from the source repo's game-heavy `package.json`. `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js), W1/task 1881) are what a consumer's own code routes through once installed.
 
 ## What the artifact is
 
@@ -12,9 +12,9 @@ A Cloud Bongos *instance* can be its **own repository** that installs a **pinned
 
 | Output | What it is |
 |---|---|
-| `cloudbongos-core-<version>.tgz` | the installable unit — a gzip'd tar of the redacted core tree, rooted at `package/` (the npm convention `npm install ./x.tgz` requires), carrying a synthesized `@cloudbongos/core` `package.json` + pruned `package-lock.json` (task 1882) |
-| `cloudbongos-core-<version>.manifest.json` | the **pin** — version, source commit, per-file hashes, and the tree hash a consumer verifies against |
-| `cloudbongos-core-<version>/` | the same redacted tree unpacked, for inspection |
+| `bongos-core-<version>.tgz` | the installable unit — a gzip'd tar of the redacted core tree, rooted at `package/` (the npm convention `npm install ./x.tgz` requires), carrying a synthesized `@bongos/core` `package.json` + pruned `package-lock.json` (task 1882) |
+| `bongos-core-<version>.manifest.json` | the **pin** — version, source commit, per-file hashes, and the tree hash a consumer verifies against |
+| `bongos-core-<version>/` | the same redacted tree unpacked, for inspection |
 
 The version is the **platform version** — `CORE_VERSION` from [`src/module-api.js`](../../src/module-api.js), the same coordinate the module loader and `bongos upgrade` compare against ([#1203](https://example.com/builders#/task/1203)). That shared coordinate is what keeps the spine coherent: a module pinned to `^core_contract` is guaranteed to load against the packaged core.
 
@@ -36,7 +36,7 @@ If the no-leak gate fails, it names the file + the residual literal. Fix the red
 
 A downstream instance repo:
 
-1. **Installs** the `.tgz` — `npm install ./cloudbongos-core-<version>.tgz` (or a fetched-in-CI path) — which lands it at `node_modules/@cloudbongos/core/`, a directory the consumer does not hand-edit.
+1. **Installs** the `.tgz` — `npm install ./bongos-core-<version>.tgz` (or a fetched-in-CI path) — which lands it at `node_modules/@bongos/core/`, a directory the consumer does not hand-edit.
 2. **Pins** by recording `core_version` + `source_commit` + `tree_sha256` from the manifest.
 3. **Verifies** the install by recomputing `tree_sha256` from the unpacked tree — for each core file, `sha256(content)` with a canonical mode (`0000644`/`0000755`), then `sha256` over the sorted `"<path> <mode> <filesha>"` lines. It must equal the manifest's `tree_sha256`. The tree hash is **compression-independent**, so it is a stable pin even though `.tgz` bytes are an implementation detail (`tarball.sha256` separately verifies the exact download).