@bongos/core 1.17.0

package/docs/architecture.md

@@ -0,0 +1,244 @@
+# Architecture — current state
+
+> Split out of `CLAUDE.md` §10 in V3.R86 ([#305](https://example.com/builders#/task/305)) to keep the agent index lean. `CLAUDE.md` §10 now
+> carries a one-paragraph orientation and points here. This file is **descriptive** — for live GDS
+> state (tasks, versions, claims, ranks) the source of truth is the database via `/api/gds/*`, and
+> for permissions specifically see [`docs/canonical-permissions.md`](canonical-permissions.md).
+
+> **For decision rationale (why we chose what), read [`docs/adr/`](adr/). The most relevant: 0001 (stack), 0002 (DigitalOcean), 0003 (Cloudflare cert), 0006 (singleton WorldRoom + queue), 0007 (persistent identity), 0008 (Google Chat OAuth), 0010 (GDS architecture), 0016 (trust boundary).**
+
+**Live & running:**
+
+- **Domain:** `example.com` — registered at Cloudflare Registrar. DNS A records (apex + `www`) point to the droplet at `REDACTED_IP`. Cloudflare proxy is **ON (orange cloud)**. CF terminates TLS at the edge; the **Cloudflare Origin Certificate** handles the CF↔origin leg (valid through 2041-05-04). A `status` subdomain is added at PMS-V1 deploy time (see [`docs/pms-v1-deploy.md`](pms-v1-deploy.md)) with the same proxy/cert posture; Origin Cert needs `*.example.com` SAN. Real client IPs come in via `CF-Connecting-IP` / `X-Forwarded-For`, wired into Caddy's `trusted_proxies static` (the Cloudflare IP ranges) in the `infra/Caddyfile` global options block.
+- **Production droplet (co-hosting box):** DigitalOcean, hostname `example`, IPv4 `REDACTED_IP`, IPv6 `REDACTED_IP`. NYC3, Premium Intel 2 GB / 1 vCPU / 60 GB NVMe. Ubuntu 24.04 LTS. ~$14/mo. Hosts the OTB game + co-hosted project instances (`emersonian-circles.`, `staging.`).
+- **Cloud Bongos control-plane droplet (NEW 2026-07-05, [ADR 0126](adr/<redacted>.md), task [#2063](https://example.com/builders#/task/2063)):** DigitalOcean, hostname `cloudbongos`, IPv4 `REDACTED_IP`, NYC3, `s-1vcpu-2gb` (2 GB / 1 vCPU), Ubuntu 24.04, ~$12/mo, tag `cloudbongos-control`. Runs **cloudbongos.com + `builders.` + `status.`** (`src/platform-server.js`, Cloud Bongos brand, port 3002, own `cloudbongos` DB, checkout `/home/lars/cloudbongos`) and is the **sole token-holding control plane** — `/etc/cloudbongos/box.env` holds the account-wide Cloudflare token (IP-locked to this box) + the DigitalOcean token; this is where `provision.js` provisions instance subdomains. **Structurally separate SSH** (own `cloudbongos_ed25519` key). IPv6 egress disabled so the IPv4-locked CF token can't be spuriously rejected. cloudbongos.com was previously a co-tenant on the co-hosting box; that unit was decommissioned at cutover. **Follow-ups:** deploy automation (task [#2064](https://example.com/builders#/task/2064)) + fully stripping cloud tokens off the co-hosting box (task [#2065](https://example.com/builders#/task/2065)).
+- **Server stack:** Node.js 22 LTS · PostgreSQL 16 · Caddy 2.11.2. `example.service` (systemd) runs `node server.js` as user `lars` on `127.0.0.1:3000`; restart-on-failure.
+- **Hardening:** `lars` user with passwordless sudo; SSH key-only (root login disabled, password auth disabled); ufw allows 22/80/443; fail2ban active; unattended-upgrades enabled; timezone `America/New_York`.
+- **TLS:** Origin cert at `/etc/caddy/origin.crt` + `/etc/caddy/origin.key` for the example apexes on the co-hosting box. **cloudbongos.com's apexes moved to the dedicated control-plane droplet** ([ADR 0126](adr/<redacted>.md)) with their own copy of the Cloudflare Origin Cert (SAN `*.cloudbongos.com, cloudbongos.com`) at `/etc/caddy/cloudbongos-origin.{crt,key}` on `REDACTED_IP`. Cloudflare SSL/TLS mode = Full (strict). Renewal is a non-issue for ~15 years. **Provisioned instance hosts use a different, coexisting posture** ([ADR 0111](adr/<redacted>.md) §4 / task P4): Caddy **on-demand ACME** (Let's Encrypt) via the global `on_demand_tls { ask … }` block, gated to hostnames the `provisioning` module actually stood up (`/api/bongos/provisioning/tls-check`). Their DNS records are **proxied=false (grey cloud)** so the ACME challenge reaches Caddy — the opposite of the origin-cert apexes; do not enable the proxy on them or renewal breaks silently ([ADR 0003](adr/<redacted>.md)). Per-instance site snippets live in `/etc/caddy/sites/*.caddy` (`import`ed by `infra/Caddyfile`). **Tradeoff (accepted, SEC review of task 1945):** `proxied=false` publishes the box's real origin IP in public DNS for every co-tenant provisioned hostname — defeating, for those names, the Cloudflare-proxy IP-hiding the apexes enjoy (a co-tenant host resolves to the same `REDACTED_IP` that serves the main game). This is inherent to on-demand ACME (the challenge must hit the origin) and acceptable under the budget/trust model; prefer a **dedicated droplet** (its own IP) for any instance expected to draw hostile attention.
+- **Platform observability (task 2020 stood it up; task 2059 re-homed it cross-project onto the control-plane box; [ADR 0127](adr/<redacted>.md)):** this watches the **Bongos API** (`gds_http`/`tasks`/`claims`/`builders`/`auth`), not any one game, so it lives **on the control-plane box** (REDACTED_IP) at **`https://metrics.cloudbongos.com`** and observes the **whole fleet**. **Prometheus** (`127.0.0.1:9090`, loopback-only) scrapes every instance's `/metrics` ([`src/bongos/metrics.js`](../src/bongos/metrics.js)), each tagged with a `project` label ([`infra/prometheus/prometheus.yml`](../infra/prometheus/prometheus.yml)): **cloudbongos** locally (`:3002`); **example + emersonian-circles** on the co-hosting box, reached over the **private VPC** via `socat` forwarders on `10.108.0.2:9101/9102` (→ their loopback `:3000`/`:3004`), ufw-locked to the control-plane box's private IP — raw TCP relays, so the exporter still sees a loopback request and needs no token; nothing is public. **Grafana** (`127.0.0.1:3003`, loopback-only) renders the 4 provisioned-as-code dashboards (folder **Cloud Bongos**: system-overview, error-watch, builder-activity, auth-security), each with a **`project`** template variable for per-instance / fleet views. Reverse-proxied on the `*.cloudbongos.com` origin cert — Archon-only, gated by Caddy `basic_auth` (user `archon`) **and** Grafana's own admin login (both secrets owner-held, never in the repo). Grafana config is a systemd `GF_*` env drop-in (`grafana-server.service.d/override.conf`, `chmod 600`). ~256 MB RAM. A future dedicated-droplet instance is added as a `METRICS_TOKEN` Bearer target instead of a VPC forwarder.
+
+**Application stack:**
+
+- **Phaser 3** (browser game engine) — UMD via `/vendor/phaser.min.js`. Game code lives as plain ES modules in `public/`.
+- **Colyseus 0.16** (server-authoritative WS rooms + state). Server pinned `^0.16` to match `colyseus.js` 0.16. UMD client bundle at `/vendor/colyseus.js`.
+- **Express 4** — static file serving + a `/healthz` route. Same Node process as Colyseus.
+- **`pg`** Postgres client over Unix socket (`host: '/var/run/postgresql'`).
+- **Auth (planned, not yet wired):** Email + magic link, tied to a Stripe customer record on first purchase.
+
+**Module system (core + modules, [ADR 0083](adr/<redacted>.md)):**
+
+The product is organized as a small kernel (`src/`) + **19 modules** under `modules/<key>/` — the four optional *feature* modules **plus** the carved *core-domain* modules. The four-feature carve (Config A) was only the least-coupled ~26% of the tree; the **core decomposition (Config B = BONGOS-V1 C7 `gds-core-modularized`)** is now done too ([ADR 0091](adr/<redacted>.md), [ADR 0093](adr/<redacted>.md)). The full, live roster + contract is at [docs/modules-contract.md](modules-contract.md).
+
+- **The one-way rule** — a module reaches core only through `src/module-api.js` (the published, semver'd doorway). Core never imports a module. Modules never import each other — they cooperate through `src/module-seams.js` (ports + events). Two CI fitness checks enforce this; a violation is a red build.
+- **The loader** (`src/module-loader/loader.js`) — discovers `modules/*/module.json` at boot, validates manifests, checks `coreVersion` compatibility, and mounts each enabled module's routes behind kernel-composed auth. No core file changes to add or remove a module.
+- **Enablement** — `config/modules.json` (instance config) or `<PREFIX>_MODULE_<KEY>=1` (env override). Vanilla = all off.
+- **Feature modules** (optional — off on a vanilla instance, enabled per-instance via `config/modules.json`):
+  - `dev-box` — per-builder cloud dev environments; ports: `box.hasEverConnected`
+  - `game` — Phaser client + Colyseus rooms + world/terrain; ports: `game.staticRoot`, `game.registerRooms`, `game.precreateWorldRoom`
+  - `discord` — ship broadcast + inbound bot + role-sync; port: `discord.isLinked`
+  - `art-pipeline` — pixel-art generation + artist discipline; port: `art.sharedKeyConfigured`
+  - (+ `character-anim`, declaration-only — ADR 0088)
+- **Core-domain modules** (`default: true` — always on unless disabled): `memory`, `grading`, `economy`, `ideas`, `security`, `builder-settings`, `onboarding`, `sessions`, plus `lifecycle` (the task/claim/version state machine), `autonomy` (the MAS), the `hall-ui` + `status-ui` internal surfaces, and the `demo` acceptance-proof module. See [docs/modules-contract.md](modules-contract.md) for the live roster and which default on.
+- **Module-owned migrations** — `modules/<key>/migrations/*.sql` applied only when the module is enabled. Stem-keyed so moving a migration never re-runs it.
+- **`bongos module new <key>`** — scaffolds a new module directory in one command.
+- **`bongos upgrade`** — the update-consumption channel a two-repo consumer uses to pull the core from version N→N+1 (task 1690, ADR 0100 §2 / ADR 0103 §4): pre-flight (module-compat + clean tree) → bump the vendored-tarball pin → `npm install` → `npm run migrate` (additive `core_*` migrations) → re-materialize `.claude/` → restart → verify. Run bare (no `--to`) it is still just the module-compat pre-check that exits 1 on mismatch; `--to <version>` runs the real bump. (`scripts/gds/upgrade.js`.)
+
+**V1 networking design:**
+
+- **Singleton `WorldRoom`** (Colyseus, `autoDispose=false`, `maxClients=100`). Pre-created via `matchMaker.createRoom`. Spawn at tile (10,10).
+- **Sibling `QueueRoom`** — unbounded, FIFO, admits via shared in-process seat bus (`src/seats.js`). Browser-close releases seat automatically (Colyseus `onLeave`).
+- **Move protocol:** client sends `{ dir }` per step. Server validates direction, applies position unless target tile is blocked or out of bounds, always commits facing.
+- **Movement is client-predicted, server-authoritative.** Both sides run identical walkability rules. Walkability lives in `BLOCKING_TERRAINS` (ground impassable — sea) and `BLOCKING_OBJECTS` (object impassable — rocks, container panels) in the shared `terrain.js` module (CJS twin at `src/world/terrain.js`, ESM twin at `public/game/world/terrain.js`); the hardcoded V1 map lives in `src/world/map.js` (server) and `public/game/world/map.js` (client) — **the two map.js + the two terrain.js files must stay in sync** until the world becomes data-driven.
+- **Cell data model ([ADR 0012](adr/<redacted>.md), extends [ADR 0011](adr/0011-terrain-id-rendering-model.md)):** each cell carries TWO independent pieces:
+  - **Ground terrain** (always defined) — `GRASS`, `SAND`, `SEA`, `MARBLE_PATH`. Drives the autotile renderer. `INITIAL_MAP.ground[y][x]`.
+  - **Object** (optional, sparse) — `ROCK` or one of the 8 `CONTAINER_PANEL_*` (V1). Painted in a second draw pass at depth 1. `INITIAL_MAP.objects[y][x]` (null in most cells).
+  The autotile picker sees the ground grid only; objects never affect tile selection. That is the invariant that lets rocks scatter through a meadow without polluting boundary tiles, and lets the container sit cleanly on sand.
+- **Render dispatch ([ADR 0011](adr/0011-terrain-id-rendering-model.md)):** ground terrains pick a render strategy declared in `TERRAIN_RENDER`:
+  - `single` — paint one PNG (sea).
+  - `blob47` — query 8 neighbors on the GROUND grid, call `selectBlob47` from `autotile.js`, paint `tex_at_<family>_<idx>` (PNG at `/assets/tiles/autotile/<family>/<NN>.png`).
+  - `path16` — same shape with 4-cardinal-only and 16 tiles.
+  Each autotile-strategy terrain declares a `fallbackTile` so the world keeps rendering before the autotile family has been generated. Objects render via single-tile dispatch only. Python (`art/pipeline/autotile_mapping.py`) and JS (`public/game/world/autotile.js`) lookup tables are cross-verified at smoke-test time via `tests/autotile_xverify.mjs`. Picker invariants + walkability are guarded by `tests/terrain_picker.mjs` and `tests/walkability.mjs`.
+- **Player positions are not broadcast** — other players are invisible in V1.
+- **Identity:** localStorage UUID sent as join option. Server keys position by UUID and rehydrates from `players` table on join.
+- **Persistence:** append-only `world_events` table is source of truth. Logged event types: `room.created · player.joined · player.left · player.moved · player.bumped · player.interacted · queue.joined · queue.left · queue.admitted`.
+
+**Code & deploy:**
+
+- **Code repo:** [github.com/example-owner/example](https://github.com/example-owner/example) — **private**. Clone URL: `git@github.com:example-owner/example.git`. Default branch: `main`. GitHub user: `example-owner`.
+- **Deploy:** two modes, selected by `config/deploy.json` `mode` (env `OTB_DEPLOY_MODE` overrides), currently **`ci`** (flipped from `laptop` 2026-06-13, [#859](https://example.com/builders#/task/859)) — see [ADR 0042](adr/<redacted>.md). **`laptop`** (legacy): `git push origin main` from the Mac → `ssh lars@REDACTED_IP ~/deploy.sh`. The droplet has a read-only deploy key at `~/.ssh/github_deploy` registered on the repo. `~/deploy.sh` does: `git fetch + reset --hard origin/main` → `npm ci --omit=dev` if `package-lock.json` changed → `./scripts/migrate.sh` → `sudo systemctl restart example` → `curl /healthz` smoke (**retried up to 15× @ 1s** — `systemctl` reports "active" before the Node process binds the port, so a single curl raced the bind and false-failed healthy deploys: [ADR 0056](adr/<redacted>.md) / [#1026](https://example.com/builders#/task/1026)). Droplet checkout: `/home/lars/example/`. `~/deploy.sh` is hand-maintained on the droplet but now has a byte-faithful, reviewable repo mirror at [`scripts/deploy/deploy-prod.sh`](../scripts/deploy/deploy-prod.sh) — **not** auto-installed (the ci deploy key is forced-command-locked, ADR 0042/0043; reinstall by hand on change: `scp scripts/deploy/deploy-prod.sh lars@…:deploy.sh`). **`ci`** (current, armed via [#679](https://example.com/builders#/task/679)): no builder box holds the droplet key — `ship.js` opens a PR + enables GitHub auto-merge, and [`.github/workflows/deploy-prod.yml`](../.github/workflows/deploy-prod.yml) runs the same `~/deploy.sh` from Actions on merge to `main`. Cutover preconditions (incl. a server-recorded **CI grade-gate**) are in ADR 0042.
+- **Post-merge branch cleanup (standard practice):** Every feature branch that lands on main via `--no-ff` merge gets deleted on origin once the deploy succeeds. The merge commit itself preserves the branch's history in main, so the named ref isn't carrying any signal — keeping it just clutters GitHub's branch list and tricks the UI into offering empty PRs against zero-diff branches. The auto-merge in [`scripts/gds/ship.js`](../scripts/gds/ship.js) does this automatically after `~/deploy.sh` returns 0; the manual [`/merge-mode`](../.claude/skills/merge-mode/SKILL.md) flow follows the same step 5b. Local refs and worktree directories stay — only the origin branch and the local tracking ref (cleaned on next `git fetch --prune`) go.
+- **Local dev machine:** Lars's MacBook Air (Apple Silicon, macOS Sequoia). Tooling installed via Homebrew at `/opt/homebrew/`. Node v26.0.0 locally; `package.json` declares `"engines": { "node": ">=22" }`. Single ed25519 SSH key (`~/.ssh/id_ed25519`) authenticates to GitHub and droplet.
+- **Smoke tests:** lightweight scripts in `/tmp/colyseus-*-smoketest.js` verify joinOrCreate, move protocol, interact, identity, queue. Run any after deploy with `node /tmp/colyseus-<name>-smoketest.js`.
+- **Repo topology today vs. the configurable-root future ([ADR 0108](adr/<redacted>.md)):** everything above describes the current **single checkout** — `git reset --hard` deploy, `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../src/instance-config.js)) both resolving to this same repo root. ADR 0108 lands (Mercury-first, then Example last) a model where Example instead installs a versioned `@cloudbongos/core` npm package and deploy becomes `git pull` (the instance repo) → `npm ci` (the pinned core) → migrate → restart — no more `git reset --hard` on a shared checkout. This section gets rewritten for the new topology once Example actually splits (ADR 0108 §6, task 1884/W4); until then it is unchanged and accurate.
+
+**Database (`example` on Postgres 16, peer auth as `lars`):**
+
+Game tables:
+
+```
+schema_migrations(version PK, applied_at)
+world_events(id bigserial PK, type text, actor_session_id text, payload jsonb, created_at)
+  indexes: (created_at), (type)
+players(id text PK, current_grid_x int, current_grid_y int, current_facing text,
+        first_seen_at timestamptz, last_seen_at timestamptz)
+  indexes: (last_seen_at)
+```
+
+GDS tables (migration `003_pms.sql`, see [ADR 0010](adr/0010-pms-architecture.md)):
+
+```
+builders(id, github_id UNIQUE, github_login, display_name, avatar_url, total_credits, karma,
+         created_at, rank, status, system_role, timezone, preferred_disciplines,
+         skill_model_prefs, behavior_prefs, deactivated_at, reactivated_at, deactivated_reason,
+         gemini_key_enc, gemini_key_last4, gemini_key_set_at)  -- mig 122: per-builder Gemini key, AES-256-GCM at rest (ADR 0073); master key BUILDER_SECRET_KEY in server env only
+  rank text NOT NULL DEFAULT 'xenos' (mig 023; default flipped to xenos in mig 029)
+       CHECK IN 16-value ladder; LIVE: archon|metic|xenos (three-rank model, #360/ADR 0018)
+  karma integer NOT NULL DEFAULT 0 (mig 040) -- good-citizenship track alongside drachmae
+       (=total_credits); append-only karma_log + AFTER INSERT trigger keep it in sync
+  status text DEFAULT 'active' (mig 025) -- 'active'|'inactive'; a deactivated builder can't claim (#307)
+  system_role text NULL (mig 065) -- NULL for every human; 'bfg' = the BFG service principal
+       (system: can't claim/earn/log-in). The cross-builder memory WRITE gate keys on this
+       EXACT value, not on rank (ADR 0026 §6C) — an Archon token is rejected.
+  + skill_model_prefs jsonb (mig 037), preferred_disciplines text[] (mig 027), timezone (PMS-V2),
+    deactivated_at/reactivated_at/deactivated_reason (mig 025 — the /builder-exit flow; #307 guard)
+tasks ... + xenos_claimable boolean NOT NULL DEFAULT false (mig 029) -- Xenos may claim only these
+versions(id PK 'V1'|'PMS-V1'..., name, track, status, scope_doc_path, ...)  -- track is free text (the product|internal CHECK was dropped in mig 112, task 1191); the valid set is instance config (config/branding.json "tracks"), not a DB constraint
+tasks(id, version_id, title, description, status, touches text[], est_minutes, est_cost_usd,
+      manual_degree, priority, automation_tag, credits_reward, source, source_ref,
+      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
+                (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
+  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)
+  UNIQUE INDEX uniq_active_claim_per_task ON (task_id) WHERE released_at IS NULL
+cost_log(id, task_id?, amount_usd, category, description, source, source_ref, recorded_at)
+credit_log(id, builder_id, task_id, delta, reason, recorded_at)
+  trigger: bumps builders.total_credits
+builder_sessions(id, builder_id, token UNIQUE, source 'cli'|'web', user_agent,
+                 created_at, last_used_at, expires_at, revoked_at)
+session_logs(id, builder_id, task_id?, claim_id?, started_at, ended_at, outcome,
+             notes_md, confidence)
+```
+
+PMS-V2 additions (migration `006_pms_v2.sql`, see [`limitations/pms-v2-shipped.md`](../limitations/pms-v2-shipped.md)):
+
+```
+-- new columns
+tasks  + kind text NOT NULL DEFAULT 'unclassified'  CHECK IN (feature|bug|infra|refactor|spike|
+                                                              learning-capture|cleanup|decision|
+                                                              blocker-resolution|unclassified)
+       + parent_task_id bigint REFERENCES tasks(id)
+       + actual_minutes integer
+       + scoping_confidence integer  CHECK (1..5)
+       + discipline text NOT NULL DEFAULT 'unclassified' (mig 014; renamed mig 086)
+                                              CHECK IN (engineer|artist|ideator|unclassified)
+                                              -- orthogonal to kind; classifies builder
+                                              -- interest area (engineer = code/infra/mechanics/bugs,
+                                              -- artist = pixel art/sprites/pipeline,
+                                              -- ideator = scoping/research/docs/narrative/lore)
+claims + head_sha text                              -- captured at claim time for incidental-work scanner
+builders + timezone text NOT NULL DEFAULT 'America/New_York'
+
+-- new tables
+achievements(id text PK, name, description, icon, credit_bonus, sort_order)  -- 8 seeded
+builder_achievements(builder_id, achievement_id, unlocked_at, unlocked_by_task_id, PK on both)
+learnings(id, title, body_md, tags text[], related_files text[], captured_by, source,
+          source_ref, task_id?, created_at)
+  indexes: GIN(tags), GIN(related_files), UNIQUE(source, source_ref) WHERE non-null
+idea_inbox(id, title, body_md, kind, suggested_version, suggested_priority, captured_at,
+           captured_by, status 'open'|'promoted'|'discarded'|'merged', promoted_to_task_id, reviewed_at)
+done_when_criteria(id, version_id, criterion_id, criterion_md, satisfied bool, satisfied_by_task_id,
+                   checked_at, sort_order, UNIQUE(version_id, criterion_id))  -- 13 seeded (V1 + PMS-V2)
+task_criteria(task_id FK tasks, criterion_id FK done_when_criteria, source 'backfill'|'manual'|'planning',
+              created_at, PK(task_id, criterion_id))  -- mig 055 (#435, ADR 0025): the forward MANY link
+              -- (the many tasks that GATE a criterion), vs done_when_criteria.satisfied_by_task_id (the one
+              -- ship that CLOSED it). Backed GET /versions/:id/progress + /status. Populated on task-create
+              -- via POST /tasks { criterion_ids } + the /tasks/:id/criteria manage endpoints (#438); "Cn" is
+              -- the 1-based position by (sort_order, criterion_id). idx on (criterion_id) + (task_id).
+session_pulses(claim_id PK, builder_id, last_pulse_at)  -- heartbeat for stale-claim detection
+task_grades(id, task_id UNIQUE, score NUMERIC(3,1), passed bool, threshold NUMERIC(3,1),
+            grader_kind 'auto'|'subagent'|'lars', grader_version, rubric_scores jsonb,
+            signals jsonb, notes_md, graded_at)  -- mig 016, one row per task
+grade_attempts(id, task_id, builder_id?, passed bool, score NUMERIC(3,1), attempted_at)
+            -- mig 064 (6D.6, ADR 0027): APPEND-ONLY, one row per grade run, so
+            -- re-grade thrash is countable (task_grades keeps only the latest)
+session_records(id, session_id UNIQUE, builder_id, task_ids bigint[], drachmae_earned,
+            total_tokens, duration_seconds, started_at, ended_at, uploaded_at,
+            detail jsonb, metrics jsonb)  -- mig 062 (6D.1, ADR 0027): per-shipped-session
+            -- secret-scrubbed digest (per-turn metadata + short snippets); idx on
+            -- ((metrics->>'tool_error_count')::int) in mig 063 (6D.2). The BFG
+            -- session-inefficiency evaluator searches + deep-dives this corpus.
+```
+
+Memory, audit, and reputation tables (later migrations — the substrate the
+`/memory/*` API + the BFG cross-builder write path operate on):
+
+```
+builder_memory(builder_id, path, content, mtime, sha256, byte_len, created_at, updated_at,
+               PK(builder_id, path))  -- mig 054 (ADR 0024): server-canonical, per-builder-
+               -- ISOLATED Claude Code memory. Quotas: 1 MB/file, 50 MB + 2000 files/builder.
+               -- The `bfg/` path prefix is RESERVED for BFG-authored notes (sync rejects it);
+               -- the self DELETE /memory/file is the builder's affordance to remove them (6C).
+karma_log(id, builder_id, delta, reason, recorded_at, granted_by)  -- mig 040: APPEND-ONLY
+               -- karma ledger; AFTER INSERT trigger gds_apply_karma bumps builders.karma.
+               -- reason e.g. peer_upvote|proposal_ratified|archon_grant|bfg_correction (6C.2,
+               -- granted_by = the BFG principal; a correction's negative delta lands here in
+               -- the SAME tx as its visible note + audit row).
+audit_log(id, builder_id, route, method CHECK IN (POST|PATCH|PUT|DELETE),
+          request_body_redacted jsonb, response_status, ip, user_agent, recorded_at)  -- mig 033
+               -- APPEND-ONLY authenticated-write log (middleware/audit.js, post-response,
+               -- fire-and-forget). GET reads bypass it, so the cross-builder memory reads +
+               -- writes log EXPLICITLY + fail-closed; the true verb/action lives in
+               -- request_body_redacted.action: archon_forensic_memory_read | bfg_memory_read |
+               -- bfg_dream_write | bfg_correction_write.
+```
+
+GDS views: `claimable_tasks` (rebuilt in 006 to use SELECT t.*; rebuilt again in 014 so the new `discipline` column flows through), `version_progress` (rebuilt in 006 to count only leaf tasks for forward-compat with task hierarchy), `tasks_session_fit` (new in 006: derives `fits_session_modes[]` and `credits_per_minute`; rebuilt in 014 for the same SELECT t.* refresh), `task_grades_with_context` (new in 016: joins task_grades × tasks × builders × cost_log so the V4 optimizer has quality-per-dollar in one read).
+
+**GDS API (`/api/gds/*`, mounted in the same Node process):**
+
+- **Canonical path is `/api/bongos` (task 1919); `/api/gds` is a PERMANENT alias.** The router + the discovery index are dual-mounted at both by `serve-internal.js`, driven by the single `src/bongos/api-prefix.js` constant (`API_PREFIX` + `LEGACY_API_PREFIXES`). The legacy `/api/gds` alias never goes away — shipped Dev Box binaries, the cached status mirror, and live boxes call it. **Exception:** the GitHub OAuth callback stays pinned to `/api/gds/auth/web/callback` (registered on the OAuth app; `src/bongos/routes/auth.js`). Not yet flipped (still ride the permanent alias): `src/**` internal callers + the deeper internal names (folders, `GDS_*` env, `gds_session` cookie) — the deferred internal-rename pass.
+- **Self-describing (task 1918, [ADR 0109](adr/<redacted>.md)).** The whole surface is documented in the standard **OpenAPI 3.1** format at [`docs/api/openapi.json`](api/openapi.json), **generated from the live route files** by `scripts/gds/gen-api-docs.js` (reusing the same `route-rank-check.js` introspection the ship-time rank gate uses — so it can't drift; a fitness `--check` + ship-time regen enforce freshness). A rendered docs site (vendored Redoc) is served at **`/docs`** on the apex of every instance (`cloudbongos.com/docs` canonical); `GET /api/gds` returns a machine-discovery index pointing at it. The generated [`docs/api-reference.md`](api-reference.md) supersedes the old hand-maintained `routes-permissions.md`. The mount prefix is the single `src/bongos/api-prefix.js` constant.
+
+- Auth: `POST /auth/device/start`, `/poll` (CLI Device Flow); `GET /auth/web/start`, `/web/callback` (browser); `POST /auth/logout`; app pairing for the Dev Box desktop app ([#904](https://example.com/builders#/task/904), [ADR 0045](adr/<redacted>.md), store [`src/bongos/app-pair.js`](../src/bongos/app-pair.js) — in-memory, 10-min TTL): `POST /auth/app-pair/start` + `/poll` (public; the secret poll_token is the bearer and the minted token is delivered to it exactly once), `GET /auth/app-pair/info` + `POST /auth/app-pair/approve` (any-builder; approve is **cookie-gated** like `/auth/cli-token/issue` so a leaked bearer can't mint siblings; approving from `/builders/pair?code=…` signs the app in as the approver, `source='cli'`).
+- Authenticated CLI/web: `GET /me` (returns `rank`), `GET /versions[/progress]`, `GET /tasks[?version=&status=&kind=&discipline=]`, `GET /tasks/claimable[?version=&discipline=]`, `GET /tasks/:id`, `POST /tasks` (accepts `discipline` + `criterion_ids`; **metic+** — [ADR 0090](adr/<redacted>.md)), `PATCH /tasks/:id` (supports `parent_task_id`, `kind`, `discipline`, `goal_id` — (re)assign the task's goal; must be a goal in the task's own version, task 1763; **metic+**), `POST /tasks/:id/promote` (**metic+**), `POST /claims`, `POST /claims/:id/resolve`, `POST /cost`.
+- Criterion rollup + task↔criterion links ([ADR 0025](adr/<redacted>.md), [#435](https://example.com/builders#/task/435)/[#438](https://example.com/builders#/task/438)): `GET /versions/:id/progress` rolls up each done-when criterion → its gating tasks (via `task_criteria`) → live status counts + the not-yet-shipped `remaining[]` + `unattributed_tasks` (the read behind the `/status` skill, in `src/bongos/done-when.js criterionProgress`). The link CRUD mirrors the dependency endpoints: `GET /tasks/:id/criteria`, `POST /tasks/:id/criteria` (**metic+** — [ADR 0090](adr/<redacted>.md)) and `DELETE /tasks/:id/criteria/:criterionId` (**metic+**). A criterion ref is a numeric `done_when_criteria.id`, a positional `"Cn"` token, or a `criterion_id` slug, resolved against the task's version (`POST /tasks` links at create time so `/status` counts the task with no backfill).
+- Server-mediated branch publish (ADR 0055 / [#1025](https://example.com/builders#/task/1025) — lets a dev box with no GitHub push credential ship). Owner-gated like ship: `POST /tasks/:id/publish-branch` (`requireBuilder` + `gateTaskOwnership`, **NOT** `allowBoxScope` → a box-scoped session is `403 box_scope`, so the builder must `/builder-reauth` first; own 32 MB json parser for the base64 thin-bundle body, 20 MB decoded cap; the server pushes the branch + opens the PR + auto-merges with a server-side push credential — a **GitHub App** installation token (short-lived, repo-scoped; preferred, [ADR 0055](adr/<redacted>.md) update / task 1028) or the `GITHUB_PUSH_TOKEN` PAT fallback; `503 push_unconfigured` when neither is set; `400 tip_mismatch` if the bundle tip ≠ the claimed `head_sha`) and `GET /tasks/:id/publish-status?branch=…` (polls PR + deploy-prod state derived live from GitHub). `ship.js` uses these in `ci` mode only when `pushVia()` resolves to server (a box, or `OTB_PUSH_VIA_SERVER=1`); a laptop with `gh` keeps the local push path unchanged. Implementation in `src/bongos/github-push.js`.
+- Archon monitoring reads backing the `/watch` page (ADR 0036): `GET /builders/roster`, `GET /grades/by-builder[?days=N]` (**archon-only**, [#726](https://example.com/builders#/task/726) — per-builder grade breakdown for the MARKS section; the project-wide aggregate stays public at `/public/grades`), `GET /audit-log`, `GET /override-requests`, `GET /access-requests`, `GET /security/reports`. Personal-prefs writes backing `/settings`: `GET/PATCH /me/skill-prefs`, `PATCH /me/disciplines`.
+- Per-builder "needs" + own Gemini key ([ADR 0073](adr/<redacted>.md), [#1013](https://example.com/builders#/task/1013)): `GET /me` now also carries `needs` ({items, action_needed_count} — the consistent "the system needs an input from you" signal; `modules/builder-settings/builder-needs.js` is the SSOT — carved out in BV1.R80, resolved by `GET /me` via the `builder-settings` kernel port — rendered by the hall Standing card + the CLI `printNeedsNudge`). The own-key (pragmatic BYOK) endpoints, all own-scoped: `GET /me/art-key/own` (masked meta — last4 only), `PUT /me/art-key/own` (validate-on-save via a Google list-models call → encrypt with `src/bongos/secret-box.js` → store; `503 storage_not_configured` until `BUILDER_SECRET_KEY` is set, `422 invalid_key` on a bad key), `DELETE /me/art-key/own`. The existing `GET /me/art-key` (shared-key box-sync delivery) is extended to also deliver the decrypted own key, which `scripts/gds/fetch-art-key.js` syncs into the local `gemini_api_key` slot (own key wins in the `gen_api.py` cascade).
+- 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` returned **only** for `shipped`|`confirmed` work and withheld for in-flight tasks so unshipped/security task names can't leak; the status dashboard renders it at `#/task/:id`), `/public/ref-ids` ([#653](https://example.com/builders#/task/653) — `{tasks:[ids]}`, ids only, token-free; the doc-ref linkifier + its CI gate consult it to decide which bare `#NNN` are real task refs). These power `status.example.com`.
+- Live updates (Server-Sent Events — [#569](https://example.com/builders#/task/569), [ADR 0030](adr/<redacted>.md) signal layer, [ADR 0069](adr/<redacted>.md) transport): an SSE stream at `GET /api/gds/live` ([`src/bongos/routes/live.js`](../src/bongos/routes/live.js)), mounted in both entrypoints (`server.js` + `src/platform-server.js`) so the hall stays live on a game-less boot. This **superseded** the original broadcast-only Colyseus `builders_hall` room (R55 / task 1194 — the room and `src/rooms/BuildersHallRoom.js` were deleted because a GDS-only instance has no Colyseus in the process). The change-signal layer is **unchanged**: a statement-level Postgres `NOTIFY` trigger (migration 066) on `tasks`/`claims`/`builders`/`builder_onboarding_state`/`credit_log`/`karma_log` fires a `gds_live` notification on every write (incl. direct `psql`); one persistent `LISTEN` connection ([`src/bongos/live-channel.js`](../src/bongos/live-channel.js)) relays each notification, and the SSE endpoint emits an **opaque empty nudge** to open hall tabs (the `{table, op}` is kept server-side so internal table names can't leak); the hall re-runs its `loadAll()` (debounced) on any nudge. No row data crosses the channel — access control stays on the per-panel re-fetches.
+
+**Builder ranks & the trust boundary:** moved to its own canonical reference —
+[`docs/canonical-permissions.md`](canonical-permissions.md) (rank ladder, live ranks, what's gated,
+failure modes) and [ADR 0016](adr/<redacted>.md) (the decision).
+**Authority lives in `builders.rank` on the prod DB, checked server-side per request with no caching;
+markdown describes, the DB enforces.**
+
+> **Two entrypoints, one serving path (ADR 0062 R51, task 1190).** The host-routing + hall/status serving below is factored into `mountInternalSurfaces(app)` in [`src/bongos/serve-internal.js`](../src/bongos/serve-internal.js), called by **both** the game boot ([`server.js`](../server.js)) and the new **GDS-only boot** ([`src/platform-server.js`](../src/platform-server.js)). The platform boot constructs **no Colyseus, no game rooms, no `/vendor/*`, no `/assets/tiles`, no `public/`** — a game-less Cloud Bongos instance runs it unchanged, and "no game route is reachable" holds by absence (the inverse of `preview-server.js`, which serves only the game). Prod still runs `node server.js`; the GDS-only entrypoint is the seam the instance model (R54/R67) boots on.
+
+**Multi-host setup (same Node process), routed by `Host` header in [`src/bongos/serve-internal.js`](../src/bongos/serve-internal.js), shared by both entrypoints:**
+
+- **`example.com`** — game (Phaser + Colyseus). Static files from `public/`. `/builders` + `/builders/*` now **301-redirect to `builders.example.com/<rest>`** ([#739](https://example.com/builders#/task/739) then promoted to permanent 301 in [#741](https://example.com/builders#/task/741), ADR 0036 cutover); the apex no longer serves the builder surface directly.
+- **`status.example.com`** — public build dashboard. **Carved to the `status-ui` module in BV1.R84** ([ADR 0093](adr/<redacted>.md) §1): the surface moved from `public-status/` to `modules/status-ui/public/`, now served by the loader's web-surface seam (`moduleWebSurfaces` → `serve-internal.js`, routed on the `status.` Host prefix the manifest declares) instead of a hardcoded block — no behavior change. Layout reorganized in [#726](https://example.com/builders#/task/726) (ADR 0036): Pulse / Watch(uptime) / Architects / Works / Treasury / Lately Inscribed / The World — the grade-aggregate, estimation-drift, and repo-health tablets moved to the Archon `/watch` page. **⚠ Served OFF the droplet** (ADR 0029, outage resilience): the live page is **GitHub Pages from the separate repo `example-owner/example-status`** (CNAME → Fastly), reading data cross-origin from the droplet's `/api/gds/public/*` (CORS open) and an availability banner from the prober's `status-data` branch. The droplet still serves `modules/status-ui/public/` (on the `status.` host) as a same-origin fallback, but **DNS points at Pages, not the droplet** — so a droplet deploy does NOT update the live page. Changes to the surface publish to the mirror via `scripts/status-mirror-sync.js` (re-pointed at `modules/status-ui/public/`; status.js/style.css/cursors are byte-identical copies; index.html gets the off-box bits injected), run automatically by `.github/workflows/sync-status-mirror.yml` (needs the `STATUS_MIRROR_TOKEN` secret) ([#737](https://example.com/builders#/task/737)). **⚠ FOLLOW-UP (R84):** that workflow's path trigger still watches `public-status/**` and must be re-pointed at `modules/status-ui/public/**` by an owner/Archon — the GitHub App can't push `.github/workflows/*` (learning 107), so until then the mirror sync won't auto-fire on future status edits.
+- **`builders.example.com`** — dedicated builder surface (`isBuildersHost`, ADR 0036). **Carved to the `hall-ui` module in BV1.R85** ([ADR 0093](adr/<redacted>.md) §1): the surface moved from `public-builders/` to `modules/hall-ui/public/` (~13k LOC, the largest module) and is a loader-discovered web-surface module (`contributes.webSurfaces` host `builders.`). UNLIKE the generic status surface it keeps its **dedicated** serving block in `serve-internal.js` (`BUILDERS_DIR = modules/hall-ui/public/`), partitioned out of the generic web-surface loop on the `isBuildersHost` predicate. A thin rewrite shim maps every non-API path onto the existing `/builders/*` tree (so all serving + gating + asset-stamping is reused), serving the hall (`/`), the Archon-only **`/watch`** monitoring page (gated by `requireArchonPage`), **`/settings`** (Voices + Craft prefs), plus ranks/sessions/primer/diagrams. No behavior change — byte-identical (only `window.__MODULES__.enabled` gains `hall-ui:true`). **Additive** — until its DNS A record + cert are live, the whole surface stays reachable at `example.com/builders/*`. No `.github/workflows/*` follow-up: unlike R84, no workflow path-trigger watches `public-builders/**`.
+- **`/downloads/devbox/*`** (every host, mounted right after the API so the builders-host shim can't rewrite it — [#904](https://example.com/builders#/task/904), [ADR 0045](adr/<redacted>.md)): branded download surface for the Dev Box desktop app. `/{mac-arm64,mac-x64,win-x64}` (+ `mac`/`win` aliases) 302 to the release assets on the public releases repo named in [`config/devbox-app.json`](../config/devbox-app.json); `latest.json` feeds the app's update check. Logic in [`src/devbox-downloads.js`](../src/devbox-downloads.js); the installers never ride the git deploy.
+- The `/api/gds/*` surface is reachable from every host. **Cross-subdomain sign-in:** the `gds_session` cookie is scoped to `.example.com` on the production hosts (apex/www/builders/status) and host-only on localhost/staging (no cross-env token bleed); the OAuth handshake runs on the canonical origin with a validated `?return=` (open-redirect-guarded) so the subdomain can land a builder back on itself.
+- Caddy gets a site block per host ([`infra/Caddyfile`](../infra/Caddyfile)), all reverse-proxying to `127.0.0.1:3000`.
+
+**Asset cache-busting (content-hash `?v=`, task [#521](https://example.com/builders#/task/521)).** The hall + status HTML pages (`modules/hall-ui/public/*.html`, `modules/status-ui/public/index.html`) are served from an **in-memory stamped copy**, not straight off disk: at boot [`src/asset-version.js`](../src/asset-version.js) rewrites each local css/js ref's `?v=` query to a 12-hex hash of the referenced file's content (`buildStampedHtml`). The on-disk HTML keeps a hand-typed `?v=` only as a fallback. This is the durable fix for stale-asset serving — Cloudflare overrides the origin's `max-age=60` with a **4h browser TTL** for js/css, so before this, editing `builders.js` without manually bumping its `?v=` left every returning browser (and CF's edge) serving pre-deploy bytes for hours. Now any content change → new hash → new URL → fetched fresh automatically. HTML pages stay short-cached (CF serves them DYNAMIC), so the new `?v=` reaches clients within ~60s. Assets and non-HTML paths still fall through to `express.static`; the sign-in gate on primer/diagrams runs before the stamped serving.
+
+**External:**
+
+- GitHub repo (private): [github.com/example-owner/example](https://github.com/example-owner/example)
+- Live site: [https://example.com](https://example.com)
+- DNS + domain registrar: Cloudflare
+- Hosting: DigitalOcean (droplet `example`, NYC3, IPv4 `REDACTED_IP`)

package/docs/branding-contract.md

@@ -0,0 +1,66 @@
+# The branding contract (`config/branding.*`)
+
+The branding contract is how a **Cloud Bongos instance** supplies its identity. It is the keystone of the Cloud Bongos decoupling (ADR [0062](adr/<redacted>.md) §3; task [#1192](https://example.com/builders#/task/1192) / V4.R53). One config, read through one resolver (`src/branding.js`), so brand strings live in **one place** instead of the ~90 hardcoded sites they occupy today.
+
+> Generalizes the single-config rule of [ADR 0004](adr/0004-example-name-and-trademark-acceptance.md) (the civ name must be one string, never baked into code) from one string to the whole identity surface. Code reads `branding().identity.worldName`, never `"Example"`.
+
+## Resolution precedence (highest wins)
+
+```
+env override   →   instance config (config/branding.json)   →   neutral starter (config/branding.neutral.json)
+```
+
+- A fresh instance with **no** `config/branding.json` resolves to the **plain neutral identity** — never to a host's brand (fail-to-vanilla).
+- `config/branding.neutral.json` is **customer 0** (vanilla Cloud Bongos). `config/branding.json` is the host instance — here, **customer 1** (Example / OTB).
+- **Configurable-root ([ADR 0108](adr/<redacted>.md) §1, task 1881/W1 shipped):** `NEUTRAL_PATH` resolves off `resolveCoreRoot()` (the neutral starter ships WITH the core package) and `INSTANCE_PATH` off `resolveInstanceRoot()` (the instance pack is host content) — [`src/instance-config.js`](../src/instance-config.js). Both resolvers return the repo root today, so resolution is unchanged; the split only diverges once a consumer installs the core as a package.
+- Env overrides apply only to the operationally-swapped fields (origins + cookie domain) for dev/staging, keyed `<envPrefix>_<FIELD>` (e.g. `OTB_PUBLIC_ORIGIN`). Everything else comes from the committed pack.
+
+## Fields
+
+| Path | Meaning |
+|---|---|
+| `identity.productName` | The product name (e.g. "Off the Boats"). **Required.** |
+| `identity.worldName` | The in-world / civilization name rendered at runtime (e.g. "Example"). **Required.** |
+| `identity.company` | `{ name, site }` of the operating company (may be empty). |
+| `llmProjectName` | The project name injected into grader / architect / onboarding **LLM prompts**, so a non-OTB instance is graded against its own identity. **Required.** |
+| `domains.publicOrigin` | Public game/app origin. **Required.** |
+| `domains.buildersOrigin` / `statusOrigin` | Hall + status origins. **These three (`publicOrigin`/`buildersOrigin`/`statusOrigin`) are the docs-discovery contract** ([ADR 0114](adr/<redacted>.md)): the hall is the canonical doc-reading surface, `/docs` on `publicOrigin` renders the API reference, the status page is the outage fallback. `GET <publicOrigin>/api/bongos` re-advertises them (`hall`/`status`/`public`) so an agent resolves the surfaces with no hard-coded host. |
+| `domains.cookieDomain` | Session cookie domain (`""` = host-only — the safe default; never widen to a parent domain by accident). |
+| `domains.oauthOrigin` | Canonical sign-in origin. |
+| `domains.devBoxBase` | Apex zone the **proxied** browser-terminal + sandbox hosts ride (`term-<login>.<devBoxBase>`, `sandbox-<login>.<devBoxBase>`). Must be a one-label-under-apex zone so free edge TLS (`*.<apex>`) covers it — a two-label host fails edge TLS (the [#771](https://example.com/builders#/task/771) lesson). Empty ⇒ no managed boxes. |
+| `domains.sshBoxBase` | Zone for the **legacy direct-IP SSH** box host (`box-<login>.<sshBoxBase>`, unproxied). Deliberately distinct from `devBoxBase` (one proxied/edge-TLS, one direct-IP). |
+| `domains.sandboxPrefix` / `termPrefix` | Subdomain prefixes for the sandbox-preview + browser-terminal hosts. |
+| `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. "drachmae"). 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 drachmae-per-USD peg (default `1`). A committed, code-reviewed change — not a live UI knob. Omit ⇒ code defaults (20% margin, 1:1 peg). |
+| `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). |
+| `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)).
+
+## Using it
+
+```js
+const { branding } = require('./src/branding');
+const b = branding();              // resolved singleton (env → config → neutral)
+res.send(`Welcome to ${b.identity.worldName}`);
+```
+
+Tests drive the pure resolver with injected objects (no I/O): `resolveBranding({ neutral, instance, env })`. See `tests/branding.mjs`.
+
+### On the client (R56 task [#1195](https://example.com/builders#/task/1195) + R57 task [#1196](https://example.com/builders#/task/1196))
+
+The browser never sees the full pack — only the **client-safe projection** `clientBranding()` (a small allow-list — `{ identity, currency, theme, copy, rankLabels }`; origins, repo, db name, `llmProjectName`, and env prefix stay server-side). It reaches the front-end two ways:
+
+- **On-box (hall + status served from the droplet):** injected synchronously by `mountInternalSurfaces` (`src/bongos/serve-internal.js` → `injectBrandingGlobal`) into the page `<head>` as **`window.__BRANDING__`** (the strings) **plus theme markup** (`themeMarkup` → a `:root` palette/font-var override `<style>`, the web-font `<link>`s, and the favicon `<link>`). The `<style>` lands after the page's own stylesheet so the pack wins. No fetch, no flash-of-default.
+- **Off-box (the GitHub-Pages status page):** read cross-origin from **`GET /api/gds/public/branding`**.
+
+R56 seeded the projection with the configurable **currency label** (`public-builders/brand-apply.js` fills `[data-currency-label]` / `[data-currency-tmpl]` markup + `window.OTBBranding.currencyLabel()`). R57 widens it to the **LOOK** — `theme.ui` (palette + fonts + favicon; note this is the WEB theme, distinct from the server-only `theme.palette` game pixel-art path) — and the **rank display-label map** (`window.OTB.rankLabel()` reads `rankLabels`; the rank ENUM stays Greek by decision, only the label is presentation). The remaining archaic **page copy + identity strings** (titles, ledes, "washed ashore" flavor) are tracked as the R57 copy-pack follow-up.
+
+## Branding a new instance
+
+Copy `config/branding.neutral.json` → `config/branding.json` and fill it in. The fastest path is to hand your own LLM the prompt in [`branding-fill-prompt.md`](branding-fill-prompt.md), which interviews you and emits a valid pack.

package/docs/branding-fill-prompt.md

@@ -0,0 +1,25 @@
+# Owner-LLM "fill-it-in" prompt — author a new instance's brand pack
+
+Paste the block below into your own LLM (Claude, etc.). It interviews you and emits a valid `config/branding.json` for a new Cloud Bongos instance. The schema + field meanings are in [`branding-contract.md`](branding-contract.md); resolution is env → this file → the neutral starter.
+
+---
+
+> You are setting up the branding for a new instance of **Cloud Bongos**, an AI-first build platform. Produce a single JSON object for `config/branding.json` that conforms to the contract below. Ask me only for what you can't reasonably infer; pick sensible defaults for the rest and tell me what you assumed. Output **only** the JSON when done.
+>
+> Interview me for:
+> 1. **Product name** and the **in-world / display name** (can be the same).
+> 2. **Operating company** name + website (optional).
+> 3. **Domains:** public origin, hall origin, status origin, the OAuth sign-in origin, and the session cookie domain (use `""` for a host-only cookie unless you run subdomains — never widen it casually).
+> 4. **GitHub repo** (`owner`, `name`) this instance ships to.
+> 5. **Reward currency label** (the unit builders earn; the math is fixed — this is display only).
+> 6. **Version tracks** (the set of work tracks; default `["default"]`).
+> 7. **Theme:** a palette file path if any, and a one-word `mode`.
+> 8. **Copy:** a short tagline, the hall's display name, and a 404 line in the instance's voice.
+> 9. **Env prefix:** an uppercase token for env-var overrides (e.g. `ACME`).
+> 10. **`llmProjectName`:** the project's name as it should appear inside grading/review LLM prompts.
+>
+> Constraints: every `domains.publicOrigin`, `identity.productName`, `identity.worldName`, and `llmProjectName` is **required** and non-empty. Default `cookieDomain` to `""`. Don't invent secrets or tokens. Keep it to the documented fields.
+
+---
+
+After it emits the JSON, save it as `config/branding.json`, then run `node --test tests/branding.mjs` to validate it loads and resolves.