@bongos/core 1.17.0

package/docs/onboarding/diagrams/README.md

@@ -0,0 +1,94 @@
+# How the GDS works — visual diagrams
+
+Five flowcharts that explain the Game Development System (GDS) to a new builder at a glance. Each diagram is committed as **Mermaid source** (`.mmd`) plus a rendered **`.svg`** (the crisp, pannable/zoomable asset) and **`.png`** (a static fallback / external-embed image), embedded in the `/builders` hall at `/builders/diagrams` and the builder primer ([V3.R13 / #237](../../../CLAUDE.md)). On those pages the diagrams are **pan-and-zoom canvases** (drag to pan, scroll to zoom, fullscreen) — see [`modules/hall-ui/public/diagram-viewer.js`](../../../modules/hall-ui/public/diagram-viewer.js).
+
+> Built under **V3.R76 ([#295](https://example.com/builders#/task/295))**; auto-regeneration + drift detection added under **[#356](https://example.com/builders#/task/356)/[#357](https://example.com/builders#/task/357)**; conceptual diagrams (03/04) made auto-generated under **[#436](https://example.com/builders#/task/436)**; a dev-box topology diagram (06) added under **[#1031](https://example.com/builders#/task/1031)** and then **merged with 04 into the single `04-architecture` map + SVG pan/zoom viewer under [#1059](https://example.com/builders#/task/1059)**.
+
+### Auto-generated vs hand-authored (important)
+
+**All five diagrams are now AUTO-GENERATED** from live facts by [`scripts/gds/gen-diagrams.js`](../../../scripts/gds/gen-diagrams.js). **Do not hand-edit any `.mmd`** — to change *layout/wording*, edit the matching template in `gen-diagrams.js`; to change *state*, change the underlying system and it regenerates.
+
+| Diagram | What drives its state |
+|---|---|
+| `01-task-lifecycle` · `02-rank-ladder` · `05-versioning` (**mechanical**) | The task-status set + rank enum/wiring (read from `migrations/` + `src/bongos/`) and the live version set (production API). No auth needed — always regenerate. |
+| `03-drachmae-karma` · `04-architecture` (**conceptual**) | Each feature-piece is **LIVE iff its backing GDS task is `shipped`**, plus 03's "N seeded" count from the achievements seed in `migrations/`. These read the **authenticated** `/tasks/:id` status, so when no GDS session is available (headless run, no creds) the generator **skips** 03/04 and leaves them untouched rather than emit wrong data. (04's device/box/server/GitHub *topology* is structural; only its LIVE/PLANNED markers — the memory chain + the box→prod ship-flow legs — are task-gated.) |
+
+The mechanical diagrams regenerate **on every deploy** (`ship.js` / `/merge-mode` run `gen-diagrams.js` before deploying; a changed diagram is committed and shipped automatically). The conceptual diagrams regenerate the same way whenever a session is present (the deploy host has one). The `diagram-drift` routine remains as a belt-and-braces backstop. So `/builders/diagrams` is never more than one deploy behind the live architecture.
+
+## Reading the diagrams — live vs planned
+
+The GDS is mid-build. These diagrams deliberately distinguish **what exists today** from **what GDS-V3 plans to add**, so they double as a "where are we at" snapshot:
+
+| Marker | Meaning |
+|---|---|
+| **LIVE** / solid box / solid arrow | Implemented and enforced right now |
+| **PLANNED** / dashed arrow / "PLANNED: R##" | Designed and task-tracked, not yet built (the `R##` is the GDS-V3 task) |
+| `○` reserved | An enum value that exists in schema but has no behavior wired to it yet |
+
+## The five diagrams
+
+### 1. Task lifecycle — backlog → shipped
+How a task moves from creation to production, and the exact edge where **credits/drachmae are awarded** (`completed → confirmed`, *not* at ship).
+
+![Task lifecycle](01-task-lifecycle.png)
+
+Source: [`01-task-lifecycle.mmd`](01-task-lifecycle.mmd)
+
+### 2. Builder rank ladder
+The 16-value reserved rank enum (migration 023) in three Greek bands, which ranks are **live today** (`archon` + `thetes`, plus `xenos` on exit), the GDS-V3 target of three write-gating ranks (Xenos / Metic / Archon), and the server-enforced permissions per rank ([ADR 0016](../../adr/<redacted>.md)).
+
+![Rank ladder](02-rank-ladder.png)
+
+Source: [`02-rank-ladder.mmd`](02-rank-ladder.mmd)
+
+### 3. Drachmae & karma — sourcing and spending
+Where each comes from and where each goes. Key facts: **drachmae = credits** (same thing, in-world name), they are **equity, not a spendable currency**, and the **primary source is now a cost-plus reward on each shipped session** — `round(true_cost × 1.20)` ([ADR 0054](../../adr/<redacted>.md)) — alongside per-task `credits_reward × kind multiplier` ([ADR 0023](../../adr/<redacted>.md)), achievements, and the (rate-card-live) security bounty. Karma is a separate peer-trust signal that does **not** gate rank promotions; its LIVE/PLANNED state tracks its backing tasks (R25/R32/R26). The full write-up is [`docs/onboarding/drachmae-and-karma.md`](../drachmae-and-karma.md).
+
+![Drachmae and karma](03-drachmae-karma.png)
+
+Source: [`03-drachmae-karma.mmd`](03-drachmae-karma.mmd)
+
+### 4. The complete architecture — where your work runs and how code reaches production
+One map of the whole system, merging the old "server ↔ repo ↔ memory" three-layer view with the dev-box → production ship flow. The four places Claude Code splits across — your **device** (screen only) · the **dev box** (the worker, the code, *and* your local memory dir) · the **server/droplet** (authority *and* production: Postgres, the server-side memory store, the push credential) · **GitHub** (branch-protected main + Actions) — plus two flows woven through it: the **per-builder memory layer** (ADR 0024 — local ↔ server, sync-on-ship / pull-on-start) and the **box → prod ship path** (a credential-less box re-auths and uploads its branch as a git bundle; the server pushes it with a GitHub App credential; the PR auto-merges and GitHub Actions deploys — no droplet key on any box). Every feature-piece + flow edge is LIVE/solid iff its backing task is `shipped`. Backing tasks: memory chain [#273](https://example.com/builders#/task/273)–[#276](https://example.com/builders#/task/276); dev box [#904](https://example.com/builders#/task/904)/[#774](https://example.com/builders#/task/774)/[#897](https://example.com/builders#/task/897)/[#919](https://example.com/builders#/task/919); box→prod [#1025](https://example.com/builders#/task/1025)/[#859](https://example.com/builders#/task/859)/[#1028](https://example.com/builders#/task/1028)/[#1027](https://example.com/builders#/task/1027) (all shipped → the map reads all-LIVE today). See [ADR 0024](../../adr/<redacted>.md) (cloneable memory), [ADR 0055](../../adr/<redacted>.md) (server-mediated publish), [ADR 0053](../../adr/0053-scoped-dev-box-session.md) (scoped box token), [ADR 0042](../../adr/<redacted>.md) (CI self-deploy), [ADR 0016](../../adr/<redacted>.md) (trust boundary).
+
+![The complete architecture](04-architecture.png)
+
+Source: [`04-architecture.mmd`](04-architecture.mmd) (the `/builders` hall serves the `.svg` for crisp pan/zoom; this PNG is the GitHub-render fallback)
+
+### 5. Versioning + planning sessions
+How a `/planning-session` seeds a version's task pool, and the close → archive → guided-review loop. Each version is a named scope milestone — some user-facing (V1, V2, V3), some improving the dev system (the platform versions).
+
+![Versioning](05-versioning.png)
+
+Source: [`05-versioning.mmd`](05-versioning.mmd)
+
+## Where builders see these
+
+The diagrams are surfaced inside the authenticated **builders' hall** at
+[`/builders/diagrams`](https://example.com/builders/diagrams) (linked from the hall home page) and inlined in the primer. `modules/hall-ui/public/diagrams.html` references each diagram's `.png`, and [`diagram-viewer.js`](../../../modules/hall-ui/public/diagram-viewer.js) progressively enhances it: it fetches the matching `.svg`, injects it inline, and turns it into a pan-and-zoom canvas (drag to pan, scroll to zoom, fullscreen). If the SVG can't be fetched it falls back to the static PNG. `server.js` serves `docs/onboarding/diagrams/` at `/builders/diagrams/` (both `.svg` and `.png`), so there's a single source of truth and no duplicated binaries.
+
+## Staying current (auto-update)
+
+Two mechanisms keep these honest as the system changes (added under [#356](https://example.com/builders#/task/356)):
+
+1. **Render-on-deploy** — all five diagrams auto-regenerate on deploy: `scripts/gds/gen-diagrams.js` re-renders every `.mmd` to its `.svg` + `.png` and rebuilds `assertions.json` in lockstep, so the committed images never drift from their source. (Do **not** hand-edit the `.mmd`/`.svg`/`.png`/`assertions.json` — edit the template in `gen-diagrams.js` and re-run it.)
+2. **Drift detection** — the `diagram-drift` scheduled task (`.claude/scheduled-tasks/diagram-drift/`) runs a deterministic checker that compares `assertions.json` (below) against the live DB/code. Since all five diagrams auto-regenerate on deploy, this is a **belt-and-braces backstop** (it should find nothing in normal operation); on divergence it files an `idea_inbox` entry. Run it manually any time:
+   ```bash
+   node .claude/scheduled-tasks/diagram-drift/check.js          # report only
+   node .claude/scheduled-tasks/diagram-drift/check.js --file-idea
+   ```
+
+`assertions.json` is the machine-readable record of what these diagrams claim about the live system (rank enum + wired ranks, task-status set, live versions, and the conceptual `architecture` + `drachmae_karma` piece→task slices). It is **rebuilt by `gen-diagrams.js` in lockstep with the diagrams**, so you no longer hand-maintain it; it stays as the drift checker's reference.
+
+## Regenerating the diagrams by hand
+
+When the system changes, edit the `.mmd` source and re-render. No global install needed (uses `npx`); the convenience script renders all sources or a given subset to **both `.svg` and `.png`**:
+
+```bash
+scripts/render-diagrams.sh                        # render every *.mmd here
+scripts/render-diagrams.sh docs/onboarding/diagrams/02-rank-ladder.mmd   # just one
+```
+
+The first run downloads a headless Chromium (one-time, ~minutes). Avoid `[]` in node labels — the renderer's font shows it as a missing-glyph box; write "dependencies" / "touches" instead.
+
+When a **PLANNED** item ships, you do **not** hand-edit anything: the next `gen-diagrams.js` run (on deploy, or manually) re-reads the backing task's status, flips its marker to **LIVE**, rebuilds `assertions.json`, and re-renders. This applies to all five diagrams now, including 03/04. If you want to change layout/wording, edit the template in `gen-diagrams.js` (not the `.mmd`).

package/docs/onboarding/diagrams/assertions.json

@@ -0,0 +1,170 @@
+{
+  "_comment": "Machine-readable facts the onboarding diagrams assert about the LIVE system. The diagram-drift scheduled task (.claude/scheduled-tasks/diagram-drift/) compares these against the live DB/code and files an idea_inbox entry when they diverge, so the diagrams stay an honest snapshot. When a diagram is intentionally updated, update the matching values here in the same commit. Baselined 2026-05-26 under task #356.",
+  "rank_ladder": {
+    "diagram": "02-rank-ladder",
+    "rank_enum": [
+      "olympian",
+      "hermes",
+      "oracle",
+      "demigod",
+      "archon",
+      "strategos",
+      "boule",
+      "aristoi",
+      "hippeis",
+      "zeugitai",
+      "thetes",
+      "metic",
+      "xenos",
+      "periokoi",
+      "doulos",
+      "helot"
+    ],
+    "default_rank": "xenos",
+    "wired_ranks": [
+      "archon",
+      "metic",
+      "xenos"
+    ],
+    "_wired_note": "A rank is 'wired' if it has behavior: it appears in a requireRank(...) call, is the column default, is SET by a migration, or is a key in the live REQUIRES_RANK_TIER claim-gate map (db.js). archon = requireRank + seeded; metic + thetes + xenos = tier-map members (claim-floor comparison); xenos = column default + set on /builder-exit (migration 025); thetes = the auto-graduation target (xenos→thetes after 3 confirmed tasks, #692 / ADR 0034)."
+  },
+  "task_lifecycle": {
+    "diagram": "01-task-lifecycle",
+    "task_statuses": [
+      "backlog",
+      "ready",
+      "active",
+      "blocked",
+      "completed",
+      "confirmed",
+      "shipped",
+      "abandoned"
+    ],
+    "credits_awarded_at": "completed->confirmed"
+  },
+  "versioning": {
+    "diagram": "05-versioning",
+    "versions": [
+      {
+        "id": "V1",
+        "status": "shipped"
+      },
+      {
+        "id": "PMS-V1",
+        "status": "shipped"
+      },
+      {
+        "id": "PMS-V2",
+        "status": "shipped"
+      },
+      {
+        "id": "GDS-V3",
+        "status": "shipped"
+      },
+      {
+        "id": "V2",
+        "status": "planning"
+      },
+      {
+        "id": "V3",
+        "status": "planning"
+      },
+      {
+        "id": "GDS-V4",
+        "status": "frozen"
+      },
+      {
+        "id": "BONGOS-V1",
+        "status": "building"
+      }
+    ]
+  },
+  "drachmae_karma": {
+    "diagram": "03-drachmae-karma",
+    "_comment": "Pieces of 03-drachmae-karma that are gated on a backing GDS task. A piece is LIVE iff its task is 'shipped'. live_tasks must ALL be shipped live; pending_tasks must NOT yet be shipped. Rebuilt automatically by scripts/gds/gen-diagrams.js from the authenticated /tasks/:id status; the diagram is regenerated in lockstep, so this slice is a redundant backstop the drift checker verifies. D_SHIP (credit_log trigger) and D_ACH (achievement bonuses) have no task gate and are always LIVE. achievements_seeded mirrors 03's 'N seeded' label, counted from the achievements seed INSERTs in migrations/.",
+    "live_tasks": [
+      {
+        "id": 284,
+        "label": "R65 — bounty payout rate card (src/bongos/security.js + /builders)"
+      },
+      {
+        "id": 282,
+        "label": "R63 — vulnerability_reports table + schema"
+      },
+      {
+        "id": 245,
+        "label": "R25 — builder-on-builder upvote/downvote on confirmed work"
+      },
+      {
+        "id": 248,
+        "label": "R32 — karma boost on proposal ratification"
+      },
+      {
+        "id": 246,
+        "label": "R26 — karma surfaced on profile + sortable on leaderboard"
+      }
+    ],
+    "pending_tasks": [
+      {
+        "id": 286,
+        "label": "R67 — auto-confirmation flow that awards drachmae (the awarding gate)"
+      }
+    ],
+    "achievements_seeded": 9
+  },
+  "architecture": {
+    "diagram": "04-architecture",
+    "_comment": "Pieces of 04-architecture gated on a backing GDS task. A piece is LIVE iff its task is 'shipped'; live_tasks must ALL be shipped, pending_tasks must NOT yet be. Rebuilt by scripts/gds/gen-diagrams.js in lockstep with the diagram, so this is the drift checker's backstop. The device/box/server/GitHub topology is structural (not task-gated); these are the LIVE/PLANNED markers. MEMORY layer (ADR 0024): 273 schema / 274 sync-on-ship / 275 pull-on-start / 276 isolation. DEV BOX + box→prod: 904/774 (on-off + browser terminal), 897 (sandbox preview), 919 (scoped box token), 1025 (server-mediated publish), 859 (CI deploy), 1028 (GitHub App push credential), 1027 (end-to-end hardware-verify). Supersedes the old server_repo_memory + dev_box slices.",
+    "live_tasks": [
+      {
+        "id": 273,
+        "label": "R54 — builder_memory store schema"
+      },
+      {
+        "id": 274,
+        "label": "R55 — sync-on-ship (push)"
+      },
+      {
+        "id": 275,
+        "label": "R56 — pull-on-session-start"
+      },
+      {
+        "id": 276,
+        "label": "R57 — per-builder isolation + Archon audited forensic read"
+      },
+      {
+        "id": 904,
+        "label": "devbox-app — desktop on-off switch"
+      },
+      {
+        "id": 774,
+        "label": "browser-only box terminal (ttyd over tunnel)"
+      },
+      {
+        "id": 897,
+        "label": "per-builder sandbox live preview"
+      },
+      {
+        "id": 919,
+        "label": "scoped dev-box session (box token deny-by-default)"
+      },
+      {
+        "id": 1025,
+        "label": "server-mediated branch publish (box uploads bundle, server pushes)"
+      },
+      {
+        "id": 859,
+        "label": "CI self-deploy (Actions deploys main to the droplet)"
+      },
+      {
+        "id": 1027,
+        "label": "hardware-verify the box-to-prod flow end-to-end"
+      },
+      {
+        "id": 1028,
+        "label": "GitHub App hardening (replace the standing push PAT)"
+      }
+    ],
+    "pending_tasks": []
+  }
+}

package/docs/onboarding/diagrams/puppeteer-config.json

@@ -0,0 +1 @@
+{ "args": ["--no-sandbox", "--disable-setuid-sandbox"] }

package/docs/onboarding/diagrams/render-config.json

@@ -0,0 +1,9 @@
+{
+  "_comment": "Shared Mermaid render config for the onboarding diagrams (task 1066). Passed to mermaid-cli via `-c` in scripts/render-diagrams.sh so EVERY diagram gets generous spacing — the hall viewer pans/zooms, so we are no longer space-constrained and prefer breathing room over compactness. nodeSpacing/rankSpacing also map onto the ELK layout used by 04-architecture.",
+  "flowchart": {
+    "nodeSpacing": 65,
+    "rankSpacing": 90,
+    "padding": 18,
+    "useMaxWidth": true
+  }
+}

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

@@ -0,0 +1,178 @@
+# Drachmae & 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.
+
+---
+
+## 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.
+- **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)
+
+### 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:
+
+- **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.
+- **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.
+
+### How you earn them
+
+There are several sources. They all land in the same `credit_log` and roll up into one `total_credits` number.
+
+#### 1. The cost-plus session reward — *the main one* ([ADR 0054](../adr/<redacted>.md))
+
+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)
+                                  └─ REWARD_MARGIN_PCT = 20 (a code constant in src/bongos/db.js)
+```
+
+The important details, because they're designed to be fair *and* un-gameable:
+
+- **The cost is computed server-side**, from the per-model token counts your ship uploads (`session_records.model_usage`), priced via the locked list-price table in `src/bongos/llm-pricing.js`. **You never send a dollar figure** — a client can't inflate its own payout.
+- **It's the API *list* price, deliberately** — not your discounted subscription cost. If you got those tokens cheaply (e.g. on a flat Claude Code subscription), the spread between list price and what you actually paid is routed to *you* as profit, on top of the 20%. That's intentional: it's how the reward funds your time and your ideas.
+- **PASS-gated.** Only a *successful ship* uploads a session record. A session that burned tokens and shipped nothing earns nothing.
+- **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.
+
+#### 2. Per-task credits, adjusted by *kind* ([ADR 0023](../adr/<redacted>.md))
+
+Every task carries a `credits_reward` an author set when scoping it. When the task is **confirmed** (verification passes — see the [lifecycle](#where-in-the-lifecycle-credits-land)), you're paid that reward **times a multiplier for the kind of work**:
+
+| Kind | × | Why |
+|---|---|---|
+| `learning-capture` | **1.5** | One captured learning saves many future debugging sessions. |
+| `blocker-resolution` | **1.5** | A resolved blocker unblocks every task that depended on it. |
+| `decision` (ADRs) | **1.3** | Durable; outlives any single feature. |
+| `bug` | **1.2** | Stops compounding failure. |
+| `spike` | **1.1** | Produces knowledge (ADRs, follow-ups). |
+| `feature` / `infra` / `unclassified` | **1.0** | The baseline. |
+| `refactor` | **0.9** | Useful as a precursor; dead weight otherwise. |
+| `cleanup` | **0.8** | Necessary housekeeping, but not what we want more of right now. |
+
+The math is written inline into the `credit_log` row (e.g. `40c × 1.5 = 60c (learning-capture)`) so an auditor can reconstruct any payout. The multipliers live in a *frozen constant* in `src/bongos/db.js` on purpose — changing them takes a code review and commit, not a quiet DB edit.
+
+#### 3. The idea-promotion bonus ([ADR 0023](../adr/<redacted>.md))
+
+If you **captured an idea** that later became a task, and **someone else ships it**, you get **25% of that task's (multiplier-adjusted) reward** — paid as a separate `idea_promotion_bonus` row, *on top of* what the shipper earns (it isn't deducted from them). No bonus if you ship your own idea (you already got the full reward). Capturing good ideas is real, paid work.
+
+#### 4. Achievements
+
+Unlocking an achievement pays its `credit_bonus`. There are **9 seeded** today (e.g. your first ship, three ships, a *net-negative* ship that deletes more than it adds). They're small, one-time, and motivational.
+
+#### 5. The net-negative ship bonus
+
+A ship whose committed diff **removes more lines than it adds** earns a small `ship.net_negative` bonus — a nudge toward deleting code, not just adding it.
+
+#### 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.
+
+### 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.
+
+```
+active ──▶ completed ──▶ confirmed ──▶ shipped
+           (declared      (verified —    (merged to main
+            done +          CREDITS        + deployed)
+            smoke)          LAND HERE)
+```
+
+> **Note:** the old up-front `touches[]` *drift scanner* that used to run at ship time is **gone** (task [#879](https://example.com/builders#/task/879), [ADR 0049](../adr/<redacted>.md)). The ship gate is **smoke tests only**; `git merge` at land time is the real collision detector.
+
+### One honest caveat: a drachma means two things
+
+We knowingly run two conventions on the same ledger ([ADR 0054](../adr/<redacted>.md)): a *unitless author estimate* (the per-task path) and a *whole-dollar drachma of real cost + 20%* (the session-reward path). That inconsistency is a deliberate MVP trade-off, recorded so it's a known decision and not a latent bug. A future version may reconcile them.
+
+---
+
+## 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.
+
+Defined in `src/bongos/cost.js` (criterion C3, [#302](https://example.com/builders#/task/302)):
+
+Builders are **uncapped by default** ([ADR 0085](../adr/<redacted>.md)) — your month-to-date spend is tracked and shown, but it never blocks you. An Archon can set a per-builder cap as a manual brake; **when a cap is set**, these levels apply:
+
+| Month-to-date spend | Level | What happens |
+|---|---|---|
+| no cap set (the default) | `ok` | nothing — uncapped |
+| under 80% of the cap | `ok` | nothing |
+| **≥ 80%** | `warn` | a CLI ping at session start + a banner on the hall |
+| **≥ 100%** | `over` | **hard refuse** — `/builder-ship` and the art pipeline stop |
+
+- **No default cap.** `monthly_budget_usd` is unset for most builders, which means uncapped. The MTD figure still resets at the start of each calendar month.
+- A cap, when set, is there to **catch a runaway**, not to ration normal work — the **$50 default was removed** ([ADR 0085](../adr/<redacted>.md)) because a new builder's own session cost crossed it within a day or two, freezing the very work it was meant to enable.
+- An **Archon** can set or clear a specific builder's ceiling (`PATCH /api/gds/builders/:id/budget`); clearing it (`null`) returns the builder to uncapped.
+
+If a cap is set and you hit `over`, you're not in trouble — you've just reached the month's ceiling. Ask an Archon to raise or clear it if the work justifies it.
+
+---
+
+## 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.
+
+### 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.
+
+> 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).
+- **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*
+
+Karma does **not** mechanically gate rank promotions. The two promotions that exist are:
+
+- **Xenos → Thetes:** automatic after your **3rd confirmed task** — by ship count, not karma.
+- **→ Metic** and **→ Archon:** deliberate **Archon** decisions.
+
+Karma is evidence an Archon *can weigh* when deciding a discretionary promotion, but no threshold of karma promotes you on its own. (See the [rank ladder](primer.md#the-rank-ladder).)
+
+---
+
+## Drachmae vs karma, side by side
+
+| | **Drachmae** (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 |
+| Direction | Only goes up | Can go up or down |
+| Who can grant | The system, automatically, on a successful ship | Metic+ builders (votes) + system signals |
+| Spendable? | No — equity/score | No — trust signal |
+| Gates promotions? | No (Xenos→Thetes is by ship count) | No (informs, doesn't gate) |
+| Lives in | `builders.total_credits` / `credit_log` | `builders.karma` / `karma_log` |
+
+Both are reputation. Neither is a spendable currency today. You don't have to *do* anything special to start earning either — claim a task, do good work, ship it, and both tracks take care of themselves.
+
+---
+
+## 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 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).