@bongos/core 1.17.1 → 1.17.3

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

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

package/docs/onboarding/primer.md

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

package/docs/recipes/audit-replay.md

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

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

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

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

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

package/docs/recipes/ops-gotchas.md

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

package/docs/recipes/private-npm-distribution.md

@@ -47,6 +47,23 @@ npm pack ./clients/bongos-client --dry-run        # token-free content preview
 npm publish ./clients/bongos-client               # real (publishConfig makes it restricted; needs npm login)
 ```
 
+## Cutting a core release (the policy — [ADR 0137](../adr/<redacted>.md))
+
+Publishing is a **manual, owner-gated step** — merges to `main` do **not** auto-publish (no npm write-token lives in CI). The update subscription ([ADR 0136](../adr/<redacted>.md)) consumes whatever the owner has published, so a release is exactly: bump → publish → the subscription picks it up on its next sweep.
+
+1. **Bump `CORE_VERSION`** in [`src/module-api.js`](../../src/module-api.js) (semver; a **patch** for a fix, **minor** for additive surface — a **major** is a deliberate, human-only event) and add a one-line changelog entry in the same file. This bump is a normal claimed task, not a release-tool side effect — the version's provenance stays in the git history + changelog.
+2. **Publish** (owner, from a clean checkout of the released commit):
+   ```sh
+   node scripts/gds/package-core.js --publish        # DRY-RUN: runs the fail-closed no-leak gate, previews @bongos/core@<version>
+   npm login                                          # once per machine (+ 2FA), or use a Classic Automation token
+   node scripts/gds/package-core.js --publish --live  # permanent; the no-leak gate must pass or nothing is built/uploaded
+   ```
+   The no-leak / mirror-redact gate is **built into the build** — a leaking artifact is never produced, so `--publish` cannot upload one.
+3. **Tag the release** (optional but recommended — the deliberate, auditable marker): `git tag core-v<version> && git push origin core-v<version>`. The tag documents intent; it triggers no CI.
+4. **Done.** Subscribed instances on the `patch`/`minor` channel take it automatically on their next routine sweep; `pinned` instances wait for a manual `bongos upgrade`. A stale (un-bumped) version is rejected by npm as a duplicate — a natural guard.
+
+> **Automating this** (a tag-triggered CI publish) is deferred to the managed-fleet epic ([#1948](https://example.com/builders#/task/1948)); revisit when the manual step becomes a real bottleneck. See [ADR 0137](../adr/<redacted>.md) "When to revisit".
+
 ## Install a private package (any consumer machine or instance)
 
 Add a one-line `.npmrc` (repo-root or `~/.npmrc`) that reads the token from the environment:

package/docs/recipes/staging-environment.md

@@ -65,7 +65,7 @@ If `*.example.com` is **not** in the output:
 The prod OAuth app points its callback at `example.com/api/gds/auth/web/callback`. Staging needs its own:
 
 1. github.com → Settings → Developer settings → OAuth Apps → New OAuth App.
-2. Application name: `Off the Boats — staging`.
+2. Application name: `Example — staging`.
 3. Homepage URL: `https://staging.example.com`.
 4. Authorization callback URL: `https://staging.example.com/api/gds/auth/web/callback`.
 5. Note the **Client ID** and **Client Secret** — they go into `/home/lars/example-staging/.env` (see step 4 of the provisioning script).

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

@@ -13,6 +13,7 @@
 5. **materialize `.claude/`** — refresh skills/settings/hooks from the new core (`materializeClaude`), rewriting invocations to the `bongos` bin.
 6. **restart** — `--service <unit>` or `--restart-cmd "<cmd>"`.
 7. **verify** — installed version == target (+ optional `--health-url`).
+8. **auto-rollback on failure** (task [#2149](https://example.com/builders#/task/2149), default ON) — if `npm install`/`migrate` fails or the step-7 health check fails, revert the pin → reinstall the previous core → restart → re-verify → write a `rolled_back:` ledger row. Opt out with `--no-rollback-on-failure`. See the section below.
 
 Run bare (`bongos upgrade`, no `--to`) it stays the module-compat **pre-check** only.
 
@@ -50,6 +51,60 @@ The instance runs on the droplet (co-tenant): systemd `emersonian-circles.servic
 6. **Update the repo of record** — run the channel on the laptop clone (`--skip-migrate`, no DB there), commit the pin bump (drop the superseded tarball), `git push origin`.
 7. **Align the droplet checkout** — the droplet has no deploy key (`git pull` fails; idea 509), so `git bundle` the new commit on the laptop, `scp`, `git fetch <bundle> && git reset --hard FETCH_HEAD`. `node_modules` is already the new version, so no re-`npm ci`; a final restart makes `/version` report the new commit.
 
+## Auto-rollback on failure (task 2149)
+
+By default (`--rollback-on-failure`, ON unless `--no-rollback-on-failure`) the channel self-heals a failed bump. If **`npm install` fails**, **`npm run migrate` fails**, or the **post-restart health check fails**, `bongos upgrade` automatically:
+
+1. reverts the `@bongos/core` pin to the exact pre-upgrade dep string (snapshotted the instant the pin moved),
+2. `npm install`s the previous core back,
+3. restarts the service,
+4. re-verifies (installed == previous, health recovers),
+5. records a `rolled_back: <reason> (attempted N → N+1, restored N)` row in `core_upgrades`.
+
+**The DB is NOT rolled back — only the code pin.** Core migrations are additive + forward-safe (the core migration rule), so an already-applied migration is left in place; a *failed* migration is never recorded in `schema_migrations`, so a retry re-runs it cleanly. The reversal is recorded via the always-present `note` column (not a new `outcome` column) so it lands even in the failed-migrate path — where a newer column wouldn't yet exist on that instance.
+
+**Proven live on demo.cloudbongos.com** (task [#2157](https://example.com/builders#/task/2157)): demo, on rollback-capable 1.17.3, was upgraded to a canary carrying a deliberately-failing migration. Migrate raised → the channel auto-reverted the pin to 1.17.3, reinstalled + restarted it, `/healthz` stayed 200 (**zero downtime** — the failure was at migrate, before the restart), and a `rolled_back` ledger row was written. This is the safety gate the unattended patch-only auto-upgrade subscription (task [#2150](https://example.com/builders#/task/2150)) depends on.
+
+## Subscribing to updates — unattended patch-only auto-upgrade (task 2150 / ADR 0136)
+
+The sections above are the *manual* `bongos upgrade`. The **subscription** runs it for you, on a cadence, safely — the "subscribe to regular updates" experience. Policy: **patch-only by default, health-gated with auto-rollback, opt-in, autonomy-gated** (full rationale in [ADR 0136](../adr/<redacted>.md)).
+
+**Per-instance channel** bounds how far an unattended upgrade may jump:
+
+| channel | takes | example (from `1.17.1`) |
+|---|---|---|
+| `pinned` | nothing (manual only) | — |
+| `patch` *(default)* | higher patch, same `x.y` | `→ 1.17.4`, never `1.18.0` |
+| `minor` | higher minor, same major | `→ 1.18.0`, never `2.0.0` |
+
+A **major** is never automatic; prereleases are never auto-targeted.
+
+**Enrolling an instance** — add it to [`config/update-subscriptions.json`](../../config/update-subscriptions.json) (ships empty). `env` carries per-instance vars merged into the upgrade child — set `PGDATABASE` so `migrate` hits the right DB (see the Gotchas):
+
+```json
+{
+  "defaultChannel": "patch",
+  "instances": [
+    { "slug": "demo", "dir": "/srv/cloudbongos/demo", "service": "demo.service",
+      "healthUrl": "https://demo.cloudbongos.com/healthz", "channel": "patch",
+      "env": { "PGDATABASE": "demo" } }
+  ]
+}
+```
+
+**Preview vs run** — dry-run is the default; the scheduled step passes `--apply`:
+
+```bash
+node .claude/scheduled-tasks/core-update-subscription/subscribe.js            # plan only
+node .claude/scheduled-tasks/core-update-subscription/subscribe.js --apply    # upgrade
+```
+
+Each subscribed instance: read its installed core → ask the registry (`npm view`, needs `NPM_TOKEN`) → resolve the newest version its channel permits → if newer, `bongos upgrade --to <v> --registry` with **auto-rollback ON**. It prints one line per instance plus a tally; a non-zero exit means an upgrade failed (already auto-reverted).
+
+**Triple-gated, so nothing moves by accident:** the `core-update-subscription` routine is `requiresAutonomy: true` + **default OFF** in [`config/scheduled-routines.json`](../../config/scheduled-routines.json), the roster ships empty, and every upgrade is health-gated. Arm it by enabling the routine's timer on the control plane once autonomy is on.
+
+**Not covered:** multi-host / SSH orchestration across a real fleet (the deferred fleet-control-plane epic, task [#1948](https://example.com/builders#/task/1948)); and *publishing* new patches, which stays a gated owner step (ADR 0134) — a follow-up task decides whether merges auto-publish.
+
 ## Gotchas
 
 - **`PGDATABASE` is load-bearing on a co-tenant droplet.** `migrate.sh` defaults `PGDATABASE` to `example` — **production**. Always set `PGDATABASE=<instance-db>` explicitly, or you migrate the wrong database.

package/docs/research/cursor-competitive-analysis.md

@@ -1,6 +1,6 @@
 # Cursor (Anysphere) — Competitive-Threat Analysis for Cloud Bongos
 
-**A competitor-research document for Cloud Bongos / Off the Boats**
+**A competitor-research document for Cloud Bongos / Example**
 Prepared 2026-06-22 · the **first committed competitor doc** in this repo · companion to the (uncommitted) `component-based-dev-research.md` deep-research doc · task [#1403](https://example.com/builders#/task/1403)
 
 ---

package/docs/research/llm-model-agnostic-and-cheaper-grader.md

@@ -1,6 +1,6 @@
 # LLM Model-Agnostic Platform + Cheaper Grader — Tools Audit & Architecture Path
 
-**A research/architecture spike for Cloud Bongos / Off the Boats**
+**A research/architecture spike for Cloud Bongos / Example**
 Prepared 2026-06-28 · task [#1069](https://example.com/builders#/task/1069) · GDS-V4 · track `internal`
 
 ---

package/modules/discord/module.json

@@ -10,5 +10,6 @@
     "uiSections": []
   },
   "provides": ["discord.isLinked"],
-  "consumes": ["ideas.capture"]
+  "consumes": ["ideas.capture"],
+  "dependencies": { "discord.js": "^14.26.4" }
 }

package/modules/economy/achievements.js

@@ -424,7 +424,15 @@ async function getLeaderboardWithAchievements(limit = 10, perBuilderCap = 5) {
                    ORDER BY a.sort_order
                    LIMIT $2
                 ) t
-            ), ARRAY[]::text[]) AS achievements
+            ), ARRAY[]::text[]) AS achievements,
+            -- task 1473: mirror of credits.leaderboard's tokens_used — total
+            -- transcript tokens across this builder's sessions, so the public
+            -- leaderboard shows efficiency (tokens per drachma) beside credits.
+            COALESCE((
+              SELECT SUM(sr.total_tokens)
+                FROM session_records sr
+               WHERE sr.builder_id = b.id
+            ), 0)::bigint AS tokens_used
        FROM builders b
        ORDER BY b.total_credits DESC, b.created_at ASC
        LIMIT $1`,

package/modules/economy/credits.js

@@ -37,7 +37,16 @@ async function leaderboard(limit = 20) {
                    ORDER BY a.sort_order
                    LIMIT 5
                 ) t
-            ), ARRAY[]::text[]) AS achievements
+            ), ARRAY[]::text[]) AS achievements,
+            -- task 1473: total transcript tokens across all of this builder's
+            -- recorded sessions, so the hall leaderboard can show efficiency
+            -- (tokens spent per drachma earned) next to credits. Mirrored in
+            -- achievements.getLeaderboardWithAchievements (the /public query).
+            COALESCE((
+              SELECT SUM(sr.total_tokens)
+                FROM session_records sr
+               WHERE sr.builder_id = builders.id
+            ), 0)::bigint AS tokens_used
        FROM builders
        ORDER BY total_credits DESC, created_at ASC
        LIMIT $1`,