@bongos/core 1.17.0 → 1.17.2

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/0133-github-app-manifest-onboarding-signin.md

@@ -33,6 +33,8 @@ The conversion endpoint is unauthenticated (the code is the auth), so the web ti
 
 `redirect_url` = the **mothership** callback (the instance can't do the exchange). `callback_urls` = the **instance's** own `/api/gds/auth/web/callback` (what `auth.js` actually builds) **and** the `/api/bongos/...` alias, so sign-in works regardless of which prefix a build emits. `default_permissions: {}` (sign-in needs none), `hook_attributes.active:false`, `public:false`. Personal vs org differs only in the POST URL (derived from the repo owner); the App works for sign-in either way.
 
+**App name (tasks 2093 → 2095).** GitHub App names are globally unique across all of GitHub, so a bare project slug (e.g. `demo`) is almost always already taken. The auto name is the **instance domain** (e.g. `demo.cloudbongos.com`): a domain is inherently unique (so it never collides) and it reads perfectly on GitHub's sign-in consent screen, where the name is shown as *"`<name>` by `<owner>` … will redirect to `https://<domain>`"* — the name IS the destination. GitHub keeps the dots in the display name (only the internal slug is transformed) and caps it at 34 chars. **Fallback** (no domain, or a domain over 34 chars): brand-qualify the project — `<mothership brand> - <project>`, e.g. `Cloud Bongos - demo`, from the mothership's own `branding().identity.productName` (portable, not hardcoded) — still far less collision-prone than a bare slug. Either way it is only a default the owner can rename on GitHub's confirmation screen.
+
 ## Consequences
 
 - **Back-compat preserved.** An instance already on an OAuth App keeps working untouched — `loadGithubCreds()` reads the same `<PREFIX>_GITHUB_CLIENT_ID/SECRET`. The manifest path is the new *default* for fresh instances; nothing about `auth.js` changed.

package/docs/adr/0134-private-first-npm-distribution.md

@@ -3,12 +3,12 @@
 - **Status:** Accepted — publish path + private-by-default config built in task 2089; the real publish is a gated owner step.
 - **Date:** 2026-07-07
 - **Deciders:** example-owner (owner/Archon), Claude. Owner asked to have the npm/CLI onboarding commands ready but kept private pre-launch, choosing paid private npm over the free GitHub Packages option.
-- **Task:** [#2089](https://example.com/builders#/task/2089) · **Goal:** 35 (project-creation flow), criterion 165.
+- **Task:** [#2089](https://example.com/builders#/task/2089) (publish path + private config) · [#2092](https://example.com/builders#/task/2092) (the `@cloudbongos` → `@bongos` scope rename + first real publish) · **Goal:** 35 (project-creation flow), criterion 165.
 - **Refines:** [#2025](https://example.com/builders#/task/2025) (the 2026-07-04 *public* unscoped `cloudbongos` decision — now the launch-time go-public step, not superseded) · **Builds on:** [ADR 0108](<redacted>.md) (core-as-npm-dep), [#2053](https://example.com/builders#/task/2053) (vendored-tarball install).
 
 ## Context
 
-A new owner stands up a standalone instance that depends on `@cloudbongos/core` (ADR 0108), and external programs call the API through `@cloudbongos/client` (ADR 0118). Today neither is on a registry: `package-core.js` produces a real, installable `.tgz`, and provisioning **vendors that tarball** into each instance repo (a `file:` pin `npm ci` resolves — task 2053). That works, but the onboarding experience isn't the clean `npm install @cloudbongos/core` an owner expects, and the client's on-ramp doc referenced a nonexistent "internal registry."
+A new owner stands up a standalone instance that depends on `@bongos/core` (ADR 0108), and external programs call the API through `@bongos/client` (ADR 0118). Today neither is on a registry: `package-core.js` produces a real, installable `.tgz`, and provisioning **vendors that tarball** into each instance repo (a `file:` pin `npm ci` resolves — task 2053). That works, but the onboarding experience isn't the clean `npm install @bongos/core` an owner expects, and the client's on-ramp doc referenced a nonexistent "internal registry."
 
 The owner wants the npm/CLI commands **ready and usable pre-launch, but not public** — Cloud Bongos shouldn't be installable by the general public before launch. Two prior decisions bear on this: the *public* install name was set to the unscoped **`cloudbongos`** (task 2025, deferred), and the `bongos` + ~10 defensive npm orgs were reserved under the owner's login.
 
@@ -16,15 +16,17 @@ One npm rule forces the shape: **unscoped packages are always public — only *s
 
 ## Decision
 
-Publish **`@cloudbongos/core`** and **`@cloudbongos/client`** as **scoped, private** npm packages during pre-launch, on a **paid** `cloudbongos` npm org. Both already use the `@cloudbongos` scope (an org the owner holds), so **no rename is needed now**.
+Publish **`@bongos/core`** and **`@bongos/client`** as **scoped, private** npm packages during pre-launch, on the owner's **paid** `bongos` npm org — the **canonical** brand org.
+
+> **Scope correction (task 2092).** The publish path first shipped (task 2089) under the `@cloudbongos` scope, matching the name the repo already used. But when publishing, the paid org turned out to be **`bongos`** (the canonical brand the owner put on Teams), while `cloudbongos` — one of the ~10 defensive orgs — was left on the free tier. Since a private scoped publish requires the scope to match a *paid* org, and `@bongos` is the intended canonical brand anyway, we **renamed the core + client package identity `@cloudbongos/*` → `@bongos/*`** (a consistent rename across the build + vendored-install flow, verified by the test suite) rather than pay for a second org. Existing vendored consumers keep their pinned `@cloudbongos/core` tarball; only new scaffolds use `@bongos`.
 
 - **Private by default in code, not just by flag.** The synthesized core `package.json` (`buildPackageJson`) and the generated client `package.json` (`gen-api-client.js`) both carry `publishConfig: { access: "restricted" }`. `package-core.js --publish` additionally passes `--access restricted` on the CLI — belt-and-suspenders so a stray config edit can't silently make the pre-launch artifact public.
 - **The publish is a gated owner step; the tooling holds no token.** `package-core.js --publish` **dry-runs** by default; the real, permanent publish needs `--publish --live` plus the owner's `npm login` and the org on a paid plan. npm owns auth — this repo never stores a token.
 - **Consumers authenticate with an env-fed `.npmrc`:** `//registry.npmjs.org/:_authToken=<redacted> The token expands from the environment, so it never lands in a committed file. Only members of the paid org can install.
 - **The vendored-tarball path stays as the working default/fallback.** Rewiring provision/init to auto-pull the pinned core from the registry (env-fed token on the control plane) is a follow-up — it touches a proven, protected control-plane flow and isn't required for "commands ready + private." Publishing privately + documented auth already delivers a real `npm install`.
-- **Going public at launch is one step**, chosen then: either `npm access public @cloudbongos/core` (keeps the scoped name), or execute task 2025 to *also* publish the unscoped vanity `cloudbongos` for `npm install -g cloudbongos`. Task 2025 is therefore the launch-time go-public leg, not replaced by this.
+- **Going public at launch is one step**, chosen then: either `npm access public @bongos/core` (keeps the scoped name), or execute task 2025 to *also* publish the unscoped vanity `cloudbongos` for `npm install -g cloudbongos`. Task 2025 is therefore the launch-time go-public leg, not replaced by this.
 
-The daily command stays `bongos` regardless of package name (the `bin` mapping in the synthesized package.json is name-independent), so `npm install -g @cloudbongos/core` → `bongos init` works today, and the eventual public `cloudbongos` name changes nothing for users.
+The daily command stays `bongos` regardless of package name (the `bin` mapping in the synthesized package.json is name-independent), so `npm install -g @bongos/core` → `bongos init` works today, and the eventual public `cloudbongos` name changes nothing for users.
 
 ## Why paid private npm over the free GitHub Packages alternative
 
@@ -32,7 +34,19 @@ The owner chose it deliberately, knowing the trade-off. GitHub Packages is free
 
 ## Consequences
 
-- Cost: a paid `cloudbongos` npm org seat per person who needs to install during pre-launch. Gone at launch.
+- Cost: a paid `bongos` npm org seat per person who needs to install during pre-launch. Gone at launch.
 - Owner-only steps (out of the build session; capture as a blocker if they gate verification): put the org on a paid plan; generate an npm access token (automation — read-write to publish, read for CI/provision installs); run `package-core.js --publish --live` (permanent; login + 2FA).
 - Follow-up: wire provision/init to install the pinned core from the private registry (env-fed `NPM_TOKEN`), keeping the vendored tarball as fallback.
 - Full operator runbook — org, plan, token, publish, consumer `.npmrc`, and the go-public flip — is [`docs/recipes/private-npm-distribution.md`](../recipes/private-npm-distribution.md).
+
+## Update — the provision/init registry path is wired (task 2090)
+
+The follow-up above shipped. The wiring is **opt-in and fail-soft**, so the proven vendored-tarball path stays the default until the registry path is proven end-to-end on a real greenfield standup:
+
+- **One source of truth**: `scripts/gds/npmrc.js` owns the env-fed `.npmrc` body (`@bongos:registry=…` + `_authToken=<redacted> and the gates (`hasNpmToken`, `registryCoreRequested`). The token expands from the environment at install time, so nothing secret is committed.
+- **init** (`--registry-core`): keeps the caret pin and writes the `.npmrc`; with `NPM_TOKEN` set it also generates `package-lock.json` from the registry. Mutually exclusive with `--vendor-core`.
+- **provision** (standalone scaffold): opt-in via `PROVISION_CORE_FROM_REGISTRY=1`; when a token is present it scaffolds via `init --registry-core` (no tarball build), and when the flag is set but no token is present it **falls back to the vendored tarball** — a tokenless standup still works.
+- **upgrade** (`--to <v> --registry`): pins the exact registry version + ensures the `.npmrc` instead of vendoring; mutually exclusive with `--from`.
+- **Verified — both legs green (task 2118, 2026-07-08).**
+  - *Tokenless:* a scaffolded instance with the caret pin + env-fed `.npmrc` and **no** `NPM_TOKEN` 404s cleanly on `npm install` (`E404 … @bongos/core … could not be found or you do not have permission to access it`) — it fails closed.
+  - *With token (the leg blocker 71 tracked):* a real `bongos init --registry-core` scaffold with a valid **read-only** token (paid `bongos` org) resolved `@bongos/core@1.17.0` from `registry.npmjs.org` and generated a reproducible `package-lock.json` (`resolved: https://registry.npmjs.org/@bongos/core/-/core-1.17.0.tgz`). The registry pull works with a token and fails closed without one — so the opt-in registry path is proven end-to-end, and blocker 71 is resolved. The vendored tarball remains the default until an owner chooses to flip a live provisioner to `PROVISION_CORE_FROM_REGISTRY=1`.

package/docs/adr/0135-module-upstream-submission-interim-queue.md

@@ -0,0 +1,34 @@
+# 0135 — Module upstream submission: the review queue lives in the submitting instance's own DB (interim)
+
+- **Status:** Accepted
+- **Date:** 2026-07-08
+- **Task:** [#1770](https://example.com/builders#/task/1770) (BONGOS-V1) — `bongos module submit` + `POST /modules/:key/submit`.
+- **Builds on:** [ADR 0107](<redacted>.md) (the upstreaming decision — submit → review → accept), [ADR 0103](<redacted>.md) (the core extracted to `github.com/example-owner/cloud-bongos`, private), [ADR 0100](<redacted>.md) §3 (per-repo GDS — each project runs its own DB).
+
+## Context
+
+ADR 0107 §1 describes `bongos module submit <key>` as packaging a module + attribution + a DCO sign-off and filing it "into a rank-gated review queue **on the core**" — without granting the submitting instance write access to core. Task 1770 depends on R88 (the core extraction, [#1727](https://example.com/builders#/task/1727), shipped) and originally also listed R85 (Mercury, the forcing-function second consumer). R85 was abandoned ([#1689](https://example.com/builders#/task/1689)): the two-repo model it was meant to prove is already proven end-to-end by a different standalone instance, so it dropped as a dependency.
+
+That leaves a gap task 1770 has to resolve to be buildable at all: **what does "on the core" concretely mean today?** The extracted core repo (`github.com/example-owner/cloud-bongos`) is a **private git repository, not a running service** — it has no HTTP API, no reachable review-queue endpoint, and (per ADR 0100 §3) each Cloud Bongos project runs its **own** GDS database; there is no shared cross-repo GDS a submission could land in. Building a real cross-repo network submission would mean inventing a core-side API that doesn't exist yet, authenticating an instance against it, and defining a wire format — none of which is this task's job (that's ADR 0107 §8's *pipeline* stage, gated on task 1771, "core-side review & accept flow," which is still `backlog`).
+
+## Decision
+
+**The review queue is a table (`module_submissions`, migration `<redacted>.sql`) in THIS instance's own Bongos DB** — the same database the module was built against — not a network call to a remote core.
+
+- `bongos module submit <key>` packages the module (manifest + a full base64 file snapshot + the recorded DCO sign-off), re-runs the ADR 0107 §4 AGPL/publish pre-check, and **refuses (exit 1)** if the pre-check fails or no sign-off is on file — exactly the ADR's "done when" bar.
+- The packaging + submission both flow through `POST /api/gds/modules/:key/submit` (rank: metic+archon) — the SAME route the hall "Modules" tab's submit button calls (ADR 0107 §9), so there is one authoritative implementation, not a CLI copy and a UI copy. The route re-runs the pre-check against **its own** on-disk copy of the module (the server's deployed checkout), which is the real gate — a builder's local pre-check pass is a courtesy/fail-fast, not proof, if their changes aren't committed + shipped + deployed yet.
+- `GET /api/gds/modules/submissions` (rank: metic+archon) lists the queue — the surface task 1771's core-side review UI reads from.
+
+This satisfies the letter of ADR 0107 §1 ("rank-gated review queue," "refuses if the pre-check fails," "captures attribution + sign-off") using infrastructure that actually exists today, and is forward-compatible: when a real core-side receiving endpoint exists (task 1771 or later), filing becomes a network hop to that endpoint instead of a local `INSERT`, with **no change to the CLI's or the hall UI's caller-facing contract** (both already only see `{ signed_by }` in, `{ submission }` out).
+
+## Alternatives considered (rejected)
+
+- **A live HTTP call to a core-hosted endpoint.** Rejected for now — no such endpoint exists; inventing one is task 1771's job (core-side review & accept), not the submit side's. Building it here would mean guessing at a contract 1771 might not honor.
+- **A GitHub Issue/PR against `github.com/example-owner/cloud-bongos` via the GitHub API.** Considered (the ADR's "fork-and-PR remains a fallback" framing), but rejected as the *native* path: it would silently degrade every submission to the explicitly-non-canonical fallback, loses the structured queue (status/reviewed_by/reviewed_at) task 1771 needs, and the repo is private — the CLI/server have no standing GitHub credential scoped for that repo today.
+- **A dry-run-only client (mirroring `do-api.js`'s DigitalOcean/Cloudflare pattern) that just logs "would submit" and writes a local file.** Rejected — a local orphan file is a worse "review queue" than a real, queryable DB table the instance already operates and backs up; it would need its own bespoke listing/status mechanism that duplicates what Postgres already gives us for free.
+
+## Consequences
+
+- **The queue is scoped per-instance, not global**, until a real cross-repo channel exists. Two instances submitting modules with the same key don't collide (each queue is local), which is fine for now (there is exactly one non-abandoned instance, this one) but is a real gap once a second live instance exists — revisit when task 1771 is scoped.
+- **Task 1771** ("core-side review & accept flow") inherits a concrete shape to review against: read `module_submissions` (`status='pending'`), accept/reject with `reviewed_by`/`reviewed_at`/`review_notes`, and the accept action still has to do the ADR 0107 §6 checklist (land in `modules/<key>/`, `default:false`, allowlist, record attribution) — this ADR does not change any of that.
+- **`scripts/gds/module.js` is required directly by `src/bongos/routes/modules.js`** (both resolve under `resolveCoreRoot()` — see `scripts/gds/CLAUDE.md`) to reuse `checkModulePublishability`/`recordSignOff`/`readSignOff`/`<redacted>` rather than re-implementing the pre-check server-side. `module.js` never statically requires the CLI session/fetch layer (`cli-lib.js`) — only `cmdSubmit`'s network leg lazy-requires it, and only when a human/agent actually runs the CLI — so this stays safe to load into the always-on server process (the same discipline `llm-cache.js` documents for the same reason).

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.