@bongos/core 1.19.714 → 1.19.724

package/docs/api/openapi.json

@@ -41,6 +41,10 @@
       "name": "analytics",
       "description": "Endpoints under `/api/bongos/analytics`."
     },
+    {
+      "name": "artist-gate",
+      "description": "Endpoints under `/api/bongos/artist-gate`."
+    },
     {
       "name": "audit-log",
       "description": "Endpoints under `/api/bongos/audit-log`."
@@ -1042,6 +1046,44 @@
         ]
       }
     },
+    "/artist-gate": {
+      "get": {
+        "operationId": "get_artist_gate",
+        "tags": [
+          "artist-gate"
+        ],
+        "summary": "GET /artist-gate",
+        "description": "GET /artist-gate — this project's artist strictness and what it is holding. rank: any authenticated builder. The payload is ordinary board state — a policy value the instance already publishes as its own behaviour, and task ids/titles any builder can read on the hall — so a floor above requireBuilder would gate a fact the board already shows. Nothing here is writable. Response: mode 'off' | 'advisory' | 'strict' the project's setting as resolved since ISO string | null when it was last RAISED to strict holds boolean does anything hold a deploy now? truncated boolean `reviews` hit the scan cap — a floor reviews [{ id, created_at }] the open reviews that count halt { code, message, detail } | null the refusal, pre-composed `halt` is composed HERE rather than by the caller on purpose: ADR 0241 §4's second guard is that the refusal must name what holds the deploy and which control releases it, and a sentence assembled independently by each caller is a sentence that eventually says something different. One composer, one wording.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/artist-gate.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetArtistGateResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/audit-log": {
       "get": {
         "operationId": "get_audit_log",
@@ -11471,7 +11513,7 @@
           "override-requests"
         ],
         "summary": "POST /override-requests/:id/decide",
-        "description": "POST /override-requests/:id/decide — body: { decision: 'approve'|'deny', note? } On approve, atomically flips the task completed→confirmed and awards the credits to the original requester (NOT the Archon). On deny, only the row updates; the task stays at completed and the builder must release or re-ship after fixing whatever the grader caught. rank: archon — grader-bypass authority; same gate as POST /tasks/:id/confirm.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `override_request.decide` (all required).",
+        "description": "POST /override-requests/:id/decide — body: { decision: 'approve'|'deny', note? } On approve, atomically flips the task completed→confirmed and awards the credits to the original requester (NOT the Archon). On deny, only the row updates; the task stays at completed and the builder must release or re-ship after fixing whatever the grader caught. rank: archon — grader-bypass authority; same gate as POST /tasks/:id/confirm. ONE EXCEPTION, and it is NARROWER than this gate rather than wider: a request whose target is an unresolved ARTIST REVIEW is a gate release (ADR 0241 §3, db-overrides.js), and only the PROJECT OWNER may decide it. That check lives in decideOverrideRequest, not here, so it cannot be bypassed by a second caller; this route only renders its refusal (403 override_owner_only). Approving one confirms nothing and pays nothing — it stops the review holding the DEPLOY and leaves it open on the board.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `override_request.decide` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
         "x-permissions": [
@@ -16058,7 +16100,7 @@
           "tasks"
         ],
         "summary": "POST /tasks/:id/override-request",
-        "description": "POST /tasks/:id/override-request — V3.R74 (task 293). The rare path: a builder whose ship failed the subagent grader believes the grader was wrong and asks an Archon to flip the task to confirmed anyway. Audit-logged via the global write-audit middleware. Open requests surface in the Archon queue. rank: any-builder — opens a request; the decision still rests with Archon.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "description": "POST /tasks/:id/override-request — V3.R74 (task 293). The rare path: a builder whose ship failed the subagent grader believes the grader was wrong and asks an Archon to flip the task to confirmed anyway. Audit-logged via the global write-audit middleware. Open requests surface in the Archon queue. rank: any-builder — opens a request; the decision still rests with Archon. The SAME route also opens the artist gate's release (ADR 0241 §3, task 1003575): a request whose target is an unresolved artist review is admitted at ANY status, because such a review sits at `backlog` and a completed-only check would make the one documented escape hatch unusable for the exact case it was written for. Who may DECIDE it is narrower — see the decide route.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
         "x-source": "modules/lifecycle/routes/tasks.js",
         "parameters": [
@@ -17324,6 +17366,31 @@
           "vocabulary"
         ]
       },
+      "GetArtistGateResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "mode": {},
+          "since": {},
+          "holds": {
+            "type": "boolean"
+          },
+          "truncated": {},
+          "reviews": {},
+          "halt": {}
+        },
+        "required": [
+          "ok",
+          "mode",
+          "since",
+          "holds",
+          "truncated",
+          "reviews",
+          "halt"
+        ]
+      },
       "GetAuditLogResponse": {
         "type": "object",
         "properties": {
@@ -23619,9 +23686,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 372,
-  "x-schema-count": 411,
+  "x-endpoint-count": 373,
+  "x-schema-count": 412,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 279,
+  "x-response-schemas": 280,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,10 +2,10 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 372 endpoints across 59 route files.
+> **Generated from the live route files** — the route file is authoritative. 373 endpoints across 60 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
-Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
+Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
 
 ## `access-requests` (5)
 
@@ -48,6 +48,12 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 |---|---|---|---|---|
 | GET | `/api/bongos/analytics/builder/:id` | `any-builder` | — | a builder's historical AI dev curve. |
 
+## `artist-gate` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/artist-gate` | `any-builder` | — | GET /artist-gate — this project's artist strictness and what it is holding. |
+
 ## `audit-log` (1)
 
 | Method | Path | Rank | Body | Description |

package/docs/architecture.md

@@ -11,11 +11,11 @@
 
 - **Domain:** `example.com` — registered at Cloudflare Registrar. DNS A records (apex + `www`) point to the droplet at `REDACTED_IP`. Cloudflare proxy is **ON (orange cloud)**. CF terminates TLS at the edge; the **Cloudflare Origin Certificate** handles the CF↔origin leg (valid through 2041-05-04). A `status` subdomain is added at PMS-V1 deploy time (see [`docs/pms-v1-deploy.md`](pms-v1-deploy.md)) with the same proxy/cert posture; Origin Cert needs `*.example.com` SAN. Real client IPs come in via `CF-Connecting-IP` / `X-Forwarded-For`, wired into Caddy's `trusted_proxies static` (the Cloudflare IP ranges) in the `infra/Caddyfile` global options block.
 - **Production droplet (co-hosting box):** DigitalOcean, hostname `example`, IPv4 `REDACTED_IP`, IPv6 `REDACTED_IP`. NYC3, Premium Intel 2 GB / 1 vCPU / 60 GB NVMe. Ubuntu 24.04 LTS. ~$14/mo. Hosts the OTB game + co-hosted project instances (`emersonian-circles.`, `staging.`).
-- **Cloud Bongos control-plane droplet (NEW 2026-07-05, [ADR 0126](adr/<redacted>.md), task [#2063](https://example.com/builders#/task/2063)):** DigitalOcean, hostname `cloudbongos`, IPv4 `REDACTED_IP`, NYC3, `s-1vcpu-2gb` (2 GB / 1 vCPU), Ubuntu 24.04, ~$12/mo, tag `cloudbongos-control`. Runs **cloudbongos.com + `builders.` + `status.`** (`src/platform-server.js`, Cloud Bongos brand, port 3002, own `cloudbongos` DB, checkout `/home/lars/cloudbongos-instance`, the root subscribed to the nightly core-patch sweep) and is the **sole token-holding control plane** — a SECOND root, `/home/lars/cloudbongos`, survives only to vendor `infra/` (the box cloud-init the core package does not ship, ADR 0150); it is not subscribed, so nothing may resolve core code from it (task 1002738, [ADR 0144](adr/<redacted>.md) follow-up 5) — `/etc/cloudbongos/box.env` holds the account-wide Cloudflare token (IP-locked to this box) + the DigitalOcean token; this is where `provision.js` provisions instance subdomains. **Structurally separate SSH** (own `cloudbongos_ed25519` key). IPv6 egress disabled so the IPv4-locked CF token can't be spuriously rejected. cloudbongos.com was previously a co-tenant on the co-hosting box; that unit was decommissioned at cutover. **Follow-ups:** deploy automation (task [#2064](https://example.com/builders#/task/2064)) + fully stripping cloud tokens off the co-hosting box (task [#2065](https://example.com/builders#/task/2065)).
+- **Cloud Bongos control-plane droplet (NEW 2026-07-05, [ADR 0126](adr/0126-dedicated-cloudbongos-control-plane-droplet.md), task [#2063](https://example.com/builders#/task/2063)):** DigitalOcean, hostname `cloudbongos`, IPv4 `REDACTED_IP`, NYC3, `s-1vcpu-2gb` (2 GB / 1 vCPU), Ubuntu 24.04, ~$12/mo, tag `cloudbongos-control`. Runs **cloudbongos.com + `builders.` + `status.`** (`src/platform-server.js`, Cloud Bongos brand, port 3002, own `cloudbongos` DB, checkout `/home/lars/cloudbongos-instance`, the root subscribed to the nightly core-patch sweep) and is the **sole token-holding control plane** — a SECOND root, `/home/lars/cloudbongos`, survives only to vendor `infra/` (the box cloud-init the core package does not ship, ADR 0150); it is not subscribed, so nothing may resolve core code from it (task 1002738, [ADR 0144](adr/0144-devbox-rehome-onto-cloudbongos-plane.md) follow-up 5) — `/etc/cloudbongos/box.env` holds the account-wide Cloudflare token (IP-locked to this box) + the DigitalOcean token; this is where `provision.js` provisions instance subdomains. **Structurally separate SSH** (own `cloudbongos_ed25519` key). IPv6 egress disabled so the IPv4-locked CF token can't be spuriously rejected. cloudbongos.com was previously a co-tenant on the co-hosting box; that unit was decommissioned at cutover. **Follow-ups:** deploy automation (task [#2064](https://example.com/builders#/task/2064)) + fully stripping cloud tokens off the co-hosting box (task [#2065](https://example.com/builders#/task/2065)).
 - **Server stack:** Node.js 22 LTS · PostgreSQL 16 · Caddy 2.11.2. `example.service` (systemd) runs `node server.js` as user `lars` on `127.0.0.1:3000`; restart-on-failure.
 - **Hardening:** `lars` user with passwordless sudo; SSH key-only (root login disabled, password auth disabled); ufw allows 22/80/443; fail2ban active; unattended-upgrades enabled; timezone `America/New_York`.
-- **TLS:** Origin cert at `/etc/caddy/origin.crt` + `/etc/caddy/origin.key` for the example apexes on the co-hosting box. **cloudbongos.com's apexes moved to the dedicated control-plane droplet** ([ADR 0126](adr/<redacted>.md)) with their own copy of the Cloudflare Origin Cert (SAN `*.cloudbongos.com, cloudbongos.com`) at `/etc/caddy/cloudbongos-origin.{crt,key}` on `REDACTED_IP`. Cloudflare SSL/TLS mode = Full (strict). Renewal is a non-issue for ~15 years. **Provisioned instance hosts use a different, coexisting posture** ([ADR 0111](adr/<redacted>.md) §4 / task P4): Caddy **on-demand ACME** (Let's Encrypt) via the global `on_demand_tls { ask … }` block, gated to hostnames the `provisioning` module actually stood up (`/api/bongos/provisioning/tls-check`). Their DNS records are **proxied=false (grey cloud)** so the ACME challenge reaches Caddy — the opposite of the origin-cert apexes; do not enable the proxy on them or renewal breaks silently ([ADR 0003](adr/<redacted>.md)). Per-instance site snippets live in `/etc/caddy/sites/*.caddy` (`import`ed by `infra/Caddyfile`). **Tradeoff (accepted, SEC review of task 1945):** `proxied=false` publishes the box's real origin IP in public DNS for every co-tenant provisioned hostname — defeating, for those names, the Cloudflare-proxy IP-hiding the apexes enjoy (a co-tenant host resolves to the same `REDACTED_IP` that serves the main game). This is inherent to on-demand ACME (the challenge must hit the origin) and acceptable under the budget/trust model; prefer a **dedicated droplet** (its own IP) for any instance expected to draw hostile attention.
-- **Platform observability (task 2020 stood it up; task 2059 re-homed it cross-project onto the control-plane box; [ADR 0127](adr/<redacted>.md)):** this watches the **Bongos API** (`gds_http`/`tasks`/`claims`/`builders`/`auth`), not any one game, so it lives **on the control-plane box** (REDACTED_IP) at **`https://metrics.cloudbongos.com`** and observes the **whole fleet**. **Prometheus** (`127.0.0.1:9090`, loopback-only) scrapes every instance's `/metrics` ([`src/bongos/metrics.js`](../src/bongos/metrics.js)), each tagged with a `project` label ([`infra/prometheus/prometheus.yml`](../infra/prometheus/prometheus.yml)): **cloudbongos** locally (`:3002`); **example + emersonian-circles** on the co-hosting box, reached over the **private VPC** via `socat` forwarders on `10.108.0.2:9101/9102` (→ their loopback `:3000`/`:3004`), ufw-locked to the control-plane box's private IP — raw TCP relays, so the exporter still sees a loopback request and needs no token; nothing is public. **Grafana** (`127.0.0.1:3003`, loopback-only) renders the 4 provisioned-as-code dashboards (folder **Cloud Bongos**: system-overview, error-watch, builder-activity, auth-security), each with a **`project`** template variable for per-instance / fleet views. Reverse-proxied on the `*.cloudbongos.com` origin cert — Archon-only, gated by Caddy `basic_auth` (user `archon`) **and** Grafana's own admin login (both secrets owner-held, never in the repo). Grafana config is a systemd `GF_*` env drop-in (`grafana-server.service.d/override.conf`, `chmod 600`). ~256 MB RAM. A future dedicated-droplet instance is added as a `METRICS_TOKEN` Bearer target instead of a VPC forwarder.
+- **TLS:** Origin cert at `/etc/caddy/origin.crt` + `/etc/caddy/origin.key` for the example apexes on the co-hosting box. **cloudbongos.com's apexes moved to the dedicated control-plane droplet** ([ADR 0126](adr/0126-dedicated-cloudbongos-control-plane-droplet.md)) with their own copy of the Cloudflare Origin Cert (SAN `*.cloudbongos.com, cloudbongos.com`) at `/etc/caddy/cloudbongos-origin.{crt,key}` on `REDACTED_IP`. Cloudflare SSL/TLS mode = Full (strict). Renewal is a non-issue for ~15 years. **Provisioned instance hosts use a different, coexisting posture** ([ADR 0111](adr/0111-instance-hosting-provisioning-module.md) §4 / task P4): Caddy **on-demand ACME** (Let's Encrypt) via the global `on_demand_tls { ask … }` block, gated to hostnames the `provisioning` module actually stood up (`/api/bongos/provisioning/tls-check`). Their DNS records are **proxied=false (grey cloud)** so the ACME challenge reaches Caddy — the opposite of the origin-cert apexes; do not enable the proxy on them or renewal breaks silently ([ADR 0003](adr/0003-cloudflare-origin-cert-over-letsencrypt.md)). Per-instance site snippets live in `/etc/caddy/sites/*.caddy` (`import`ed by `infra/Caddyfile`). **Tradeoff (accepted, SEC review of task 1945):** `proxied=false` publishes the box's real origin IP in public DNS for every co-tenant provisioned hostname — defeating, for those names, the Cloudflare-proxy IP-hiding the apexes enjoy (a co-tenant host resolves to the same `REDACTED_IP` that serves the main game). This is inherent to on-demand ACME (the challenge must hit the origin) and acceptable under the budget/trust model; prefer a **dedicated droplet** (its own IP) for any instance expected to draw hostile attention.
+- **Platform observability (task 2020 stood it up; task 2059 re-homed it cross-project onto the control-plane box; [ADR 0127](adr/0127-cross-box-fleet-observability.md)):** this watches the **Bongos API** (`gds_http`/`tasks`/`claims`/`builders`/`auth`), not any one game, so it lives **on the control-plane box** (REDACTED_IP) at **`https://metrics.cloudbongos.com`** and observes the **whole fleet**. **Prometheus** (`127.0.0.1:9090`, loopback-only) scrapes every instance's `/metrics` ([`src/bongos/metrics.js`](../src/bongos/metrics.js)), each tagged with a `project` label ([`infra/prometheus/prometheus.yml`](../infra/prometheus/prometheus.yml)): **cloudbongos** locally (`:3002`); **example + emersonian-circles** on the co-hosting box, reached over the **private VPC** via `socat` forwarders on `10.108.0.2:9101/9102` (→ their loopback `:3000`/`:3004`), ufw-locked to the control-plane box's private IP — raw TCP relays, so the exporter still sees a loopback request and needs no token; nothing is public. **Grafana** (`127.0.0.1:3003`, loopback-only) renders the 4 provisioned-as-code dashboards (folder **Cloud Bongos**: system-overview, error-watch, builder-activity, auth-security), each with a **`project`** template variable for per-instance / fleet views. Reverse-proxied on the `*.cloudbongos.com` origin cert — Archon-only, gated by Caddy `basic_auth` (user `archon`) **and** Grafana's own admin login (both secrets owner-held, never in the repo). Grafana config is a systemd `GF_*` env drop-in (`grafana-server.service.d/override.conf`, `chmod 600`). ~256 MB RAM. A future dedicated-droplet instance is added as a `METRICS_TOKEN` Bearer target instead of a VPC forwarder.
 
 **Application stack:**
 
@@ -25,9 +25,9 @@
 - **`pg`** Postgres client over Unix socket (`host: '/var/run/postgresql'`).
 - **Auth (planned, not yet wired):** Email + magic link, tied to a Stripe customer record on first purchase.
 
-**Module system (core + modules, [ADR 0083](adr/<redacted>.md)):**
+**Module system (core + modules, [ADR 0083](adr/0083-modular-architecture-strangler-build-plan.md)):**
 
-The product is organized as a small kernel (`src/`) + **19 modules** under `modules/<key>/` — the four optional *feature* modules **plus** the carved *core-domain* modules. The four-feature carve (Config A) was only the least-coupled ~26% of the tree; the **core decomposition (Config B = BONGOS-V1 C7 `gds-core-modularized`)** is now done too ([ADR 0091](adr/<redacted>.md), [ADR 0093](adr/<redacted>.md)). The full, live roster + contract is at [docs/modules-contract.md](modules-contract.md).
+The product is organized as a small kernel (`src/`) + **19 modules** under `modules/<key>/` — the four optional *feature* modules **plus** the carved *core-domain* modules. The four-feature carve (Config A) was only the least-coupled ~26% of the tree; the **core decomposition (Config B = BONGOS-V1 C7 `gds-core-modularized`)** is now done too ([ADR 0091](adr/0091-bounding-the-kernel-and-db-carve.md), [ADR 0093](adr/0093-tranche-2-core-carve-sequence.md)). The full, live roster + contract is at [docs/modules-contract.md](modules-contract.md).
 
 - **The one-way rule** — a module reaches core only through `src/module-api.js` (the published, semver'd doorway). Core never imports a module. Modules never import each other — they cooperate through `src/module-seams.js` (ports + events). Two CI fitness checks enforce this; a violation is a red build.
 - **The loader** (`src/module-loader/loader.js`) — discovers `modules/*/module.json` at boot, validates manifests, checks `coreVersion` compatibility, and mounts each enabled module's routes behind kernel-composed auth. No core file changes to add or remove a module.
@@ -38,7 +38,7 @@ The product is organized as a small kernel (`src/`) + **19 modules** under `modu
   - `discord` — ship broadcast + inbound bot + role-sync; port: `discord.isLinked`
   - `art-pipeline` — pixel-art generation + artist discipline; port: `art.sharedKeyConfigured`
   - (+ `character-anim`, declaration-only — ADR 0088)
-- **Core-domain modules** (`default: true` — always on unless disabled): `memory`, `grading`, `economy`, `ideas`, `security`, `builder-settings`, `onboarding`, `sessions`, plus `lifecycle` (the task/claim/version state machine), `autonomy` (the MAS), the `hall-ui` + `status-ui` internal surfaces, `public-landing` (the apex front door — [ADR 0218](adr/<redacted>.md)), `ui-design` (the design contract, its adapters and the `/design` playbook as a platform capability — [ADR 0197](adr/<redacted>.md)), and the `demo` acceptance-proof module. See [docs/modules-contract.md](modules-contract.md) for the live roster and which default on.
+- **Core-domain modules** (`default: true` — always on unless disabled): `memory`, `grading`, `economy`, `ideas`, `security`, `builder-settings`, `onboarding`, `sessions`, plus `lifecycle` (the task/claim/version state machine), `autonomy` (the MAS), the `hall-ui` + `status-ui` internal surfaces, `public-landing` (the apex front door — [ADR 0218](adr/0218-the-apex-root-web-surface.md)), `ui-design` (the design contract, its adapters and the `/design` playbook as a platform capability — [ADR 0197](adr/0197-the-ui-design-module.md)), and the `demo` acceptance-proof module. See [docs/modules-contract.md](modules-contract.md) for the live roster and which default on.
 - **Module-owned migrations** — `modules/<key>/migrations/*.sql` applied only when the module is enabled. Stem-keyed so moving a migration never re-runs it.
 - **`bongos module new <key>`** — scaffolds a new module directory in one command.
 - **`bongos upgrade`** — the update-consumption channel a two-repo consumer uses to pull the core from version N→N+1 (task 1690, ADR 0100 §2 / ADR 0103 §4): pre-flight (module-compat + clean tree) → bump the vendored-tarball pin → `npm install` → `npm run migrate` (additive `core_*` migrations) → re-materialize `.claude/` → restart → verify. Run bare (no `--to`) it is still just the module-compat pre-check that exits 1 on mismatch; `--to <version>` runs the real bump. (`scripts/gds/upgrade.js`.)
@@ -49,7 +49,7 @@ The product is organized as a small kernel (`src/`) + **19 modules** under `modu
 - **Sibling `QueueRoom`** — unbounded, FIFO, admits via shared in-process seat bus (`src/seats.js`). Browser-close releases seat automatically (Colyseus `onLeave`).
 - **Move protocol:** client sends `{ dir }` per step. Server validates direction, applies position unless target tile is blocked or out of bounds, always commits facing.
 - **Movement is client-predicted, server-authoritative.** Both sides run identical walkability rules. Walkability lives in `BLOCKING_TERRAINS` (ground impassable — sea) and `BLOCKING_OBJECTS` (object impassable — rocks, container panels) in the shared `terrain.js` module (CJS twin at `src/world/terrain.js`, ESM twin at `public/game/world/terrain.js`); the hardcoded V1 map lives in `src/world/map.js` (server) and `public/game/world/map.js` (client) — **the two map.js + the two terrain.js files must stay in sync** until the world becomes data-driven.
-- **Cell data model ([ADR 0012](adr/<redacted>.md), extends [ADR 0011](adr/0011-terrain-id-rendering-model.md)):** each cell carries TWO independent pieces:
+- **Cell data model ([ADR 0012](adr/0012-ground-object-cell-split.md), extends [ADR 0011](adr/0011-terrain-id-rendering-model.md)):** each cell carries TWO independent pieces:
   - **Ground terrain** (always defined) — `GRASS`, `SAND`, `SEA`, `MARBLE_PATH`. Drives the autotile renderer. `INITIAL_MAP.ground[y][x]`.
   - **Object** (optional, sparse) — `ROCK` or one of the 8 `CONTAINER_PANEL_*` (V1). Painted in a second draw pass at depth 1. `INITIAL_MAP.objects[y][x]` (null in most cells).
   The autotile picker sees the ground grid only; objects never affect tile selection. That is the invariant that lets rocks scatter through a meadow without polluting boundary tiles, and lets the container sit cleanly on sand.
@@ -65,11 +65,11 @@ The product is organized as a small kernel (`src/`) + **19 modules** under `modu
 **Code & deploy:**
 
 - **Code repo:** [github.com/example-owner/example](https://github.com/example-owner/example) — **private**. Clone URL: `git@github.com:example-owner/example.git`. Default branch: `main`. GitHub user: `example-owner`.
-- **Deploy:** two modes, selected by `config/deploy.json` `mode` (env `OTB_DEPLOY_MODE` overrides), currently **`ci`** (flipped from `laptop` 2026-06-13, [#859](https://example.com/builders#/task/859)) — see [ADR 0042](adr/<redacted>.md). **`laptop`** (legacy): `git push origin main` from the Mac → `ssh lars@REDACTED_IP ~/deploy.sh`. The droplet has a read-only deploy key at `~/.ssh/github_deploy` registered on the repo. `~/deploy.sh` does: `git fetch + reset --hard origin/main` → `npm ci --omit=dev` if `package-lock.json` changed → `./scripts/migrate.sh` → `sudo systemctl restart example` → `curl /healthz` smoke (**retried up to 15× @ 1s** — `systemctl` reports "active" before the Node process binds the port, so a single curl raced the bind and false-failed healthy deploys: [ADR 0056](adr/<redacted>.md) / [#1026](https://example.com/builders#/task/1026)). Droplet checkout: `/home/lars/example/`. `~/deploy.sh` is hand-maintained on the droplet but now has a byte-faithful, reviewable repo mirror at [`scripts/deploy/deploy-prod.sh`](../scripts/deploy/deploy-prod.sh) — **not** auto-installed (the ci deploy key is forced-command-locked, ADR 0042/0043; reinstall by hand on change: `scp scripts/deploy/deploy-prod.sh lars@…:deploy.sh`). **`ci`** (current, armed via [#679](https://example.com/builders#/task/679)): no builder box holds the droplet key — `ship.js` opens a PR + enables GitHub auto-merge, and [`.github/workflows/deploy-prod.yml`](../.github/workflows/deploy-prod.yml) runs the same `~/deploy.sh` from Actions on merge to `main`. Cutover preconditions (incl. a server-recorded **CI grade-gate**) are in ADR 0042.
+- **Deploy:** two modes, selected by `config/deploy.json` `mode` (env `OTB_DEPLOY_MODE` overrides), currently **`ci`** (flipped from `laptop` 2026-06-13, [#859](https://example.com/builders#/task/859)) — see [ADR 0042](adr/0042-builder-self-deploy-ci-auto-merge.md). **`laptop`** (legacy): `git push origin main` from the Mac → `ssh lars@REDACTED_IP ~/deploy.sh`. The droplet has a read-only deploy key at `~/.ssh/github_deploy` registered on the repo. `~/deploy.sh` does: `git fetch + reset --hard origin/main` → `npm ci --omit=dev` if `package-lock.json` changed → `./scripts/migrate.sh` → `sudo systemctl restart example` → `curl /healthz` smoke (**retried up to 15× @ 1s** — `systemctl` reports "active" before the Node process binds the port, so a single curl raced the bind and false-failed healthy deploys: [ADR 0056](adr/0056-prod-deploy-script-mirror-and-healthcheck-retry.md) / [#1026](https://example.com/builders#/task/1026)). Droplet checkout: `/home/lars/example/`. `~/deploy.sh` is hand-maintained on the droplet but now has a byte-faithful, reviewable repo mirror at [`scripts/deploy/deploy-prod.sh`](../scripts/deploy/deploy-prod.sh) — **not** auto-installed (the ci deploy key is forced-command-locked, ADR 0042/0043; reinstall by hand on change: `scp scripts/deploy/deploy-prod.sh lars@…:deploy.sh`). **`ci`** (current, armed via [#679](https://example.com/builders#/task/679)): no builder box holds the droplet key — `ship.js` opens a PR + enables GitHub auto-merge, and [`.github/workflows/deploy-prod.yml`](../.github/workflows/deploy-prod.yml) runs the same `~/deploy.sh` from Actions on merge to `main`. Cutover preconditions (incl. a server-recorded **CI grade-gate**) are in ADR 0042.
 - **Post-merge branch cleanup (standard practice):** Every feature branch that lands on main via `--no-ff` merge gets deleted on origin once the deploy succeeds. The merge commit itself preserves the branch's history in main, so the named ref isn't carrying any signal — keeping it just clutters GitHub's branch list and tricks the UI into offering empty PRs against zero-diff branches. The auto-merge in [`scripts/gds/ship.js`](../scripts/gds/ship.js) does this automatically after `~/deploy.sh` returns 0; the manual [`/merge-mode`](../.claude/skills/merge-mode/SKILL.md) flow follows the same step 5b. Local refs and worktree directories stay — only the origin branch and the local tracking ref (cleaned on next `git fetch --prune`) go.
 - **Local dev machine:** Lars's MacBook Air (Apple Silicon, macOS Sequoia). Tooling installed via Homebrew at `/opt/homebrew/`. Node v26.0.0 locally; `package.json` declares `"engines": { "node": ">=22" }`. Single ed25519 SSH key (`~/.ssh/id_ed25519`) authenticates to GitHub and droplet.
 - **Smoke tests:** lightweight scripts in `/tmp/colyseus-*-smoketest.js` verify joinOrCreate, move protocol, interact, identity, queue. Run any after deploy with `node /tmp/colyseus-<name>-smoketest.js`.
-- **Repo topology today vs. the configurable-root future ([ADR 0108](adr/<redacted>.md)):** everything above describes the current **single checkout** — `git reset --hard` deploy, `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../src/instance-config.js)) both resolving to this same repo root. ADR 0108 lands (Mercury-first, then Example last) a model where Example instead installs a versioned `@bongos/core` npm package and deploy becomes `git pull` (the instance repo) → `npm ci` (the pinned core) → migrate → restart — no more `git reset --hard` on a shared checkout. This section gets rewritten for the new topology once Example actually splits (ADR 0108 §6, task 1884/W4); until then it is unchanged and accurate.
+- **Repo topology today vs. the configurable-root future ([ADR 0108](adr/0108-instance-composition-configurable-root.md)):** everything above describes the current **single checkout** — `git reset --hard` deploy, `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../src/instance-config.js)) both resolving to this same repo root. ADR 0108 lands (Mercury-first, then Example last) a model where Example instead installs a versioned `@bongos/core` npm package and deploy becomes `git pull` (the instance repo) → `npm ci` (the pinned core) → migrate → restart — no more `git reset --hard` on a shared checkout. This section gets rewritten for the new topology once Example actually splits (ADR 0108 §6, task 1884/W4); until then it is unchanged and accurate.
 
 **Database (`example` on Postgres 16, peer auth as `lars`):**
 
@@ -218,23 +218,23 @@ Bongos views: `claimable_tasks` (rebuilt in 006 to use SELECT t.*; rebuilt again
 **Bongos API (`/api/gds/*`, mounted in the same Node process):**
 
 - **Canonical path is `/api/bongos` (task 1919); `/api/gds` is a PERMANENT alias.** The router + the discovery index are dual-mounted at both by `serve-internal.js`, driven by the single `src/bongos/api-prefix.js` constant (`API_PREFIX` + `LEGACY_API_PREFIXES`). The legacy `/api/gds` alias never goes away — shipped Dev Box binaries, the cached status mirror, and live boxes call it. **Exception:** the GitHub OAuth callback stays pinned to `/api/gds/auth/web/callback` (registered on the OAuth app; `src/bongos/routes/auth.js`). Not yet flipped (still ride the permanent alias): `src/**` internal callers + the deeper internal names (folders, `GDS_*` env, `gds_session` cookie) — the deferred internal-rename pass.
-- **Self-describing (task 1918, [ADR 0109](adr/<redacted>.md)).** The whole surface is documented in the standard **OpenAPI 3.1** format at [`docs/api/openapi.json`](api/openapi.json), **generated from the live route files** by `scripts/gds/gen-api-docs.js` (reusing the same `route-rank-check.js` introspection the ship-time rank gate uses — so it can't drift; a fitness `--check` + ship-time regen enforce freshness). A rendered docs site (vendored Redoc) is served at **`/docs`** on the apex of every instance (`cloudbongos.com/docs` canonical); `GET /api/gds` returns a machine-discovery index pointing at it. The generated [`docs/api-reference.md`](api-reference.md) supersedes the old hand-maintained `routes-permissions.md`. The mount prefix is the single `src/bongos/api-prefix.js` constant.
+- **Self-describing (task 1918, [ADR 0109](adr/0109-self-describing-openapi-and-hosted-docs.md)).** The whole surface is documented in the standard **OpenAPI 3.1** format at [`docs/api/openapi.json`](api/openapi.json), **generated from the live route files** by `scripts/gds/gen-api-docs.js` (reusing the same `route-rank-check.js` introspection the ship-time rank gate uses — so it can't drift; a fitness `--check` + ship-time regen enforce freshness). A rendered docs site (vendored Redoc) is served at **`/docs`** on the apex of every instance (`cloudbongos.com/docs` canonical); `GET /api/gds` returns a machine-discovery index pointing at it. The generated [`docs/api-reference.md`](api-reference.md) supersedes the old hand-maintained `routes-permissions.md`. The mount prefix is the single `src/bongos/api-prefix.js` constant.
 
-- Auth: `POST /auth/device/start`, `/poll` (CLI Device Flow); `GET /auth/web/start`, `/web/callback` (browser); `POST /auth/logout`; app pairing for the Dev Box desktop app ([#904](https://example.com/builders#/task/904), [ADR 0045](adr/<redacted>.md), store [`src/bongos/app-pair.js`](../src/bongos/app-pair.js) — in-memory, 10-min TTL): `POST /auth/app-pair/start` + `/poll` (public; the secret poll_token is the bearer and the minted token is delivered to it exactly once), `GET /auth/app-pair/info` + `POST /auth/app-pair/approve` (any-builder; approve is **cookie-gated** like `/auth/cli-token/issue` so a leaked bearer can't mint siblings; approving from `/builders/pair?code=…` signs the app in as the approver, `source='cli'`).
-- Own-scoped session self-service ([ADR 0206](adr/<redacted>.md), task 1003341), in [`src/bongos/routes/my-sessions.js`](../src/bongos/routes/my-sessions.js): `GET /me/sessions` (every live session on the caller's own account — source, user agent, created/last-used/expires, a `current` flag; the token value is never selected), `POST /me/sessions/revoke` (`{session_id}` — one of your own; a miss answers `revoked: 0` so a stranger's id cannot be probed) and `POST /me/sessions/revoke-all` (sign out everywhere, the requesting session included). All three gate on `requireBuilder` alone and key every statement on `req.builder.id` — an account is never named in the query, body or path. They exist because a bearer refreshes to `now()+24h` on every call, so a leaked one never expires, and the cross-builder pair (`POST /auth/revoke`, `/auth/revoke-all`, both still gated on the admin `auth.session.revoke` atom) needed an Archon the victim might not have. Surfaced in the hall at Settings → Active sessions.
-- Authenticated CLI/web: `GET /me` (returns `rank`), `GET /versions[/progress]`, `GET /tasks[?version=&status=&kind=&discipline=]`, `GET /tasks/claimable[?version=&discipline=]`, `GET /tasks/:id`, `POST /tasks` (accepts `discipline` + `criterion_ids`; **metic+** — [ADR 0090](adr/<redacted>.md)), `PATCH /tasks/:id` (supports `parent_task_id`, `kind`, `discipline`, `goal_id` — (re)assign the task's goal; must be a goal in the task's own version, task 1763; **metic+**), `POST /tasks/:id/promote` (**metic+**), `POST /claims`, `POST /claims/:id/resolve`, `POST /cost`.
-- Criterion rollup + task↔criterion links ([ADR 0025](adr/<redacted>.md), [#435](https://example.com/builders#/task/435)/[#438](https://example.com/builders#/task/438)): `GET /versions/:id/progress` rolls up each done-when criterion → its gating tasks (via `task_criteria`) → live status counts + the not-yet-shipped `remaining[]` + `unattributed_tasks` (the read behind the `/status` skill, in `src/bongos/done-when.js criterionProgress`). The link CRUD mirrors the dependency endpoints: `GET /tasks/:id/criteria`, `POST /tasks/:id/criteria` (**metic+** — [ADR 0090](adr/<redacted>.md)) and `DELETE /tasks/:id/criteria/:criterionId` (**metic+**). A criterion ref is a numeric `done_when_criteria.id`, a positional `"Cn"` token, or a `criterion_id` slug, resolved against the task's version (`POST /tasks` links at create time so `/status` counts the task with no backfill).
-- Server-mediated branch publish (ADR 0055 / [#1025](https://example.com/builders#/task/1025) — lets a dev box with no GitHub push credential ship). Owner-gated like ship: `POST /tasks/:id/publish-branch` (`requireBuilder` + `gateTaskOwnership`, **NOT** `allowBoxScope` → a box-scoped session is `403 box_scope`, so the builder must `/builder-reauth` first; own 32 MB json parser for the base64 thin-bundle body, 20 MB decoded cap; the server pushes the branch + opens the PR + auto-merges with a server-side push credential — a **GitHub App** installation token (short-lived, repo-scoped; preferred, [ADR 0055](adr/<redacted>.md) update / task 1028) or the `GITHUB_PUSH_TOKEN` PAT fallback; `503 push_unconfigured` when neither is set; `400 tip_mismatch` if the bundle tip ≠ the claimed `head_sha`) and `GET /tasks/:id/publish-status?branch=…` (polls PR + deploy-prod state derived live from GitHub). `ship.js` uses these in `ci` mode only when `pushVia()` resolves to server (a box, or `OTB_PUSH_VIA_SERVER=1`); a laptop with `gh` keeps the local push path unchanged. Implementation in `src/bongos/github-push.js`.
+- Auth: `POST /auth/device/start`, `/poll` (CLI Device Flow); `GET /auth/web/start`, `/web/callback` (browser); `POST /auth/logout`; app pairing for the Dev Box desktop app ([#904](https://example.com/builders#/task/904), [ADR 0045](adr/0045-devbox-desktop-app.md), store [`src/bongos/app-pair.js`](../src/bongos/app-pair.js) — in-memory, 10-min TTL): `POST /auth/app-pair/start` + `/poll` (public; the secret poll_token is the bearer and the minted token is delivered to it exactly once), `GET /auth/app-pair/info` + `POST /auth/app-pair/approve` (any-builder; approve is **cookie-gated** like `/auth/cli-token/issue` so a leaked bearer can't mint siblings; approving from `/builders/pair?code=…` signs the app in as the approver, `source='cli'`).
+- Own-scoped session self-service ([ADR 0206](adr/0206-own-scoped-session-revocation-no-absolute-ceiling.md), task 1003341), in [`src/bongos/routes/my-sessions.js`](../src/bongos/routes/my-sessions.js): `GET /me/sessions` (every live session on the caller's own account — source, user agent, created/last-used/expires, a `current` flag; the token value is never selected), `POST /me/sessions/revoke` (`{session_id}` — one of your own; a miss answers `revoked: 0` so a stranger's id cannot be probed) and `POST /me/sessions/revoke-all` (sign out everywhere, the requesting session included). All three gate on `requireBuilder` alone and key every statement on `req.builder.id` — an account is never named in the query, body or path. They exist because a bearer refreshes to `now()+24h` on every call, so a leaked one never expires, and the cross-builder pair (`POST /auth/revoke`, `/auth/revoke-all`, both still gated on the admin `auth.session.revoke` atom) needed an Archon the victim might not have. Surfaced in the hall at Settings → Active sessions.
+- Authenticated CLI/web: `GET /me` (returns `rank`), `GET /versions[/progress]`, `GET /tasks[?version=&status=&kind=&discipline=]`, `GET /tasks/claimable[?version=&discipline=]`, `GET /tasks/:id`, `POST /tasks` (accepts `discipline` + `criterion_ids`; **metic+** — [ADR 0090](adr/0090-metic-task-authoring.md)), `PATCH /tasks/:id` (supports `parent_task_id`, `kind`, `discipline`, `goal_id` — (re)assign the task's goal; must be a goal in the task's own version, task 1763; **metic+**), `POST /tasks/:id/promote` (**metic+**), `POST /claims`, `POST /claims/:id/resolve`, `POST /cost`.
+- Criterion rollup + task↔criterion links ([ADR 0025](adr/0025-structured-criterion-task-link.md), [#435](https://example.com/builders#/task/435)/[#438](https://example.com/builders#/task/438)): `GET /versions/:id/progress` rolls up each done-when criterion → its gating tasks (via `task_criteria`) → live status counts + the not-yet-shipped `remaining[]` + `unattributed_tasks` (the read behind the `/status` skill, in `src/bongos/done-when.js criterionProgress`). The link CRUD mirrors the dependency endpoints: `GET /tasks/:id/criteria`, `POST /tasks/:id/criteria` (**metic+** — [ADR 0090](adr/0090-metic-task-authoring.md)) and `DELETE /tasks/:id/criteria/:criterionId` (**metic+**). A criterion ref is a numeric `done_when_criteria.id`, a positional `"Cn"` token, or a `criterion_id` slug, resolved against the task's version (`POST /tasks` links at create time so `/status` counts the task with no backfill).
+- Server-mediated branch publish (ADR 0055 / [#1025](https://example.com/builders#/task/1025) — lets a dev box with no GitHub push credential ship). Owner-gated like ship: `POST /tasks/:id/publish-branch` (`requireBuilder` + `gateTaskOwnership`, **NOT** `allowBoxScope` → a box-scoped session is `403 box_scope`, so the builder must `/builder-reauth` first; own 32 MB json parser for the base64 thin-bundle body, 20 MB decoded cap; the server pushes the branch + opens the PR + auto-merges with a server-side push credential — a **GitHub App** installation token (short-lived, repo-scoped; preferred, [ADR 0055](adr/0055-server-mediated-branch-publish.md) update / task 1028) or the `GITHUB_PUSH_TOKEN` PAT fallback; `503 push_unconfigured` when neither is set; `400 tip_mismatch` if the bundle tip ≠ the claimed `head_sha`) and `GET /tasks/:id/publish-status?branch=…` (polls PR + deploy-prod state derived live from GitHub). `ship.js` uses these in `ci` mode only when `pushVia()` resolves to server (a box, or `OTB_PUSH_VIA_SERVER=1`); a laptop with `gh` keeps the local push path unchanged. Implementation in `src/bongos/github-push.js`.
 - Archon monitoring reads backing the `/watch` page (ADR 0036): `GET /builders/roster`, `GET /grades/by-builder[?days=N]` (**archon-only**, [#726](https://example.com/builders#/task/726) — per-builder grade breakdown for the MARKS section; the project-wide aggregate stays public at `/public/grades`), `GET /audit-log`, `GET /override-requests`, `GET /access-requests`, `GET /security/reports`. Personal-prefs writes backing `/settings`: `GET/PATCH /me/skill-prefs`, `PATCH /me/disciplines`.
-- Per-builder "needs" + own Gemini key ([ADR 0073](adr/<redacted>.md), [#1013](https://example.com/builders#/task/1013)): `GET /me` now also carries `needs` ({items, action_needed_count} — the consistent "the system needs an input from you" signal; `modules/builder-settings/builder-needs.js` is the SSOT — carved out in BV1.R80, resolved by `GET /me` via the `builder-settings` kernel port — rendered by the hall Standing card + the CLI `printNeedsNudge`). The own-key (pragmatic BYOK) endpoints, all own-scoped: `GET /me/art-key/own` (masked meta — last4 only), `PUT /me/art-key/own` (validate-on-save via a Google list-models call → encrypt with `src/bongos/secret-box.js` → store; `503 storage_not_configured` until `BUILDER_SECRET_KEY` is set, `422 invalid_key` on a bad key), `DELETE /me/art-key/own`. The existing `GET /me/art-key` (shared-key box-sync delivery) is extended to also deliver the decrypted own key, which `scripts/gds/fetch-art-key.js` syncs into the local `gemini_api_key` slot (own key wins in the `gen_api.py` cascade).
+- Per-builder "needs" + own Gemini key ([ADR 0073](adr/0073-builder-needs-signal-and-byok-gemini-key.md), [#1013](https://example.com/builders#/task/1013)): `GET /me` now also carries `needs` ({items, action_needed_count} — the consistent "the system needs an input from you" signal; `modules/builder-settings/builder-needs.js` is the SSOT — carved out in BV1.R80, resolved by `GET /me` via the `builder-settings` kernel port — rendered by the hall Standing card + the CLI `printNeedsNudge`). The own-key (pragmatic BYOK) endpoints, all own-scoped: `GET /me/art-key/own` (masked meta — last4 only), `PUT /me/art-key/own` (validate-on-save via a Google list-models call → encrypt with `src/bongos/secret-box.js` → store; `503 storage_not_configured` until `BUILDER_SECRET_KEY` is set, `422 invalid_key` on a bad key), `DELETE /me/art-key/own`. The existing `GET /me/art-key` (shared-key box-sync delivery) is extended to also deliver the decrypted own key, which `scripts/gds/fetch-art-key.js` syncs into the local `gemini_api_key` slot (own key wins in the `gen_api.py` cascade).
 - Builder memory (ADR 0024 cloneable memory + ADR 0026 BFG). Self-scoped (owner is always `req.builder.id`, never input): `POST /memory/sync` (push own memory; own 64 MB parser, vs the global 64 KB), `GET /memory/files`, `GET /memory/file`, `DELETE /memory/file` (the BFG delete affordance, 6C.2). Cross-builder (input-owner) endpoints — all privileged + audit-logged fail-closed: `GET /memory/builders/:id/files`+`/file` (**archon forensic** read), `GET /memory/bfg/builders/:id/files`+`/file` (**BFG-principal only**, 6B.1 read), and the one cross-builder WRITE `POST /memory/builders/:id/bfg-write` (**BFG-principal only**, kill-switched `BFG_WRITE_ENABLED` default-OFF, namespaced `bfg/`, attributed `author: BFG`, write+audit in one tx — dreams + transparent corrections, 6C.1/6C.2).
 - Session corpus (BFG evaluator — 6D, ADR 0027): `POST /sessions` (upload own session digest; own **4 MB** json parser — capped, vs the global 64 KB — and the digest is per-turn metadata + short scrubbed snippets, never raw transcript content), `GET /sessions/mine` (self-serve), `GET /sessions/search` (cross-builder, **archon-gated** — the BFG-principal stand-in; the principal now exists (6C.1) and the *memory* cross-reads moved to it (6B.1), but these *session* reads still use the archon stand-in pending a retrofit, + audit_log row per read), `GET /sessions/:id` (own self-serve; cross-builder needs archon + audit; non-owner → 404).
 - Public (no auth, `Cache-Control: max-age=60`): `/public/versions`, `/public/progress`, `/public/cost-summary`, `/public/recent-shipped`, `/public/leaderboard`, `/public/grades[?days=N]`, `/public/tasks/:id` ([#604](https://example.com/builders#/task/604) — single-task resolver for `#NNN` doc deep-links; `title`/`value_summary`/`visual_url` returned **only** for `shipped`|`confirmed` work and withheld for in-flight tasks so unshipped/security task names can't leak; the status dashboard renders it at `#/task/:id`), `/public/ref-ids` ([#653](https://example.com/builders#/task/653) — `{tasks:[ids]}`, ids only, token-free; the doc-ref linkifier + its CI gate consult it to decide which bare `#NNN` are real task refs). These power `status.example.com`.
-- Live updates (Server-Sent Events — [#569](https://example.com/builders#/task/569), [ADR 0030](adr/<redacted>.md) signal layer, [ADR 0069](adr/<redacted>.md) transport): an SSE stream at `GET /api/gds/live` ([`src/bongos/routes/live.js`](../src/bongos/routes/live.js)), mounted in both entrypoints (`server.js` + `src/platform-server.js`) so the hall stays live on a game-less boot. This **superseded** the original broadcast-only Colyseus `builders_hall` room (R55 / task 1194 — the room and `src/rooms/BuildersHallRoom.js` were deleted because a Bongos-only instance has no Colyseus in the process). The change-signal layer is **unchanged**: a statement-level Postgres `NOTIFY` trigger (migration 066) on `tasks`/`claims`/`builders`/`builder_onboarding_state`/`credit_log`/`karma_log` fires a `gds_live` notification on every write (incl. direct `psql`); one persistent `LISTEN` connection ([`src/bongos/live-channel.js`](../src/bongos/live-channel.js)) relays each notification, and the SSE endpoint emits an **opaque empty nudge** to open hall tabs (the `{table, op}` is kept server-side so internal table names can't leak); the hall re-runs its `loadAll()` (debounced) on any nudge. No row data crosses the channel — access control stays on the per-panel re-fetches.
+- Live updates (Server-Sent Events — [#569](https://example.com/builders#/task/569), [ADR 0030](adr/0030-builders-hall-live-updates.md) signal layer, [ADR 0069](adr/0069-hall-live-channel-sse-decouple.md) transport): an SSE stream at `GET /api/gds/live` ([`src/bongos/routes/live.js`](../src/bongos/routes/live.js)), mounted in both entrypoints (`server.js` + `src/platform-server.js`) so the hall stays live on a game-less boot. This **superseded** the original broadcast-only Colyseus `builders_hall` room (R55 / task 1194 — the room and `src/rooms/BuildersHallRoom.js` were deleted because a Bongos-only instance has no Colyseus in the process). The change-signal layer is **unchanged**: a statement-level Postgres `NOTIFY` trigger (migration 066) on `tasks`/`claims`/`builders`/`builder_onboarding_state`/`credit_log`/`karma_log` fires a `gds_live` notification on every write (incl. direct `psql`); one persistent `LISTEN` connection ([`src/bongos/live-channel.js`](../src/bongos/live-channel.js)) relays each notification, and the SSE endpoint emits an **opaque empty nudge** to open hall tabs (the `{table, op}` is kept server-side so internal table names can't leak); the hall re-runs its `loadAll()` (debounced) on any nudge. No row data crosses the channel — access control stays on the per-panel re-fetches.
 
 **Builder ranks & the trust boundary:** moved to its own canonical reference —
 [`docs/canonical-permissions.md`](canonical-permissions.md) (rank ladder, live ranks, what's gated,
-failure modes) and [ADR 0016](adr/<redacted>.md) (the decision).
+failure modes) and [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md) (the decision).
 **Authority lives in `builders.rank` on the prod DB, checked server-side per request with no caching;
 markdown describes, the DB enforces.**
 
@@ -242,11 +242,11 @@ markdown describes, the DB enforces.**
 
 **Multi-host setup (same Node process), routed by `Host` header in [`src/bongos/serve-internal.js`](../src/bongos/serve-internal.js), shared by both entrypoints:**
 
-- **the apex root itself** — the public front door (`/`, `/projects`, `/create`, `/privacy`, `/terms`, `/contact`). **Carved to the `public-landing` module in task 1003322** ([ADR 0218](adr/<redacted>.md)): the surface moved from repo-root `public-landing/` to `modules/public-landing/public/` and is a loader-discovered web-surface module — the THIRD, and the first that is not a subdomain. Where `hall-ui`/`status-ui` declare a Host PREFIX, this one declares `{ apexRoot: true, dir }`, because the apex is whatever host is left once the subdomains are taken (`isApexHost` = `!isStatusHost && !isBuildersHost`); `host: ""` is rejected, since `host.startsWith("")` is true for every host and would swallow the other two surfaces. Like the hall it keeps its **dedicated** serving block — in `src/platform-server.js`, now resolving its root through `moduleWebSurfaces()` by the `apexRoot` predicate rather than a hardcoded path — so the apex-only sentinel strip, the brand-token stamp and the `?v=` content stamp are unchanged. Disable the module and the front door vanishes: every route falls through to the game-less 404 tail. Served bytes are identical across the carve apart from the module's own `window.__MODULES__` entry.
+- **the apex root itself** — the public front door (`/`, `/projects`, `/create`, `/privacy`, `/terms`, `/contact`). **Carved to the `public-landing` module in task 1003322** ([ADR 0218](adr/0218-the-apex-root-web-surface.md)): the surface moved from repo-root `public-landing/` to `modules/public-landing/public/` and is a loader-discovered web-surface module — the THIRD, and the first that is not a subdomain. Where `hall-ui`/`status-ui` declare a Host PREFIX, this one declares `{ apexRoot: true, dir }`, because the apex is whatever host is left once the subdomains are taken (`isApexHost` = `!isStatusHost && !isBuildersHost`); `host: ""` is rejected, since `host.startsWith("")` is true for every host and would swallow the other two surfaces. Like the hall it keeps its **dedicated** serving block — in `src/platform-server.js`, now resolving its root through `moduleWebSurfaces()` by the `apexRoot` predicate rather than a hardcoded path — so the apex-only sentinel strip, the brand-token stamp and the `?v=` content stamp are unchanged. Disable the module and the front door vanishes: every route falls through to the game-less 404 tail. Served bytes are identical across the carve apart from the module's own `window.__MODULES__` entry.
 - **`example.com`** — game (Phaser + Colyseus). Static files from `public/`. `/builders` + `/builders/*` now **301-redirect to `builders.example.com/<rest>`** ([#739](https://example.com/builders#/task/739) then promoted to permanent 301 in [#741](https://example.com/builders#/task/741), ADR 0036 cutover); the apex no longer serves the builder surface directly.
-- **`status.example.com`** — public build dashboard. **Carved to the `status-ui` module in BV1.R84** ([ADR 0093](adr/<redacted>.md) §1): the surface moved from `public-status/` to `modules/status-ui/public/`, now served by the loader's web-surface seam (`moduleWebSurfaces` → `serve-internal.js`, routed on the `status.` Host prefix the manifest declares) instead of a hardcoded block — no behavior change. Layout reorganized in [#726](https://example.com/builders#/task/726) (ADR 0036): Pulse / Watch(uptime) / Architects / Works / Treasury / Lately Inscribed / The World — the grade-aggregate, estimation-drift, and repo-health tablets moved to the Archon `/watch` page. **⚠ Served OFF the droplet** (ADR 0029, outage resilience): the live page is **GitHub Pages from the separate repo `example-owner/example-status`** (CNAME → Fastly), reading data cross-origin from the droplet's `/api/gds/public/*` (CORS open) and an availability banner from the prober's `status-data` branch. The droplet still serves `modules/status-ui/public/` (on the `status.` host) as a same-origin fallback, but **DNS points at Pages, not the droplet** — so a droplet deploy does NOT update the live page. Changes to the surface publish to the mirror via `scripts/status-mirror-sync.js` (re-pointed at `modules/status-ui/public/`; status.js/style.css/cursors are byte-identical copies; index.html gets the off-box bits injected), run automatically by `.github/workflows/sync-status-mirror.yml` (needs the `STATUS_MIRROR_TOKEN` secret) ([#737](https://example.com/builders#/task/737)). **⚠ FOLLOW-UP (R84):** that workflow's path trigger still watches `public-status/**` and must be re-pointed at `modules/status-ui/public/**` by an owner/Archon — the GitHub App can't push `.github/workflows/*` (learning 107), so until then the mirror sync won't auto-fire on future status edits.
-- **`builders.example.com`** — dedicated builder surface (`isBuildersHost`, ADR 0036). **Carved to the `hall-ui` module in BV1.R85** ([ADR 0093](adr/<redacted>.md) §1): the surface moved from `public-builders/` to `modules/hall-ui/public/` (~13k LOC, the largest module) and is a loader-discovered web-surface module (`contributes.webSurfaces` host `builders.`). UNLIKE the generic status surface it keeps its **dedicated** serving block in `serve-internal.js` (`BUILDERS_DIR = modules/hall-ui/public/`), partitioned out of the generic web-surface loop on the `isBuildersHost` predicate. A thin rewrite shim maps every non-API path onto the existing `/builders/*` tree (so all serving + gating + asset-stamping is reused), serving the hall (`/`), the Metic+ **`/watch`** monitoring page (gated by `requireGovernmentPage`), **`/settings`** (Voices + Craft prefs), plus ranks/sessions/primer/diagrams. No behavior change — byte-identical (only `window.__MODULES__.enabled` gains `hall-ui:true`). **Additive** — until its DNS A record + cert are live, the whole surface stays reachable at `example.com/builders/*`. No `.github/workflows/*` follow-up: unlike R84, no workflow path-trigger watches `public-builders/**`.
-- **`/downloads/devbox/*`** (every host, mounted right after the API so the builders-host shim can't rewrite it — [#904](https://example.com/builders#/task/904), [ADR 0045](adr/<redacted>.md)): branded download surface for the Dev Box desktop app. `/{mac-arm64,mac-x64,win-x64}` (+ `mac`/`win` aliases) 302 to the release assets on the public releases repo named in [`config/devbox-app.json`](../config/devbox-app.json); `latest.json` feeds the app's update check. Logic in [`src/devbox-downloads.js`](../src/devbox-downloads.js); the installers never ride the git deploy.
+- **`status.example.com`** — public build dashboard. **Carved to the `status-ui` module in BV1.R84** ([ADR 0093](adr/0093-tranche-2-core-carve-sequence.md) §1): the surface moved from `public-status/` to `modules/status-ui/public/`, now served by the loader's web-surface seam (`moduleWebSurfaces` → `serve-internal.js`, routed on the `status.` Host prefix the manifest declares) instead of a hardcoded block — no behavior change. Layout reorganized in [#726](https://example.com/builders#/task/726) (ADR 0036): Pulse / Watch(uptime) / Architects / Works / Treasury / Lately Inscribed / The World — the grade-aggregate, estimation-drift, and repo-health tablets moved to the Archon `/watch` page. **⚠ Served OFF the droplet** (ADR 0029, outage resilience): the live page is **GitHub Pages from the separate repo `example-owner/example-status`** (CNAME → Fastly), reading data cross-origin from the droplet's `/api/gds/public/*` (CORS open) and an availability banner from the prober's `status-data` branch. The droplet still serves `modules/status-ui/public/` (on the `status.` host) as a same-origin fallback, but **DNS points at Pages, not the droplet** — so a droplet deploy does NOT update the live page. Changes to the surface publish to the mirror via `scripts/status-mirror-sync.js` (re-pointed at `modules/status-ui/public/`; status.js/style.css/cursors are byte-identical copies; index.html gets the off-box bits injected), run automatically by `.github/workflows/sync-status-mirror.yml` (needs the `STATUS_MIRROR_TOKEN` secret) ([#737](https://example.com/builders#/task/737)). **⚠ FOLLOW-UP (R84):** that workflow's path trigger still watches `public-status/**` and must be re-pointed at `modules/status-ui/public/**` by an owner/Archon — the GitHub App can't push `.github/workflows/*` (learning 107), so until then the mirror sync won't auto-fire on future status edits.
+- **`builders.example.com`** — dedicated builder surface (`isBuildersHost`, ADR 0036). **Carved to the `hall-ui` module in BV1.R85** ([ADR 0093](adr/0093-tranche-2-core-carve-sequence.md) §1): the surface moved from `public-builders/` to `modules/hall-ui/public/` (~13k LOC, the largest module) and is a loader-discovered web-surface module (`contributes.webSurfaces` host `builders.`). UNLIKE the generic status surface it keeps its **dedicated** serving block in `serve-internal.js` (`BUILDERS_DIR = modules/hall-ui/public/`), partitioned out of the generic web-surface loop on the `isBuildersHost` predicate. A thin rewrite shim maps every non-API path onto the existing `/builders/*` tree (so all serving + gating + asset-stamping is reused), serving the hall (`/`), the Metic+ **`/watch`** monitoring page (gated by `requireGovernmentPage`), **`/settings`** (Voices + Craft prefs), plus ranks/sessions/primer/diagrams. No behavior change — byte-identical (only `window.__MODULES__.enabled` gains `hall-ui:true`). **Additive** — until its DNS A record + cert are live, the whole surface stays reachable at `example.com/builders/*`. No `.github/workflows/*` follow-up: unlike R84, no workflow path-trigger watches `public-builders/**`.
+- **`/downloads/devbox/*`** (every host, mounted right after the API so the builders-host shim can't rewrite it — [#904](https://example.com/builders#/task/904), [ADR 0045](adr/0045-devbox-desktop-app.md)): branded download surface for the Dev Box desktop app. `/{mac-arm64,mac-x64,win-x64}` (+ `mac`/`win` aliases) 302 to the release assets on the public releases repo named in [`config/devbox-app.json`](../config/devbox-app.json); `latest.json` feeds the app's update check. Logic in [`src/devbox-downloads.js`](../src/devbox-downloads.js); the installers never ride the git deploy.
 - The `/api/gds/*` surface is reachable from every host. **Cross-subdomain sign-in:** the `gds_session` cookie is scoped to `.example.com` on the production hosts (apex/www/builders/status) and host-only on localhost/staging (no cross-env token bleed); the OAuth handshake runs on the canonical origin with a validated `?return=` (open-redirect-guarded) so the subdomain can land a builder back on itself.
 - Caddy gets a site block per host ([`infra/Caddyfile`](../infra/Caddyfile)), all reverse-proxying to `127.0.0.1:3000`.
 

package/docs/branding-contract.md

@@ -1,6 +1,6 @@
 # The branding contract (`config/branding.*`)
 
-The branding contract is how a **Cloud Bongos instance** supplies its identity. It is the keystone of the Cloud Bongos decoupling (ADR [0062](adr/<redacted>.md) §3; task [#1192](https://example.com/builders#/task/1192) / V4.R53). One config, read through one resolver (`src/branding.js`), so brand strings live in **one place** instead of the ~90 hardcoded sites they occupy today.
+The branding contract is how a **Cloud Bongos instance** supplies its identity. It is the keystone of the Cloud Bongos decoupling (ADR [0062](adr/0062-medusa-instance-model-decoupling.md) §3; task [#1192](https://example.com/builders#/task/1192) / V4.R53). One config, read through one resolver (`src/branding.js`), so brand strings live in **one place** instead of the ~90 hardcoded sites they occupy today.
 
 > Generalizes the single-config rule of [ADR 0004](adr/0004-example-name-and-trademark-acceptance.md) (the civ name must be one string, never baked into code) from one string to the whole identity surface. Code reads `branding().identity.worldName`, never `"Example"`.
 
@@ -12,7 +12,7 @@ env override   →   instance config (config/branding.json)   →   neutral star
 
 - A fresh instance with **no** `config/branding.json` resolves to the **plain neutral identity** — never to a host's brand (fail-to-vanilla).
 - `config/branding.neutral.json` is **customer 0** (vanilla Cloud Bongos). `config/branding.json` is the host instance — here, **customer 1** (Example / OTB).
-- **Configurable-root ([ADR 0108](adr/<redacted>.md) §1, task 1881/W1 shipped):** `NEUTRAL_PATH` resolves off `resolveCoreRoot()` (the neutral starter ships WITH the core package) and `INSTANCE_PATH` off `resolveInstanceRoot()` (the instance pack is host content) — [`src/instance-config.js`](../src/instance-config.js). Both resolvers return the repo root today, so resolution is unchanged; the split only diverges once a consumer installs the core as a package.
+- **Configurable-root ([ADR 0108](adr/0108-instance-composition-configurable-root.md) §1, task 1881/W1 shipped):** `NEUTRAL_PATH` resolves off `resolveCoreRoot()` (the neutral starter ships WITH the core package) and `INSTANCE_PATH` off `resolveInstanceRoot()` (the instance pack is host content) — [`src/instance-config.js`](../src/instance-config.js). Both resolvers return the repo root today, so resolution is unchanged; the split only diverges once a consumer installs the core as a package.
 - Env overrides apply only to the operationally-swapped fields (origins + cookie domain) for dev/staging, keyed `<envPrefix>_<FIELD>` (e.g. `OTB_PUBLIC_ORIGIN`). Everything else comes from the committed pack.
 
 ## Fields
@@ -24,7 +24,7 @@ env override   →   instance config (config/branding.json)   →   neutral star
 | `identity.company` | `{ name, site }` of the operating company (may be empty). |
 | `llmProjectName` | The project name injected into grader / architect / onboarding **LLM prompts**, so a non-OTB instance is graded against its own identity. **Required.** |
 | `domains.publicOrigin` | Public game/app origin. **Required.** |
-| `domains.buildersOrigin` / `statusOrigin` | Hall + status origins. **These three (`publicOrigin`/`buildersOrigin`/`statusOrigin`) are the docs-discovery contract** ([ADR 0114](adr/<redacted>.md)): the hall is the canonical doc-reading surface, `/docs` on `publicOrigin` renders the API reference, the status page is the outage fallback. `GET <publicOrigin>/api/bongos` re-advertises them (`hall`/`status`/`public`) so an agent resolves the surfaces with no hard-coded host. |
+| `domains.buildersOrigin` / `statusOrigin` | Hall + status origins. **These three (`publicOrigin`/`buildersOrigin`/`statusOrigin`) are the docs-discovery contract** ([ADR 0114](adr/0114-instance-docs-discovery-contract.md)): the hall is the canonical doc-reading surface, `/docs` on `publicOrigin` renders the API reference, the status page is the outage fallback. `GET <publicOrigin>/api/bongos` re-advertises them (`hall`/`status`/`public`) so an agent resolves the surfaces with no hard-coded host. |
 | `domains.statusDataUrl` | **Optional.** The off-box prober's `status.json` URL that the mirrored status page's availability banner polls (ADR 0029). Read by `scripts/status-mirror-sync.js`; `""` (the neutral default) = this instance publishes no off-box mirror, and the publisher REFUSES rather than shipping a banner that points nowhere. (task [#1002510](https://cloudbongos.com/builders#/task/1002510)) |
 | `domains.cookieDomain` | Session cookie domain (`""` = host-only — the safe default; never widen to a parent domain by accident). |
 | `domains.oauthOrigin` | Canonical sign-in origin. |
@@ -36,10 +36,10 @@ env override   →   instance config (config/branding.json)   →   neutral star
 | `repo` | `{ owner, name }` GitHub binding. |
 | `db.database` | DB name Bongos pool connects to when neither `DATABASE_URL` nor `PGHOST`/`PGDATABASE` is set (`src/bongos/pool.js`, ADR 0062 §5). `null` in the neutral starter = **fail loud** rather than silently target a host DB. |
 | `currency` | `{ label, symbol }` — the reward unit label (e.g. "example"). Display only. |
-| `reward` | `{ marginPct, usdPeg, mode }` — the per-instance reward POLICY the economy module reads ([ADR 0054](adr/<redacted>.md) + ADR 0146, tasks 2009/1002270): the cost-plus margin percent (default `20`), the example-per-USD peg (default `1`), and `mode` — `"cost-plus-and-estimate"` (default; pay both the per-task author estimate AND the cost-plus session reward) or `"cost-plus-only"` (suppress the per-task estimate payout; the cost-plus session reward is the sole equity reward). A committed, code-reviewed change — not a live UI knob. Omit ⇒ code defaults (20% margin, 1:1 peg, pay both streams). |
+| `reward` | `{ marginPct, usdPeg, mode }` — the per-instance reward POLICY the economy module reads ([ADR 0054](adr/0054-session-token-reward-cost-plus.md) + ADR 0146, tasks 2009/1002270): the cost-plus margin percent (default `20`), the example-per-USD peg (default `1`), and `mode` — `"cost-plus-and-estimate"` (default; pay both the per-task author estimate AND the cost-plus session reward) or `"cost-plus-only"` (suppress the per-task estimate payout; the cost-plus session reward is the sole equity reward). A committed, code-reviewed change — not a live UI knob. Omit ⇒ code defaults (20% margin, 1:1 peg, pay both streams). |
 | `models` | `{ main, subagentDefault, subagentRoutine }` — the per-instance subagent model-allocation DEFAULT the builder-settings module reads (task 2011): the tier for the main session, subagent-default work, and routine plumbing (tiers: `haiku`/`sonnet`/`opus`/`fable`). A per-builder override resolves over this. Omit ⇒ code defaults (`opus`/`opus`/`haiku`). |
 | `tracks` | The configurable version-track set (replaces the hardcoded `product\|internal`). |
-| `theme` | `{ palette, mode, ui }` — palette file ref + theme mode, plus `ui`, the WEB look `themeMarkup()` splices into every served page as a plain `:root` after the page's stylesheet: `colors` (the thirteen contract tokens — **light-mode values**; each stylesheet derives its own dark tier from them at `:root[data-mode="dark"]` + its `prefers-color-scheme` twin, which outrank the pack), `fonts` (`display`, `body`, `links`), `favicon`, and `backdrop` — a `body{background:…}` rule that outranks every sheet in **both** modes, so a dual-mode world sets it to `var(--bg)` (the neutral pack does since [task 1003298](https://cloudbongos.com/builders#/task/1003298), ADR 0196) rather than a literal. The neutral values are the chrome world's; `config/design-tokens.neutral.json` must mirror `colors` + `fonts` key for key (`tests/design_tokens_sync.mjs`), and the world's derived recipes are recorded in `DESIGN.md`. The ui-design module's **style library** (`modules/ui-design/styles/`, [ADR 0219](adr/<redacted>.md)) ships ready-made `theme.ui` blocks (looks) an instance copies into this field; every served sheet reads only these fifteen, so a look re-themes every surface with no page edit. |
+| `theme` | `{ palette, mode, ui }` — palette file ref + theme mode, plus `ui`, the WEB look `themeMarkup()` splices into every served page as a plain `:root` after the page's stylesheet: `colors` (the thirteen contract tokens — **light-mode values**; each stylesheet derives its own dark tier from them at `:root[data-mode="dark"]` + its `prefers-color-scheme` twin, which outrank the pack), `fonts` (`display`, `body`, `links`), `favicon`, and `backdrop` — a `body{background:…}` rule that outranks every sheet in **both** modes, so a dual-mode world sets it to `var(--bg)` (the neutral pack does since [task 1003298](https://cloudbongos.com/builders#/task/1003298), ADR 0196) rather than a literal. The neutral values are the chrome world's; `config/design-tokens.neutral.json` must mirror `colors` + `fonts` key for key (`tests/design_tokens_sync.mjs`), and the world's derived recipes are recorded in `DESIGN.md`. The ui-design module's **style library** (`modules/ui-design/styles/`, [ADR 0219](adr/0219-a-look-is-a-branding-pack-the-style-library.md)) ships ready-made `theme.ui` blocks (looks) an instance copies into this field; every served sheet reads only these fifteen, so a look re-themes every surface with no page edit. |
 | `copy` | Instance copy keys (tagline, hallName, notFound, …). Full copy pack adoption = task [#1196](https://example.com/builders#/task/1196). |
 | `landing.postLogin` | Where a successful web sign-in lands when it carried no explicit `?return=` / same-apex `Referer` (`src/bongos/routes/auth.js` `postLoginLanding`). **Portable default `/builders`** — the hall always exists. A platform-home instance points this at its OWN front door so a visitor who signs in from there returns there instead of being auto-redirected into the hall (cloudbongos.com → `/gate/`, the orbs). Validated through the same open-redirect allowlist as `?return=` (a misconfigured value falls back to `/builders`). Env-overridable: `<PREFIX>_POST_LOGIN_LANDING`. (task [#1002240](https://cloudbongos.com/builders#/task/1002240)) |
 | `envPrefix` | Env-var namespace for overrides (`BONGOS` for vanilla, `OTB`, …). Legacy `CLOUDBONGOS_`, `OTB_`, `GDS_` and `PMS_` spellings still resolve, with one deprecation warning per name, until core 1.21 (task 1003703). |

package/docs/canonical-permissions.md

@@ -5,7 +5,7 @@
 > plus the `requireRank()` middleware on each route. This file *describes* that model so humans
 > and agents can read it in one place; it cannot *grant* anything. If this file and a route ever
 > disagree, **the route is authoritative and the doc is the bug.** See
-> [ADR 0016 — Trust boundary](adr/<redacted>.md).
+> [ADR 0016 — Trust boundary](adr/0016-trust-boundary-server-enforced-permissions.md).
 >
 > Changing the permission model is a code + migration + ADR change, never an edit to this file alone.
 > A builder editing local files (this doc, `CLAUDE.md`, skills, `settings.json`, hooks) cannot
@@ -56,7 +56,7 @@ forming the ordered claim-gate tier **`xenos` (1) < `thetes` (2) < `metic` (3) <
 (`REQUIRES_RANK_TIER` in `src/bongos/db.js`):
 
 - **`archon`** — Lars (`github_login = 'example-owner'`, set by migration 023). **Since
-  [ADR 0157](adr/<redacted>.md) (2026-08-05) the Archon rank is responsible for
+  [ADR 0157](adr/0157-archon-is-rank-and-identity-only.md) (2026-08-05) the Archon rank is responsible for
   RANK and IDENTITY, not day-to-day administration.** It is everything a Metic can do, plus: **rank**
   (grant/revoke — the single writer), **identity** (offboard/(de)activate, admit an access request, revoke
   sessions), the **four escalation keys** that would otherwise make that delegation self-reversible
@@ -64,21 +64,21 @@ forming the ordered claim-gate tier **`xenos` (1) < `thetes` (2) < `metic` (3) <
   **version close**, cross-tier dependency edges, and the substrate floors (push `main`, protected paths,
   ssh — ADR 0043). Version-**level** criteria (a `done-when` with no `goal_id`, or one outside an open
   version / outside a goal they own) also stay Archon per
-  [ADR 0154](adr/<redacted>.md), though that ADR's `done-when/:id/unsatisfy`
+  [ADR 0154](adr/0154-goal-owner-criterion-authoring.md), though that ADR's `done-when/:id/unsatisfy`
   carve-out was superseded — unsatisfy is Metic now. Overrides any claim. The authority that
   stays *exclusively* Archon — never delegated to Metic — is **setting rank** (`PATCH /builders/:id/rank`)
   and **closing versions**.
 - **`metic`** — the Archon-approved **working rank**. Full claim/ship of any ready task (own work),
   plus the review/triage powers criterion C2 assigns: **idea triage** (`PATCH /inbox/:id`), **blocker
-  review** (`POST /blockers/:id/{resolve,link}`), and planning/priority sessions. **As of [ADR 0090](adr/<redacted>.md)
+  review** (`POST /blockers/:id/{resolve,link}`), and planning/priority sessions. **As of [ADR 0090](adr/0090-metic-task-authoring.md)
   (owner decision 2026-06-26) a Metic may also author + shape tasks**: create (`POST /tasks`), edit
   (`PATCH /tasks/:id`), promote (`POST /tasks/:id/promote`), and wire a task's dependencies + criterion
   links (`/tasks/:id/dependencies`, `/tasks/:id/criteria`) — the reasoning being that a rank trusted to
-  *triage* ideas is trusted to *seed* the work they become. **As of [ADR 0152](adr/<redacted>.md)
+  *triage* ideas is trusted to *seed* the work they become. **As of [ADR 0152](adr/0152-metic-task-abandonment.md)
   (owner decision 2026-07-27) a Metic may also retire work** — `POST /tasks/:id/abandon` — and undo a
   mis-retire, since `POST /tasks/:id/promote` now also restores `abandoned → backlog`. **Still cannot**
   set rank, close versions, grader-bypass confirm, or author cross-tier `POST /dependencies` / goal-scope edges
-  ([ADR 0086](adr/<redacted>.md)) — those stay Archon. A builder reaches Metic
+  ([ADR 0086](adr/0086-goal-scoped-work-hierarchy.md)) — those stay Archon. A builder reaches Metic
   only by deliberate Archon promotion (`PATCH /builders/:id/rank`).
 - **`thetes`** — the **graduated-newcomer rank** (ADR 0034). Claims the **whole general queue** — any
   task whose `requires_rank` is the default `'xenos'` — and is **not** limited to `newcomer_friendly`,
@@ -132,7 +132,7 @@ index = higher authority). So `requireRank('archon')` admits `archon` **and the
 silently *lost* all archon-gated authority — while still denying everything below the floor. Unknown
 or missing ranks fail closed.
 
-- **Archon-only** — **rank, identity, and the four escalation keys ([ADR 0157](adr/<redacted>.md), owner decision 2026-08-05).**
+- **Archon-only** — **rank, identity, and the four escalation keys ([ADR 0157](adr/0157-archon-is-rank-and-identity-only.md), owner decision 2026-08-05).**
   That ADR narrowed Archon from ~50 route gates to 9 live ones, on the rule *"the Archon rank is
   responsible for rank and identity only"*:
   - **rank** — `PATCH /api/gds/builders/:id/rank` (the single writer).
@@ -140,17 +140,17 @@ or missing ranks fail closed.
     (who is admitted), `POST /api/gds/auth/revoke[-all]` (whose sessions are valid).
   - **the four escalation keys**, which look operational but are not: `POST /api/gds/tasks/:id/confirm`
     (grader-bypass), `POST /api/gds/gate-approvals/:pr/approve` (CI deploy-gate override), protected-module
-    **goal scope** ([ADR 0086](adr/<redacted>.md)), and `government.manage` (the
+    **goal scope** ([ADR 0086](adr/0086-goal-scoped-work-hierarchy.md)), and `government.manage` (the
     ranks/permissions tab). Delegating any one of them lets a Metic reach Archon in four steps — create a
     protected-scope goal in the permission core, claim a task there (protected paths already floor at
-    *metic* per [ADR 0043](adr/<redacted>.md)), confirm
+    *metic* per [ADR 0043](adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md)), confirm
     past the failed grade, approve their own red gate — so keeping rank Archon-only depends on keeping
     these Archon-only too. **Any future delegation must re-check that chain.**
   - plus `version.close` (paired with rank as the powers that never delegate), the cross-tier
     `POST|DELETE /api/gds/dependencies` (`system: true`), and the substrate floors
     (`deploy.push_main` / `path.protected.modify` / `infra.ssh`, ADR 0043).
 
-  > **Amended by [ADR 0172](adr/<redacted>.md) (owner decision, 2026-08-16).**
+  > **Amended by [ADR 0172](adr/0172-editable-rank-roles-substrate-axis.md) (owner decision, 2026-08-16).**
   > The paragraphs above describe the SEEDED ladder, which is still what a fresh instance boots with — but
   > they are no longer a guarantee about a running one. The owner made the three sub-Archon **ranks**
   > editable from the Government tab and chose to include the seven in-app Archon powers, `government.manage`
@@ -166,11 +166,11 @@ or missing ranks fail closed.
 
   Earlier one-power delegations that ADR 0157 generalises: **task authoring** — `POST /api/gds/tasks`,
   `PATCH /api/gds/tasks/:id` (incl. the `newcomer_friendly` flag), `POST /api/gds/tasks/:id/promote`, and the
-  `tasks/:id/{dependencies,criteria}` CRUD — moved to Metic+ in [ADR 0090](adr/<redacted>.md),
+  `tasks/:id/{dependencies,criteria}` CRUD — moved to Metic+ in [ADR 0090](adr/0090-metic-task-authoring.md),
   and **task retirement** — `POST /api/gds/tasks/:id/abandon`, plus the `abandoned → backlog` restore on
-  `/promote` — in [ADR 0152](adr/<redacted>.md) (see the Metic+Archon bullet).
+  `/promote` — in [ADR 0152](adr/0152-metic-task-abandonment.md) (see the Metic+Archon bullet).
   `POST /api/gds/done-when/:id/unsatisfy` **was** Archon-only and moved to Metic in ADR 0157, superseding
-  [ADR 0154](adr/<redacted>.md)'s "the backward ratchet stays Archon" carve-out;
+  [ADR 0154](adr/0154-goal-owner-criterion-authoring.md)'s "the backward ratchet stays Archon" carve-out;
   satisfy and unsatisfy remain separate permissions, so confirming a criterion still never confers
   un-confirming one. **A manual promotion advances exactly
   ONE live rung at a time** (`xenos→thetes→metic→archon`; [#707](https://example.com/builders#/task/707)) — a multi-rung jump (e.g. `xenos→metic`) returns
@@ -178,21 +178,21 @@ or missing ranks fail closed.
   drops straight to `xenos`); the automatic `xenos→thetes` graduation is +1 and unaffected.
 - **Metic + Archon** — the working rank's review/triage powers ([#360](https://example.com/builders#/task/360) / ADR 0018): `PATCH /api/gds/inbox/:id`
   (idea triage), `POST /api/gds/blockers/:id/{resolve,link}` (blocker review) — **plus, since
-  [ADR 0090](adr/<redacted>.md), full task authoring**: `POST /api/gds/tasks`,
+  [ADR 0090](adr/0090-metic-task-authoring.md), full task authoring**: `POST /api/gds/tasks`,
   `PATCH /api/gds/tasks/:id`, `POST /api/gds/tasks/:id/promote`, the `tasks/:id/dependencies` +
   `tasks/:id/criteria` CRUD, and `POST /api/gds/done-when/:id/satisfy` (criterion confirm,
-  [ADR 0086](adr/<redacted>.md)). Since
-  [ADR 0154](adr/<redacted>.md), also `POST /api/gds/versions/:id/done-when`
+  [ADR 0086](adr/0086-goal-scoped-work-hierarchy.md)). Since
+  [ADR 0154](adr/0154-goal-owner-criterion-authoring.md), also `POST /api/gds/versions/:id/done-when`
   (criterion **create**) — but walled by goal ownership, not by rank alone: a non-Archon must name a
   `goal_id`, on an open (`planning`/`building`) version, in an `open` goal they **own or manage** (the same
   `authorizeGoalManagement` wall as goal visibility/invites/memberships — the membership column is
   `goal_members.membership_kind` ('lead' | 'member') since task 1003013, never `role`, which
-  [ADR 0174](adr/<redacted>.md) reserves for the three crafts). Version-level criteria stay Archon;
-  `done-when/:id/unsatisfy` moved here in [ADR 0157](adr/<redacted>.md). The floor here is
+  [ADR 0174](adr/0174-government-terminology-ranks-not-roles.md) reserves for the three crafts). Version-level criteria stay Archon;
+  `done-when/:id/unsatisfy` moved here in [ADR 0157](adr/0157-archon-is-rank-and-identity-only.md). The floor here is
   `metic`, so **`thetes` does NOT pass these** — it sits below `metic` on the ladder and inherits none
   of its grants (ADR 0034); `archon` and the divine tiers above it do.
 
-  **[ADR 0157](adr/<redacted>.md) added the whole operational block here** —
+  **[ADR 0157](adr/0157-archon-is-rank-and-identity-only.md) added the whole operational block here** —
   20 permissions that had been Archon-gated only by ADR 0016's fail-closed default, never by a decision:
   the government/monitoring **pages** (`/watch`, `/harbor`, `/gate` — `page.view.government`) and
   `GET /api/gds/sessions/search` (whose own `/sessions` page had no server gate at all until
@@ -237,7 +237,7 @@ nothing set it, so every task sat at the `'xenos'` default and the claim gate ab
 - **Derivation (`db.deriveRequiredRank(touches, security_sensitive)`):** a task floors at `metic` when
   it is `security_sensitive` **or** any `touches[]` entry hits the permission-sensitive set — reusing
   the **same** `permission-path-check.matchProtected` matcher the trust boundary uses (so the claim
-  floor and the [ADR 0043](adr/<redacted>.md) git-push floor can never disagree). Everything else stays `'xenos'` (the open
+  floor and the [ADR 0043](adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md) git-push floor can never disagree). Everything else stays `'xenos'` (the open
   general queue). The rule **never auto-assigns `archon`** — owner-only is a deliberate manual call.
 - **Override is upward-only (`db.highestRank`):** the stored value is `max(derived floor, requested)`.
   An Archon may RAISE a task's floor (incl. to `archon`) on `POST /api/gds/tasks` or
@@ -285,7 +285,7 @@ pre-merge gate misses, independent of the builder's cooperation:
   activated per-clone by `/builder-setup` via `install-git-hooks.js` — inert on a clone that never
   activated it; ADR 0043 §"G-2/G-17 resolution") blocks it. This hook is a CORE-repo control:
   scaffolded standalone instances are hookless by default — deliberate, not a gap
-  ([ADR 0165](adr/<redacted>.md)); the graded
+  ([ADR 0165](adr/0165-instances-hookless-by-default.md)); the graded
   pipeline pushes only via `scripts/gds/push-main.js` (which carries the `OTB_ALLOW_MAIN_PUSH`
   override). A raw push is caught and reverted by the **post-push main audit**
   (`scripts/gds/main-audit.js`) — nightly and as the `~/deploy.sh` deploy gate — which is the
@@ -310,7 +310,7 @@ pre-merge gate misses, independent of the builder's cooperation:
 A builder who edits their checkout to try to elevate themselves hits the boundary and fails every
 time, in a defined way (`403 rank_forbidden`), because the server never consults anything the
 builder's machine can write. The full enumeration of local-edit attack attempts and their outcomes
-lives in [ADR 0016 §"Failure mode when a builder edits local files"](adr/<redacted>.md).
+lives in [ADR 0016 §"Failure mode when a builder edits local files"](adr/0016-trust-boundary-server-enforced-permissions.md).
 
 ---