@bongos/core 1.18.3 → 1.18.18

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`. -->
 
-# GDS API reference
+# Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 245 endpoints across 41 route files.
+> **Generated from the live route files** — the route file is authoritative. 258 endpoints across 42 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`.
@@ -34,7 +34,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 |---|---|---|---|---|
 | GET | `/api/bongos/audit-log` | `archon` | — | GET /api/gds/audit-log?limit=&offset=&builder_id=&method= Paginated, newest-first. |
 
-## `auth` (16)
+## `auth` (18)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -42,6 +42,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/auth/app-pair/info` | `any-builder` | — | read-only: what the approve page shows BEFORE the click (device name/platform for the given code). |
 | POST | `/api/bongos/auth/app-pair/poll` | `public` | `poll_token` | poll with the secret poll_token; the token IS the bearer (mirrors /auth/device/poll, where the device_code is the bearer). |
 | POST | `/api/bongos/auth/app-pair/start` | `public` | `device_name`, `platform` | starts a pairing; returns opaque codes only, no identity. |
+| POST | `/api/bongos/auth/backchannel-logout` | `public` | `logout_token` | POST /auth/backchannel-logout — the INSTANCE side of federated single-logout (ADR 0144, task 1002238). |
 | POST | `/api/bongos/auth/cli-token/issue` | `any-builder` | — | POST /auth/cli-token/issue — V3.R91 / task 401. |
 | POST | `/api/bongos/auth/device/exchange` | `public` | `assertion` | POST /auth/device/exchange — CLI federation (ADR 0141 §1). |
 | POST | `/api/bongos/auth/device/poll` | `public` | `device_code` | auth flow; the device code itself is the bearer. |
@@ -52,6 +53,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/auth/logout` | `any-builder` | — | own session, no rank gate (a Xenos can log themselves out). |
 | POST | `/api/bongos/auth/revoke` | `archon` | `session_id` | POST /auth/revoke — V3.R38 / task 259. |
 | POST | `/api/bongos/auth/revoke-all` | `archon` | `builder_id` | POST /auth/revoke-all — V3.R38 / task 259. |
+| GET | `/api/bongos/auth/web/admission-status` | `public` | — | GET /auth/web/admission-status?login=X — the probe renderAccessPendingPage polls (task 1002097). |
 | GET | `/api/bongos/auth/web/callback` | `public` | — | OAuth callback; the state cookie + code are the bearer. |
 | GET | `/api/bongos/auth/web/start` | `public` | — | /auth/web — browser flow (used by the /builders page). |
 
@@ -78,7 +80,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/blockers/:id/link` | `metic+archon` | `task_id` | Link an existing blocker to a task (puts the task in 'blocked' status if it's currently 'backlog' or 'ready'). |
 | POST | `/api/bongos/blockers/:id/resolve` | `metic+archon` | `resolution_note` | Resolve. |
 
-## `box` (17)
+## `box` (18)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -92,6 +94,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/box/host-keys` | `any-builder` | `host_keys` | POST /box/host-keys — the box publishes its own PUBLIC SSH host keys (task 1187 / idea 235). |
 | GET | `/api/bongos/box/managed-settings` | `any-builder` | — | GET /box/managed-settings — the caller's Claude Desktop managed-settings.json. |
 | GET | `/api/bongos/box/me` | `any-builder` | — | GET /box/me — the caller's own box. |
+| GET | `/api/bongos/box/scope` | `any-builder` | — | GET /box/scope — the credential-FREE companion to /box/source-access (BV1.R100 / goal 1000051). |
 | GET | `/api/bongos/box/source-access` | `any-builder` | — | GET /box/source-access — the box fetches its rank-scoped clone spec + the credential to pull it (ADR 0031 §6, task 600). |
 | GET | `/api/bongos/box/ssh-key` | `any-builder` | — | GET /box/ssh-key — list the caller's registered keys. |
 | POST | `/api/bongos/box/ssh-key` | `any-builder` | `public_key`, `label` | POST /box/ssh-key — register the caller's own public SSH key. |
@@ -223,14 +226,15 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 |---|---|---|---|---|
 | GET | `/api/bongos/healthz` | `public` | — | liveness probe; status.example.com hits this anonymously. |
 
-## `inbox` (4)
+## `inbox` (5)
 
 | 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` | 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). |
-| PATCH | `/api/bongos/inbox/:id` | `metic+archon` | `status`, `kind`, `promoted_to_task_id`, `reviewed_at` | Metic+ (task 360 / ADR 0018): idea triage (promote/discard/merge) shapes the backlog. |
+| PATCH | `/api/bongos/inbox/:id` | `metic+archon` | `status`, `kind`, `promoted_to_task_id`, `reviewed_at`, `merged_into_idea_id`, `triage_note` | Metic+ (task 360 / ADR 0018): idea triage (promote/discard/merge) shapes the backlog. |
+| POST | `/api/bongos/inbox/:id/ratify` | `archon` | `notes_md` | V3.R31 (task 252) — Archon ratifies a criterion-proposal idea, atomically: - INSERT done_when_criteria row on the target version - UPDATE… |
 
 ## `instance` (1)
 
@@ -290,13 +294,15 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/me/wandering` | `any-builder` | — | Per-builder "wandering" level (task 1268, migration 119). |
 | PATCH | `/api/bongos/me/wandering` | `any-builder` | _undocumented_ | PATCH the wandering level. |
 
-## `memory` (7)
+## `memory` (9)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/memory/bfg/builders/:builderId/file` | `bfg-principal` | — |  |
 | GET | `/api/bongos/memory/bfg/builders/:builderId/files` | `bfg-principal` | — |  |
 | POST | `/api/bongos/memory/builders/:builderId/bfg-write` | `bfg-principal` | `kind`, `slug`, `title`, `body_md`, `rationale`, `karma_delta` | ----------------------------------------------------------------------- BFG CROSS-BUILDER WRITE (task 446 / ADR 0026 §6C) — the FIRST cro… |
+| GET | `/api/bongos/memory/builders/:builderId/file` | `archon` | — | GET /memory/builders/:builderId/file?path=... |
+| GET | `/api/bongos/memory/builders/:builderId/files` | `archon` | — | GET /memory/builders/:builderId/files — Archon lists ANOTHER builder's memory file metadata. |
 | GET | `/api/bongos/memory/file` | `any-builder` | — | GET /memory/file?path=... |
 | DELETE | `/api/bongos/memory/file` | `any-builder` | validated | DELETE /memory/file?path=... |
 | GET | `/api/bongos/memory/files` | `any-builder` | — | GET /memory/files — list the AUTHENTICATED builder's memory files (metadata only, no content). |
@@ -393,13 +399,20 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/search` | `any-builder` | `expand`, `q`, `source_kind`, `limit` | POST /search — two modes (ADR 0095 C1 / task 1658, progressive disclosure): 1. |
 | POST | `/api/bongos/search/mark` | `any-builder` | `chunk_id`, `useful` | POST /search/mark — the write half of the memory-usefulness feedback loop (ADR 0095 C3, task 1660). |
 
-## `security` (3)
+## `security` (10)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
+| GET | `/api/bongos/security/adr` | `metic+archon` | — | GET /api/gds/security/adr Metic+ only. |
 | GET | `/api/bongos/security/docs` | `archon` | — | GET /api/gds/security/docs — list doc METADATA (no content). |
 | POST | `/api/bongos/security/docs` | `archon` | `slug`, `title`, `content_md` | POST /api/gds/security/docs — upsert a doc by slug. |
 | GET | `/api/bongos/security/docs/:slug` | `archon` | — | GET /api/gds/security/docs/:slug — one doc WITH content, or 404. |
+| GET | `/api/bongos/security/reports` | `archon` | — | GET /api/bongos/security/reports?status=<status> Archon-only, newest-first. |
+| POST | `/api/bongos/security/reports` | `metic+archon` | `target`, `severity`, `title`, `description`, `repro_steps_md` | POST /api/bongos/security/reports — file a new vulnerability report. |
+| POST | `/api/bongos/security/reports/:id/confirm` | `archon` | `drachmae_awarded` | POST /api/bongos/security/reports/:id/confirm Body: { drachmae_awarded?: integer } — defaults to the severity tier bounty if omitted. |
+| POST | `/api/bongos/security/reports/:id/dispute` | `archon` | — | POST /api/bongos/security/reports/:id/dispute Marks the report disputed and clears drachmae_awarded. |
+| POST | `/api/bongos/security/reports/:id/fix` | `archon` | — | POST /api/bongos/security/reports/:id/fix Marks the report fixed and stamps fixed_at. |
+| POST | `/api/bongos/security/reports/:id/link-fix` | `archon` | `task_id` | POST /api/bongos/security/reports/:id/link-fix Body: { task_id: integer } — attaches a fix-task FK. |
 
 ## `session` (1)
 
@@ -436,7 +449,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/tasks` | `metic+archon` | `version_id`, `title`, `description`, `status`, `touches`, `est_minutes`, `est_cost_usd`, `manual_degree`, `priority`, `automation_tag`, `credits_reward`, `source`, `source_ref`, `value_summary`, `kind`, `discipline`, `parallel_safe`, `newcomer_friendly`, `security_sensitive`, `requires_rank`, `auto_detect_touches`, `criterion_ids`, `module_key`, `goal_id` | Task create/promote/edit (plan/scope mutation) is Metic+ as of ADR 0090 (owner decision 2026-06-26): a Metic who can run idea-triage may … |
 | GET | `/api/bongos/tasks/:id` | `any-builder` | — | single-task read; preserved per CRITICAL §4 (supervisor hot path). |
 | PATCH | `/api/bongos/tasks/:id` | `metic+archon` | `kind`, `discipline`, `requires_rank`, `module_key`, `goal_id`, `parent_task_id`, `parallel_safe`, `newcomer_friendly`, `xenos_claimable`, `security_sensitive`, `automation_tag` | PATCH /tasks/:id — supports body.parent_task_id (V2 C2), body.kind (V2 B1), body.discipline (mig 014), body.parallel_safe (mig 028), and … |
-| POST | `/api/bongos/tasks/:id/abandon` | `archon` | `reason` | POST /tasks/:id/abandon — terminal "retire this task" transition (task 987). |
+| POST | `/api/bongos/tasks/:id/abandon` | `metic+archon` | `reason` | POST /tasks/:id/abandon — terminal "retire this task" transition (task 987). |
 | POST | `/api/bongos/tasks/:id/attest-gate` | `any-builder` | `head_sha` | POST /tasks/:id/attest-gate — body: { head_sha }. |
 | POST | `/api/bongos/tasks/:id/confirm` | `any-builder` | `verified` |  |
 | GET | `/api/bongos/tasks/:id/criteria` | `any-builder` | — | GET /tasks/:id/criteria — the criteria this task gates (with live "Cn" + source). |
@@ -467,7 +480,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/versions` | `public` | — | read-only version list; mirrors /public/versions. |
 | POST | `/api/bongos/versions` | `archon` | `id`, `name`, `status`, `done_when`, `scope_doc_path`, `criteria` | POST /versions — create a version + its done-when criteria in one call. |
 | GET | `/api/bongos/versions/:id/done-when` | `public` | — | Public: status.example.com fetches this every 60s alongside other public/* surfaces. |
-| POST | `/api/bongos/versions/:id/done-when` | `archon` | `criterion_id`, `criterion_md`, `goal_id`, `sort_order` | Auth (Archon): create a done-when criterion at RUNTIME. |
+| POST | `/api/bongos/versions/:id/done-when` | `metic+archon` | `criterion_id`, `criterion_md`, `goal_id`, `sort_order` | Auth (Metic+, then the goal's own authority): create a done-when criterion at RUNTIME. |
 | GET | `/api/bongos/versions/:id/progress` | `public` | — | Per-criterion progress rollup: each done-when criterion → the tasks that gate it (task_criteria, migration 055) → live statuses → what re… |
 | GET | `/api/bongos/versions/close-suggestions` | `public` | — | Close-flow gate suggestions for every version still 'building'. |
 | GET | `/api/bongos/versions/progress` | `public` | — | read-only progress aggregate; mirrors /public/progress. |

package/docs/architecture.md

@@ -108,11 +108,13 @@ tasks(id, version_id, title, description, status, touches text[], est_minutes, e
       promoted_at, shipped_at, shipped_by, value_summary, created_at, updated_at)
   status ∈ {backlog, ready, active, blocked, completed, confirmed, shipped, abandoned}
     completed = builder declared done (Phase 5 / 2026-05-10)
-    confirmed = scanner+smoke passed AND quality grader >= threshold; credits awarded
+    confirmed = scanner+smoke passed AND quality grader >= threshold; verified, NOT yet paid
                 (task 197 / 2026-05-12 — grader is a hard gate; on grader fail the task
                  stays at completed, no credits, builder can manual-confirm via POST
                  /tasks/:id/confirm if they think the grade is wrong)
-    shipped   = merged to main + deployed
+    shipped   = merged to main + deployed; credits awarded here (credit_log.reason =
+                'task.shipped' — ADR 0120 pays on land, not on confirm; which streams
+                actually pay depends on the instance reward mode, ADR 0146)
   indexes: (version_id, status), (priority), GIN(touches)
 task_blockers(task_id, blocker_ref)            -- markdown anchors are canonical
 claims(id, task_id, builder_id, worktree_name, claimed_at, released_at, outcome)

package/docs/branding-contract.md

@@ -25,6 +25,7 @@ env override   →   instance config (config/branding.json)   →   neutral star
 | `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.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. |
 | `domains.provisioningOrigin` | **Optional.** Control-plane front-door origin the [provisioning module](../../modules/provisioning/CLAUDE.md) uses to build a new customer's GitHub-App `redirect_url`. Set it when the control plane co-hosts a game whose `publicOrigin` is the game's own domain (OTB = customer 0) so the customer's App carries the PLATFORM brand (e.g. `https://get.cloudbongos.com`), not the game's. **Falls back to `publicOrigin` when unset** — an instance whose `publicOrigin` is already the platform needs no override. Env-overridable: `<PREFIX>_PROVISIONING_ORIGIN`. ([#2101](https://example.com/builders#/task/2101)) |
@@ -34,11 +35,12 @@ env override   →   instance config (config/branding.json)   →   neutral star
 | `repo` | `{ owner, name }` GitHub binding. |
 | `db.database` | DB name the GDS 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 }` — the per-instance reward POLICY the economy module reads ([ADR 0054](adr/<redacted>.md), task 2009): the cost-plus margin percent (default `20`) and the example-per-USD peg (default `1`). A committed, code-reviewed change — not a live UI knob. Omit ⇒ code defaults (20% margin, 1:1 peg). |
+| `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). |
 | `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 }` — palette file ref + theme mode. |
 | `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 (`OTB`, `CLOUDBONGOS`, …). |
 
 **Not here:** feature-module on/off flags (game, art, discord, dev-box) are a sibling config owned by R54 (task [#1193](https://example.com/builders#/task/1193)).

package/docs/canonical-permissions.md

@@ -56,7 +56,9 @@ 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). Top authority: everything a
-  Metic can do, plus grader-bypass confirm, abandon a task, set version scope (`done-when`),
+  Metic can do, plus grader-bypass confirm, set **version-level** scope (a `done-when` criterion with no
+  `goal_id`, any criterion outside an open version or outside a goal they own, and `done-when/:id/unsatisfy`
+  — [ADR 0154](adr/<redacted>.md)),
   grant/revoke ranks, offboard builders, version close, infra. Overrides any claim. The authority that
   stays *exclusively* Archon — never delegated to Metic — is **setting rank** (`PATCH /builders/:id/rank`)
   and **closing versions**.
@@ -66,8 +68,10 @@ forming the ordered claim-gate tier **`xenos` (1) < `thetes` (2) < `metic` (3) <
   (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. **Still cannot** set rank, close versions,
-  abandon a task, grader-bypass confirm, or author cross-tier `POST /dependencies` / goal-scope edges
+  *triage* ideas is trusted to *seed* the work they become. **As of [ADR 0152](adr/<redacted>.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
   only by deliberate Archon promotion (`PATCH /builders/:id/rank`).
 - **`thetes`** — the **graduated-newcomer rank** (ADR 0034). Claims the **whole general queue** — any
@@ -123,12 +127,13 @@ silently *lost* all archon-gated authority — while still denying everything be
 or missing ranks fail closed.
 
 - **Archon-only** — ratification / scope / infra: `POST /api/gds/tasks/:id/confirm` (grader-bypass past
-  a failed grade), `POST /api/gds/tasks/:id/abandon` (terminal scope removal),
-  `POST /api/gds/done-when/:id/unsatisfy`, `PATCH /api/gds/builders/:id/{rank,status}`, and the
+  a failed grade), `POST /api/gds/done-when/:id/unsatisfy`, `PATCH /api/gds/builders/:id/{rank,status}`, and the
   cross-tier `POST|DELETE /api/gds/dependencies` + goal-scope edges ([ADR 0086](adr/<redacted>.md)).
   **Task authoring itself — `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)** (see the Metic+Archon bullet).
+  CRUD — moved to Metic+ in [ADR 0090](adr/<redacted>.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).
   Setting rank and closing versions never delegate below Archon. **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
   `400 multi_rung_promotion` naming the next allowed rung. Demotions are unconstrained (offboarding
@@ -138,7 +143,12 @@ or missing ranks fail closed.
   [ADR 0090](adr/<redacted>.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)). The floor here is
+  [ADR 0086](adr/<redacted>.md)). Since
+  [ADR 0154](adr/<redacted>.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/roles). Version-level criteria and
+  `done-when/:id/unsatisfy` stay Archon. 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.
 - **Any authenticated builder** — own work: claim/ship/cost/learnings/file-blocker/file-idea. Two
@@ -196,7 +206,10 @@ Authority over *the code itself* rides the same ladder, enforced server-side fro
 ADR 0016's per-request rank check covers `/api/gds/*` only. Two surfaces it does **not** cover —
 `git push` to `main` and `ssh` to the droplet — were used in the Builder 25 incident to land an
 un-graded tiering change straight on prod `main`. The repo is a free-plan private repo, so GitHub
-branch protection is unavailable; the enforcement is therefore code-side, in three layers (ADR 0043):
+branch protection is unavailable; the enforcement is therefore code-side, in three layers (ADR 0043).
+**Verified still true 2026-07-24** — no classic protection, no rulesets, no CODEOWNERS, and a
+non-admin merged PR #19 to `main` with zero required checks; see ADR 0043 §"Branch-protection status"
+for the probes. `main-audit.js` is therefore still the *authoritative* layer, not a backup one:
 
 - A builder **below Metic** (`xenos`, `thetes`) may **not modify permission-sensitive paths** — the
   rank/authz machinery, the ship/grade/deploy pipeline, DB `migrations/`, `infra/`, and the

package/docs/file-map.md

@@ -36,6 +36,8 @@
 ├── brand/                       ← repo-canonical design system (ADR 0081)
 │   └── cloud-bongos/            ← Cloud Bongos brand: README design guide + tokens.json + regen_*.py + assets/ (mascot, 9 animation states, Docker-homage sky-whale, coin logo + Baloo 2 wordmark, painted code-glyph charms). Built under task 1506 (mascot restyle 1529, code glyphs 1527); illustrations generated via Gemini (modules/art-pipeline/pipeline gen_api).
 │
+├── config/                      ← per-instance config packs. Each pair resolves env → `X.json` (this host's, boundary-excluded) → `X.neutral.json` (the portable starter, the twin that publishes with the core): branding (ADR 0062 §3), modules, design-tokens, and governance role templates (BV1.R96 — labels/descriptions/custom-role templates only; live grants + assignments are DB rows).
+│
 ├── docs/
 │   ├── adr/                     ← Architecture Decision Records
 │   │   ├── README.md            ← full ADR index (authoritative)
@@ -151,6 +153,8 @@
 │       ├── sandbox-stage.js     ← stage the working tree on the live game preview (box OR local) for browser review before ship; resolvePreviewContext picks the context (`/builder-stage`; #927, ADR 0046; local: task 1056)
 │       ├── local-preview.js     ← builder CLI for the LOCAL sandbox: start/stop/status/restart/logs/url of the game-only preview at http://localhost:3100 (`npm run preview`; task 1056)
 │       ├── local-preview-lib.js ← core of the local sandbox launcher (detached `node src/preview-server.js`, pid/health/port mgmt); shared by local-preview.js + sandbox-stage.js (task 1056)
+│       ├── dev.js               ← `bongos dev`: one-command LOCAL launcher for a standalone instance (Postgres → createdb → migrate → server on the branding port → sign-in); up/stop/status (ADR 0149)
+│       ├── dev-lib.js           ← pure + injectable core of `bongos dev` (branding→port/db/env resolution, managed detached server pid/health); unit-tested by tests/dev_lib.mjs (ADR 0149)
 │       ├── session-eval.js      ← BFG session-inefficiency analysis engine (6D.3): classify turns, compute ceremony-vs-work, detect footguns, file systemic findings (ADR 0027)
 │       ├── linkify-refs.js      ← rewrite bare `#NNN` task refs across ALL docs → status-dashboard permalinks (stops GitHub's PR/issue autolinker mis-linking them); conservative classifier, token-free id list via /public/ref-ids; --apply / --check (CI gate: .github/workflows/doc-ref-linkify.yml) / --dry-run default ([#604](https://example.com/builders#/task/604), [#653](https://example.com/builders#/task/653)).
 │       ├── release.js           ← resolve claim as abandoned (`/builder-release`)
@@ -330,15 +334,19 @@ tests/
 ├── builder-reauth/SKILL.md        ← /builder-reauth — refresh an expired GDS CLI session the UI-first way (no terminal Device Flow)
 ├── builder-redteam/SKILL.md       ← /builder-redteam — file a red-team / vulnerability report (severity, target, repro) to /api/gds/security
 ├── builder-release/SKILL.md       ← /builder-release — abandon a claim (task returns to ready, no credits)
+├── builder-sequence/SKILL.md      ← /builder-sequence N — walk a whole dependency chain from one kickoff (claim → build → ship → next), one claim at a time; halts and reports on migration/security/protected-path/thin-spec/judgement tasks (scripts/gds/sequence.js, task 1002484)
 ├── builder-setup/SKILL.md         ← /builder-setup — one-time GitHub Device Flow auth (GDS); multi-builder-on-one-device gate
 ├── builder-ship/SKILL.md          ← /builder-ship — record + award credits (runs touches[] scanner; warns on drift; sandbox-first review gate on dev boxes, ADR 0046)
 ├── builder-stage/SKILL.md         ← /builder-stage — stage work on the builder's sandbox (sandbox-<login>) for browser review before shipping (#927, ADR 0046)
 ├── builder-start/SKILL.md         ← /builder-start — list claimable tasks (parallel-safe vs active claims)
+├── builder-sync/SKILL.md          ← /builder-sync — 'sync now': re-run the box source-fetch on demand so a freshly-claimed task's code lands within seconds, re-scoped to the active claim (BV1.R96, ADR 0148)
 ├── close-box/SKILL.md             ← /close-box — tear down the dev box you're working on, from inside the box terminal (POST /box/close)
 ├── design-sync/SKILL.md           ← /design-sync — export repo design tokens + surfaces into Claude Design (token-preview bundle) and land generated UI code back as a GDS task (ADR 0081)
 ├── dev/SKILL.md                   ← /dev — engineering-session playbook for engineer-discipline tasks; the default understand→scoped-change→verify→ship loop made explicit ([#1272](https://example.com/builders#/task/1272))
 ├── feedback/SKILL.md              ← /feedback — pull the latest Bongos feedback bundle (prompt.md + screenshot file paths) into a Claude Code session; backed by scripts/gds/feedback-latest.js (BV1.R13, ADR 0087)
 ├── figma-design-sync/SKILL.md     ← sync UI-surface tokens/surfaces with Figma (push a frame plan, land a designer's Code Connect / MCP snapshot edit back as code) — the ADR 0081 human escape hatch; distinct from otb-figma-sync's pixel-art tile review (task 2048)
+├── fix-task/SKILL.md              ← /fix-task N — claim, fix (test-first), verify, and ship a single GDS task by id end to end; defers to /builder-claim + /builder-ship for their own mechanics
+├── goal-create/SKILL.md           ← /goal-create — plan and create ONE goal (the module-scoped workspace between version and criteria, ADR 0086) in one session: <redacted>, scope wall, 2-4 criteria, seed tasks; also the auto-pickup when a task is created with no goal to live in (goal_advisory); Metic+ (Archon for a protected-module scope)
 ├── goal-review/SKILL.md           ← /goal-review — walk the criterion review queue: each auto-flagged 'met — pending review' criterion gets confirm / reject / defer; confirming a goal's last criterion auto-achieves it (ADR 0086 §6); Metic+
 ├── idea-triage/SKILL.md           ← /idea-triage — daily walk through the GDS idea_inbox (promote / discard / merge); Metic+
 ├── ideate/SKILL.md                ← /ideate — ideation-session playbook for ideator-discipline tasks; inverts the loop (human drives, Claude is the sounding board) ([#1267](https://example.com/builders#/task/1267))

package/docs/onboarding/diagrams/01-task-lifecycle.mmd

@@ -9,8 +9,8 @@ stateDiagram-v2
     blocked --> active: blocker resolved
     active --> ready: /builder-release (no credits)
     active --> completed: /builder-ship: declared done + smoke tests
-    completed --> confirmed: grader passes  ◀ CREDITS AWARDED HERE
-    confirmed --> shipped: CI + gate-review → auto-merge + deploy
+    completed --> confirmed: grader passes  (verified — not yet paid)
+    confirmed --> shipped: CI + gate-review → auto-merge + deploy  ◀ CREDITS AWARDED HERE
     backlog --> abandoned: dropped
     shipped --> [*]: live in production
     note right of confirmed

package/docs/onboarding/diagrams/02-rank-ladder.mmd

@@ -31,7 +31,7 @@ flowchart TB
     subgraph B_outsider["Outsider / sub-citizen — sandboxed"]
         direction TB
         r_metic["● metic — LIVE"]
-        r_thetes["○ thetes — reserved"]
+        r_thetes["● thetes — LIVE"]
         r_metic --> r_thetes
         r_xenos["● xenos — default for new builders, LIVE"]
         r_thetes --> r_xenos
@@ -47,8 +47,10 @@ flowchart TB
         direction TB
         P_archon["archon: create/promote/PATCH tasks · version close · grant ranks · override claims"]
         P_metic["metic: claim any task · idea triage · blocker review · planning/priority · file red-team; CANNOT create tasks or grant ranks"]
+        P_thetes["thetes (auto-graduated after 3 ships): claim the whole general queue; NO scope-shaping — cannot triage, file red-team, resolve blockers, or create/edit tasks"]
         P_default["xenos (default): claim ONLY newcomer_friendly tasks + ship/release OWN work · log cost · capture learnings · file blockers+ideas; CANNOT create/edit tasks or touch others' claims"]
     end
     r_archon -.-> P_archon
     r_metic -.-> P_metic
+    r_thetes -.-> P_thetes
     r_xenos -.-> P_default

package/docs/onboarding/diagrams/05-versioning.mmd

@@ -7,14 +7,12 @@ flowchart TB
     POOL --> VERSIONS
     subgraph VERSIONS["Every task inherits its version; role/discipline is the work-type axis"]
         direction TB
-        v_V1["V1 — building"]
         v_PMS_V1["PMS-V1 — shipped"]
-        v_V1 --> v_PMS_V1
         v_PMS_V2["PMS-V2 — shipped"]
         v_PMS_V1 --> v_PMS_V2
         v_GDS_V3["GDS-V3 — shipped"]
         v_PMS_V2 --> v_GDS_V3
-        v_GDS_V4["GDS-V4 — frozen"]
+        v_GDS_V4["GDS-V4 — shipped"]
         v_GDS_V3 --> v_GDS_V4
         v_BONGOS_V1["BONGOS-V1 — building"]
         v_GDS_V4 --> v_BONGOS_V1

package/docs/onboarding/diagrams/assertions.json

@@ -24,7 +24,8 @@
     "wired_ranks": [
       "archon",
       "metic",
-      "xenos"
+      "xenos",
+      "thetes"
     ],
     "_wired_note": "A rank is 'wired' if it has behavior: it appears in a requireRank(...) call, is the column default, is SET by a migration, or is a key in the live REQUIRES_RANK_TIER claim-gate map (db.js). archon = requireRank + seeded; metic + thetes + xenos = tier-map members (claim-floor comparison); xenos = column default + set on /builder-exit (migration 025); thetes = the auto-graduation target (xenos→thetes after 3 confirmed tasks, #692 / ADR 0034)."
   },
@@ -40,15 +41,11 @@
       "shipped",
       "abandoned"
     ],
-    "credits_awarded_at": "completed->confirmed"
+    "credits_awarded_at": "confirmed->shipped"
   },
   "versioning": {
     "diagram": "05-versioning",
     "versions": [
-      {
-        "id": "V1",
-        "status": "building"
-      },
       {
         "id": "PMS-V1",
         "status": "shipped"
@@ -63,7 +60,7 @@
       },
       {
         "id": "GDS-V4",
-        "status": "frozen"
+        "status": "shipped"
       },
       {
         "id": "BONGOS-V1",

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

@@ -84,13 +84,13 @@ There's a published payout rate-card by severity for red-team / security finding
 
 ### Where in the lifecycle credits land
 
-Example are awarded at the **`completed → confirmed`** edge — when verification (smoke tests, and the grader when it's enabled) passes — **not** at the final ship/deploy. Releasing a task with `/builder-release` pays nothing.
+Example are awarded at the **`confirmed → shipped`** edge — when the code actually lands on `main` and deploys — **not** when verification passes. Passing the grader gets you to `confirmed`, which is verified but *unpaid*; a task that strands there without landing earns nothing until it does ([ADR 0120](../adr/<redacted>.md), "pay on land"). Releasing a task with `/builder-release` pays nothing.
 
 ```
 active ──▶ completed ──▶ confirmed ──▶ shipped
            (declared      (verified —    (merged to main
-            done +          CREDITS        + deployed)
-            smoke)          LAND HERE)
+            done +          NOT yet        + deployed —
+            smoke)          paid)          CREDITS LAND HERE)
 ```
 
 > **Note:** the old up-front `touches[]` *drift scanner* that used to run at ship time is **gone** (task [#879](https://example.com/builders#/task/879), [ADR 0049](../adr/<redacted>.md)). The ship gate is **smoke tests only**; `git merge` at land time is the real collision detector.

package/docs/onboarding/primer.md

@@ -12,11 +12,11 @@ When you're done, open [/builders](https://example.com/builders) and run `/build
 
 This primer teaches the **platform** — how you claim work and ship it, the same on every Cloud Bongos instance. *What* you're building here — the product, its world, and its visual style — is specific to this instance and lives in **[`docs/project-context.md`](../project-context.md)**. Read that first for the product; everything below is the build system you'll use to make it.
 
-## What the GDS is
+## What Bongos is
 
-The **Game Development System** (GDS) is the project's internal nervous system. It's a Postgres-backed task database with a small HTTP API, a CLI (the `/builder-*` slash commands), and a public dashboard at [status.example.com](https://status.example.com). Every change to the project — code, docs, art, migrations, even direct DB writes — happens under a **claim** on a GDS task. The claim is what makes parallel work safe (no two builders editing the same files at once) and what gives credit-tracking, cost-tracking, and the karma system something concrete to hang off.
+**Bongos** is the project's internal nervous system. It's a Postgres-backed task database with a small HTTP API, a CLI (the `/builder-*` slash commands), and a public dashboard at [status.example.com](https://status.example.com). Every change to the project — code, docs, art, migrations, even direct DB writes — happens under a **claim** on a Bongos task. The claim is what makes parallel work safe (no two builders editing the same files at once) and what gives credit-tracking, cost-tracking, and the karma system something concrete to hang off.
 
-You don't need to understand the GDS schema to ship work. You just need to know: *claim a task, work on it inside your worktree, ship it.* The CLI handles the rest.
+You don't need to understand the Bongos schema to ship work. You just need to know: *claim a task, work on it inside your worktree, ship it.* The CLI handles the rest.
 
 ## The claim → ship lifecycle
 
@@ -25,8 +25,8 @@ Every piece of work moves through this loop:
 ```
 backlog ─────▶ ready ─────▶ active ─────▶ completed ─────▶ confirmed ─────▶ shipped
    │             │             │              │                │               │
-   │             │             │              │                │               └─ deployed to example.com
-   │             │             │              │                └─ verification passed, credits awarded
+   │             │             │              │                │               └─ deployed to example.com, credits awarded
+   │             │             │              │                └─ verification passed (not yet paid)
    │             │             │              └─ you said "done", ship.js runs the smoke tests
    │             │             └─ you ran /builder-claim (locks the task to your session)
    │             └─ dependencies all shipped (auto-promoted by a DB trigger)
@@ -37,7 +37,7 @@ You drive the middle three states. The system handles the rest.
 
 **One claim at a time** while you're a Xenos. New builders hold a single active claim — ship it (or release it) before opening another, so the first work gets carried through. The limit is keyed to your rank: it lifts automatically when you graduate to **Thetes** (after your third shipped task), after which you can hold parallel claims if you want.
 
-When you ship, `ship.js` runs the project's **smoke tests** and the quality grader. If they pass, the task auto-confirms and **credits land** (this is the `completed → confirmed` edge — *not* the final deploy). The final `confirmed → shipped` hop — landing on `main` and deploying — is then handled for you, but *what it takes to land* depends on your rank and what you changed; the next section covers it. (There used to be an up-front `touches[]` "drift scanner" here too; it was retired — `git merge` at land time is the real collision detector. See [ADR 0049](../adr/<redacted>.md).)
+When you ship, `ship.js` runs the project's **smoke tests** and the quality grader. If they pass, the task auto-confirms — verified, but **not yet paid**. **Credits land at the final `confirmed → shipped` hop**, when your code actually merges to `main` and deploys ([ADR 0120](../adr/<redacted>.md) — you're paid for landed code, so a branch that never lands never pays). That hop is handled for you, but *what it takes to land* depends on your rank and what you changed; the next section covers it. (There used to be an up-front `touches[]` "drift scanner" here too; it was retired — `git merge` at land time is the real collision detector. See [ADR 0049](../adr/<redacted>.md).)
 
 ## How work lands — and what auto-ships
 
@@ -51,7 +51,7 @@ The one thing that decides whether your ship is **instant** or **waits for an Ar
 | **A protected "gate surface"** — migrations, server routes, the ship / deploy plumbing | Auto-merges **only if you are Metic or above** (rank trust). A Xenos or Thetes ship here **waits for an Archon** to approve. |
 | **The safety core** — the gate's own machinery, the deploy switch, the rank / permission enforcement | **Always** waits for an Archon, whatever your rank. |
 
-So your first tasks **ship with no approval**: the newcomer chores — a tile, a doc fix, a unit test, a batch of ideas — all sit on the safe side of that line, and a clean ship merges and deploys on its own. You only meet the Archon gate if your change reaches into the project's own safety machinery, which builders below Metic are asked to stay clear of anyway ([ADR 0043](../adr/<redacted>.md)). Landing is always the GDS's job: you never run `git push origin main`, `ssh` to the server, or deploy by hand — `/builder-ship` opens the PR and the server does the rest ([ADR 0042](../adr/<redacted>.md)).
+So your first tasks **ship with no approval**: the newcomer chores — a tile, a doc fix, a unit test, a batch of ideas — all sit on the safe side of that line, and a clean ship merges and deploys on its own. You only meet the Archon gate if your change reaches into the project's own safety machinery, which builders below Metic are asked to stay clear of anyway ([ADR 0043](../adr/<redacted>.md)). Landing is always Bongos's job: you never run `git push origin main`, `ssh` to the server, or deploy by hand — `/builder-ship` opens the PR and the server does the rest ([ADR 0042](../adr/<redacted>.md)).
 
 ## The rank ladder
 
@@ -68,9 +68,9 @@ So the sandbox is short: ship three small `newcomer_friendly` tasks and the city
 
 ## Example and karma
 
-Two parallel reputation tracks. You don't need to *do* anything special to earn either — claim a task, do good work, ship it, and the system tracks both. The full mechanics (formulas, the kind table, the budget cap, every karma source) live in **[Example & karma — how you get paid](example-and-karma.md)**; here's the shape of it.
+Two parallel reputation tracks. You don't need to *do* anything special to earn either — claim a task, do good work, ship it, and the system tracks both. The full mechanics (formulas, the kind table, the budget cap, every karma source) live in **[Example & karma — how you get paid](drachmae-and-karma.md)**; here's the shape of it.
 
-- **Example** (called "credits" in code) are your **equity** in the project — a score and a stake, *not* a currency you spend on anything. They only go up, and they persist if you leave and come back. Most of your example now come from a **cost-plus reward on each shipped session**: the server prices the LLM tokens your work actually burned and pays you that real cost **plus 20%** ([ADR 0054](../adr/<redacted>.md)). On top of that, each task pays its `credits_reward` adjusted by the *kind* of work (a captured learning or a resolved blocker is worth 1.5×; cleanup 0.8×), and capturing an idea that someone else then ships earns you a 25% bonus ([ADR 0023](../adr/<redacted>.md)). Credits land at the `completed → confirmed` edge — when verification passes, not at deploy. See the standings on [/builders](https://example.com/builders).
+- **Example** (called "credits" in code) are your **equity** in the project — a score and a stake, *not* a currency you spend on anything. They only go up, and they persist if you leave and come back. Most of your example now come from a **cost-plus reward on each shipped session**: the server prices the LLM tokens your work actually burned and pays you that real cost **plus 20%** ([ADR 0054](../adr/<redacted>.md)). On top of that, each task pays its `credits_reward` adjusted by the *kind* of work (a captured learning or a resolved blocker is worth 1.5×; cleanup 0.8×), and capturing an idea that someone else then ships earns you a 25% bonus ([ADR 0023](../adr/<redacted>.md)). Credits land at the `confirmed → shipped` edge — when your code actually merges and deploys, not when verification passes ([ADR 0120](../adr/<redacted>.md)). Which of those two streams actually pays is per-instance config ([ADR 0146](../adr/<redacted><redacted>.md)): the default pays both, while a `cost-plus-only` instance pays the session reward alone and treats each task's `credits_reward` as an advertised estimate only. See the standings on [/builders](https://example.com/builders).
 
 - **Karma** is a *separate* signal that measures **peer trust** — how other builders rate the *way* you work, not how much you ship. It's earned when Metic-and-above builders upvote your confirmed work (tallied weekly), when a proposal of yours is ratified, and when you capture ideas; it can also go *down* if you break things. Karma shows up on your profile (with a 30-day trend) and as a sortable column on the leaderboard, and it feeds your "builder strength" score. **It does not gate rank promotions** — those happen automatically by ship count (Xenos → Thetes after three ships) or by an Archon's deliberate decision. A builder who ships fast but breaks things gains example and loses karma; a builder who ships thoughtfully gains both.
 
@@ -87,11 +87,11 @@ Claude is your pair-programmer here, but it doesn't know the project until you p
 
 What doesn't work well:
 
-- *"How does the GDS work?"* — too open. Claude will hallucinate or read everything inefficiently.
-- *"What should I work on?"* — ask `/builder-start` instead. That's the GDS's job, not Claude's.
+- *"How does Bongos work?"* — too open. Claude will hallucinate or read everything inefficiently.
+- *"What should I work on?"* — ask `/builder-start` instead. That's Bongos's job, not Claude's.
 - *"Is this safe to ship?"* — ask `/builder-ship` (it runs the smoke tests and, when enabled, the quality grader). Or run `/code-review` if you want a second opinion.
 
-**Use slash commands for plumbing, use Claude for thinking.** The `/builder-*` skills know how to talk to the GDS. Claude knows how to read your code and reason about it. Don't ask Claude to do something a slash command already does — it's slower and less reliable.
+**Use slash commands for plumbing, use Claude for thinking.** The `/builder-*` skills know how to talk to Bongos. Claude knows how to read your code and reason about it. Don't ask Claude to do something a slash command already does — it's slower and less reliable. And when you can't tell whether a command is ours or Claude Code's own, [**slash-commands.md**](slash-commands.md) sorts them apart — including the handful that collide.
 
 ## What the system remembers for you
 
@@ -106,12 +106,13 @@ The map stays light on its own: a session-start guard warns if it's drifting lar
 
 The whole project's source-of-truth index is [`CLAUDE.md`](../../CLAUDE.md). Two starting points:
 
-- **For *what's true right now*** — go to the GDS DB via `/builder-start` or [/builders](https://example.com/builders). Tasks, claims, ranks, credits, costs all live there. CLAUDE.md is *descriptive*; the DB is *authoritative*.
+- **For *what's true right now*** — go to the Bongos database via `/builder-start` or [/builders](https://example.com/builders). Tasks, claims, ranks, credits, costs all live there. CLAUDE.md is *descriptive*; the DB is *authoritative*.
 - **For *why we chose what we chose*** — go to [`docs/adr/`](../adr/) (Architecture Decision Records). Each ADR is one decision with the trade-offs that drove it.
 
 Other depth, in roughly the order you'll need it:
 
-- [`docs/onboarding/example-and-karma.md`](example-and-karma.md) — the full reward economy: how example and karma are earned, the cost-plus session reward, and the monthly budget cap
+- [`docs/onboarding/example-and-karma.md`](drachmae-and-karma.md) — the full reward economy: how example and karma are earned, the cost-plus session reward, and the monthly budget cap
+- [`docs/onboarding/slash-commands.md`](slash-commands.md) — which slash commands ship with Claude Code and which are this project's, and what to do about the ones that collide
 - [`docs/architecture.md`](../architecture.md) — live system: droplet, stack, schema, API surface
 - [`docs/modules-contract.md`](../modules-contract.md) — the product is built as a small core plus swappable `modules/<key>/` (dev boxes, the game, Discord, art, and more); this is the live roster and how a task lands inside one
 - [`docs/canonical-permissions.md`](../canonical-permissions.md) — who can do what (rank gates)
@@ -169,9 +170,9 @@ Take them in order — each one sets up the next, from "I'm admitted" to "I'm lo
    
    Once it finishes, that folder **is** the project. **One catch worth knowing:** the `/builder-*` commands came down *with* the code, but Claude Code only loads them when a session *starts* on a folder that already contains them — and this session started on an *empty* folder. So before the next step, **start a fresh Claude Code session on this same folder**: end this session and open a new one pointing at the folder. (Starting fresh is the clean way — the new session scans the folder from scratch, and the `/builder-*` commands will all be there.)
 
-**4. Enrol yourself and begin.** In the **fresh** session, type `/builder-setup` — or just say *"set up builder"* in plain English — and follow the prompts. It signs you in with GitHub once and registers you in the GDS so the commands know who you are. Then type `/builder-start` to see the works you can claim right now.
+**4. Enrol yourself and begin.** In the **fresh** session, type `/builder-setup` — or just say *"set up builder"* in plain English — and follow the prompts. It signs you in with GitHub once and registers you in Bongos so the commands know who you are. Then type `/builder-start` to see the works you can claim right now.
 
-If a `/builder-*` command ever says "no GDS session," just run `/builder-setup` again — that re-links you. And if `/builder-setup` itself comes back **"unknown command,"** you're almost certainly still in the session that did the cloning — start a fresh session on the folder (end of step 3) and it'll be there.
+If a `/builder-*` command ever says "no Bongos session," just run `/builder-setup` again — that re-links you. And if `/builder-setup` itself comes back **"unknown command,"** you're almost certainly still in the session that did the cloning — start a fresh session on the folder (end of step 3) and it'll be there.
 
 > **Prefer a terminal? (the quicker path if you're technical.)** Steps 3–4 above are the no-terminal route. If you're comfortable on a command line, skip them — clone the repo yourself, `cd` into it, and run the bootstrap:
 >