@bongos/core 1.19.714 → 1.19.724

package/docs/onboarding/diagrams/README.md

@@ -35,21 +35,21 @@ How a task moves from creation to production, and the exact edge where **credits
 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)).
+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/0016-trust-boundary-server-enforced-permissions.md)).
 
 ![Rank ladder](02-rank-ladder.png)
 
 Source: [`02-rank-ladder.mmd`](02-rank-ladder.mmd)
 
 ### 3. Example & karma — sourcing and spending
-Where each comes from and where each goes. Key facts: **example = credits** (same thing, in-world name), they are **equity, not a spendable currency**, and the **primary source is now a cost-plus reward on each shipped session** — `round(true_cost × 1.20)` ([ADR 0054](../../adr/<redacted>.md)) — alongside per-task `credits_reward × kind multiplier` ([ADR 0023](../../adr/<redacted>.md)), achievements, and the (rate-card-live) security bounty. Karma is a separate peer-trust signal that does **not** gate rank promotions; its LIVE/PLANNED state tracks its backing tasks (R25/R32/R26). The full write-up is [`docs/onboarding/example-and-karma.md`](../example-and-karma.md).
+Where each comes from and where each goes. Key facts: **example = credits** (same thing, in-world name), they are **equity, not a spendable currency**, and the **primary source is now a cost-plus reward on each shipped session** — `round(true_cost × 1.20)` ([ADR 0054](../../adr/0054-session-token-reward-cost-plus.md)) — alongside per-task `credits_reward × kind multiplier` ([ADR 0023](../../adr/0023-kind-multipliers-and-idea-bonus.md)), achievements, and the (rate-card-live) security bounty. Karma is a separate peer-trust signal that does **not** gate rank promotions; its LIVE/PLANNED state tracks its backing tasks (R25/R32/R26). The full write-up is [`docs/onboarding/example-and-karma.md`](../example-and-karma.md).
 
 ![Example and karma](03-example-karma.png)
 
 Source: [`03-example-karma.mmd`](03-example-karma.mmd)
 
 ### 4. The complete architecture — where your work runs and how code reaches production
-One map of the whole system, merging the old "server ↔ repo ↔ memory" three-layer view with the dev-box → production ship flow. The four places Claude Code splits across — your **device** (screen only) · the **dev box** (the worker, the code, *and* your local memory dir) · the **server/droplet** (authority *and* production: Postgres, the server-side memory store, the push credential) · **GitHub** (branch-protected main + Actions) — plus two flows woven through it: the **per-builder memory layer** (ADR 0024 — local ↔ server, sync-on-ship / pull-on-start) and the **box → prod ship path** (a credential-less box re-auths and uploads its branch as a git bundle; the server pushes it with a GitHub App credential; the PR auto-merges and GitHub Actions deploys — no droplet key on any box). Every feature-piece + flow edge is LIVE/solid iff its backing task is `shipped`. Backing tasks: memory chain [#273](https://example.com/builders#/task/273)–[#276](https://example.com/builders#/task/276); dev box [#904](https://example.com/builders#/task/904)/[#774](https://example.com/builders#/task/774)/[#897](https://example.com/builders#/task/897)/[#919](https://example.com/builders#/task/919); box→prod [#1025](https://example.com/builders#/task/1025)/[#859](https://example.com/builders#/task/859)/[#1028](https://example.com/builders#/task/1028)/[#1027](https://example.com/builders#/task/1027) (all shipped → the map reads all-LIVE today). See [ADR 0024](../../adr/<redacted>.md) (cloneable memory), [ADR 0055](../../adr/<redacted>.md) (server-mediated publish), [ADR 0053](../../adr/0053-scoped-dev-box-session.md) (scoped box token), [ADR 0042](../../adr/<redacted>.md) (CI self-deploy), [ADR 0016](../../adr/<redacted>.md) (trust boundary).
+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/0024-cloneable-repo-local-first-memory.md) (cloneable memory), [ADR 0055](../../adr/0055-server-mediated-branch-publish.md) (server-mediated publish), [ADR 0053](../../adr/0053-scoped-dev-box-session.md) (scoped box token), [ADR 0042](../../adr/0042-builder-self-deploy-ci-auto-merge.md) (CI self-deploy), [ADR 0016](../../adr/0016-trust-boundary-server-enforced-permissions.md) (trust boundary).
 
 ![The complete architecture](04-architecture.png)
 

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

@@ -19,7 +19,7 @@
 
 ### What 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:
+Example are the in-world name for the `total_credits` counter on your builder row. The owner's framing ([ADR 0054](../adr/0054-session-token-reward-cost-plus.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 example are still there (migration 025). They are reputation, not a session balance.
@@ -30,7 +30,7 @@ Example are the in-world name for the `total_credits` counter on your builder ro
 
 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))
+#### 1. The cost-plus session reward — *the main one* ([ADR 0054](../adr/0054-session-token-reward-cost-plus.md))
 
 When you **ship** a session, the server looks at the LLM tokens that session actually burned, prices them, and pays you:
 
@@ -47,9 +47,9 @@ 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*; 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.
+> **Why pay for cost at all — doesn't that reward waste?** It can, and that was accepted on purpose ([ADR 0054](../adr/0054-session-token-reward-cost-plus.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/0027-bfg-session-inefficiency-evaluator.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))
+#### 2. Per-task credits, adjusted by *kind* ([ADR 0023](../adr/0023-kind-multipliers-and-idea-bonus.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**:
 
@@ -66,7 +66,7 @@ Every task carries a `credits_reward` an author set when scoping it. When the ta
 
 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))
+#### 3. The idea-promotion bonus ([ADR 0023](../adr/0023-kind-multipliers-and-idea-bonus.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.
 
@@ -84,7 +84,7 @@ There's a published payout rate-card by severity for red-team / security finding
 
 ### Where in the lifecycle credits land
 
-Example are awarded at the **`confirmed → shipped`** edge — when the code actually lands on `main` and deploys — **not** when verification passes. Passing the grader gets you to `confirmed`, which is verified but *unpaid*; a task that strands there without landing earns nothing until it does ([ADR 0120](../adr/<redacted>.md), "pay on land"). Releasing a task with `/builder-release` pays nothing.
+Example are awarded at the **`confirmed → shipped`** edge — when the code actually lands on `main` and deploys — **not** when verification passes. Passing the grader gets you to `confirmed`, which is verified but *unpaid*; a task that strands there without landing earns nothing until it does ([ADR 0120](../adr/0120-pay-on-land-and-builder-owned-rebase-gate.md), "pay on land"). Releasing a task with `/builder-release` pays nothing.
 
 ```
 active ──▶ completed ──▶ confirmed ──▶ shipped
@@ -93,11 +93,11 @@ active ──▶ completed ──▶ confirmed ──▶ shipped
             smoke)          paid)          CREDITS 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.
+> **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/0049-split-parallel-safety-contract.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.
+We knowingly run two conventions on the same ledger ([ADR 0054](../adr/0054-session-token-reward-cost-plus.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.
 
 ---
 
@@ -107,7 +107,7 @@ Example are what you *earn*; the budget cap limits what you *spend*. They're lin
 
 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:
+Builders are **uncapped by default** ([ADR 0085](../adr/0085-remove-default-per-builder-spend-cap.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 |
 |---|---|---|
@@ -117,7 +117,7 @@ Builders are **uncapped by default** ([ADR 0085](../adr/<redacted>.md)) — your
 | **≥ 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.
+- A cap, when set, is there to **catch a runaway**, not to ration normal work — the **$50 default was removed** ([ADR 0085](../adr/0085-remove-default-per-builder-spend-cap.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.
@@ -133,9 +133,9 @@ Karma (added in migration 040) is a **completely separate** counter from example
 - **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 example — you can ship fast and still lose karma if you break things.
+- **It can go down.** The [BFG](../adr/0026-bfg-memory-hygiene-and-cross-builder-learning.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.
+> Discord cheers don't count. Reaction "applause" in Discord is cosmetic and **never** mints karma — only rank-gated peer votes do ([ADR 0033](../adr/0033-discord-bot-service-principal.md)). Unranked enthusiasm can't manufacture trust.
 
 ### Where karma shows up
 
@@ -174,5 +174,5 @@ Both are reputation. Neither is a spendable currency today. You don't have to *d
 
 - **Your numbers:** [builders' hall](https://example.com/builders) (profile card + leaderboard), or `/builder-start` (shows your credit total).
 - **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 decisions:** [ADR 0054](../adr/0054-session-token-reward-cost-plus.md) (cost-plus reward), [ADR 0023](../adr/0023-kind-multipliers-and-idea-bonus.md) (kind multipliers + idea bonus), [ADR 0028](../adr/0028-honest-llm-spend-accounting.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

@@ -37,13 +37,13 @@ You drive the middle three states. The system handles the rest.
 
 **One claim at a time** while you're a Xenos. New builders hold a single active claim — ship it (or release it) before opening another, so the first work gets carried through. The limit is keyed to your rank: it lifts automatically when you graduate to **Thetes** (after your third shipped task), after which you can hold parallel claims if you want.
 
-When you ship, `ship.js` runs the project's **smoke tests** and the quality grader. If they pass, the task auto-confirms — verified, but **not yet paid**. **Credits land at the final `confirmed → shipped` hop**, when your code actually merges to `main` and deploys ([ADR 0120](../adr/<redacted>.md) — you're paid for landed code, so a branch that never lands never pays). That hop is handled for you, but *what it takes to land* depends on your rank and what you changed; the next section covers it. (There used to be an up-front `touches[]` "drift scanner" here too; it was retired — `git merge` at land time is the real collision detector. See [ADR 0049](../adr/<redacted>.md).)
+When you ship, `ship.js` runs the project's **smoke tests** and the quality grader. If they pass, the task auto-confirms — verified, but **not yet paid**. **Credits land at the final `confirmed → shipped` hop**, when your code actually merges to `main` and deploys ([ADR 0120](../adr/0120-pay-on-land-and-builder-owned-rebase-gate.md) — you're paid for landed code, so a branch that never lands never pays). That hop is handled for you, but *what it takes to land* depends on your rank and what you changed; the next section covers it. (There used to be an up-front `touches[]` "drift scanner" here too; it was retired — `git merge` at land time is the real collision detector. See [ADR 0049](../adr/0049-split-parallel-safety-contract.md).)
 
 ## How work lands — and what auto-ships
 
 `confirmed → shipped` is not a person clicking "merge". When you ship, `ship.js` opens a pull request and the project lands it for you — **nobody pushes to `main` by hand**. The PR has to go green on the automated checks (the test suite, a secret scan, and the **gate-review** classifier); the server then auto-merges it and `main` deploys to production. If a green PR ever stalls, a server sweep lands it within about five minutes, and `/merge-mode` is the manual fallback.
 
-The one thing that decides whether your ship is **instant** or **waits for an Archon** is *what your change touches*, weighed against your rank by the **gate-review** step ([ADR 0058](../adr/<redacted>.md)):
+The one thing that decides whether your ship is **instant** or **waits for an Archon** is *what your change touches*, weighed against your rank by the **gate-review** step ([ADR 0058](../adr/0058-automatic-gate-surface-gatekeeper.md)):
 
 | What your change touches | What happens |
 |---|---|
@@ -51,7 +51,7 @@ The one thing that decides whether your ship is **instant** or **waits for an Ar
 | **A protected "gate surface"** — migrations, server routes, the ship / deploy plumbing | Auto-merges **only if you are Metic or above** (rank trust). A Xenos or Thetes ship here **waits for an Archon** to approve. |
 | **The safety core** — the gate's own machinery, the deploy switch, the rank / permission enforcement | **Always** waits for an Archon, whatever your rank. |
 
-So your first tasks **ship with no approval**: the newcomer chores — a tile, a doc fix, a unit test, a batch of ideas — all sit on the safe side of that line, and a clean ship merges and deploys on its own. You only meet the Archon gate if your change reaches into the project's own safety machinery, which builders below Metic are asked to stay clear of anyway ([ADR 0043](../adr/<redacted>.md)). Landing is always Bongos's job: you never run `git push origin main`, `ssh` to the server, or deploy by hand — `/builder-ship` opens the PR and the server does the rest ([ADR 0042](../adr/<redacted>.md)).
+So your first tasks **ship with no approval**: the newcomer chores — a tile, a doc fix, a unit test, a batch of ideas — all sit on the safe side of that line, and a clean ship merges and deploys on its own. You only meet the Archon gate if your change reaches into the project's own safety machinery, which builders below Metic are asked to stay clear of anyway ([ADR 0043](../adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md)). Landing is always Bongos's job: you never run `git push origin main`, `ssh` to the server, or deploy by hand — `/builder-ship` opens the PR and the server does the rest ([ADR 0042](../adr/0042-builder-self-deploy-ci-auto-merge.md)).
 
 ## The rank ladder
 
@@ -64,17 +64,17 @@ Four ranks, in ancient-Greek-civilization order:
 | **Metic**  | Approved working rank. The "real builders."                            | Claim any ready task. Idea triage, blocker review. Most of the work happens here. |
 | **Archon** | Project keeper.                                                        | Scope mutations, rank changes, infra-level operations.                            |
 
-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.
+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/0016-trust-boundary-server-enforced-permissions.md) and [ADR 0034](../adr/0034-thetes-graduated-newcomer-rank.md) for the full trust model.
 
 ## 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 **[Example & karma — how you get paid](drachmae-and-karma.md)**; here's the shape of it.
 
-- **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 `confirmed → shipped` edge — when your code actually merges and deploys, not when verification passes ([ADR 0120](../adr/<redacted>.md)). Which of those two streams actually pays is per-instance config ([ADR 0146](../adr/<redacted><redacted>.md)): the default pays both, while a `cost-plus-only` instance pays the session reward alone and treats each task's `credits_reward` as an advertised estimate only. 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/0054-session-token-reward-cost-plus.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/0023-kind-multipliers-and-idea-bonus.md)). Credits land at the `confirmed → shipped` edge — when your code actually merges and deploys, not when verification passes ([ADR 0120](../adr/0120-pay-on-land-and-builder-owned-rebase-gate.md)). Which of those two streams actually pays is per-instance config ([ADR 0146](../adr/<redacted><redacted>.md)): the default pays both, while a `cost-plus-only` instance pays the session reward alone and treats each task's `credits_reward` as an advertised estimate only. 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 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)).
+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/0085-remove-default-per-builder-spend-cap.md)).
 
 ## How to ask Claude about anything
 
@@ -100,7 +100,7 @@ As you work, Claude writes down durable facts — your standing preferences, a g
 - **The map** (`MEMORY.md`) — a short index loaded at the **start of every session**: one line per memory, just enough to know *what* is known and where the detail lives. Kept deliberately small.
 - **The drawer** — the full notes themselves. They live on your machine, sync to the server (so your memory follows you across machines and boxes), and are searchable with `/recall`. They cost nothing until something fetches them.
 
-The map stays light on its own: a session-start guard warns if it's drifting large, and an auto-tidy moves the oldest, least-relevant notes off the map into the drawer when it crosses a threshold — **nothing is deleted**, it's just no longer loaded every session (a `/recall` away when a task needs it). Your standing rules, and anything pinned, always stay on the map. Full picture: [ADR 0074](../adr/<redacted>.md) and [diagram 4 — the architecture](diagrams/).
+The map stays light on its own: a session-start guard warns if it's drifting large, and an auto-tidy moves the oldest, least-relevant notes off the map into the drawer when it crosses a threshold — **nothing is deleted**, it's just no longer loaded every session (a `/recall` away when a task needs it). Your standing rules, and anything pinned, always stay on the map. Full picture: [ADR 0074](../adr/0074-memory-map-stays-light.md) and [diagram 4 — the architecture](diagrams/).
 
 ## Where to find more depth
 

package/docs/packs/artist.md

@@ -2,7 +2,7 @@
 
 > **The role pack for `discipline = artist`.** The kernel ([`CLAUDE.md`](../../CLAUDE.md)) is what every session reads whatever its craft; this file is the half that is only true for artists. Read the whole thing before acting — it changes how you *communicate* for the rest of the session. Registered in [`scripts/gds/discipline-modes.json`](../../scripts/gds/discipline-modes.json), which `claim.js` prints on a claim.
 
-An art session is not the engineer's text-heavy build loop. The artist's subject is how the project **looks and reads** — its visuals, its copy, its voice, the feeling of the thing. A craft is an identity, not a toolchain ([ADR 0272](../adr/<redacted>.md)): an instance has artists whether or not it ships an art pipeline.
+An art session is not the engineer's text-heavy build loop. The artist's subject is how the project **looks and reads** — its visuals, its copy, its voice, the feeling of the thing. A craft is an identity, not a toolchain ([ADR 0272](../adr/0272-a-craft-is-an-identity-not-a-toolchain.md)): an instance has artists whether or not it ships an art pipeline.
 
 ---
 

package/docs/packs/ideator.md

@@ -17,7 +17,7 @@ In every other craft, Claude does the work and asks the human to approve it. **H
 
 ## The second rule: be quiet about the machinery
 
-The behaviour above inverts for this role — and so does the **surface** ([ADR 0271](../adr/<redacted>.md)). Someone came here to think about an idea, not to watch a build. **Report outcomes, not mechanism.**
+The behaviour above inverts for this role — and so does the **surface** ([ADR 0271](../adr/0271-the-ideator-surface-is-two-halves.md)). Someone came here to think about an idea, not to watch a build. **Report outcomes, not mechanism.**
 
 - **Don't narrate the plumbing.** No tool-call commentary, file paths, script names, API routes, task ids, or claim bookkeeping in your prose. You still *use* all of it — you just don't make the ideator read about it.
 - **Speak in the language of the idea.** "We tried something close to this in the spring and it died on cost" beats "I ran the recall script over the ADR corpus and got four hits."

package/docs/project-context.template.md

@@ -1,9 +1,9 @@
 # <Product Name> — Project Identity (host instance context)
 
-> **Neutral template — the skeleton a new Cloud Bongos instance fills in.** This is the project-context *template* Cloud Bongos ships ([ADR 0062](adr/<redacted>.md) §7, task [#1205](https://example.com/builders#/task/1205)); `cloudbongos init` ([#1204](https://example.com/builders#/task/1204)) copies it to `docs/project-context.md` and an owner's own LLM fills the placeholders. It is the prose counterpart to the neutral branding starter [`config/branding.neutral.json`](../config/branding.neutral.json). **Instance 1's filled version is [`docs/project-context.md`](project-context.md).** Do not edit this template per-instance — edit your copy.
+> **Neutral template — the skeleton a new Cloud Bongos instance fills in.** This is the project-context *template* Cloud Bongos ships ([ADR 0062](adr/0062-medusa-instance-model-decoupling.md) §7, task [#1205](https://example.com/builders#/task/1205)); `cloudbongos init` ([#1204](https://example.com/builders#/task/1204)) copies it to `docs/project-context.md` and an owner's own LLM fills the placeholders. It is the prose counterpart to the neutral branding starter [`config/branding.neutral.json`](../config/branding.neutral.json). **Instance 1's filled version is [`docs/project-context.md`](project-context.md).** Do not edit this template per-instance — edit your copy.
 >
 > **Relationship to the rest of the project:**
-> - [`CLAUDE.md`](../CLAUDE.md) is the **portable methodology core** Cloud Bongos ships — working rules, session protocol, claim→ship lifecycle, the [ADR 0061](adr/<redacted>.md) content charter, the nested-`CLAUDE.md` pattern. Instance-agnostic; you do not author it.
+> - [`CLAUDE.md`](../CLAUDE.md) is the **portable methodology core** Cloud Bongos ships — working rules, session protocol, claim→ship lifecycle, the [ADR 0061](adr/0061-context-layer-decomposition.md) content charter, the nested-`CLAUDE.md` pattern. Instance-agnostic; you do not author it.
 > - **This file is the *prose* identity** — lore, vision, the why. The **machine-readable** identity (exact strings code reads: product/world/company names, domains, cookie/OAuth origins, currency label, palette, repo binding) lives in the branding contract [`config/branding.json`](../config/branding.json) ([`docs/branding-contract.md`](branding-contract.md)). **Where a name must be exact for code, the branding contract wins** — never re-hardcode a contract-owned string here.
 
 <!--
@@ -51,7 +51,7 @@ the experience permanent / distinctive / worth building.&gt;
 
 > ⚠️ **Naming / trademark posture:** &lt;any protected marks or naming risks, and the contingency.&gt; **Operating rule:** any
 > rebrand-sensitive name must live as a single string in [`config/branding.json`](../config/branding.json) — never baked into
-> class names, file names, DB schema, or asset filenames — so a forced rebrand is a one-line change ([ADR 0062](adr/<redacted>.md) §3).
+> class names, file names, DB schema, or asset filenames — so a forced rebrand is a one-line change ([ADR 0062](adr/0062-medusa-instance-model-decoupling.md) §3).
 
 ---
 

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

@@ -1,6 +1,6 @@
 # Recipe — per-builder dev box lifecycle (provision · auto-suspend · reclaim)
 
-> **Task [#598](https://example.com/builders#/task/598) · [ADR 0031](../adr/<redacted>.md) §2/§5/§9.3.** This is the operator guide for the per-builder DigitalOcean dev boxes. The code ships in the repo; **going live is a deliberate, money-spending operator action** (like `provision-staging.sh`) — nothing here runs until you set `DO_API_TOKEN` and pass `--apply`.
+> **Task [#598](https://example.com/builders#/task/598) · [ADR 0031](../adr/0031-cloud-dev-environments-for-builders.md) §2/§5/§9.3.** This is the operator guide for the per-builder DigitalOcean dev boxes. The code ships in the repo; **going live is a deliberate, money-spending operator action** (like `provision-staging.sh`) — nothing here runs until you set `DO_API_TOKEN` and pass `--apply`.
 
 ## The shape
 
@@ -59,7 +59,7 @@ node scripts/gds/box.js reconcile-drift         # DO⇄DB drift; add --apply to
 
 `<builder>` is a GitHub login or a numeric builder id.
 
-### Drift reconcile — `reconcile-drift` (task [#1289](https://example.com/builders#/task/1289), [ADR 0071](../adr/<redacted>.md))
+### Drift reconcile — `reconcile-drift` (task [#1289](https://example.com/builders#/task/1289), [ADR 0071](../adr/0071-box-confirm-before-destroyed-and-drift-reconcile.md))
 
 The teardown is now **confirm-before-destroyed**: `deprovision` only marks a box `destroyed` AFTER DigitalOcean confirms the droplet is deleted (idempotent + retried). A delete that genuinely fails parks the box at `state='error'` with `droplet_id` preserved and **throws** — it never silently leaves a running droplet behind a `destroyed` row (the old "zombie" bug).
 
@@ -135,8 +135,8 @@ These spend money and are intentionally manual.
    ```
    Tail `journalctl -u box-idle-suspend.service` for a day to confirm boxes park + wake cleanly.
    > **`box-intent-runner.timer` ([#701](https://example.com/builders#/task/701)) is the on-ramp's responsiveness knob.** It runs `box.js run-intents --apply` every minute, draining the `box_intents` queue that `POST /api/gds/box/ensure` writes — so a builder who hits "connect" gets their box **auto-provisioned** (no box yet) or **woken** (parked) within ~1 min, with no operator CLI. It reads the SAME `/etc/example/box.env` as the sweeps. Without it installed, `ensure` still queues intents — they just sit pending until someone runs `box.js run-intents --apply` by hand. Confirm with `journalctl -u box-intent-runner.service` after a test `ensure`.
-   > **`box-drift-reconcile.timer` (task [#1289](https://example.com/builders#/task/1289)/[ADR 0071](../adr/<redacted>.md)) is the zombie backstop.** It runs `box.js reconcile-drift --apply` hourly, reading the live DO droplet list and repairing DO⇄DB drift both ways — force-deleting **zombie** droplets (running but no live box row claims them) and marking **ghost** rows destroyed (droplet gone from DO). Reads the SAME `/etc/example/box.env` (needs `DO_API_TOKEN` to enumerate droplets). Without it, the confirm-before-destroyed teardown still prevents *new* zombies, but a pre-existing one (or an out-of-band DO change) only heals on the next manual `reconcile-drift`. Confirm with `journalctl -u box-drift-reconcile.service`.
-   > **Chromebook / browser terminal ([#760](https://example.com/builders#/task/760)/[ADR 0038](../adr/<redacted>.md), superseding the old `claude rc` pairing).** Research proved `claude rc` cannot run headless, so the box instead serves its OWN browser terminal — **ttyd** (127.0.0.1:7681, per-box basic-auth, drops into `/workspace`) exposed over an outbound-only **Cloudflare Tunnel** — where the builder runs normal interactive `claude`. A browser/Chromebook builder gets the URL + credential from `GET /api/gds/box/terminal` after their box is active — no SSH needed. The terminal/cloudflared units are inlined in cloud-init and start at first boot ([#774](https://example.com/builders#/task/774)). The deleted RC bits (`claude-rc.service`, `box-report-pairing.sh`, `/box/pairing(-link)`) are gone.
+   > **`box-drift-reconcile.timer` (task [#1289](https://example.com/builders#/task/1289)/[ADR 0071](../adr/0071-box-confirm-before-destroyed-and-drift-reconcile.md)) is the zombie backstop.** It runs `box.js reconcile-drift --apply` hourly, reading the live DO droplet list and repairing DO⇄DB drift both ways — force-deleting **zombie** droplets (running but no live box row claims them) and marking **ghost** rows destroyed (droplet gone from DO). Reads the SAME `/etc/example/box.env` (needs `DO_API_TOKEN` to enumerate droplets). Without it, the confirm-before-destroyed teardown still prevents *new* zombies, but a pre-existing one (or an out-of-band DO change) only heals on the next manual `reconcile-drift`. Confirm with `journalctl -u box-drift-reconcile.service`.
+   > **Chromebook / browser terminal ([#760](https://example.com/builders#/task/760)/[ADR 0038](../adr/0038-chromebook-ttyd-cloudflare-tunnel.md), superseding the old `claude rc` pairing).** Research proved `claude rc` cannot run headless, so the box instead serves its OWN browser terminal — **ttyd** (127.0.0.1:7681, per-box basic-auth, drops into `/workspace`) exposed over an outbound-only **Cloudflare Tunnel** — where the builder runs normal interactive `claude`. A browser/Chromebook builder gets the URL + credential from `GET /api/gds/box/terminal` after their box is active — no SSH needed. The terminal/cloudflared units are inlined in cloud-init and start at first boot ([#774](https://example.com/builders#/task/774)). The deleted RC bits (`claude-rc.service`, `box-report-pairing.sh`, `/box/pairing(-link)`) are gone.
 
 ## Cloudflare token: the edge cookie-strip rule (ADR 0053 / SR#11)
 
@@ -164,7 +164,7 @@ curl -sI https://term-<login>.<apex>/ -H 'Cookie: x=1'   # from a box-facing che
 ## Boundaries (other ADR-0031 tasks)
 
 - **[#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.)
+- **[#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/0038-chromebook-ttyd-cloudflare-tunnel.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`/example system). [#598](https://example.com/builders#/task/598) logs the cost; [#602](https://example.com/builders#/task/602) rebills it.
 

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

@@ -1,7 +1,7 @@
 # Recipe: Claude Design loop
 
 > End-to-end guide for the repo ↔ Claude Design sync cycle.
-> ADR: [ADR 0081](../adr/<redacted>.md).
+> ADR: [ADR 0081](../adr/0081-tool-agnostic-design-layer.md).
 > Adapter: `modules/ui-design/adapters/claude-design/index.js` (the `ui-design` module — ADR 0197).
 > CLI: `modules/ui-design/scripts/design-sync.js` (`scripts/gds/design-sync.js` is a thin shim over it).
 > Skill: `.claude/skills/design-sync/SKILL.md`.

package/docs/recipes/core-release-pipeline.md

@@ -4,7 +4,7 @@
 >
 > ## **Merging to `main` ships nothing.**
 >
-> A change that has landed on `main` is running on **zero** instances. It reaches users only after someone bumps `CORE_VERSION`, cuts an artifact, and moves an instance's pin. Those are three separate acts by design ([ADR 0137](../adr/<redacted>.md)) — and every layer around them reports success in the meantime.
+> A change that has landed on `main` is running on **zero** instances. It reaches users only after someone bumps `CORE_VERSION`, cuts an artifact, and moves an instance's pin. Those are three separate acts by design ([ADR 0137](../adr/0137-upstream-publish-policy-manual-owner-gated.md)) — and every layer around them reports success in the meantime.
 
 ## Why this file exists
 
@@ -33,7 +33,7 @@ Bongos vocabulary collides with gate 1 in a way worth naming: **task status `shi
 
 ## Gate 0 — does your change ship at all?
 
-The core is not "this repo." It is exactly the subtree [`isPublishable()`](../../scripts/gds/publish-manifest.js) selects ([ADR 0098](../adr/<redacted>.md)) — a **default-deny, two-layer** gate:
+The core is not "this repo." It is exactly the subtree [`isPublishable()`](../../scripts/gds/publish-manifest.js) selects ([ADR 0098](../adr/0098-public-mirror-publish-manifest.md)) — a **default-deny, two-layer** gate:
 
 ```
 isPublishable(p)  ==  matchesDeny(p) ? false : matchesAllow(p)
@@ -50,7 +50,7 @@ A path publishes only if it falls in `PUBLISH_ALLOWLIST` **and** escapes `PUBLIS
 | **Content / copyright** — the instance's product layer and all art | `modules/game/`, `modules/art-pipeline/`, `public/`, `brand/` |
 | **Host-module tests** — tests that statically import an excluded module | see the list in `publish-manifest.js` |
 
-Note the deliberate non-exclusion: the rank / trust-boundary / ship-grade machinery **is published** — it is the open-source methodology ([ADR 0065 §4](../adr/<redacted>.md)). Only the *topology* subset of the protected surfaces is held back.
+Note the deliberate non-exclusion: the rank / trust-boundary / ship-grade machinery **is published** — it is the open-source methodology ([ADR 0065 §4](../adr/0065-agpl-nonprofit-ai-first-governance.md)). Only the *topology* subset of the protected surfaces is held back.
 
 Check a path before you assume:
 
@@ -60,7 +60,7 @@ node -e "console.log(require('./scripts/gds/publish-manifest').isPublishable('do
 
 ## Gate 1 — land it on `main`
 
-The ordinary claim→ship loop: `/builder-claim N` → build → `/builder-ship`. That chains `completed` → `confirmed` → `shipped`, and credits land at `shipped` ([ADR 0120](../adr/<redacted>.md)).
+The ordinary claim→ship loop: `/builder-claim N` → build → `/builder-ship`. That chains `completed` → `confirmed` → `shipped`, and credits land at `shipped` ([ADR 0120](../adr/0120-pay-on-land-and-builder-owned-rebase-gate.md)).
 
 Landing is CI-gated (tasks 1002610/1002611/1002619, ADR 0159): every PR runs the **`unit`** check — the DB-free suite plus the fitness gates, via `npm test` — and branch protection **requires** it, so a red suite blocks the merge. PRs touching the hard-floor safety surfaces ([`CODEOWNERS`](../../CODEOWNERS)) additionally need the owner's review. The owner kill-switch is `node scripts/gds/gating.js on|off|status` — reversible by construction, snapshot-restored.
 
@@ -72,9 +72,9 @@ Three steps. The first two are ordinary claimed work; only the publish (2c) is o
 
 ### 2a. Bump `CORE_VERSION` — the step with no automation behind it
 
-`CORE_VERSION` lives in [`src/module-api.js`](../../src/module-api.js) and is bumped **by hand, inside a claimed task**, with an entry appended to the release ledger [`docs/module-api-changelog.md`](../module-api-changelog.md) in the same commit. (The ledger used to be a comment block inside `module-api.js`; appending to it there on every CI release grew the file past the oversized-file fitness ratchet and broke `unit` on `main` — [ADR 0203](../adr/<redacted>.md).) The version's provenance stays in git history + ledger ([ADR 0137](../adr/<redacted>.md) §2).
+`CORE_VERSION` lives in [`src/module-api.js`](../../src/module-api.js) and is bumped **by hand, inside a claimed task**, with an entry appended to the release ledger [`docs/module-api-changelog.md`](../module-api-changelog.md) in the same commit. (The ledger used to be a comment block inside `module-api.js`; appending to it there on every CI release grew the file past the oversized-file fitness ratchet and broke `unit` on `main` — [ADR 0203](../adr/0203-doorway-changelog-out-of-module-api.md).) The version's provenance stays in git history + ledger ([ADR 0137](../adr/0137-upstream-publish-policy-manual-owner-gated.md) §2).
 
-Semver here is not decoration — it decides **who receives the change automatically** ([ADR 0136](../adr/<redacted>.md)):
+Semver here is not decoration — it decides **who receives the change automatically** ([ADR 0136](../adr/0136-update-channel-subscription-policy.md)):
 
 | Bump | Reaches `patch` subscribers (the default) | Reaches `minor` subscribers |
 |---|---|---|
@@ -99,7 +99,7 @@ node scripts/gds/package-core.js --ref main --self-verify
 
 ### 2c. Publish — automatic on merge
 
-**Every merge to `main` publishes** ([ADR 0161](../adr/<redacted>.md), superseding ADR 0137's manual gate): once the required `unit` check succeeds on a main push, the `publish` workflow auto-bumps a **patch** if nobody bumped (via `scripts/gds/bump-version.js`, which writes the literal AND appends the ledger entry to [`docs/module-api-changelog.md`](../module-api-changelog.md) — ADR 0203; the carrier commit stages both), builds through the fail-closed no-leak gate with `--self-verify`, publishes, and tags `core-v<version>`. A **minor/major is still a human in-task bump** — CI never makes that call, because it decides what patch-channel subscribers receive unattended.
+**Every merge to `main` publishes** ([ADR 0161](../adr/0161-publish-on-merge.md), superseding ADR 0137's manual gate): once the required `unit` check succeeds on a main push, the `publish` workflow auto-bumps a **patch** if nobody bumped (via `scripts/gds/bump-version.js`, which writes the literal AND appends the ledger entry to [`docs/module-api-changelog.md`](../module-api-changelog.md) — ADR 0203; the carrier commit stages both), builds through the fail-closed no-leak gate with `--self-verify`, publishes, and tags `core-v<version>`. A **minor/major is still a human in-task bump** — CI never makes that call, because it decides what patch-channel subscribers receive unattended.
 
 The lane is armed by the owner via the `PUBLISH_ON_MERGE=1` repo variable + two secrets (`NPM_TOKEN`, `RELEASE_PUSH_TOKEN`); while disarmed it no-ops loudly. Manual fallback, same command CI runs:
 
@@ -152,8 +152,8 @@ carries the target, and names every halt condition it found. Add `--apply` to mo
 
 It **halts rather than guessing** on exactly the things that need judgement — unreleased commits
 on `main`, a registry missing the target, a dirty tree on either end, a failed health check, an
-uncommitted pin. When it halts, fall through to the manual steps below and use your own head;
-that is what the rest of this section is for.
+uncommitted pin, and an unresolved artist review (see below). When it halts, fall through to the
+manual steps below and use your own head; that is what the rest of this section is for.
 
 Two flags worth knowing:
 
@@ -164,6 +164,47 @@ Two flags worth knowing:
 - `--allow-unreleased` downgrades the UNRELEASED halt to a warning. Reach for it only when you
   have already confirmed *why* main is ahead of its last release.
 
+**The one halt that is not about git: `ARTIST_REVIEW_UNRESOLVED`** (task 1003575,
+[ADR 0241](../adr/0241-the-artist-gate-is-a-per-project-deploy-gate-that-reads-a-state.md)).
+A project running `artist_gate: 'strict'` — the default — may not move its pin while a
+cascade-filed **artist review task** is still open. Note what it is and is not: it reads a task
+*status*, never an artist's opinion, and it holds **this gate only**. Nothing about a builder's
+ship, grade, merge, credit or landing on `main` consults it, which is exactly what lets a gate
+that stops work coexist with [ADR 0162](../adr/0162-review-gates-retired-rank-consistent-ci-only.md).
+
+There are three ways past it, and the first two are the ordinary ones:
+
+1. **Resolve or dismiss the reviews.** Shipping one, or abandoning it in triage, is what the
+   gate reads — the same board moves as any other task.
+2. **Lower the setting.** `PATCH /provisioning/instances/:id/settings` with
+   `artist_gate: 'advisory'` keeps the reviews being filed and stops them holding deploys.
+   (Raising it back to `strict` is **not retroactive** — reviews filed before the raise never
+   hold again.)
+3. **Release one.** `POST /tasks/:id/override-request` with a rationale, then the **project
+   owner** approves it at `POST /override-requests/:id/decide`. Three things about that, each of
+   which is a deliberate narrowing rather than a new mechanism:
+
+   - It is the *same* request flow as the grader bypass — ADR 0241 §3 rules out a second
+     authority path — but the **owner alone** may decide this class. An Archon is refused with
+     `override_owner_only`, and that is correct, not a bug.
+   - Approving it **confirms nothing and pays nothing.** The review stays open on the board;
+     what stops is its hold on the pin. (A release is why `POST /tasks/:id/override-request`
+     accepts an artist review at `backlog` at all — the completed-only rule still applies to
+     every other task.)
+   - A **self-release** (owner is also the builder or the artist) is permitted and written to
+     the audit log as a self-override. It is the valve that stops a solo project deadlocking,
+     not a routine step: the right answer to being gated is to fix the work or fix the grader.
+
+`go-live.js` prints the gate's level on every plan, held or not, so "why did nothing stop?" is
+answerable without going and looking. Two different unknowns, two different verdicts:
+
+- It cannot *reach* the gate (no CLI session, or an instance too old to serve `/api/bongos/artist-gate`) —
+  a **note**, not a halt. We do not know the gate applies, and bricking the pin over that would
+  leave no task id to release against.
+- The route is there and **errors** — `ARTIST_GATE_UNREADABLE`, a **halt**. The gate applies and
+  will not answer, and a broken read must never be a quieter way past it than the owner's own
+  override. The fix is in the instance's logs, not on anyone's review queue.
+
 Host topology (ssh alias, box paths, service names, health URL) lives in a host-owned
 `config/go-live.json`, never in the core — run `node scripts/gds/go-live.js --help` for the
 schema. A core that named one instance's box would not be a core.
@@ -268,10 +309,10 @@ Exit codes: `0` aligned, `1` diverged, `2` undetermined.
 | Land a change on `main` | 1 | any builder holding a claim, behind the required `unit` check (protected paths are Metic+; hard-floor paths need owner review per [`CODEOWNERS`](../../CODEOWNERS); [canonical-permissions](../canonical-permissions.md)) |
 | Bump `CORE_VERSION` | 2a | a builder, inside a claimed task |
 | Build the artifact | 2b | any builder — `package-core` is tokenless and network-free |
-| Publish to npm | 2c | **automatic on merge** once the owner arms the lane ([ADR 0161](../adr/<redacted>.md)); the manual `--publish --live` fallback stays owner-only |
+| Publish to npm | 2c | **automatic on merge** once the owner arms the lane ([ADR 0161](../adr/0161-publish-on-merge.md)); the manual `--publish --live` fallback stays owner-only |
 | Move an instance's pin | 3 | whoever operates that instance |
 
-Automating gate 2c (a tag-triggered CI publish) is deliberately deferred until a real fleet makes the manual step a bottleneck — see [ADR 0137](../adr/<redacted>.md) "When to revisit".
+Automating gate 2c (a tag-triggered CI publish) is deliberately deferred until a real fleet makes the manual step a bottleneck — see [ADR 0137](../adr/0137-upstream-publish-policy-manual-owner-gated.md) "When to revisit".
 
 ## Where to go next
 
@@ -280,6 +321,6 @@ Automating gate 2c (a tag-triggered CI publish) is deliberately deferred until a
 | build / verify / inspect the artifact | [packaging-the-core](packaging-the-core.md) |
 | publish it, or set up private npm access | [private-npm-distribution](private-npm-distribution.md) |
 | move an instance from N → N+1, or subscribe it to updates | [upgrading-the-core](upgrading-the-core.md) |
-| know *why* publishing is manual | [ADR 0137](../adr/<redacted>.md) |
-| know *what* an unattended upgrade is allowed to take | [ADR 0136](../adr/<redacted>.md) |
-| know what counts as "the core" | [ADR 0098](../adr/<redacted>.md) · [ADR 0103](../adr/<redacted>.md) |
+| know *why* publishing is manual | [ADR 0137](../adr/0137-upstream-publish-policy-manual-owner-gated.md) |
+| know *what* an unattended upgrade is allowed to take | [ADR 0136](../adr/0136-update-channel-subscription-policy.md) |
+| know what counts as "the core" | [ADR 0098](../adr/0098-public-mirror-publish-manifest.md) · [ADR 0103](../adr/0103-core-first-extraction-cloud-bongos-trunk.md) |

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

@@ -1,7 +1,7 @@
 # Recipe: Figma round-trip loop
 
 > End-to-end guide for the repo ↔ Figma sync cycle — the human escape hatch in ADR 0081.
-> ADR: [ADR 0081](../adr/<redacted>.md).
+> ADR: [ADR 0081](../adr/0081-tool-agnostic-design-layer.md).
 > Adapter: `modules/ui-design/adapters/figma/index.js` (the `ui-design` module — ADR 0197).
 > CLI: `modules/ui-design/scripts/figma-design-sync.js` (`scripts/gds/figma-design-sync.js` is a thin shim over it).
 > Skill: `.claude/skills/figma-design-sync/SKILL.md`.

package/docs/recipes/gds-db-backup.md

@@ -1,6 +1,6 @@
 # Recipe — Bongos DB backup (local nightly + offsite weekly)
 
-> **Filed by:** task [#412](https://example.com/builders#/task/412) (V3.R62-precondition, local nightly) + [#415](https://example.com/builders#/task/415) (V3.R62-offsite, weekly offsite archive) — both under [ADR 0024](../adr/<redacted>.md) §5 (backup cadence). Vendor choice for the offsite copy: [ADR 0025](../adr/<redacted>.md) (DigitalOcean Spaces).
+> **Filed by:** task [#412](https://example.com/builders#/task/412) (V3.R62-precondition, local nightly) + [#415](https://example.com/builders#/task/415) (V3.R62-offsite, weekly offsite archive) — both under [ADR 0024](../adr/0024-cloneable-repo-local-first-memory.md) §5 (backup cadence). Vendor choice for the offsite copy: [ADR 0025](../adr/0025-offsite-backup-vendor-digitalocean-spaces.md) (DigitalOcean Spaces).
 > **Two layers:** a **local daily** `pg_dump` to `/var/backups/gds/` (protects against corruption / bad migration / accidental delete) **plus** a **weekly offsite copy** of the latest local dump to a DigitalOcean Space (protects against whole-droplet loss).
 > **Reads:** `/etc/systemd/system/gds-db-backup.{service,timer}` (copies of [`scripts/gds/gds-db-backup.service`](../../scripts/gds/gds-db-backup.service) / [`.timer`](../../scripts/gds/gds-db-backup.timer)) + [`scripts/gds/db-backup-nightly.sh`](../../scripts/gds/db-backup-nightly.sh); `/etc/systemd/system/gds-db-offsite.{service,timer}` (copies of [`scripts/gds/gds-db-offsite.service`](../../scripts/gds/gds-db-offsite.service) / [`.timer`](../../scripts/gds/gds-db-offsite.timer)) + [`scripts/gds/db-backup-offsite.sh`](../../scripts/gds/db-backup-offsite.sh).
 
@@ -252,4 +252,4 @@ curl -s https://example.com/api/gds/public/progress | jq '.progress[0]'
 ## Cost
 
 - **Local nightly ([#412](https://example.com/builders#/task/412)):** $0/mo. `/var/backups/gds/` lives on the existing droplet disk; dumps are sub-MB; the systemd timer is free. The droplet is 67 GB total; years of dumps would not be a sizing concern.
-- **Offsite weekly ([#415](https://example.com/builders#/task/415)):** $5/mo flat — a DigitalOcean Space (250 GB + 1 TB transfer included). We retain only 4 sub-MB objects, so we use a rounding error of the tier. The $5/mo over Backblaze B2's ~$0 is a deliberate one-vendor / same-region simplicity choice — see [ADR 0025](../adr/<redacted>.md).
+- **Offsite weekly ([#415](https://example.com/builders#/task/415)):** $5/mo flat — a DigitalOcean Space (250 GB + 1 TB transfer included). We retain only 4 sub-MB objects, so we use a rounding error of the tier. The $5/mo over Backblaze B2's ~$0 is a deliberate one-vendor / same-region simplicity choice — see [ADR 0025](../adr/0025-offsite-backup-vendor-digitalocean-spaces.md).

package/docs/recipes/instance-deploy.md

@@ -1,6 +1,6 @@
 # Recipe — deploying a Cloud Bongos instance on a pinned core (`git reset` → `npm ci`)
 
-> ADR [0108](../adr/<redacted>.md) §4 (configurable-root W4, task [#1884](https://example.com/builders#/task/1884)). How a **consumer instance** — one that installs `@bongos/core` as a versioned npm dependency rather than living in the monorepo — deploys. This is the target the live droplet deploy converts to; the reference implementation is [`scripts/deploy/deploy-instance.sh`](../../scripts/deploy/deploy-instance.sh).
+> ADR [0108](../adr/0108-instance-composition-configurable-root.md) §4 (configurable-root W4, task [#1884](https://example.com/builders#/task/1884)). How a **consumer instance** — one that installs `@bongos/core` as a versioned npm dependency rather than living in the monorepo — deploys. This is the target the live droplet deploy converts to; the reference implementation is [`scripts/deploy/deploy-instance.sh`](../../scripts/deploy/deploy-instance.sh).
 
 ## The two models
 
@@ -33,6 +33,6 @@
 
 1. Install the script as the droplet's `~/deploy.sh` (the CI deploy key is forced-command-locked to `~/deploy.sh` — ADR 0043 — so it stays hand-installed, like `deploy-prod.sh`).
 2. Create a systemd unit for the instance: `ExecStart=/usr/bin/node <instanceRoot>/node_modules/@bongos/core/src/platform-server.js`, `WorkingDirectory=<instanceRoot>`, `Environment=PORT=… HOST=127.0.0.1 <PREFIX>_INSTANCE_ROOT=<instanceRoot>`.
-   **`bongos serve` now writes exactly this unit for you** (plus the DB/migrate/health legs) — see [`server-bring-up.md`](server-bring-up.md) / [ADR 0169](../adr/<redacted>.md). Step 4 of the flow above ("restart the platform") is `systemctl restart bongos-<db>` once it has.
+   **`bongos serve` now writes exactly this unit for you** (plus the DB/migrate/health legs) — see [`server-bring-up.md`](server-bring-up.md) / [ADR 0169](../adr/0169-bongos-serve-server-bring-up.md). Step 4 of the flow above ("restart the platform") is `systemctl restart bongos-<db>` once it has.
 3. Set `INSTANCE_SERVICE=<unit>` + `PORT=<port>` in the deploy environment.
 4. Front it with TLS and point the origins at the real domain (see [self-host.md](self-host.md)).

package/docs/recipes/instance-service-restart.md

@@ -1,6 +1,6 @@
 # Recipe — letting `bongos upgrade` restart the instance service unattended
 
-> [ADR 0279](../adr/<redacted>.md) · [task 1002884](https://cloudbongos.com/builders#/task/1002884). A core bump only counts once the **running process** is the new core, so `bongos upgrade` has to be able to restart the service without a human at a keyboard. This is what to do when it cannot.
+> [ADR 0279](../adr/0279-an-upgrade-is-proven-by-the-served-version-not-the-health-check.md) · [task 1002884](https://cloudbongos.com/builders#/task/1002884). A core bump only counts once the **running process** is the new core, so `bongos upgrade` has to be able to restart the service without a human at a keyboard. This is what to do when it cannot.
 
 ## The symptom
 
@@ -84,6 +84,6 @@ curl -s https://<instance>/version
 
 ## Related
 
-- [ADR 0279](../adr/<redacted>.md) — why a health check cannot confirm an upgrade
-- [ADR 0136](../adr/<redacted>.md) §3 — the unattended subscription lane's health-gate + auto-rollback policy
+- [ADR 0279](../adr/0279-an-upgrade-is-proven-by-the-served-version-not-the-health-check.md) — why a health check cannot confirm an upgrade
+- [ADR 0136](../adr/0136-update-channel-subscription-policy.md) §3 — the unattended subscription lane's health-gate + auto-rollback policy
 - [`docs/recipes/ops-gotchas.md`](ops-gotchas.md) — the wider set of deploy traps

package/docs/recipes/local-dev.md

@@ -3,7 +3,7 @@
 > The one-command path from a freshly-cloned **standalone instance repo** (one whose
 > `config/branding.json` points at `http://localhost:<port>`) to a running, signed-in
 > instance on your Mac. This is the local counterpart of `bongos onboard` (which
-> stands an instance up in the **cloud**) — see [ADR 0149](../adr/<redacted>.md).
+> stands an instance up in the **cloud**) — see [ADR 0149](../adr/0149-bongos-dev-local-launcher.md).
 
 ## TL;DR
 
@@ -81,4 +81,4 @@ the Client ID + secret to `~/.config/<configDir>/gds-github.json` as
   local database or server to run.
 - **Ready for a real host?** `bongos serve` runs this *same* boot path on a server —
   systemd-supervised, bind address derived from your public origin, no browser needed. See
-  [`server-bring-up.md`](server-bring-up.md) ([ADR 0169](../adr/<redacted>.md)).
+  [`server-bring-up.md`](server-bring-up.md) ([ADR 0169](../adr/0169-bongos-serve-server-bring-up.md)).

package/docs/recipes/managed-settings-remote-control.md

@@ -1,8 +1,8 @@
 # Recipe - managed-settings SSH + browser-terminal on-ramps
 
-> **Task [#599](https://example.com/builders#/task/599) · [ADR 0031](../adr/<redacted>.md) §1.** This is the operator guide for distributing a locked Claude Desktop SSH connection to builders and for serving the browser web-terminal on the box. Read [builder-box-lifecycle.md](builder-box-lifecycle.md) first — this recipe assumes a box is already provisioned and running.
+> **Task [#599](https://example.com/builders#/task/599) · [ADR 0031](../adr/0031-cloud-dev-environments-for-builders.md) §1.** This is the operator guide for distributing a locked Claude Desktop SSH connection to builders and for serving the browser web-terminal on the box. Read [builder-box-lifecycle.md](builder-box-lifecycle.md) first — this recipe assumes a box is already provisioned and running.
 
-> **Chromebook/browser path (ADR 0038 → [ADR 0040](../adr/<redacted>.md), [#760](https://example.com/builders#/task/760) / [#824](https://example.com/builders#/task/824)):** the box serves its own web terminal - `ttyd` bound to localhost, exposed via an outbound-only Cloudflare Tunnel - and the builder runs a NORMAL interactive `claude` inside it from any browser. Because there is a real human at a real browser-backed terminal, `/login`, workspace-trust, and Trusted-Devices enrollment all succeed (the things that made headless `claude rc` unworkable). **ADR 0040 narrows that terminal to a one-time launchpad:** the builder logs in there once, runs the in-session **`/remote-control`** slash command, and then drives the box from the Claude web/mobile app — the terminal is no longer their daily surface. **The SSH path (Mac/Windows) below is unaffected and works.**
+> **Chromebook/browser path (ADR 0038 → [ADR 0040](../adr/0040-remote-control-default-browser-onramp.md), [#760](https://example.com/builders#/task/760) / [#824](https://example.com/builders#/task/824)):** the box serves its own web terminal - `ttyd` bound to localhost, exposed via an outbound-only Cloudflare Tunnel - and the builder runs a NORMAL interactive `claude` inside it from any browser. Because there is a real human at a real browser-backed terminal, `/login`, workspace-trust, and Trusted-Devices enrollment all succeed (the things that made headless `claude rc` unworkable). **ADR 0040 narrows that terminal to a one-time launchpad:** the builder logs in there once, runs the in-session **`/remote-control`** slash command, and then drives the box from the Claude web/mobile app — the terminal is no longer their daily surface. **The SSH path (Mac/Windows) below is unaffected and works.**
 
 ---
 
@@ -161,7 +161,7 @@ The `sshHostAllowlist: ["*.dev.example.com"]` entry prevents the builder from us
 
 ---
 
-## Part 2 - Browser on-ramp: terminal launchpad -> Remote Control (Chromebook / any browser) - ADR 0038 -> [ADR 0040](../adr/<redacted>.md), [#760](https://example.com/builders#/task/760) / [#824](https://example.com/builders#/task/824)
+## Part 2 - Browser on-ramp: terminal launchpad -> Remote Control (Chromebook / any browser) - ADR 0038 -> [ADR 0040](../adr/0040-remote-control-default-browser-onramp.md), [#760](https://example.com/builders#/task/760) / [#824](https://example.com/builders#/task/824)
 
 ### How it works
 

package/docs/recipes/memory-backup.md

@@ -1,10 +1,10 @@
 # Recipe — Builder memory backup + restore drill
 
-> **Filed by:** task [#281](https://example.com/builders#/task/281) (V3.R62), GDS-V3 criterion C8 ("memory is local-first, server-canonical on ship"). Depends on the server-side memory store ([#273](https://example.com/builders#/task/273) R54) and the DB backup pipeline ([#412](https://example.com/builders#/task/412) local nightly + [#415](https://example.com/builders#/task/415) weekly offsite). Companion to [`gds-db-backup.md`](gds-db-backup.md); vendor choice in [ADR 0025](../adr/<redacted>.md).
+> **Filed by:** task [#281](https://example.com/builders#/task/281) (V3.R62), GDS-V3 criterion C8 ("memory is local-first, server-canonical on ship"). Depends on the server-side memory store ([#273](https://example.com/builders#/task/273) R54) and the DB backup pipeline ([#412](https://example.com/builders#/task/412) local nightly + [#415](https://example.com/builders#/task/415) weekly offsite). Companion to [`gds-db-backup.md`](gds-db-backup.md); vendor choice in [ADR 0025](../adr/0025-offsite-backup-vendor-digitalocean-spaces.md).
 
 ## Key decision — memory is backed up *as part of the full-DB backup*, not separately
 
-C8 makes each builder's local memory dir **server-canonical on ship**: `/builder-ship` upserts the builder's memory files into the `builder_memory` Postgres table ([#274](https://example.com/builders#/task/274) R55). Because that table lives in the same `example` database as everything else, **it is already captured by the full-DB backup pipeline** — there is deliberately **no separate `backup-memory.sh`**. A memory-only dump would duplicate what `pg_dump` already writes nightly and ship offsite weekly, and would be a second thing to keep in sync. One backup story, not two (same principle as [ADR 0025](../adr/<redacted>.md)'s retirement of the redundant [#7](https://example.com/builders#/task/7) cron).
+C8 makes each builder's local memory dir **server-canonical on ship**: `/builder-ship` upserts the builder's memory files into the `builder_memory` Postgres table ([#274](https://example.com/builders#/task/274) R55). Because that table lives in the same `example` database as everything else, **it is already captured by the full-DB backup pipeline** — there is deliberately **no separate `backup-memory.sh`**. A memory-only dump would duplicate what `pg_dump` already writes nightly and ship offsite weekly, and would be a second thing to keep in sync. One backup story, not two (same principle as [ADR 0025](../adr/0025-offsite-backup-vendor-digitalocean-spaces.md)'s retirement of the redundant [#7](https://example.com/builders#/task/7) cron).
 
 So builder memory inherits both layers:
 
@@ -67,5 +67,5 @@ The first drill run **failed correctly**: the most recent nightly dump (04:02 UT
 ## See also
 
 - [`gds-db-backup.md`](gds-db-backup.md) — the full backup pipeline, install steps, and the general (non-memory-specific) restore drills.
-- [ADR 0025](../adr/<redacted>.md) — offsite vendor decision.
-- [ADR 0024](../adr/<redacted>.md) — the local-first / server-canonical memory model this backs up.
+- [ADR 0025](../adr/0025-offsite-backup-vendor-digitalocean-spaces.md) — offsite vendor decision.
+- [ADR 0024](../adr/0024-cloneable-repo-local-first-memory.md) — the local-first / server-canonical memory model this backs up.