@bongos/core 1.17.1 → 1.17.2

package/docs/adr/0062-medusa-instance-model-decoupling.md

@@ -17,7 +17,7 @@ Today it is one fused codebase. A file-grounded coupling analysis (2026-06-18) f
 
 1. **Process/HTTP** — one Express app + one Colyseus server. The GDS (`/api/gds`, hall, status) mounts host-agnostic *first*; the **game is the fall-through default**, not a module. Good news: `src/rooms/register.js` + `src/preview-server.js` already factor the game-room set out — the cleanest existing seam and the template for the cut.
 2. **DB** — *one shared `pg` Pool*: `src/bongos/db.js` does `require('../db')` and reuses the game's pool. Game tables (`world_events`, `players`, migrations 001/002) and ~78 GDS tables share one pool and one flat migration sequence. `track` is a 2-value `CHECK (track IN ('product','internal'))` column on `versions`, woven into analytics + hall UI — an OTB-specific taxonomy.
-3. **Brand/identity** — leaked, not single-config. "Example" is hardcoded across ~50 hits / 28 files; `example.com` across ~90 (cookie domain `.example.com`, OAuth origin, `*.dev.` SSH allowlist); "drachmae" in 23 files; "Off the Boats"/"Example" baked into **grader/architect/onboarding LLM prompts**. Only `devbox-app/src/brand.js` honors the single-config ideal.
+3. **Brand/identity** — leaked, not single-config. "Example" is hardcoded across ~50 hits / 28 files; `example.com` across ~90 (cookie domain `.example.com`, OAuth origin, `*.dev.` SSH allowlist); "example" in 23 files; "Example"/"Example" baked into **grader/architect/onboarding LLM prompts**. Only `devbox-app/src/brand.js` honors the single-config ideal.
 4. **Methodology/skills** — already clean: `.claude/skills/builder-*` + idea/blocker/planning/status/recall are portable; the four `otb-*` art skills + `stop-sound.js` are host; `art/` is self-contained (no `src/` imports); Discord is already `DISCORD_BOT_ENABLED`-gated.
 
 Why a spike-ADR first: 24 structural tasks (R51–R74) depend on this. They need **one** locked boundary, branding-contract schema, and module mechanism to build against, or they will diverge.
@@ -46,7 +46,7 @@ Why a spike-ADR first: 24 structural tasks (R51–R74) depend on this. They need
 
 - **Engine entrypoint** (R51, [#1190](https://example.com/builders#/task/1190)): boots Express + `buildGdsRouter()` + hall + status, host-agnostic, **no Colyseus, no game/tile mounts** — sibling to `src/preview-server.js`. Today's `server.js` becomes the *OTB instance boot* (engine + game module).
 - **A host instance** = branding pack (§3) + feature-module flags (§4) + owner/repo/OAuth binding (R62, [#1201](https://example.com/builders#/task/1201)) + its own DB (R52).
-- Customer 0 = vanilla brand, no modules (the dogfood); customer 1 = OTB (game + art + discord + dev-box, drachmae, Greek pack).
+- Customer 0 = vanilla brand, no modules (the dogfood); customer 1 = OTB (game + art + discord + dev-box, example, Greek pack).
 
 ### 3. The branding contract (`config/branding.*` — R53 keystone, [#1192](https://example.com/builders#/task/1192))
 
@@ -54,7 +54,7 @@ One per-instance config; **resolution precedence: env var → instance config
 
 - **Identity:** `productName`, `worldName` (the in-world / civilization name), `company` (+ site).
 - **Domains:** `publicOrigin`, `buildersOrigin`, `statusOrigin`, `cookieDomain`, box subdomain pattern (`*.dev.`/`sandbox-`/`term-`). *(Load-bearing security strings — a swap must not widen cookie/SSH scope.)*
-- **Currency label** (R56, [#1195](https://example.com/builders#/task/1195)): "drachmae" → configurable; the cost-plus reward **math is unchanged**.
+- **Currency label** (R56, [#1195](https://example.com/builders#/task/1195)): "example" → configurable; the cost-plus reward **math is unchanged**.
 - **Tracks:** replace the 2-value `product|internal` CHECK with a configurable set (R52, [#1191](https://example.com/builders#/task/1191)).
 - **Theme/palette + copy pack:** hall lore/primer/404 copy, Discord persona, and — critically — the **grader/architect/onboarding prompt brand header** must read the project name from config, or a non-OTB instance grades against the wrong project identity.
 
@@ -103,5 +103,5 @@ R50 (this ADR) → **R51 entrypoint + R52 DB pool** (independent foundations)
 
 - A clear, file-grounded target the 24 epics build against — one boundary, one contract, one module mechanism.
 - The trust boundary + rank enforcement stay core and unchanged; a feature-module must never be able to bypass server-side rank checks (a Path-C assertion).
-- **Hardest knots (called out so the epics plan for them):** (1) shared Pool + flat migrations; (2) the brand-saturated, *not* data-driven hall UI (~50 brand hits, drachmae in 23 files) — the largest mechanical job; (3) inverting game-as-default into a mounted module; (4) domains woven into auth/security — config swaps must not widen cookie/SSH scope; (5) brand inside LLM prompts (grader/architect/onboarding).
+- **Hardest knots (called out so the epics plan for them):** (1) shared Pool + flat migrations; (2) the brand-saturated, *not* data-driven hall UI (~50 brand hits, example in 23 files) — the largest mechanical job; (3) inverting game-as-default into a mounted module; (4) domains woven into auth/security — config swaps must not widen cookie/SSH scope; (5) brand inside LLM prompts (grader/architect/onboarding).
 - **Risk: scope.** Mitigation: R53 keystone first; modules incremental; Path-C enforces no regression; customer-0 dogfood ([#1206](https://example.com/builders#/task/1206)) is the falsifiable proof the cut actually worked.

package/docs/adr/0065-agpl-nonprofit-ai-first-governance.md

@@ -9,7 +9,7 @@
 
 ## Context
 
-[ADR 0062](<redacted>.md) decoupled the GDS into **Cloud Bongos** — a configurable, self-hostable build platform where AI agents claim tasks and ship code, with a human owner setting scope and the hard gates. Example (the Off the Boats game) becomes **customer 1** running on it; Cloud Bongos runs on its own plain vanilla brand as **customer 0** and builds itself.
+[ADR 0062](<redacted>.md) decoupled the GDS into **Cloud Bongos** — a configurable, self-hostable build platform where AI agents claim tasks and ship code, with a human owner setting scope and the hard gates. Example (the Example game) becomes **customer 1** running on it; Cloud Bongos runs on its own plain vanilla brand as **customer 0** and builds itself.
 
 Criterion **C9 (`medusa-open-and-protected`)** commits Cloud Bongos to being *open, free, and protected from capture*: released to the public as open source on a deliberate, delayed cadence. Three questions had to be answered before any of R69–R73 could be built, because each is downstream of the answer:
 
@@ -34,7 +34,7 @@ The license covers the **publishable subset only** — the portable methodology
 The project is run as a **non-profit**: it is **not monetized from its contributors**, and it is structured so no single party can capture it.
 
 - No contributor pays to contribute, and no contribution is resold as a proprietary add-on by the project.
-- The drachmae/credit economy ([ADR 0054](<redacted>.md)) is an **instance-internal** mechanism — it rewards builders on a given instance out of that instance's own budget; it is not the project monetizing the commons. It ships as a feature an instance configures, not as a revenue stream flowing to a central owner.
+- The example/credit economy ([ADR 0054](<redacted>.md)) is an **instance-internal** mechanism — it rewards builders on a given instance out of that instance's own budget; it is not the project monetizing the commons. It ships as a feature an instance configures, not as a revenue stream flowing to a central owner.
 - The AGPL is the legal backstop; the non-profit posture is the social one. Together they are the "protected from capture" half of C9.
 
 Optional **managed-hosting** (operating instances for owners) was captured as a post-C8 idea in the planning session. If it is ever built, it is a service offered *on top of* the same AGPL artifact — it does not change the artifact's license or the non-profit posture of the platform itself.

package/docs/adr/0085-remove-default-per-builder-spend-cap.md

@@ -36,4 +36,4 @@ No schema change (`monthly_budget_usd` stays; `NULL` now means "uncapped" instea
 - **The brake survives.** An Archon can still cap a specific runaway builder by setting a positive `monthly_budget_usd`; clearing it (`null`) returns them to uncapped.
 - **Cost stays honest.** Spend attribution, the savings ledger, and the public dashboard are untouched — we still see exactly where the $5K goes; we just don't gate work on it.
 - **Project-wide guards are unaffected.** The separate autonomous-fleet spend brake (`autonomy-gate.js`, `OTB_AUTONOMY_CEILING_USD`) and the art-pipeline `HARD_STOP_USD` ledger cap are independent mechanisms and remain in force.
-- **C3's intent narrows** from "every builder has a default ceiling" to "a ceiling is an opt-in, per-builder Archon tool." The onboarding drachmae/karma diagram note is updated to match.
+- **C3's intent narrows** from "every builder has a default ceiling" to "a ceiling is an opt-in, per-builder Archon tool." The onboarding example/karma diagram note is updated to match.

package/docs/adr/0086-goal-scoped-work-hierarchy.md

@@ -82,7 +82,7 @@ The create-time gate sees only *declared* touches (advisory — git merge is the
 
 ### Deferred (explicit non-decisions)
 
-- **Rewards** — whether *achieving a goal* earns anything beyond the per-task cost-plus already paid ([ADR 0054](<redacted>.md)), and how any reward splits among a goal's members. The leaning is karma by default (budget-safe, since drachmae are real money) with contribution-weighted splits, but this is **not yet decided** and rides a follow-on.
+- **Rewards** — whether *achieving a goal* earns anything beyond the per-task cost-plus already paid ([ADR 0054](<redacted>.md)), and how any reward splits among a goal's members. The leaning is karma by default (budget-safe, since example are real money) with contribution-weighted splits, but this is **not yet decided** and rides a follow-on.
 - **A sub-Metic builder joining a protected-scope goal** — letting a newcomer work *inside* the dangerous core under a tightly-scoped, Archon-granted goal amends the [ADR 0043](<redacted>.md) hard floor (and needs the ship-time gates to become goal-aware). Deliberately **last**, behind its own security-reviewed ADR. Until then, protected-scope goals require a Metic+ holder.
 - **An AI relevance / anti-hack judge** at create/claim time (reusing the grader subagent harness; advisory-first, flag-for-Metic, never hard-blocking a newcomer) — a later phase; the deterministic scope + protected-path gates ship first.
 

package/docs/adr/0096-require-reward-before-workable.md

@@ -1,4 +1,4 @@
-# ADR 0096 — Require a `credits_reward` (drachmae) value before a task is workable
+# ADR 0096 — Require a `credits_reward` (example) value before a task is workable
 
 **Date:** 2026-06-28
 **Status:** Accepted
@@ -7,12 +7,12 @@
 
 ## Context — the problem
 
-Every task carries a `credits_reward` integer — the in-world drachmae payout when it
+Every task carries a `credits_reward` integer — the in-world example payout when it
 ships ([ADR 0023](<redacted>.md), [ADR 0054](<redacted>.md)).
 That column was created with `NOT NULL DEFAULT 0` (migration `003_pms.sql`). Nothing in
 the lifecycle ever required it to be set, so the default path was:
 
-> create a task (reward = 0) → promote it to `ready` → claim → ship → **pay 0 drachmae**.
+> create a task (reward = 0) → promote it to `ready` → claim → ship → **pay 0 example**.
 
 A task could travel the whole claim→ship→credit pipeline paying nothing. The credit
 ledger then records a real shipped task with a zero payout — the reward economy is
@@ -96,7 +96,7 @@ complete and no zero-reward `ready` tasks remain.
 
 ## Consequences
 
-- No task created/promoted/claimed after this change can be worked while paying 0 drachmae.
+- No task created/promoted/claimed after this change can be worked while paying 0 example.
 - Existing `ready` + in-flight zero-reward tasks stay fully workable (grandfathered).
 - The promote/claim refusals name the way forward (suggested value + the `PATCH` call),
   matching the `TASK_NOT_READY` actionable-hint precedent ([#952](https://example.com/builders#/task/952)).
@@ -112,7 +112,7 @@ The original decision above made a missing reward **block** the two workable tra
 that turned a missing-value into a hard wall: a perfectly good task with a deps-met,
 ready-to-work footprint could not be promoted or claimed until someone hand-set a value
 first. That is friction the methodology doesn't want — the goal is "no task is worked for
-0 drachmae", not "stop work until a human types a number."
+0 example", not "stop work until a human types a number."
 
 **The shift: the gate now AUTO-ASSIGNS a fair, capped value and PROCEEDS.**
 
@@ -143,7 +143,7 @@ author-set precisely because auto-deriving it from `est_minutes` is gameable (in
 estimate → inflate the pay). Auto-assigning at the gate crosses that line — so two guards
 contain the blast radius:
 
-1. **CAP.** `suggestCreditsReward` is capped at `REWARD_SUGGESTION_CAP = 60` drachmae. The
+1. **CAP.** `suggestCreditsReward` is capped at `REWARD_SUGGESTION_CAP = 60` example. The
    formula stays modest (~1 drachma/estimated-minute, weighted by a coarse per-kind factor,
    floored at 5), and the cap bounds how far an inflated estimate can push the *auto-assigned*
    value. Anyone who genuinely needs more sets `credits_reward` by hand via `PATCH /tasks/:id`
@@ -161,7 +161,7 @@ contain the blast radius:
 
 ### Net effect
 
-No task is ever worked for 0 drachmae **and** no promote/claim is ever blocked for a missing
+No task is ever worked for 0 example **and** no promote/claim is ever blocked for a missing
 value. The friction is gone; the economy stays funded; the gameable surface is a capped,
 audited floor sitting under the ungameable cost-plus primary reward.
 
@@ -170,7 +170,7 @@ audited floor sitting under the ungameable cost-plus primary reward.
 The first amendment moved assignment to the two *workable* transitions (promote, claim). That
 still left a window: a freshly **created** `backlog` task read `credits_reward = 0` until it was
 later promoted or claimed. The owner's intent is stronger — **every task should carry a fair
-drachmae value from the moment it is born**, so anyone reading the backlog sees real numbers, not
+example value from the moment it is born**, so anyone reading the backlog sees real numbers, not
 zeros waiting to be filled in.
 
 **The shift: creation is now the PRIMARY assignment point; promote/claim becomes the backstop.**
@@ -204,6 +204,6 @@ just now lands at birth instead of at first-work.
 
 ### Net effect (post-1677)
 
-Every task is born with a fair, capped drachmae value. The backlog never shows a placeholder zero;
+Every task is born with a fair, capped example value. The backlog never shows a placeholder zero;
 promote/claim no longer carries the assignment weight (it's a backstop); the economy stays funded
 end-to-end with the same anti-gaming ceiling.

package/docs/adr/0097-retroactive-reward-backfill.md

@@ -1,4 +1,4 @@
-# ADR 0097 — Retroactive drachmae backfill for shipped 0-reward tasks
+# ADR 0097 — Retroactive example backfill for shipped 0-reward tasks
 
 - **Date:** 2026-06-28
 - **Status:** Accepted
@@ -11,7 +11,7 @@
 A task's `credits_reward` column **defaults to 0**. The per-task ship credit is
 minted by `modules/economy/credits.js insertMultipliedConfirmCredit`, which
 computes `applyKindMultiplier(credits_reward, kind)` — so a task that shipped
-with `credits_reward = 0` (or NULL) paid `0 × multiplier = 0` drachmae. Many
+with `credits_reward = 0` (or NULL) paid `0 × multiplier = 0` example. Many
 early ships, and most dev-box / CI agent ships, never had a fair per-task reward
 set, so the builders who did real, shipped work earned nothing for it on the
 per-task stream.
@@ -28,7 +28,7 @@ There are **two reward streams** a builder accrues to `builders.total_credits`:
    `priceModelUsage` returns ~$0 and the reward rounds to 0. So for exactly the
    ships that missed the per-task reward, the cost-plus stream *also* paid nothing.
 
-The net effect: a real backlog of shipped work that minted no drachmae for its
+The net effect: a real backlog of shipped work that minted no example for its
 builders. This ADR records the decision (and the tool) to remediate that **once,
 fairly, and safely** — with an Archon authorizing the amounts.
 

package/docs/adr/0100-two-repo-instance-model.md

@@ -16,7 +16,7 @@ ADR 0062 drew the **logical** cut-line — portable core / host instance / gated
 
 Two owner priorities now push past the single-repo model:
 
-- **Mercury** — Example' internal platform — should be "its own Cloud Bongos project": not code living inside the Off the Boats repo, and not merely another reskin of one checkout.
+- **Mercury** — Example' internal platform — should be "its own Cloud Bongos project": not code living inside the Example repo, and not merely another reskin of one checkout.
 - **Core improvements should flow to future projects** on each project's own schedule — an explicit "update to the latest platform" capability.
 
 The 2026-06-26 gap analysis (planning [#1604](https://example.com/builders#/task/1604)) found the logical boundary ~70% built and CI-enforced. Since then the load-bearing pieces landed: the bounded kernel ([#1570](https://example.com/builders#/task/1570)), the completed Config-B core-carve ([#1578](https://example.com/builders#/task/1578) + ADR 0093 — BONGOS-V1 C7 now satisfied), the hall-widget registry ([#1612](https://example.com/builders#/task/1612)), and core de-branding ([#1613](https://example.com/builders#/task/1613)). The boundary now holds, so a split is **mechanical, not a leap** — which is exactly the precondition this gate ([#1607](https://example.com/builders#/task/1607)) was told to wait for.

package/docs/adr/0101-goal-hierarchy-phase-5-judge-membership-reward.md

@@ -57,11 +57,11 @@ We adopt a three-part design. Each part is an independent, revertible build task
 
 **Leaning (recorded; the money is owner-gated).**
 
-- **Karma by default, not drachmae.** Drachmae are real money (1 = $1) against a tight $5k budget, and a goal is a *coordination construct*, not a unit of billable work — the per-task cost-plus already pays for the actual shipping. A goal-achievement **karma** bonus recognizes the collaboration with **no new monetary spend**.
+- **Karma by default, not example.** Example are real money (1 = $1) against a tight $5k budget, and a goal is a *coordination construct*, not a unit of billable work — the per-task cost-plus already pays for the actual shipping. A goal-achievement **karma** bonus recognizes the collaboration with **no new monetary spend**.
 - **Contribution-weighted, not membership-flat.** The bonus tracks **who actually shipped tasks under the goal** (reuse the shipped-task/credit attribution + the BFG contribution signals, [ADR 0027](<redacted>.md)), never mere membership — a flat per-member reward would incentivize goal-squatting. A `lead` may take a small coordination share.
 - **On achievement, not creation.** The reward attaches when a goal is **achieved** (all criteria satisfied + confirmed via `/goal-review`), never on creation or joining — which, with contribution-weighting and the Metic confirmation, closes the free-rider and squatting surfaces.
 
-**Owner-gated.** Whether *any* monetary (drachmae) component attaches, and the exact karma amount/curve, is **Lars's call at build time** — money is owner authority. This ADR records the budget-safe default (karma-only, contribution-weighted); the build task (P5.3) surfaces the money decision explicitly rather than presuming it.
+**Owner-gated.** Whether *any* monetary (example) component attaches, and the exact karma amount/curve, is **Lars's call at build time** — money is owner authority. This ADR records the budget-safe default (karma-only, contribution-weighted); the build task (P5.3) surfaces the money decision explicitly rather than presuming it.
 
 ### The child task list (filed backlog under BONGOS-V1, `source_ref` = this ADR)
 
@@ -76,7 +76,7 @@ We adopt a three-part design. Each part is an independent, revertible build task
 - **A hard-blocking relevance judge — rejected.** A fallible LLM as a hard gate re-introduces the bottleneck ADR 0086 removed and creates a gaming/DoS surface; the deterministic gates are the hard wall, the judge is a soft signal.
 - **Keep protected-scope Metic+-only forever — rejected as the long-term posture** (it caps the maneuverability grant's reach), but it **is** the safe default that stays in force until P5.2 ships with its security review.
 - **Flat per-member goal reward — rejected.** It incentivizes goal-squatting; contribution-weighting is fairer and anti-gaming.
-- **A drachmae goal bonus by default — rejected as the default** (real money, tight budget); left as an explicit owner-gated option, not presumed.
+- **A example goal bonus by default — rejected as the default** (real money, tight budget); left as an explicit owner-gated option, not presumed.
 - **Fold Phase 5 into Phase 4 rather than its own ADR — rejected** (ADR 0086 already decided this): the boundary-widening warrants a standalone security review, which is this document.
 
 ---

package/docs/adr/0103-core-first-extraction-cloud-bongos-trunk.md

@@ -17,7 +17,7 @@ A next-day owner review (2026-07-02, task [#1726](https://example.com/builders#/
 
 - **Cloud Bongos is the real product** — the thing of durable value — and should live as a clean standalone artifact, with Example as *one consumer of it*, not its host.
 - **The coupling actively hurts.** One repo carrying both the game and the platform, with a convoluted shared history, is hard to reason about and hand off.
-- **The boundary stays theoretical while Example is coupled.** OTB specifics keep leaking into the "portable" core. Evidence: a walk of the ~105 accumulated memory-file learnings on 2026-07-02 found **~85% are platform knowledge wearing OTB-specific framing** (example.com links, the droplet, `drachmae`) — the substance is core, the *wording* is coupled. Only 7 items are genuinely instance-bound.
+- **The boundary stays theoretical while Example is coupled.** OTB specifics keep leaking into the "portable" core. Evidence: a walk of the ~105 accumulated memory-file learnings on 2026-07-02 found **~85% are platform knowledge wearing OTB-specific framing** (example.com links, the droplet, `example`) — the substance is core, the *wording* is coupled. Only 7 items are genuinely instance-bound.
 - **Mercury is imminent** — the separation should be proven on something that matters to the business now.
 
 "Leave Example coupled until later" reads, under these priorities, as "never." The precondition ADR 0100 waited for — a mechanical, CI-enforced boundary — already holds (ADR 0093 core-carve, the module system, `isPublishable()`), so the more ambitious cut is now buildable rather than a leap.
@@ -65,6 +65,6 @@ Each repo runs its own GDS (own DB, tasks, builders, credits) — a shared GDS i
 §1 is done. The core was extracted into **[github.com/example-owner/cloud-bongos](https://github.com/example-owner/cloud-bongos)** — **private**, `main`, **AGPL-3.0**, **fresh single-commit history**.
 
 - **What was extracted:** the `isPublishable()` subtree via R84's `scripts/gds/package-core.js` — **989 core files** (of 2203), redacted in-memory through the fail-closed no-leak gate (0 residual leaks). The pin travels in-repo as `.cloudbongos-core.json`: `core_version 1.14.0`, `source_commit 2783a396…`, `tree_sha256 2bf9f8ee9a97…`. R85 ([#1689](https://example.com/builders#/task/1689)) and R89 ([#1728](https://example.com/builders#/task/1728)) can now depend on this pin.
-- **Genericized on the way in:** identity surface branded to Cloud Bongos (README, package.json, CLAUDE.md 298→258 lines, GOVERNANCE); instance identity re-pointed to `docs/project-context.template.md` + `config/branding.neutral.json`; `drachmae→credits`, owner-name and Off-the-Boats/ancient-Greece framing removed.
+- **Genericized on the way in:** identity surface branded to Cloud Bongos (README, package.json, CLAUDE.md 298→258 lines, GOVERNANCE); instance identity re-pointed to `docs/project-context.template.md` + `config/branding.neutral.json`; `example→credits`, owner-name and Off-the-Boats/ancient-Greece framing removed.
 - **§4 mirror re-evaluation (ADR 0099):** the physical-extraction trigger has now fired, and `cloud-bongos` is the **designated canonical public artifact** — but it is **PRIVATE for now**. So the ADR 0099 generated mirror is **NOT retired yet**; it stays the public surface until the owner flips `cloud-bongos` public, at which point the mirror is retired (or repointed). Retirement is bound to the public-flip, not to this extraction.
-- **Deferred to follow-ups (tracked in the GDS):** the exhaustive `Off the Boats`→neutral sweep across the ~32 remaining ADR/test/recipe files; standalone vanilla-boot wiring (`server.js`/entrypoints still reference the reference instance's product layer) — naturally proven by R85/R89; core `package.json` dependency pruning (game deps carried in); dangling in-repo links to topology/instance paths the scaffold populates on `init`; seeding the CORE-bucketed learnings; and tagging R88/R89 to goal 26 (their `goal_id` is null).
+- **Deferred to follow-ups (tracked in the GDS):** the exhaustive `Example`→neutral sweep across the ~32 remaining ADR/test/recipe files; standalone vanilla-boot wiring (`server.js`/entrypoints still reference the reference instance's product layer) — naturally proven by R85/R89; core `package.json` dependency pruning (game deps carried in); dangling in-repo links to topology/instance paths the scaffold populates on `init`; seeding the CORE-bucketed learnings; and tagging R88/R89 to goal 26 (their `goal_id` is null).

package/docs/adr/0107-module-upstreaming-contribution-to-core-catalog.md

@@ -32,7 +32,7 @@ Each repo runs its own GDS with its own builder identities ([ADR 0100](<redacted
 
 ### 3. Reward: credit now, money later.
 
-Accepted contributions earn **visible credit** (author + origin in the catalog) immediately. Any monetary reward (drachmae) — and the cross-instance identity/payout mechanics it would require — is **explicitly deferred** to a separate economics decision (owner call, 2026-07-03). This keeps the build unblocked and avoids prematurely solving cross-GDS identity.
+Accepted contributions earn **visible credit** (author + origin in the catalog) immediately. Any monetary reward (example) — and the cross-instance identity/payout mechanics it would require — is **explicitly deferred** to a separate economics decision (owner call, 2026-07-03). This keeps the build unblocked and avoids prematurely solving cross-GDS identity.
 
 ### 4. Licensing: AGPL-in, sign-off, no CLA.
 

package/docs/adr/0120-pay-on-land-and-builder-owned-rebase-gate.md

@@ -1,4 +1,4 @@
-# ADR 0120 — Pay drachmae on land (not on confirm) + a builder-owned rebase gate
+# ADR 0120 — Pay example on land (not on confirm) + a builder-owned rebase gate
 
 **Date:** 2026-07-04
 **Status:** Accepted
@@ -7,7 +7,7 @@
 
 ## Context — the problem
 
-The per-task drachmae reward is awarded in **`confirmTask`** (`modules/lifecycle/db.js`,
+The per-task example reward is awarded in **`confirmTask`** (`modules/lifecycle/db.js`,
 `reward.insertMultipliedConfirmCredit`, `credit_log.reason = 'task.confirmed'`) — at the
 `completed → confirmed` transition. Confirmed means *verified + credited*, but the code is
 **not yet on `main`**: the merge to `main` + deploy is the later `confirmed → shipped`
@@ -16,7 +16,7 @@ transition, run by the auto-lander / `publish-reconciler`.
 So a builder is paid the moment they declare done and pass verification — **before their
 code lands.** When the branch then can't merge (stale after a big codebase change, a real
 conflict, or never pushed at all), the task strands at `confirmed` indefinitely with **no
-consequence to the builder**: they already have the drachmae, and nothing stops them
+consequence to the builder**: they already have the example, and nothing stops them
 claiming new work while the stranded branch rots.
 
 This is not hypothetical. On 2026-07-04 the confirmed queue held ~17 tasks across three
@@ -38,7 +38,7 @@ Re-couple reward and queue-access to **landed code**, in four parts.
    The award becomes idempotent on ship (`credit_log.reason = 'task.shipped'`, guarded by a
    uniqueness check per task, mirroring today's confirm-time guard). **The happy path barely
    changes:** a clean PR auto-merges within a minute or two of confirm, so the credit lands
-   almost immediately. The teeth only bite when a task strands — no landed code, no drachmae.
+   almost immediately. The teeth only bite when a task strands — no landed code, no example.
 
 2. **A stalled land becomes the builder's own chore (`needs_rebase`).** The
    `publish-reconciler` already detects why a confirmed task won't land — `merge_conflict`,
@@ -73,11 +73,11 @@ can do it.
 
 - **Good behavior is unaffected.** Clean work still auto-lands in minutes and pays out then;
   most builders never see `needs_rebase` or the gate.
-- **Stranding now has teeth.** No landed code → no drachmae, and a stalled land blocks new
+- **Stranding now has teeth.** No landed code → no example, and a stalled land blocks new
   claims until the builder rebases (or releases the task, forfeiting its reward).
 - **The credit ledger tells the truth.** `credit_log` credits now correspond to code that is
   actually on `main`, not to verified-but-unlanded branches.
-- **Retroactive sting.** The clawback reverses already-shown drachmae for currently-stranded
+- **Retroactive sting.** The clawback reverses already-shown example for currently-stranded
   tasks. This is intentional (it creates the pressure) and is applied uniformly, but it will
   feel punitive to builders who were paid under the old rule. The reversal is fully re-earnable:
   land the task and the `task.shipped` credit books.

package/docs/adr/0136-update-channel-subscription-policy.md

@@ -0,0 +1,51 @@
+# ADR 0136 — Update-channel subscription policy (patch-only, health-gated, opt-in, autonomy-gated)
+
+**Date:** 2026-07-10
+**Status:** Accepted.
+**Context:** [task 2150](https://example.com/builders#/task/2150) (BONGOS-V1, goal 26). The last piece of the update-consumption workstream: [ADR 0100](<redacted>.md) §2 / [task 1690](https://example.com/builders#/task/1690) gave a consumer the manual `bongos upgrade` channel; [ADR 0134](<redacted>.md) / [task 2090](https://example.com/builders#/task/2090) added the private-registry source; [task 2149](https://example.com/builders#/task/2149) added auto-rollback; [task 2157](https://example.com/builders#/task/2157) proved rollback live on the demo instance. What was missing is the **subscription** — how a consumer instance takes new releases *on a cadence, unattended*, rather than a human running `bongos upgrade` each time. Builds on the scheduled-routines portability contract ([ADR 0115](<redacted>.md)).
+
+## Problem
+
+"How do projects subscribe to regular updates?" needs a policy, not just a mechanism. Left unspecified, an auto-updater is a footgun: it could take a breaking major unattended, upgrade an instance nobody meant to enroll, or leave an instance down after a bad release. Two questions had to be answered together: **(1)** how far may an unattended upgrade jump, and **(2)** what has to be true before anything moves on its own. A third question — who *publishes* the releases the subscription consumes — is related but separable, and conflating it would have blocked (1) and (2) behind a publishing-automation decision.
+
+## Decision
+
+Adopt the owner-chosen policy (2026-07-09): **patch-only by default, health-gated with auto-rollback, opt-in, and autonomy-gated.**
+
+**1. Update channels bound the blast radius.** Each subscribed instance carries an `update_channel`:
+
+- `pinned` — never auto-upgrade (manual `bongos upgrade` only).
+- `patch` — take a higher **patch** within the same `major.minor` (`1.17.1 → 1.17.4`, never `1.18.0`). **The default.**
+- `minor` — take a higher **minor** within the same major (`1.17.1 → 1.18.0`, never `2.0.0`).
+
+A **major** bump is never automatic under any channel — a breaking change wants a human. Prereleases (`1.17.2-rc.1`) are never auto-targeted. This math is the pure, unit-tested core [`scripts/gds/update-channel.js`](../../scripts/gds/update-channel.js) (`resolveChannelTarget` / `channelAllows`), so the "what should this instance move to?" decision is testable in isolation from any I/O.
+
+**2. The registry is the source of truth for "what's newest."** A subscription needs a live feed of published versions — `npm view @bongos/core versions` against the private registry (ADR 0134), not a vendored tarball. The vendored path stays the manual-bump fallback.
+
+**3. Every auto-upgrade is health-gated with auto-rollback.** The routine drives `bongos upgrade --to <v> --registry` with auto-rollback **ON** (task 2149): a patch that fails install/migrate/health reverts its pin, reinstalls the previous core, restarts, and records a `rolled_back` ledger row. The DB is left intact (core migrations are additive/forward-safe). So "unattended" never means "unsafe."
+
+**4. Triple-gated before anything moves.** The scheduled routine [`core-update-subscription`](../../.claude/scheduled-tasks/core-update-subscription/) is:
+
+- **Autonomy-gated** — `requiresAutonomy: true` in [`config/scheduled-routines.json`](../../config/scheduled-routines.json), a no-op until the instance arms `<PREFIX>_AUTONOMY_ENABLED`. Default **OFF** (ADR 0115's rule for autonomous-action routines).
+- **Opt-in** — the roster [`config/update-subscriptions.json`](../../config/update-subscriptions.json) ships **empty**; an instance is touched only after an operator lists it (with its dir, systemd unit, health URL, channel, and an optional `env` map so `migrate` hits the right DB).
+- **Health-gated** — per (3).
+
+The routine is `mode: deterministic` (System 4, [ADR 0078](<redacted>.md)) — it runs as plain `node` with no model session — and **instance-wide** (ADR 0115): one run per instance iterating the roster, not one cron per instance-being-watched.
+
+**5. Upstream auto-publish is explicitly split out, not decided here.** For a subscription to deliver anything, new patches must be *published*. Today that is a gated owner step (`package-core.js --publish --live`, ADR 0134). This ADR deliberately scopes the subscription to **consume whatever the owner has published** and does **not** decide whether merges to `main` auto-publish a patch. That is its own decision (publishing cadence, provenance, who holds the token) and is filed as [task 2158](https://example.com/builders#/task/2158). Splitting it lets goal 26 close on the consumption half, which is what the switchover needs.
+
+**6. Scope: local, same-host instances.** The routine upgrades instances reachable from the control plane on the same host (the co-hosted shape — e.g. the demo instance beside the control plane). Multi-host / SSH orchestration across a real fleet is the deferred managed-fleet-control-plane epic ([task 1948](https://example.com/builders#/task/1948) / idea 303, "no fleet registry exists"); this routine is the per-instance consumption half that epic will call.
+
+## Alternatives considered
+
+- **A `provisioning_instances` DB column for the roster + channel.** Rejected for now: the provisioning module models a *request→standup* lifecycle, not a subscription; coupling the subscription to it presumes the fleet-registry schema that is still being designed. A config manifest is migration-free (matches the task's `needs_migration:false`), matches the ADR-0115 "operator configures via a manifest" pattern, and is trivially superseded later by a `loadSubscriptions()` seam swap.
+- **Auto-take minors by default.** Rejected: minors can carry behavior changes; patch-only is the conservative default an operator can widen per instance.
+- **No dry-run / apply-always.** Rejected: `subscribe.js` is dry-run by default (the box-sweep convention); the scheduled step passes `--apply`. A hand run previews safely.
+- **Deciding auto-publish here.** Rejected — see (5); it would have blocked the consumption half behind an orthogonal publishing decision.
+
+## Consequences
+
+- **`config/update-subscriptions.json` is the portability surface** for subscriptions — the one place an operator opts an instance in and sets its channel. A vanilla instance boots subscribed to nothing.
+- **The policy is enforced by a pure, tested core**, not prose: [`tests/update_channel.mjs`](../../tests/update_channel.mjs) pins the channel matrix (majors/prereleases never auto, patch stays on its minor, pinned/unknown → no-op).
+- **A follow-up task owns upstream auto-publish** — [task 2158](https://example.com/builders#/task/2158) (whether/how `main` merges publish a patch: cadence, version-bump provenance, token custody, the pre-publish no-leak gate). Until it lands, the subscription simply picks up whatever the owner publishes, which is safe and useful on day one.
+- **No behavior change until armed.** OTB (and any fresh instance) ships this OFF with an empty roster; nothing auto-upgrades until an operator both arms autonomy and enrolls an instance.

package/docs/adr/0137-upstream-publish-policy-manual-owner-gated.md

@@ -0,0 +1,40 @@
+# 0137 — Upstream publish policy: `@bongos/core` patches are published manually (owner-gated), not auto-published on merge
+
+- **Status:** Accepted
+- **Date:** 2026-07-10
+- **Deciders:** example-owner (owner/Archon), Claude. Presented the manual-vs-auto fork; the owner chose to keep publishing a manual, owner-triggered step.
+- **Task:** [#2158](https://example.com/builders#/task/2158) (BONGOS-V1, goal 26) — the **supply** half split out of [ADR 0136](<redacted>.md) §5 / [#2150](https://example.com/builders#/task/2150).
+- **Builds on:** [ADR 0134](<redacted>.md) (private-first npm, tokenless tooling), [ADR 0136](<redacted>.md) (subscription consumption policy). **Relates to:** the deferred managed-fleet-control-plane epic ([#1948](https://example.com/builders#/task/1948)).
+
+## Context
+
+[ADR 0136](<redacted>.md) (task 2150) built the **consumption** half of the `@bongos/core` update subscription — the channel math (`pinned`/`patch`/`minor`, never `major`/prerelease unattended) and the auto-upgrade routine that consumes published releases on a cadence. It explicitly deferred (§5) the **supply** half: *"does not decide whether merges to `main` auto-publish a patch. That is its own decision (publishing cadence, provenance, who holds the token)."* This ADR is that decision.
+
+Today, per [ADR 0134](<redacted>.md), publishing is a **gated owner step**: `node scripts/gds/package-core.js --publish --live` requires the owner's `npm login` + 2FA, and *the repo/tooling holds no token* ("npm owns auth — this repo never stores a token"). Consumers install with a **read-only** token via an env-fed `.npmrc`. For a subscription to deliver anything, new patches must be published — so the open question was whether to **automate** that publish (on-merge, using a CI-stored write token) or keep it **manual**.
+
+## Decision
+
+**Publishing `@bongos/core` stays a manual, owner-gated step. Merges to `main` do NOT auto-publish.**
+
+1. **Trigger / cadence — owner-initiated.** The owner runs `package-core.js --publish --live` when they decide to cut a release. Recommended convention: tag the released commit `core-v<version>` as the deliberate, auditable release marker. The tag *documents* the release; it does **not** trigger CI.
+2. **Version-bump provenance — deliberate, in-task.** `CORE_VERSION` (`src/module-api.js`) is bumped by hand as part of a task, with a changelog line in the same file (the existing discipline — e.g. task 2148 bumped `1.17.1 → 1.17.2` with a changelog entry). It is **not** auto-bumped. A release publishes whatever `CORE_VERSION` currently is; a stale (un-bumped) version collides with the already-published npm version and npm rejects the duplicate — a natural guard against an accidental no-op republish.
+3. **Token custody — no write-token at rest.** No npm **write** token is stored in CI or the repo. The owner authenticates at publish time (a Classic Automation token bypasses the interactive 2FA-OTP prompt when scripting locally; interactive `npm login` + 2FA otherwise). This preserves ADR 0134's tokenless-tooling posture. Only the **read** token (for consumer / CI installs, env-fed `NPM_TOKEN`) exists.
+4. **No-leak / mirror-redact gate — already fail-closed.** `package-core.js` builds the artifact *through* the no-leak gate (docs genericized + secret-scrubbed; functional files scanned for a live-credential leak) and **produces nothing** if anything leaks, so `--publish` structurally cannot upload a leaking artifact. No extra gate is needed for the manual path — and any future automated path inherits the same fail-closed gate because it runs the same build.
+5. **The subscription is unchanged.** The [ADR 0136](<redacted>.md) routine consumes whatever the owner has published. Its freshness is bounded by the owner's release cadence — intended and acceptable at current scale.
+
+## Why manual over auto (the trade-off)
+
+- **Security surface.** <redacted> requires a long-lived npm **automation write** token as a standing CI secret — a powerful credential that could publish to the canonical brand org from any merge. That reverses ADR 0134's deliberate tokenless-tooling posture for little near-term gain.
+- **Low, deliberate volume.** Core patches are infrequent and intentional (`1.17.0 → .1 → .2` over days, each driven by a specific task). The manual publish is not the bottleneck; the consumption side already flows.
+- **Bootstrapped posture** ([CLAUDE.md §4](../../CLAUDE.md)). Don't build and secure CI-publishing machinery before a real fleet justifies it.
+
+## When to revisit
+
+When the **managed-fleet-control-plane epic** ([#1948](https://example.com/builders#/task/1948)) stands up a real multi-instance fleet and the manual publish becomes a genuine bottleneck, re-evaluate a **tag-triggered** CI publish (a human still cuts the `core-v<version>` tag; CI runs the already-fail-closed gated publish with a narrowly-scoped token). That is deliberately out of scope here — this ADR keeps the supply side simple so goal 26 closes on the consumption half.
+
+## Consequences
+
+- **Owner-only step at each release** (out of a build session; capture as a blocker if it ever gates verification): bump `CORE_VERSION` + changelog in a task, then run `package-core.js --publish --live`.
+- The **release ritual** is documented in [`docs/recipes/private-npm-distribution.md`](../recipes/private-npm-distribution.md) → "Cutting a core release".
+- **No CI secret, no new automation** to maintain.
+- A consumer on the `patch`/`minor` channel only receives an update **after** the owner publishes — the subscription's freshness is owner-paced by design.

package/docs/adr/0138-bundled-module-deps-declared-per-module.md

@@ -0,0 +1,45 @@
+# 0138 — A core-bundled module's external npm deps are declared per-module; the consumer composes them (core stays lean)
+
+- **Status:** Accepted
+- **Date:** 2026-07-10
+- **Deciders:** example-owner (owner/Archon), Claude. Presented the fork (keep core lean + declare per-module vs. hoist the dep into `@bongos/core`); the owner chose to keep core lean.
+- **Task:** [#2160](https://example.com/builders#/task/2160) (BONGOS-V1, goal 26) — rehearsal finding **F2** from the R89 cutover rehearsal ([`docs/reviews/<redacted>.md`](../reviews/<redacted>.md)).
+- **Builds on:** [ADR 0108](<redacted>.md) (core consumed as a pinned npm dep; core deps = express+pg), [ADR 0083](<redacted>.md) (the module manifest contract).
+
+## Context
+
+The R89 cutover rehearsal converted the example monolith into a `@bongos/core` consumer and surfaced **F2**: with `dependencies: { "@bongos/core" }` alone the consumer boots and then crashes on `Cannot find module 'colyseus'` — and, more subtly, on `Cannot find module 'discord.js'`. The game/art deps (`colyseus`, `phaser`, `sharp`) are obviously the host's. But `discord.js` is different: the **discord module ships INSIDE `@bongos/core`** (it's one of the ~15 bundled core modules), yet `package-core.js` synthesizes only `express` + `pg` as the core's `dependencies` ([ADR 0108](<redacted>.md) §Context). So the core ships the discord module's *code* but declares none of its *runtime dep* — the consumer is silently expected to provide `discord.js`, with a boot crash as the only feedback.
+
+Two facts frame the decision:
+
+- **`discord.js` is the only such case today.** A scan of every bundled core module found exactly one external npm require beyond `express`/node built-ins: `discord.js`, in the discord module.
+- **The discord module is opt-in** (`module.json` `default: false`). Most instances never enable it.
+
+So the open question (rehearsal F2, "separately decide"): should `@bongos/core` declare its bundled-module deps (e.g. `discord.js`) itself — as `optionalDependencies`/`peerDependencies` — or should the consumer provide them?
+
+## Decision
+
+**`@bongos/core` stays lean (`express` + `pg`). A bundled module that needs an external npm dependency declares it in its own `module.json` `dependencies`, and the consumer composes the deps of the modules it ENABLES.**
+
+1. **Core deps unchanged.** `package-core.js` continues to synthesize `dependencies: { express, pg }` (+ the undici pin). We do **not** hoist `discord.js` (or any future module dep) into the core package.
+2. **Manifest field.** `module.json` gains an optional `dependencies: { "<npm-name>": "<semver-range>" }` block ([`src/module-loader/manifest-schema.js`](../../src/module-loader/manifest-schema.js) validates it — a typo'd range is caught, not silently ignored). The discord manifest declares `{ "discord.js": "^14.26.4" }` — the honest home for the fact.
+3. **Consumer composition.** Greenfield `bongos init` composes the ENABLED modules' declared deps into the instance `package.json` ([`scripts/gds/init.js`](../../scripts/gds/init.js) `enabledModuleDeps` → `buildInstancePackageJson`), so turning a module on brings its npm deps. Precedence: module deps fill gaps, an explicit pre-existing instance pin wins, `@bongos/core` is always set.
+4. **The cutover preserves.** The example R89 cutover re-authors the consumer `package.json` from the monolith's **existing** dependency closure ∪ `@bongos/core` (runbook §2) — the monolith already carries `discord.js` + the game/art deps, so preserving is sufficient there. `enabledModuleDeps` is the greenfield/adopt path, not the conversion path.
+
+## Why lean-core over hoisting (the trade-off)
+
+- **Hoisting bloats the common case.** `optionalDependencies` still install by default, so declaring `discord.js` in core makes **every** consumer download it (and its transitive `undici`, WebSocket stack, …) for a module that is **off by default**. That directly cuts against [ADR 0108](<redacted>.md)'s deliberate lean-core choice.
+- **`peerDependencies` don't fix the crash.** An *optional* peer dep is not auto-installed by npm, so the boot crash would remain; a *required* peer dep is just hoisting with extra warnings.
+- **Per-module declaration is honest and scales.** The dep lives with the code that needs it, the manifest stays the single source of truth for "what this module is," and the pattern generalizes to any future module without re-touching core.
+- **`--omit=optional` is opt-out, not opt-in.** Relying on consumers to prune an unwanted dep is the wrong default; composing only enabled modules' deps is opt-in by construction.
+
+## Consequences
+
+- **`@bongos/core`'s dependency surface stays minimal + auditable** — the property [ADR 0108](<redacted>.md) and `package_core.mjs` (`dependencies == { express, pg }`) already lock in.
+- **A bundled module with an external dep MUST declare it** in `module.json` `dependencies`, or a consumer that enables it crashes at boot. Documented in [`docs/modules-contract.md`](../modules-contract.md).
+- **Greenfield/adopt** instances that enable a module get its deps automatically; the **R89 cutover** stays a preserve-existing-closure step.
+- **No new standing credential or CI machinery** — this is authoring-time composition, not an install-time core change.
+
+## When to revisit
+
+If a bundled module ever becomes `default: true` AND carries a heavy external dep, revisit whether that module belongs in the core bundle at all (vs. an opt-in add-on) — the dep-posture question would then be downstream of a module-bundling question.