@bongos/core 1.21.175 → 1.21.177

package/docs/api-reference.md

@@ -1,8 +1,8 @@
-<!-- GENERATED by scripts/gds/gen-api-docs.js — do not hand-edit. Run `node scripts/gds/gen-api-docs.js`. -->
+<!-- GENERATED by scripts/bongos/gen-api-docs.js — do not hand-edit. Run `node scripts/bongos/gen-api-docs.js`. -->
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 572 endpoints across 96 route files.
+> **Generated from the live route files** — the route file is authoritative. 580 endpoints across 99 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/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -122,7 +122,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 |---|---|---|---|---|
 | GET | `/api/bongos/bug-attachments/:name` | `any-builder` | — | GET /api/bongos/bug-attachments/:name — stream one stored image. |
 
-## `builders` (12)
+## `builders` (13)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -135,6 +135,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/builders/:id/profile` | `public` | — | GET /builders/:id/profile — the viewable builder profile page's read (task 1467, goal 25 "bx-identity"). |
 | PATCH | `/api/bongos/builders/:id/rank` | `archon` | `rank` | sole chokepoint that mutates builders.rank; ADR 0016 §enforcement. |
 | PATCH | `/api/bongos/builders/:id/status` | `archon` | `status`, `reason` | PATCH /builders/:id/status — graceful exit + reactivation (V3.R88 task 307). |
+| PATCH | `/api/bongos/builders/:id/tester` | `archon` | `is_tester` | PATCH /builders/:id/tester — mark or unmark an account as a tester (task 1004845). |
 | GET | `/api/bongos/builders/directory` | `any-builder` | — | GET /builders/directory — the any-builder-readable picker roster (task 1877): every ACTIVE builder's identity, for a client-side invite d… |
 | GET | `/api/bongos/builders/me/pending-rank-change` | `any-builder` | — | GET /builders/me/pending-rank-change — V3.R28 / task 249 ceremony signal task 3. |
 | GET | `/api/bongos/builders/roster` | `metic+archon` | — | GET /builders/roster — V3.R14 (task 238) onboarding observability. |
@@ -184,7 +185,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/connections/requests` | `any-builder` | — | MY pending requests, both directions (own data). |
 | GET | `/api/bongos/connections/suggestions` | `any-builder` | — | "builders you may know" (R21, task 1002297; ADR 0202 D5). |
 
-## `copy-desk` (20)
+## `copy-desk` (21)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -202,6 +203,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | PUT | `/api/bongos/copy-desk/pages/:pageId/draft` | `any-builder` | `reading_hash`, `lines` | ------------------------------------------------------------------------- PUT /copy-desk/pages/:pageId/draft — autosave the artist's draf… |
 | GET | `/api/bongos/copy-desk/pages/:pageId/draft.docx` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/pages/:pageId/draft.docx — download the page's w… |
 | POST | `/api/bongos/copy-desk/pages/:pageId/draft.docx` | `any-builder` | _undocumented_ | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/draft.docx — upload the Word file… |
+| POST | `/api/bongos/copy-desk/pages/:pageId/release` | `metic+archon` | `note`, `task_id` | POST /copy-desk/pages/:pageId/release — release a page round the reads cannot name: back to the /tweak queue with a note when it still ho… |
 | POST | `/api/bongos/copy-desk/pages/:pageId/send-back` | `any-builder` | `note`, `task_id` | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/send-back — back to the /tweak qu… |
 | POST | `/api/bongos/copy-desk/pages/:pageId/submit` | `any-builder` | validated | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/submit — freeze the draft and que… |
 | POST | `/api/bongos/copy-desk/proposals` | `any-builder` | `string_id`, `proposed_text`, `why`, `file`, `line`, `flag_id` | ------------------------------------------------------------------------- POST /copy-desk/proposals — an artist proposes new wording, and… |
@@ -436,13 +438,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/help-requests/for-me` | `any-builder` | — | The addressed read — C01's answer to "and fires a notification". |
 | GET | `/api/bongos/help-requests/mine` | `any-builder` | — | your own asks, so you can settle them. |
 
-## `inbox` (18)
+## `inbox` (20)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/inbox` | `any-builder` | — | read open ideas; skill-friction rows filtered by viewer rank. |
 | POST | `/api/bongos/inbox` | `any-builder` | `title`, `body_md`, `kind`, `suggested_version`, `suggested_priority`, `goal_id`, `grade`, `template_key`, `field_values`, `recommendation`, `filed_via` | for ordinary ideas; metic+ for kind='criterion-proposal'. |
-| GET | `/api/bongos/inbox/:id` | `any-builder` | — | single idea read for the "#NNN" deep-link resolver (task 1047). |
+| GET | `/api/bongos/inbox/:id` | `any-builder` | — |  |
 | PATCH | `/api/bongos/inbox/:id` | `metic+archon` | `status`, `kind`, `promoted_to_task_id`, `reviewed_at`, `merged_into_idea_id`, `triage_note` |  |
 | PATCH | `/api/bongos/inbox/:id/body` | `any-builder` | `body_md` | Metic+ (task 360 / ADR 0018): idea triage (promote/discard/merge) shapes the backlog. |
 | POST | `/api/bongos/inbox/:id/develop` | `any-builder` | `field_values`, `template_key`, `recommendation` | POST /inbox/:id/develop — DEVELOP A SPARK INTO A FULL IDEA (task 1002922 / BV1.R146, goal 1000062). |
@@ -451,6 +453,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/inbox/:id/resubmit` | `any-builder` | `field_values`, `template_key`, `recommendation` | RESUBMIT a Full Idea after a rejection (R13 of goal 1000069, criterion C2: an idea never dies and never stalls). |
 | POST | `/api/bongos/inbox/:id/spark` | `any-builder` | — | Mark a Quick Idea as a Big Idea Spark — "I have the spark but not the full picture, someone develop this". |
 | DELETE | `/api/bongos/inbox/:id/spark` | `any-builder` | — | Withdraw the Big Idea Spark mark — the reversibility half of R144. |
+| POST | `/api/bongos/inbox/:id/vote` | `metic+archon` | `vote` | POST /inbox/:id/vote { vote: 1 \| -1 \| 0 } — a karma vote on an idea (task 1004727). |
 | GET | `/api/bongos/inbox/awaiting-nod` | `metic+archon` | — | GET /inbox/awaiting-nod — the NOD QUEUE (task 1003066, BV1.R05). |
 | GET | `/api/bongos/inbox/by-builder/:id` | `any-builder` | — | THE IDEA TRAIL: every idea one builder filed, newest first, with what became of each (task 1003281, goal 1000072, criterion legibility-ac… |
 | POST | `/api/bongos/inbox/preview-landing` | `any-builder` | `goal_id`, `kind`, `grade` | POST /inbox/preview-landing — GRAVITY, MADE VISIBLE (task 1004083, BV2.R02). |
@@ -458,6 +461,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/inbox/score` | `any-builder` | `field_values`, `template_key` |  |
 | GET | `/api/bongos/inbox/sparks` | `any-builder` | — | GET /inbox/sparks — THE SPARK QUEUE (task 1002921 / BV1.R145, goal 1000062). |
 | GET | `/api/bongos/inbox/template` | `any-builder` | — | ----------------------------------------------------------------------- The two reads the hall's Full Idea composer is built from (task 1… |
+| GET | `/api/bongos/inbox/votes` | `any-builder` | — | single idea read for the "#NNN" deep-link resolver (task 1047). |
 
 ## `instance` (1)
 
@@ -531,7 +535,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | PATCH | `/api/bongos/me/profile` | `any-builder` | `display_name`, `bio`, `links` | the caller's OWN profile fields (P02, task 1002798; spec Decision 4): bio, typed links, account display name. |
 | GET | `/api/bongos/me/profile-nudge` | `any-builder` | — | The "Complete your profile" nudge dismissal (task 1002802 / P06). |
 | PATCH | `/api/bongos/me/profile-nudge` | `any-builder` | _undocumented_ | PATCH the dismissal. |
-| GET | `/api/bongos/me/recent-ships` | `any-builder` | — | Tasks this builder has shipped, most recent first. |
+| GET | `/api/bongos/me/recent-ships` | `any-builder` | — | Tasks this builder has shipped, most recent first, plus `total` — how many there are in all. |
 | GET | `/api/bongos/me/render` | `any-builder` | — | Per-builder CARD RICHNESS knob (task 1279, a four-rung ladder since task 1002518; shares the behavior_prefs jsonb / migration 119). |
 | PATCH | `/api/bongos/me/render` | `any-builder` | _undocumented_ | PATCH the render knob. |
 | GET | `/api/bongos/me/sessions` | `any-builder` | — | GET /api/bongos/me/sessions — every live session on the CALLER's account. |
@@ -720,7 +724,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/provisioning/starter-bundles` | `public` | — | GET /provisioning/starter-bundles — the curated module preset for each declared project type (BV1.R19, task 1002338; goal 1000046 criteri… |
 | GET | `/api/bongos/provisioning/tls-check` | `public` | — | GET /provisioning/tls-check?domain=<host> — the Caddy on-demand-TLS ALLOW-LIST (ADR 0111 §4, task P4 task 1945). |
 
-## `public` (18)
+## `public` (17)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -736,13 +740,20 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/public/modules` | `public` | — | the client-safe feature-module set (R54 task 1193, ADR 0062 §4). |
 | GET | `/api/bongos/public/progress` | `public` | — | version progress aggregate. |
 | GET | `/api/bongos/public/recent-shipped` | `public` | — | Bongos task 191: `?days=7\|30\|90` restricts to that trailing window; `?days=all` or omitted with no query returns the historical 30-row "r… |
-| GET | `/api/bongos/public/ref-ids` | `public` | — | The id allow-list the doc-ref linkifier (scripts/gds/linkify-refs.js) and its CI gate consult to decide which bare "#NNN" are real refere… |
+| GET | `/api/bongos/public/ref-ids` | `public` | — | The id allow-list the doc-ref linkifier (scripts/bongos/linkify-refs.js) and its CI gate consult to decide which bare "#NNN" are real ref… |
 | GET | `/api/bongos/public/repo-health` | `public` | — | V3.R91 task 352: repo-health substrate. |
 | GET | `/api/bongos/public/repo-info` | `public` | — | GitHub URL bases for the deployed checkout (V3.R13-followup-2 task 411). |
 | GET | `/api/bongos/public/tasks/:id` | `public` | — | Single-task resolver for "#NNN" deep links. |
-| GET | `/api/bongos/public/uptime` | `public` | — | Uptime: current status + 90-day history bucketed by hour. |
 | GET | `/api/bongos/public/versions` | `public` | — | read-only surface for the status dashboard (status.<apex>). |
 
+## `raise` (3)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/raise/edit` | `any-builder` | `copy`, `settings` | Any active builder may edit (owner, 2026-10-25) — requireRank at the lowest rank is "signed in and active", with the full deny gates of r… |
+| POST | `/api/bongos/raise/enter` | `public` | `name`, `linkedin`, `password` | the investor sign-in: an authentication entry point gated by the shared password itself (scrypt-checked, attempts limited per address). |
+| POST | `/api/bongos/raise/interest` | `public` | `amount` | a signed-in INVESTOR's non-binding indication; investors are not builders, so the gate is the raise session cookie, checked here. |
+
 ## `removal-proposals` (2)
 
 | Method | Path | Rank | Body | Description |
@@ -859,7 +870,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/sso/pubkey` | `public` | — | GET /sso/pubkey — the hub's Ed25519 assertion-verification key (public). |
 | POST | `/api/bongos/sso/token` | `public` | `client_id`, `client_secret`, `code`, `redirect_uri` | POST /sso/token — server-to-server code redemption. |
 
-## `store` (17)
+## `store` (18)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -869,6 +880,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/store/modules/:key/acquired` | `any-builder` | `version` |  |
 | POST | `/api/bongos/store/modules/:key/delist` | `metic+archon` | `reason` | POST /api/bongos/store/modules/:key/delist — a Metic+ person takes a module out of the store (task 1003797, ADR 0338 D2). |
 | GET | `/api/bongos/store/modules/:key/entitlement` | `any-builder` | — |  |
+| GET | `/api/bongos/store/modules/:key/listing` | `any-builder` | — | GET /api/bongos/store/modules/:key/listing — whether one module is in the catalog and why (task 1003810): the reason in a sentence, what … |
 | POST | `/api/bongos/store/modules/:key/versions` | `metic+archon` | _undocumented_ | POST /api/bongos/store/modules/:key/versions — publish one module version to the store (task 1004271, ADR 0338 D1). |
 | GET | `/api/bongos/store/modules/:key/versions/:version/channel` | `any-builder` | — | GET /api/bongos/store/modules/:key/versions/:version/channel — where a version stands on the promotion gate (task 1003804, ADR 0344 D3): … |
 | POST | `/api/bongos/store/modules/:key/versions/:version/error-count` | `any-builder` | `day`, `count` |  |
@@ -896,7 +908,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 |---|---|---|---|---|
 | GET | `/api/bongos/task-visuals/:name` | `public` | — | the WIDEST path this route can take, declared honestly. |
 
-## `tasks` (35)
+## `tasks` (36)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -934,6 +946,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/tasks/newcomer-floor` | `any-builder` | — | GET /tasks/newcomer-floor — supply gauge for the newcomer queue (task 614). |
 | POST | `/api/bongos/tasks/newcomer-restock` | `metic+archon` | — | POST /tasks/newcomer-restock (task 1168) — bring every evergreen newcomer chore's standing pool up to its configured floor. |
 | GET | `/api/bongos/tasks/peer-votes/feed` | `any-builder` | — | GET /tasks/peer-votes/feed — recent confirmed/shipped work by OTHER builders, each with its net vote total and the caller's own current v… |
+| GET | `/api/bongos/tasks/peer-votes/lookup` | `any-builder` | — | GET /tasks/peer-votes/lookup?ids=1,2,3 — { votes: { [id]: { net, mine } } } for the hall's list vote control (task 1004727). |
 | POST | `/api/bongos/tasks/peer-votes/tally` | `metic+archon` | — | POST /tasks/peer-votes/tally — fold matured votes (≥7 days old, not yet counted) into karma_log, one net row per shipping builder, then m… |
 
 ## `versions` (10)

package/docs/architecture.md

@@ -15,7 +15,7 @@
 - **Where projects run ([ADR 0345](adr/0345-we-host-every-projects-hall-and-its-app-deploys-where-the-owner-chooses.md), 2026-09-28):** every project's **Builders Hall** is hosted by us on the shared control-plane box (`hosting_shape='cloud-host'`, labelled "hosted by us"), at one of our addresses or the owner's own domain. The project's **app** deploys wherever its owner chooses; the setup wizard offers Render first, creating the app on the owner's own Render account with a borrowed, never-stored key (ADR 0327 §2). ADR 0323's plan to move the halls to Render is reversed. Halls at our addresses receive the hub cookie until task 1004357 ships.
 - **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`.
-- **Credentials:** every credential the instance needs — what it is for, which env file holds it (`web.env` · `box.env` · `spaces.env`), GitHub Actions secrets and builder-machine logins — is listed in [`docs/credentials.md`](credentials.md), names only. Whether each is SET on a host is one command run there: `node scripts/gds/credential-presence.js` (task 1002880). Check both before asking the owner for a credential.
+- **Credentials:** every credential the instance needs — what it is for, which env file holds it (`web.env` · `box.env` · `spaces.env`), GitHub Actions secrets and builder-machine logins — is listed in [`docs/credentials.md`](credentials.md), names only. Whether each is SET on a host is one command run there: `node scripts/bongos/credential-presence.js` (task 1002880). Check both before asking the owner for a credential.
 - **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`); the provisioning runner verifies the box's resolved Caddy config carries that import and the `on_demand_tls` ask before it reports a domain wired, and refuses with the line to add rather than editing the base file ([ADR 0303](adr/0303-provisioning-verifies-the-base-caddyfile-and-never-edits-it.md)). **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 — REMOVED 2026-09-15 ([ADR 0284](adr/0284-the-control-plane-carries-no-metrics-stack.md), task 1003876):** the control plane runs **no Grafana and no Prometheus**, and `metrics.cloudbongos.com` has no Caddy site. They cost ~300 MB RSS + 2.5 GB of data on the box every provisioned project shares, and scraped none of those projects. Every instance still exports `/metrics` ([`src/bongos/metrics.js`](../src/bongos/metrics.js), loopback or `METRICS_TOKEN`), so a scraper can return from a box that is *not* the control plane. The rest of this bullet is the **historical** ADR 0127 layout, kept so its leftovers (co-hosting-box forwarders, instance `infra/` copies) can be found: this watched the **Bongos API** (`gds_http`/`tasks`/`claims`/`builders`/`auth`), not any one game, so it lived **on the control-plane box** (REDACTED_IP) at **`https://metrics.cloudbongos.com`** and observed 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` (instance-side)): **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.
 
@@ -42,7 +42,7 @@ The product is organized as a small kernel (`src/`) + **19 modules** under `modu
 - **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; the core's own `migrate.sh` when an adopted instance declares no such script — task 1004274) → 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`.)
+- **`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; the core's own `migrate.sh` when an adopted instance declares no such script — task 1004274) → 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/bongos/upgrade.js`.)
 
 **V1 networking design:**
 
@@ -67,7 +67,7 @@ The product is organized as a small kernel (`src/`) + **19 modules** under `modu
 
 - **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 `<PREFIX>_DEPLOY_MODE` overrides — `BONGOS_DEPLOY_MODE` on a vanilla instance; the legacy `OTB_DEPLOY_MODE` is still read), 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` (instance-side) — **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 machine holds the droplet key — `ship.js` opens a PR + enables GitHub auto-merge, and `.github/workflows/deploy-prod.yml` (instance-side) 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.
+- **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/bongos/ship.js`](../scripts/bongos/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/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.
@@ -128,6 +128,7 @@ tasks(id, version_id, title, description, status, touches text[], est_minutes, e
                 actually pay depends on the instance reward mode, ADR 0146)
   indexes: (version_id, status), (priority), GIN(touches), (goal_id), (parent_task_id),
            (created_by), (shipped_by) WHERE needs_rebase,
+           (shipped_by, shipped_at DESC) WHERE status = 'shipped' (idx_tasks_shipped_by_shipped_at, core_228),
            (source, source_ref) WHERE source IS NOT NULL (idx_tasks_source_ref, core_240)
 task_blockers(task_id, blocker_ref)            -- markdown anchors are canonical
 claims(id, task_id, builder_id, worktree_name, claimed_at, released_at, outcome)
@@ -303,7 +304,7 @@ module_assessment_scores(id, version_id, kind IN (computed|override), overall 0-
               -- and is a new row on the computed history, never an edit (D6)
 ```
 
-Signals that fill it: **Tests** — `scripts/gds/module-assess-tests.js <version id>` (task 1003791) unpacks the published tarball to `<core root>/.module-assess-<run>/<key>/` (gitignored, removed after), runs each `tests/*.mjs` in its own node process with a timeout and a credential-free environment — regardless of `isModuleEnabled`, which skips every default-off catalog module in the unit gate — and appends one `tests` row: `scored` = % of test files passing (sample_size = files), `no_data` = declares no tests, `not_scored` = tarball unreadable. The store path **refuses unless `MODULE_TEST_SANDBOX=1`** — a published module's tests run only in a separate testing environment with no secrets on disk, never on the control plane (owner, 2026-09-30). `--dir modules/<key>` is a DB-free dry run on your own checkout. On publish the version's Tests part is recorded `pending` until that environment runs it. **Security** — `scripts/gds/module-assess-security.js <version id>` (task 1003792, ADR 0343 D2 gate) appends one `security` row, `passed`/`failed` only: fails on a publish-denylist file, a `module.json` dependency fetched outside the registry (an allowlist: a plain npm name with a plain semver range or dist-tag, anything else fails and is never handed to npm), or a high/critical `npm audit` advisory (resolved metadata-only with `--ignore-scripts`; nothing of the module runs, so it is control-plane safe). An audit that cannot run is `not_scored` — the gate stays shut. Floating ranges and the `maintenance` posture (ADR 0166) are noted in `detail`, never failed on. **Docs** — `scripts/gds/module-assess-docs.js <version id>` (task 1004367, ADR 0347 D5/D6) grades the version's `HOWTO.md`, read from its verified tarball (never the optional `howto.artifactUrl`), with one Claude Sonnet 5 call through the `grade` port's cached `runSubagent` (no tools, the file fenced as untrusted, cut to 40,000 characters to stay under 5¢), retried once. It appends a `pending` row, then `scored` (the average of four 0–100 criteria — purpose, newcomer could use it, runnable example, limits stated — each with a reason, kept in `detail`) or `not_scored` (outage, malformed reply twice, no `HOWTO.md`, bad tarball). Each call's spend goes to `cost_log` via the `reward` port (source `module-docs-grader`). Price is never in the prompt. `--file <HOWTO.md>` is a DB-free dry run. **Score** — `scripts/gds/module-assess-score.js` (task 1003794) composes a version's newest signal per part into a `module_assessment_scores` row: `security_passed` from the gate (NULL = not run), `overall` = the plain average of the SCORED parts among Tests, Install, Reliability and Tester feedback (a part with no data is left out, never zero; none → NULL), Docs shown but never averaged, `is_new` until Install or Reliability is scored, plus the signal ids and a readable `formula`. A recompose that would repeat the current score writes nothing. All three signal CLIs recompose after recording, and the store's publish route queues `assessVersion` after answering the author (one at a time per process, at most 20 waiting; past that it is logged as not assessed): Tests `pending` (only if no Tests result exists), the Security gate, Docs, then the score. `node scripts/gds/module-assess-version.js <id>` re-runs it by hand (`scripts/gds/module-assess-version.js` holds the publish-time half, apart from the composer so the signal CLIs recompose without a require cycle). **No score is ever set by hand** (owner, ADR 0359): a Metic+ person can only ask for a re-check, `POST /store/modules/:key/versions/:version/reassess { reason }` (atom `module.assessment.rerun`, metic + archon via `government_021`), which queues the same `assessVersion` a publish runs and answers 202.
+Signals that fill it: **Tests** — `scripts/bongos/module-assess-tests.js <version id>` (task 1003791) unpacks the published tarball to `<core root>/.module-assess-<run>/<key>/` (gitignored, removed after), runs each `tests/*.mjs` in its own node process with a timeout and a credential-free environment — regardless of `isModuleEnabled`, which skips every default-off catalog module in the unit gate — and appends one `tests` row: `scored` = % of test files passing (sample_size = files), `no_data` = declares no tests, `not_scored` = tarball unreadable. The store path **refuses unless `MODULE_TEST_SANDBOX=1`** — a published module's tests run only in a separate testing environment with no secrets on disk, never on the control plane (owner, 2026-09-30). `--dir modules/<key>` is a DB-free dry run on your own checkout. On publish the version's Tests part is recorded `pending` until that environment runs it. **Security** — `scripts/bongos/module-assess-security.js <version id>` (task 1003792, ADR 0343 D2 gate) appends one `security` row, `passed`/`failed` only: fails on a publish-denylist file, a `module.json` dependency fetched outside the registry (an allowlist: a plain npm name with a plain semver range or dist-tag, anything else fails and is never handed to npm), or a high/critical `npm audit` advisory (resolved metadata-only with `--ignore-scripts`; nothing of the module runs, so it is control-plane safe). An audit that cannot run is `not_scored` — the gate stays shut. Floating ranges and the `maintenance` posture (ADR 0166) are noted in `detail`, never failed on. **Docs** — `scripts/bongos/module-assess-docs.js <version id>` (task 1004367, ADR 0347 D5/D6) grades the version's `HOWTO.md`, read from its verified tarball (never the optional `howto.artifactUrl`), with one Claude Sonnet 5 call through the `grade` port's cached `runSubagent` (no tools, the file fenced as untrusted, cut to 40,000 characters to stay under 5¢), retried once. It appends a `pending` row, then `scored` (the average of four 0–100 criteria — purpose, newcomer could use it, runnable example, limits stated — each with a reason, kept in `detail`) or `not_scored` (outage, malformed reply twice, no `HOWTO.md`, bad tarball). Each call's spend goes to `cost_log` via the `reward` port (source `module-docs-grader`). Price is never in the prompt. `--file <HOWTO.md>` is a DB-free dry run. **Score** — `scripts/bongos/module-assess-score.js` (task 1003794) composes a version's newest signal per part into a `module_assessment_scores` row: `security_passed` from the gate (NULL = not run), `overall` = the plain average of the SCORED parts among Tests, Install, Reliability and Tester feedback (a part with no data is left out, never zero; none → NULL), Docs shown but never averaged, `is_new` until Install or Reliability is scored, plus the signal ids and a readable `formula`. A recompose that would repeat the current score writes nothing. All three signal CLIs recompose after recording, and the store's publish route queues `assessVersion` after answering the author (one at a time per process, at most 20 waiting; past that it is logged as not assessed): Tests `pending` (only if no Tests result exists), the Security gate, Docs, then the score. `node scripts/bongos/module-assess-version.js <id>` re-runs it by hand (`scripts/bongos/module-assess-version.js` holds the publish-time half, apart from the composer so the signal CLIs recompose without a require cycle). **No score is ever set by hand** (owner, ADR 0359): a Metic+ person can only ask for a re-check, `POST /store/modules/:key/versions/:version/reassess { reason }` (atom `module.assessment.rerun`, metic + archon via `government_021`), which queues the same `assessVersion` a publish runs and answers 202.
 
 Code: `src/bongos/module-entitlements.js` (`grantEntitlement`, `recordAcquired`, `revokeEntitlement`, `checkEntitlement`, `listEntitlements`). Read routes (own-scoped, `requireBuilder`): `GET /store/entitlements`, `GET /store/modules/:key/entitlement`. Install (task 1003785) grants a free module through `POST /store/modules/:key/acquire`; the buy action (area 8) will grant a paid one.
 
@@ -312,18 +313,18 @@ Bongos views: `claimable_tasks` (rebuilt in 006 to use SELECT t.*; rebuilt again
 **Bongos API (`/api/bongos/*`, 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 older CLI binaries, the cached status mirror, and older instances 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/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/bongos` 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`, **generated from the live route files** by `scripts/bongos/gen-api-docs.js` (reusing the same `route-rank-check.js` introspection the ship-time rank gate uses — so it can't drift). Since task 1004866 the spec, the reference and the typed client are **gitignored**: `package-core.js` generates them into every core tarball (and refuses to build if that fails), `serve-internal.js` generates `/docs/openapi.json` and `/lib/bongos-client.js` in-process when the files are absent, and fitness proves generation succeeds. A rendered docs site (vendored Redoc) is served at **`/docs`** on the apex of every instance (`cloudbongos.com/docs` canonical); `GET /api/bongos` returns a machine-discovery index pointing at it. The generated `docs/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`.
 - 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).
-- Module store publish (ADR 0338 D1, task 1004271): `POST /store/modules/:key/versions` (`requireBuilder` + `requirePermission('module.submit')`, Metic floor). The body is the raw gzip tarball `bongos module publish` builds (own `express.raw` parser, 5 MB cap; 16 MB / 2000 files unpacked). `scripts/gds/module-artifact.js` re-verifies every hash and the publish gate, then `src/bongos/module-store.js` keeps the file under the INSTANCE root's `var/module-store/` (`MODULE_STORE_DIR` overrides; never inside the installed core package, which every upgrade replaces, and a boot move carries files from that old path, task 1004399) and inserts the `store_module_versions` row in one transaction. The first publish makes the caller the author; later versions are author-only, newer than the last and never overwritten; a delisted key takes none.
+- Module store publish (ADR 0338 D1, task 1004271): `POST /store/modules/:key/versions` (`requireBuilder` + `requirePermission('module.submit')`, Metic floor). The body is the raw gzip tarball `bongos module publish` builds (own `express.raw` parser, 5 MB cap; 16 MB / 2000 files unpacked). `scripts/bongos/module-artifact.js` re-verifies every hash and the publish gate, then `src/bongos/module-store.js` keeps the file under the INSTANCE root's `var/module-store/` (`MODULE_STORE_DIR` overrides; never inside the installed core package, which every upgrade replaces, and a boot move carries files from that old path, task 1004399) and inserts the `store_module_versions` row in one transaction. The first publish makes the caller the author; later versions are author-only, newer than the last and never overwritten; a delisted key takes none.
 - Module store install (ADR 0338 D1, task 1003785), all `requireBuilder` and own-scoped (the holder is the caller): `POST /store/modules/:key/acquire` (`{version?}`; grants a free entitlement — no price row, or a zero price, is free — or `402 payment_required` for a priced module; refuses a delisted one), `GET /store/modules/:key/versions/:version/tarball` (served only to a live entitlement holder; `X-Tarball-Sha256`), `POST /store/modules/:key/acquired` (`{version}` → `recordAcquired`). Read side in `src/bongos/module-store.js` (`resolveAcquirable`, `isFreePrice`, `versionArtifactFile`). No channel check yet (tasks 1003815, 1003805). `bongos module update` (task 1003786) reuses the same three calls; the acquire route reads price only for a caller with no entitlement, so a holder is never charged again.
 - Module store delist (ADR 0338 D2, task 1003797): `POST /store/modules/:key/delist` (`requireBuilder` + `requirePermission('module.delist')`, Metic floor, granted by `government_022`; strict body `{reason}`, reason required, recorded by the audit middleware). Sets `store_modules.status='delisted'` and `delisted_at` — one-way, no relist route. Every store read already refuses a delisted key (acquire, tarball, acquired, publish), while `GET /store/modules/latest` still answers with the status so `bongos upgrade` warns the holder. `GET /modules` sets `store_delisted` on an instance-tree module the store delisted (hall pill "delisted · no more updates"), and `bongos module list` marks it DELISTED (fail-soft store check, instance modules only). Never revokes an entitlement, never reaches an installed copy, never writes a score (ADR 0359). 404 unknown key, 409 `already_delisted`.
 - Server-mediated branch publish (ADR 0055 / [#1025](https://example.com/builders#/task/1025) — lets a checkout with no GitHub push credential ship). Owner-gated like ship: `POST /tasks/:id/publish-branch` (`requireBuilder` + `gateTaskOwnership`; 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). `branch` is optional: without it the server finds the task's own PR by its `task <id>: …` title, and the answer names the `branch` it used and its `branch_source` (`query` / `task_pr`, or `null` with a `branch_hint` when there is no such PR) — never a `400` (task 1003764). When the PR is still open it also carries `merge_driver`, whose `reason` says why it has not merged; on a red PR `failing_tests` names the failing unit tests (read from the `unit-report` commit status the `unit` workflow posts) and `checks_unreadable: true` says the check list is blind because the App lacks `Checks: read` — so an empty `checks[]` is never read as "nothing failed" (task 1003988, ADR 0301). Because the server's credential is the PR's AUTHOR, publish also **assigns the PR to the task's claim holder** and names them in the body (`modules/lifecycle/pr-assign.js`, task 1003991) — best-effort: the 201 carries `pr_assignee` (the login, or `null` when GitHub would not assign it) and a failed assignment never fails the publish. `ship.js` uses these in `ci` mode only when `pushVia()` resolves to server (no authenticated `gh` on the machine, or `<PREFIX>_PUSH_VIA_SERVER=1`); a machine 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/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 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 delivery) is extended to also deliver the decrypted own key, which `scripts/bongos/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`.

package/docs/canonical-permissions.md

@@ -94,7 +94,7 @@ forming the ordered claim-gate tier **`xenos` (1) < `thetes` (2) < `metic` (3) <
   deliberate Archon promotion.
 - **`xenos`** — the **sandboxed entry rank** every new GitHub-authed builder defaults to (migration
   029 flipped the column default here). Read-only on public surfaces; may claim + ship **only** tasks
-  an Archon (or the newcomer-generator) has flagged `newcomer_friendly = true` (enforced in
+  an Archon has flagged `newcomer_friendly = true` (enforced in
   `db.claimTask` / `claimTasksBatch`, returns `rank_too_low_for_task`). Cannot triage, resolve
   blockers, or run planning/priority sessions. This is also the tier a deactivated/offboarded builder
   is dropped to by `/builder-exit` (migration `025`); for them `status='inactive'` additionally blocks
@@ -310,9 +310,9 @@ pre-merge gate misses, independent of the builder's cooperation:
   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/0165-instances-hookless-by-default.md)); the graded
-  pipeline pushes only via `scripts/gds/push-main.js` (which carries the `<PREFIX>_ALLOW_MAIN_PUSH`
+  pipeline pushes only via `scripts/bongos/push-main.js` (which carries the `<PREFIX>_ALLOW_MAIN_PUSH`
   override — `BONGOS_ALLOW_MAIN_PUSH` on a vanilla instance). 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
+  (`scripts/bongos/main-audit.js`) — nightly and as the `~/deploy.sh` deploy gate — which is the
   authoritative layer (it reads the real git history + real ranks, independent of the builder).
 - **The pre-push hook fails OPEN by contract, and the wrapper is what enforces that** (task 1002725).
   The gate exits **13** — and only 13 — when it *deliberately* blocks; `.husky/pre-push` turns that
@@ -351,7 +351,7 @@ identity. Use `req.builder.*` server-side, the active session client-side, `$HOM
   project's history.
 - **Infra config, not impersonation:** the droplet's operational identity (`User=lars`,
   `lars@REDACTED_IP`, `/home/lars/example`, `lars@example.com`).
-- **Enforcement:** [`scripts/gds/audit-authorship.sh`](../scripts/gds/audit-authorship.sh) — exits 0
+- **Enforcement:** [`scripts/bongos/audit-authorship.sh`](../scripts/bongos/audit-authorship.sh) — exits 0
   clean, exits 1 with a hit list + remediation hints if a new hardcode shows up. Runs on every PR
   inside the required `unit` check via `tests/authorship_audit.mjs` (task 1002640 — it previously had
   no caller and its exclusions had rotted to 342 stale hits). State clean (0 hits) as of that rewire.