@bongos/core 1.19.715 → 1.19.724

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.

package/docs/recipes/memory-sync-conflicts.md

@@ -1,6 +1,6 @@
 # Recipe — Memory sync conflicts: policy + clobber recovery
 
-> **Filed by:** task [#277](https://example.com/builders#/task/277) (V3.R58), GDS-V3 criterion C8. Documents the conflict policy chosen by the R04 spike ([ADR 0024](../adr/<redacted>.md) §3) and implemented across [#274](https://example.com/builders#/task/274) (push), [#275](https://example.com/builders#/task/275) (pull), [#276](https://example.com/builders#/task/276) (isolation). Recovery leans on the backup pipeline from [#281](https://example.com/builders#/task/281) ([`memory-backup.md`](memory-backup.md)).
+> **Filed by:** task [#277](https://example.com/builders#/task/277) (V3.R58), GDS-V3 criterion C8. Documents the conflict policy chosen by the R04 spike ([ADR 0024](../adr/0024-cloneable-repo-local-first-memory.md) §3) and implemented across [#274](https://example.com/builders#/task/274) (push), [#275](https://example.com/builders#/task/275) (pull), [#276](https://example.com/builders#/task/276) (isolation). Recovery leans on the backup pipeline from [#281](https://example.com/builders#/task/281) ([`memory-backup.md`](memory-backup.md)).
 
 ## The policy in one line
 
@@ -93,6 +93,6 @@ sudo -u postgres dropdb example_recover && rm -f /tmp/recovered.txt
 
 ## See also
 
-- [ADR 0024](../adr/<redacted>.md) §3 — the decision + rejected alternatives.
+- [ADR 0024](../adr/0024-cloneable-repo-local-first-memory.md) §3 — the decision + rejected alternatives.
 - [`memory-backup.md`](memory-backup.md) — backup cadence + the restore drill the recovery above relies on.
 - [`gds-db-backup.md`](gds-db-backup.md) — the underlying dump/offsite pipeline.

package/docs/recipes/multi-builder-merge.md

@@ -1,6 +1,6 @@
 # Multi-builder merge safety — audit + serialization model
 
-> **Deploy-mode note (current state).** This recipe documents the **`laptop`** merge path (operator merges `main` + SSHes the droplet). Since the 2026-06-13 cutover `config/deploy.json` is **`mode: ci`** — the merge + deploy run **server-side** (PR auto-merge + `.github/workflows/deploy-prod.yml`), and credential-less dev boxes ship via server-mediated publish ([ADR 0055](../adr/<redacted>.md)). The local-`main`-worktree + merge-lock model below applies only if `deploy.json` is reverted to `mode: laptop`.
+> **Deploy-mode note (current state).** This recipe documents the **`laptop`** merge path (operator merges `main` + SSHes the droplet). Since the 2026-06-13 cutover `config/deploy.json` is **`mode: ci`** — the merge + deploy run **server-side** (PR auto-merge + `.github/workflows/deploy-prod.yml`), and credential-less dev boxes ship via server-mediated publish ([ADR 0055](../adr/0055-server-mediated-branch-publish.md)). The local-`main`-worktree + merge-lock model below applies only if `deploy.json` is reverted to `mode: laptop`.
 
 > **Task:** V3.R50 / [#269](https://example.com/builders#/task/269) (criterion **C6 — parallel-safe-under-load**).
 > **Question it answers:** when N>1 builders ship and merge concurrently, where do `ship.js` and `/merge-mode` assume "I am the only builder," and what serializes the shared state so they don't collide?
@@ -72,7 +72,7 @@ Behavior is pinned by [`tests/merge_lock.mjs`](../../tests/merge_lock.mjs) (auto
 
 ## Related
 
-- [ADR 0024](../adr/<redacted>.md) — multi-agent system (the reason N>1 builders exist).
+- [ADR 0024](../adr/0024-multi-agent-system-architecture.md) — multi-agent system (the reason N>1 builders exist).
 - [#462](https://example.com/builders#/task/462) — the C4 auto-merge lock this task generalizes.
 - [#270](https://example.com/builders#/task/270) (V3.R51) — server-side worktree-name uniqueness (a sibling parallel-safety fix).
 - [#272](https://example.com/builders#/task/272) — the parallel-load smoke test that *exercises* this serialization under 5 simulated builders (the other open C6 task). Its **DB rank is R53** (the DB is king); the original planning-seed cross-ref text called it "R54", but the live rank renumbering settled it at R53/[#272](https://example.com/builders#/task/272).

package/docs/recipes/ops-gotchas.md

@@ -28,7 +28,7 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 ### Re-provisioning an EXISTING instance moves its `HOME`, orphaning any stored builder secrets
 
 - **Symptom:** after a re-provision, an instance that had builder API keys stored can no longer decrypt them. Nothing errors at startup — the instance comes up healthy and simply behaves as though no key was ever saved.
-- **Root cause:** task [1003369](https://cloudbongos.com/builders#/task/1003369) ([ADR 0281](../adr/<redacted>.md)) gives each instance its own unix account with `HOME=/var/lib/bongos-<slug>`. [`src/bongos/secret-box.js`](../../src/bongos/secret-box.js) keeps its master key at `~/.config/<configDir>/builder-secret.key`, so the key an instance wrote under the OLD shared home (`/home/lars/.config/…`) is no longer on its `HOME` path. `provisionMasterKey()` finds nothing, mints a fresh key, and every previously encrypted secret is now undecryptable ciphertext.
+- **Root cause:** task [1003369](https://cloudbongos.com/builders#/task/1003369) ([ADR 0281](../adr/0281-an-instance-identity-is-its-own-unix-account-and-pg-role.md)) gives each instance its own unix account with `HOME=/var/lib/bongos-<slug>`. [`src/bongos/secret-box.js`](../../src/bongos/secret-box.js) keeps its master key at `~/.config/<configDir>/builder-secret.key`, so the key an instance wrote under the OLD shared home (`/home/lars/.config/…`) is no longer on its `HOME` path. `provisionMasterKey()` finds nothing, mints a fresh key, and every previously encrypted secret is now undecryptable ciphertext.
 - **Who this hits:** only a **re-provision of an instance that has already stored secrets**. A fresh standup has nothing to lose, and an instance whose `web.env` sets `BUILDER_SECRET_KEY` is unaffected — that env wins over the file.
 - **Fix (before the re-provision, one command as root):**
   ```bash
@@ -70,7 +70,7 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 
 - **Symptom:** Caddy obtained the initial cert fine, then failed to renew at the 90-day mark — site went down.
 - **Root cause:** With Cloudflare proxy ON (orange cloud), CF intercepts port 80 at the edge and Caddy never sees the HTTP-01 challenge from Let's Encrypt. Renewal silently fails.
-- **Fix (already in place):** Replaced Let's Encrypt with a Cloudflare Origin Certificate (15-year cert at `/etc/caddy/origin.crt` + `.key`, explicit `tls` directive in Caddyfile). Eliminates the auto-renewal dependency for the CF↔origin leg. See [ADR 0003](../adr/<redacted>.md).
+- **Fix (already in place):** Replaced Let's Encrypt with a Cloudflare Origin Certificate (15-year cert at `/etc/caddy/origin.crt` + `.key`, explicit `tls` directive in Caddyfile). Eliminates the auto-renewal dependency for the CF↔origin leg. See [ADR 0003](../adr/0003-cloudflare-origin-cert-over-letsencrypt.md).
 - **Why it bites:** The failure mode is silent for ~89 days, then catastrophic. Easy to think the site is "set and forget" when it is actually approaching a cliff.
 
 ### Deploying configs to `/etc/caddy/` requires staging through `~/`
@@ -249,7 +249,7 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 
 - **Symptom:** the site is down for hours, but The Watch still shows 100% / "standing".
 - **Root cause:** `status.example.com` is served by the same Node process on the same droplet as the game, and the in-process poller (`src/bongos/uptime-poller.js`) probes `127.0.0.1`. When the droplet dies, the page dies with it and the poller writes **zero rows** — the gap renders as green. A monitor that lives inside the monitored thing cannot witness its own death.
-- **Fix:** measure availability from **outside** (the external GitHub-Actions prober — `.github/workflows/status-probe.yml`, task [#565](https://example.com/builders#/task/565)) and host the status page **off-box** (follow-up [#566](https://example.com/builders#/task/566)). See [ADR 0029](../adr/<redacted>.md) + Bongos learning `#35`.
+- **Fix:** measure availability from **outside** (the external GitHub-Actions prober — `.github/workflows/status-probe.yml`, task [#565](https://example.com/builders#/task/565)) and host the status page **off-box** (follow-up [#566](https://example.com/builders#/task/566)). See [ADR 0029](../adr/0029-status-page-outage-resilience.md) + Bongos learning `#35`.
 - **Why it bites:** a status page that lies is worse than none — it actively reassures you while the product is on fire.
 
 ### The live status page is NOT served by the droplet — editing the status surface + deploying does nothing
@@ -268,7 +268,7 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 ### `bypassPermissions` "still not available" even though the box was provisioned for it (task 2022)
 
 - **Symptom:** you reconnect to the browser terminal (or SSH) on a dev box and `claude` still stops for permission prompts, even though tasks [#1251](https://example.com/builders#/task/1251) and [#1314](https://example.com/builders#/task/1314) default every box to `bypassPermissions`.
-- **Root cause:** `otb-box-launch.sh` (behind `box-terminal.service`) only ever runs `claude` once — the first time it creates the tmux `otb` session. Every later connect just reattaches to that **same running process**. The `defaultMode=bypassPermissions` setting is written into `~/.claude/settings.json` by `box-source-fetch.sh`'s cron, on its own `*/10` schedule (and, on an already-provisioned box, only after that box's baked copy of the script has self-updated to even contain the fix). If the `otb` tmux session got created before that write landed — an older box, or a fresh box whose very first connect raced the first cron tick — `claude` started once in normal `auto` mode and is stuck there for the life of the box; reconnecting never re-launches it, so the fix never takes effect even once the setting is correct on disk. (Flagged as an open follow-up in [ADR 0104](../adr/<redacted>.md).)
+- **Root cause:** `otb-box-launch.sh` (behind `box-terminal.service`) only ever runs `claude` once — the first time it creates the tmux `otb` session. Every later connect just reattaches to that **same running process**. The `defaultMode=bypassPermissions` setting is written into `~/.claude/settings.json` by `box-source-fetch.sh`'s cron, on its own `*/10` schedule (and, on an already-provisioned box, only after that box's baked copy of the script has self-updated to even contain the fix). If the `otb` tmux session got created before that write landed — an older box, or a fresh box whose very first connect raced the first cron tick — `claude` started once in normal `auto` mode and is stuck there for the life of the box; reconnecting never re-launches it, so the fix never takes effect even once the setting is correct on disk. (Flagged as an open follow-up in [ADR 0104](../adr/0104-trust-gds-api-channel-in-auto-mode.md).)
 - **Fix:** `otb-box-launch.sh` now asserts `defaultMode=bypassPermissions` itself, synchronously, right before it creates a **new** `otb` tmux session — so a fresh session never depends on cron timing. This prevents the race going forward but does **not** repair a box whose `otb` session is already running in the wrong mode: for that, from an SSH/browser-terminal shell run `tmux kill-session -t otb` then reconnect (the launcher creates a fresh session and picks up the corrected setting immediately). Killing the session only drops the terminal pane — it does not touch `/workspace` or in-flight git state.
 - **Why it bites:** every layer *looks* fixed — `~/.claude/settings.json` has the right value, `IS_SANDBOX=1` is set — because you're inspecting the box's filesystem, not the already-running process that never re-read it.
 

package/docs/recipes/overnight-builder.md

@@ -33,7 +33,7 @@ curl -sS -X PATCH -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: applicat
   -d '{"parallel_safe": true}' https://example.com/api/gds/tasks/<id>
 ```
 
-In parallel mode each worker stops at `confirmed` (verified, not yet paid — [ADR 0120](../adr/<redacted>.md) books credits at land) and the runner lands the merges **one at a time** — concurrent merges to `main` are never allowed. Credits land as each merge completes.
+In parallel mode each worker stops at `confirmed` (verified, not yet paid — [ADR 0120](../adr/0120-pay-on-land-and-builder-owned-rebase-gate.md) books credits at land) and the runner lands the merges **one at a time** — concurrent merges to `main` are never allowed. Credits land as each merge completes.
 
 ## Reading the morning report
 

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

@@ -2,13 +2,13 @@
 
 > **This is one leg of three.** For how a change to Cloud Bongos actually reaches a live instance — and why merging to `main` ships nothing on its own — start at [the core release pipeline](core-release-pipeline.md).
 >
-> Implements [ADR 0100 §1](../adr/<redacted>.md) (the two-repo instance model). This is **R84**, the first step of the `R84 → R85 → R86` spine: package the core → stand a downstream instance up on a pinned core → make `bongos upgrade` a real update channel. Tooling: [`scripts/gds/package-core.js`](../../scripts/gds/package-core.js) (`bongos package-core`).
+> Implements [ADR 0100 §1](../adr/0100-two-repo-instance-model.md) (the two-repo instance model). This is **R84**, the first step of the `R84 → R85 → R86` spine: package the core → stand a downstream instance up on a pinned core → make `bongos upgrade` a real update channel. Tooling: [`scripts/gds/package-core.js`](../../scripts/gds/package-core.js) (`bongos package-core`).
 >
-> **Real installable npm package ([ADR 0108](../adr/<redacted>.md) §2, task 1882/W2, shipped):** the artifact is `package/`-rooted (the npm convention `npm install ./x.tgz` requires) and carries a synthesized `package.json` — `name: "@bongos/core"`, `version` = `CORE_VERSION`, `main: "src/platform-server.js"`, `exports` for the default entry (`buildPlatformApp`) plus `./serve-internal` (`mountInternalSurfaces`) and `./module-api`, `bin: "bongos"` — and a **pruned** `package-lock.json` (express + pg's own transitive closure only, resolved offline from the source lockfile — no colyseus/phaser/sharp/discord.js). Both files are synthesized fresh, never copied verbatim from the source repo's game-heavy `package.json`. `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js), W1/task 1881) are what a consumer's own code routes through once installed.
+> **Real installable npm package ([ADR 0108](../adr/0108-instance-composition-configurable-root.md) §2, task 1882/W2, shipped):** the artifact is `package/`-rooted (the npm convention `npm install ./x.tgz` requires) and carries a synthesized `package.json` — `name: "@bongos/core"`, `version` = `CORE_VERSION`, `main: "src/platform-server.js"`, `exports` for the default entry (`buildPlatformApp`) plus `./serve-internal` (`mountInternalSurfaces`) and `./module-api`, `bin: "bongos"` — and a **pruned** `package-lock.json` (express + pg's own transitive closure only, resolved offline from the source lockfile — no colyseus/phaser/sharp/discord.js). Both files are synthesized fresh, never copied verbatim from the source repo's game-heavy `package.json`. `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js), W1/task 1881) are what a consumer's own code routes through once installed.
 
 ## What the artifact is
 
-A Cloud Bongos *instance* can be its **own repository** that installs a **pinned version** of the Cloud Bongos **core** — the portable methodology + platform + neutral branding — and layers its own content, branding, and modules on top. "The core" is not re-defined here: it is exactly the subtree [`isPublishable()`](../../scripts/gds/publish-manifest.js) already defines ([ADR 0098](../adr/<redacted>.md)).
+A Cloud Bongos *instance* can be its **own repository** that installs a **pinned version** of the Cloud Bongos **core** — the portable methodology + platform + neutral branding — and layers its own content, branding, and modules on top. "The core" is not re-defined here: it is exactly the subtree [`isPublishable()`](../../scripts/gds/publish-manifest.js) already defines ([ADR 0098](../adr/0098-public-mirror-publish-manifest.md)).
 
 `bongos package-core` produces three things in `dist/` (git-ignored — the artifact is a build product, not committed):
 
@@ -20,7 +20,7 @@ A Cloud Bongos *instance* can be its **own repository** that installs a **pinned
 
 The version is the **platform version** — `CORE_VERSION` from [`src/module-api.js`](../../src/module-api.js), the same coordinate the module loader and `bongos upgrade` compare against ([#1203](https://example.com/builders#/task/1203)). That shared coordinate is what keeps the spine coherent: a module pinned to `^core_contract` is guaranteed to load against the packaged core.
 
-Every file is **redacted** through the same fail-closed pipeline the public mirror uses ([ADR 0099](../adr/<redacted>.md)): instance literals + public IPs are stripped, a secret backstop runs, and if *any* residual leak survives the packager **produces nothing** (`dist/` is never touched). So a downstream repo never inherits the source instance's identity or secrets — it gets a neutral core.
+Every file is **redacted** through the same fail-closed pipeline the public mirror uses ([ADR 0099](../adr/0099-delayed-redacted-mirror-export.md)): instance literals + public IPs are stripped, a secret backstop runs, and if *any* residual leak survives the packager **produces nothing** (`dist/` is never touched). So a downstream repo never inherits the source instance's identity or secrets — it gets a neutral core.
 
 ## Produce it
 
@@ -59,6 +59,6 @@ The manifest's `files[]` carries the same `{ path, mode, sha256 }` triples, so t
 
 ## Boundaries + relation to the mirror
 
-- **Not the public mirror.** The delayed, redacted, ~6-month-lagged public mirror ([ADR 0099](../adr/<redacted>.md)) is the open-source surface. This artifact is a *current*, versioned unit for **dependency consumption** by a sister repo — no lag. Both reuse the same `isPublishable()` selection and the same redaction; `package-core.js` imports the mirror's `redactBlob` so the redaction logic is defined once.
-- **Per-repo Bongos.** Each instance runs its own database, tasks, builders, and credits ([ADR 0100 §3](../adr/<redacted>.md)). Packaging the core moves *code*, never work-tracking state.
+- **Not the public mirror.** The delayed, redacted, ~6-month-lagged public mirror ([ADR 0099](../adr/0099-delayed-redacted-mirror-export.md)) is the open-source surface. This artifact is a *current*, versioned unit for **dependency consumption** by a sister repo — no lag. Both reuse the same `isPublishable()` selection and the same redaction; `package-core.js` imports the mirror's `redactBlob` so the redaction logic is defined once.
+- **Per-repo Bongos.** Each instance runs its own database, tasks, builders, and credits ([ADR 0100 §3](../adr/0100-two-repo-instance-model.md)). Packaging the core moves *code*, never work-tracking state.
 - **The single-checkout instance model is not deprecated** — it stays the cheaper shape for a quick reskin (cloudbongos.com). Two-repo is the destination for a project that wants to be its own thing and pull core updates on its own schedule.

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

@@ -2,7 +2,7 @@
 
 > **This is one leg of three.** For the whole path from a change on core `main` to a live instance — and for when publishing to npm is *not* what moves an instance — start at [the core release pipeline](core-release-pipeline.md).
 >
-> Implements [ADR 0134](../adr/<redacted>.md), **core half only**. Pre-launch, `@bongos/core` publishes as a **private, scoped** npm package on the owner's paid `bongos` npm org (the canonical brand); at launch it flips to public. The daily command is `bongos` regardless of package name.
+> Implements [ADR 0134](../adr/0134-private-first-npm-distribution.md), **core half only**. Pre-launch, `@bongos/core` publishes as a **private, scoped** npm package on the owner's paid `bongos` npm org (the canonical brand); at launch it flips to public. The daily command is `bongos` regardless of package name.
 >
 > **`@bongos/client` is no longer part of this.** It was published once (2026-07-07, 0.0.2), never updated while the API moved 500+ core versions, and had **zero** consumers the whole time — every consumer vendors a copy instead. The owner removed it from npm on 2026-09-09; ADR 0134's client half is superseded ([task 1003742](https://cloudbongos.com/builders#/task/1003742)). The generated client still exists and still regenerates — it is simply not a package.
 >
@@ -52,13 +52,13 @@ npm pack ./clients/bongos-client --dry-run        # token-free content preview
 npm publish ./clients/bongos-client               # real (publishConfig makes it restricted; needs npm login)
 ```
 
-## Cutting a core release (the policy — [ADR 0161](../adr/<redacted>.md), superseding ADR 0137)
+## Cutting a core release (the policy — [ADR 0161](../adr/0161-publish-on-merge.md), superseding ADR 0137)
 
-**Publishing is automatic on merge** as of 2026-08-08: the `publish` workflow rides behind the required `unit` check, auto-bumps a patch when nobody bumped, builds through the fail-closed no-leak gate, publishes, and tags — see the workflow header (`.github/workflows/publish.yml`) and ADR 0161. It ships inert until the owner arms it (repo variable `PUBLISH_ON_MERGE=1` + secrets `NPM_TOKEN`, `RELEASE_PUSH_TOKEN`). A **minor/major bump stays a human in-task edit**. The update subscription ([ADR 0136](../adr/<redacted>.md)) consumes whatever is published, on its next sweep.
+**Publishing is automatic on merge** as of 2026-08-08: the `publish` workflow rides behind the required `unit` check, auto-bumps a patch when nobody bumped, builds through the fail-closed no-leak gate, publishes, and tags — see the workflow header (`.github/workflows/publish.yml`) and ADR 0161. It ships inert until the owner arms it (repo variable `PUBLISH_ON_MERGE=1` + secrets `NPM_TOKEN`, `RELEASE_PUSH_TOKEN`). A **minor/major bump stays a human in-task edit**. The update subscription ([ADR 0136](../adr/0136-update-channel-subscription-policy.md)) consumes whatever is published, on its next sweep.
 
 The steps below remain as the **manual fallback** (lane disarmed, npm outage, or a deliberate out-of-band release):
 
-1. **Bump `CORE_VERSION`** in [`src/module-api.js`](../../src/module-api.js) (semver; a **patch** for a fix, **minor** for additive surface — a **major** is a deliberate, human-only event) and append an entry to the release ledger [`docs/module-api-changelog.md`](../module-api-changelog.md) in the same commit ([ADR 0203](../adr/<redacted>.md) moved that ledger out of `module-api.js`). This bump is a normal claimed task, not a release-tool side effect — the version's provenance stays in the git history + ledger.
+1. **Bump `CORE_VERSION`** in [`src/module-api.js`](../../src/module-api.js) (semver; a **patch** for a fix, **minor** for additive surface — a **major** is a deliberate, human-only event) and append an entry to the release ledger [`docs/module-api-changelog.md`](../module-api-changelog.md) in the same commit ([ADR 0203](../adr/0203-doorway-changelog-out-of-module-api.md) moved that ledger out of `module-api.js`). This bump is a normal claimed task, not a release-tool side effect — the version's provenance stays in the git history + ledger.
 2. **Publish** (owner, from a clean checkout of the released commit):
    ```sh
    node scripts/gds/package-core.js --publish        # DRY-RUN: runs the fail-closed no-leak gate, previews @bongos/core@<version>
@@ -69,7 +69,7 @@ The steps below remain as the **manual fallback** (lane disarmed, npm outage, or
 3. **Tag the release** (optional but recommended — the deliberate, auditable marker): `git tag core-v<version> && git push origin core-v<version>`. The tag documents intent; it triggers no CI.
 4. **Done.** Subscribed instances on the `patch`/`minor` channel take it automatically on their next routine sweep; `pinned` instances wait for a manual `bongos upgrade`. A stale (un-bumped) version is rejected by npm as a duplicate — a natural guard.
 
-> **Automating this** (a tag-triggered CI publish) is deferred to the managed-fleet epic ([#1948](https://example.com/builders#/task/1948)); revisit when the manual step becomes a real bottleneck. See [ADR 0137](../adr/<redacted>.md) "When to revisit".
+> **Automating this** (a tag-triggered CI publish) is deferred to the managed-fleet epic ([#1948](https://example.com/builders#/task/1948)); revisit when the manual step becomes a real bottleneck. See [ADR 0137](../adr/0137-upstream-publish-policy-manual-owner-gated.md) "When to revisit".
 
 ## Install a private package (any consumer machine or instance)
 

package/docs/recipes/search-index-ingestion.md

@@ -10,13 +10,13 @@ How the `search_chunks` index (the recall layer, [ADR 0060](../adr/0060-gds-retr
 
 - **Delta-driven.** Each chunk's `content_hash` (sha256 of its body) is the change key. The upsert's `ON CONFLICT … DO UPDATE … WHERE content_hash IS DISTINCT FROM EXCLUDED.content_hash` makes an unchanged chunk a **no-op** (no row rewrite). A re-run over an unchanged tree writes nothing.
 - **Prunes shrinkage.** If a file loses sections, chunks beyond the new count are deleted; if a file is removed from the tree entirely, all its chunks are deleted (`source_kind='doc' AND source_ref NOT IN (present)`).
-- **Scopes by rank.** Most docs are `min_rank='xenos'` (shared). Read-sensitive documentation surfaces are tagged `min_rank='metic'` so a sub-Metic search can never surface them ([ADR 0060](../adr/0060-gds-retrieval-layer.md) §6 / [ADR 0043](../adr/<redacted>.md)). The metic set is curated in `SENSITIVE_DOC_GLOBS`: `docs/canonical-permissions.md`, `docs/security/`, `docs/audits/`, and the two trust-boundary ADRs (0016, 0043). **`CLAUDE.md` is deliberately `xenos`** — it's write-protected but the universal read-public onboarding index. Docs are never owner-scoped (`owner_builder_id` stays NULL); per-builder private content is the DB-prose ingester's job (memory rows).
+- **Scopes by rank.** Most docs are `min_rank='xenos'` (shared). Read-sensitive documentation surfaces are tagged `min_rank='metic'` so a sub-Metic search can never surface them ([ADR 0060](../adr/0060-gds-retrieval-layer.md) §6 / [ADR 0043](../adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md)). The metic set is curated in `SENSITIVE_DOC_GLOBS`: `docs/canonical-permissions.md`, `docs/security/`, `docs/audits/`, and the two trust-boundary ADRs (0016, 0043). **`CLAUDE.md` is deliberately `xenos`** — it's write-protected but the universal read-public onboarding index. Docs are never owner-scoped (`owner_builder_id` stays NULL); per-builder private content is the DB-prose ingester's job (memory rows).
 
 ## When it runs
 
 A **non-blocking step in the prod deploy** ([`scripts/deploy/deploy-prod.sh`](../../scripts/deploy/deploy-prod.sh), mirrored in the droplet's hand-maintained `~/deploy.sh`), after the code update + migrations + healthz, where the new markdown and the DB are both on disk. It's wrapped `timeout 60 … || echo "…deploy unaffected"` — **an ingest failure never fails a deploy**; the next deploy (or a manual run) catches up.
 
-> ⚠️ `scripts/deploy/deploy-prod.sh` is a **byte-faithful mirror** of the droplet's `~/deploy.sh`, which is **hand-maintained and NOT auto-installed** (the ci deploy key is forced-command-locked — [ADR 0042](../adr/<redacted>.md)/[0043](../adr/<redacted>.md)). When you change the mirror, **re-apply the same edit to `~/deploy.sh` on the droplet by hand** (`ssh lars@REDACTED_IP`), or the deploy hook won't actually run there. (Same caveat as the [prod deploy-script mirror](../../docs/recipes/ops-gotchas.md) note.)
+> ⚠️ `scripts/deploy/deploy-prod.sh` is a **byte-faithful mirror** of the droplet's `~/deploy.sh`, which is **hand-maintained and NOT auto-installed** (the ci deploy key is forced-command-locked — [ADR 0042](../adr/0042-builder-self-deploy-ci-auto-merge.md)/[0043](../adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md)). When you change the mirror, **re-apply the same edit to `~/deploy.sh` on the droplet by hand** (`ssh lars@REDACTED_IP`), or the deploy hook won't actually run there. (Same caveat as the [prod deploy-script mirror](../../docs/recipes/ops-gotchas.md) note.)
 
 ## Operating it
 
@@ -39,7 +39,7 @@ Output reports `inserted / updated / unchanged / pruned / deleted_sources_chunks
 
 `node scripts/gds/search-ingest-db.js` indexes the prose that lives in the DB, not in git, as `source_kind='db'`: task descriptions + value summaries (`task:<id>`), learnings (`learning:<id>`), idea inbox (`idea:<id>`), done-when criteria (`criterion:<id>`), blockers (`blocker:<id>`), session-log notes (`session_log:<id>`), grade notes (`grade:<id>`), per-builder memory (`memory:<builder>:<path>`), and recent git commit subjects (`commit:<sha>`). Same delta-by-content_hash + prune-vanished behavior as the repo-md ingester.
 
-Security ([ADR 0060](../adr/0060-gds-retrieval-layer.md) §6 / [ADR 0016](../adr/<redacted>.md) / [ADR 0022](../adr/0022-secrets-policy.md)):
+Security ([ADR 0060](../adr/0060-gds-retrieval-layer.md) §6 / [ADR 0016](../adr/0016-trust-boundary-server-enforced-permissions.md) / [ADR 0022](../adr/0022-secrets-policy.md)):
 
 - **`builder_memory` is owner-scoped** — each chunk carries `owner_builder_id`, so a builder's private memory only ever surfaces to that builder (the search route's owner filter, [#950](https://example.com/builders#/task/950)).
 - **`security_sensitive` tasks are tagged `min_rank='metic'`**.