@bongos/core 1.17.0

package/CLAUDE.md

@@ -0,0 +1,242 @@
+# Off the Boats — Project Memory
+
+> **This file is descriptive. The source of truth for permissions, scope, and state is the Bongos database accessed via `/api/bongos/*`.**
+> CLAUDE.md is the index and durable *framing* for AI agents — not an authority. Where it describes live state (tasks, versions, claims, ranks, costs) the database wins; where it describes permissions, [`docs/canonical-permissions.md`](docs/canonical-permissions.md) + the server's `requireRank` checks win (see [ADR 0016](docs/adr/<redacted>.md)). If this file and a route/DB row disagree, the route/row is authoritative and the doc is the bug. Editing this file cannot grant any authority.
+
+This file is the **index and durable framing** for the project. Read it at the start of every session. When a section is relevant to your task, **drill into the linked detail files** rather than expecting all the depth here. Update this file (or a linked detail file) at the end of every session — see [§12 Session Update Protocol](#<redacted>). **Read docs on your instance's builders' hall (`domains.buildersOrigin` in [`config/branding.json`](config/branding.json)), not raw on github.com** — the hall is the canonical doc-reading surface (task refs render as working links there, §8's hall-link convention); github.com is the code host only, where a bare `#NNN` autolinks to a GitHub issue and 404s (tolerated, not supported). If the hall is down, your instance's status page (`domains.statusOrigin`) is the fallback for project state ([ADR 0029](docs/adr/<redacted>.md), off-box), though not full doc rendering. How an agent resolves these surfaces from config alone (with no hard-coded host) is the **docs-discovery contract** — [ADR 0114](docs/adr/<redacted>.md); `GET <publicOrigin>/api/bongos` re-advertises them for zero-config bootstrap.
+
+**AI-first norm — the foundational assumption.** Cloud Bongos is an **AI-first build platform: AI agents write the code.** A human owner sets scope, direction, and the hard gates (rank, approval, deploy); the day-to-day building — code, docs, migrations, reviews — is done by AI agents claiming tasks. **Every rule in this file is written for that reader.**
+
+---
+
+## Working with this file (content charter)
+
+CLAUDE.md loads **in full, every session** — so every line spends context budget, and a bloated file makes agents *miss* real instructions ([ADR 0061](docs/adr/<redacted>.md); the context-rot literature). Two rules keep it lean:
+
+- **Per-line test:** *would removing this line cause an agent to make a mistake?* If not, cut it.
+- **What goes where:**
+
+| Content | Home |
+|---|---|
+| Portable methodology — working rules, session protocol, claim→ship lifecycle, this charter | **this file** (the core Cloud Bongos ships to any instance) |
+| Host instance identity — product/world/company, vision, visual style | [`docs/project-context.md`](docs/project-context.md) (prose) + [`config/branding.json`](config/branding.json) (the strings code reads) |
+| Live state — tasks, versions, ranks, costs, claims | the **Bongos DB** (`/builder-start`, `/status`) |
+| *Why* a non-obvious choice was made | an **ADR** ([`docs/adr/`](docs/adr/)) |
+| Multi-page how-to / ops guide | a **recipe** ([`docs/recipes/`](docs/recipes/)) |
+| One module's public surface + gotchas | that dir's **nested `CLAUDE.md`** (loads on demand) |
+| Short per-rule learning | the **`learnings`** table (`learning-capture.js`) |
+
+**Budget: ≤ ~200 lines.** Past that, relocate detail *down this table* — don't append here. Per-module maps live at [`src/bongos/`](src/bongos/CLAUDE.md), [`src/bongos/routes/`](src/bongos/routes/CLAUDE.md), and [`scripts/gds/`](scripts/gds/CLAUDE.md), and load only when an agent works in that folder.
+
+---
+
+## Quick navigation
+
+| If you need… | Go to |
+|---|---|
+| **What I should claim right now** (parallel-safe tasks) | Run `/builder-start` |
+| **What's the status of a version / criterion** (what's left for C8?) | Run `/status` — rolls up each done-when criterion → gating tasks → what remains ([ADR 0025](docs/adr/<redacted>.md)) |
+| **Project identity** (product, world, visual style — host context) | [`docs/project-context.md`](docs/project-context.md) (prose) + [`config/branding.json`](config/branding.json) (strings code reads, [contract](docs/branding-contract.md)); split out per [ADR 0062](docs/adr/<redacted>.md) §7 |
+| **Live architecture detail** (infra, stack, DB schema, Bongos API) | [`docs/architecture.md`](docs/architecture.md) |
+| **API reference** (every endpoint, gate, params) | Generated **OpenAPI 3.1** at [`docs/api/openapi.json`](docs/api/openapi.json) + [`docs/api-reference.md`](docs/api-reference.md); rendered at **`/docs`** on the instance's own origin. Regenerate: `node scripts/gds/gen-api-docs.js` ([ADR 0109](docs/adr/<redacted>.md)). **External consumers**: typed client [`clients/bongos-client`](clients/bongos-client/README.md) + auth/hello-world on-ramp [`docs/api-onramp.md`](docs/api-onramp.md) |
+| **Module system** (plugin-API contract, manifest schema, seams, rank-gate rule, module-owned migrations, module-author recipe) | [`docs/modules-contract.md`](docs/modules-contract.md) · [ADR 0083](docs/adr/<redacted>.md) |
+| **Who can do what** (rank ladder, trust boundary — DB enforces) | [`docs/canonical-permissions.md`](docs/canonical-permissions.md) · [ADR 0016](docs/adr/<redacted>.md) |
+| **How builders earn the reward currency** (cost-plus token reward + per-task credits) | The **economy module** owns the reward policy as per-instance config — currency label + cost-plus margin + USD peg: [`modules/economy/CLAUDE.md`](modules/economy/CLAUDE.md) (`config/branding.json` `currency.label` + `reward.{marginPct,usdPeg}`) · [ADR 0054](docs/adr/<redacted>.md), [ADR 0023](docs/adr/<redacted>.md) |
+| **What do we already know about X** (search before re-solving) | Run `/recall <query>` — rank-scoped lexical search over every repo doc + indexed DB prose ([ADR 0060](docs/adr/0060-gds-retrieval-layer.md)) |
+| **Where does symbol/function X live** (code altitude map) | `docs/repo-map.md` — generated symbol skeleton (complements `/recall`), now also a **doc link-graph + staleness flags** (which docs a key doc links to; which docs carry unresolved links needing a touch-up — task 2013). **Gitignored + regenerated at deploy/box-fetch, not committed** ([ADR 0110](docs/adr/<redacted>.md)); if absent in your tree run `node scripts/gds/gen-repo-map.js` ([ADR 0063](docs/adr/<redacted>.md)) |
+| **What keeps the architecture boundary from rotting** (fitness functions) | `node scripts/gds/fitness.js` — CI gate (in the `unit` check): core↔host import boundary, CLAUDE.md budget + nested-doc presence, no route bypasses rank checks, repo-map freshness ([ADR 0061](docs/adr/<redacted>.md), [0062](docs/adr/<redacted>.md) §1; nested-doc discovery assumes core dirs sit at the instance root — [0108](docs/adr/<redacted>.md) moves them into the core package) |
+| **Docs/markdown entropy** (stale links, broken anchors, duplicate prose) | `node scripts/gds/docs-entropy.js [--verbose] [--file-ideas]` — parallel to knip dead-code scan; surfaces broken internal links and cross-file duplicate prose across all tracked `.md` files |
+| **Where files live** (full repo tree) | [`docs/file-map.md`](docs/file-map.md) |
+| **What a past version shipped / a version's scope** | Per-version scope archives are [`limitations/*-shipped.md`](limitations/) (each written only *after* a guided review — a fresh instance's core template ships with none). This instance's specific game + platform version history + roadmap framing lives in [`docs/project-context.md`](docs/project-context.md); live status via `/status`. |
+| **Dev Box desktop app** (mac menu-bar / Windows tray switch for the builder box: pairing auth, downloads, release flow) | [`devbox-app/README.md`](devbox-app/README.md) · [ADR 0045](docs/adr/<redacted>.md) · [`docs/recipes/devbox-app-release.md`](docs/recipes/devbox-app-release.md) |
+| **Future limitations to lift / next-version planning** | `limitations/backlog.md` (read-only archive — live tasks now in Bongos DB) |
+| **In-flight feature ideas captured during a session** | Capture to the live `idea_inbox` via `node scripts/gds/capture.js "…"`; triage with `/idea-triage`. (The old [`generative-ideas.md`](generative-ideas.md) is a frozen 2026-05-11 snapshot.) |
+| **Inbound team messages** (chat → `idea_inbox`, then `/idea-triage`) | The mechanism lives in the **discord module** → [`modules/discord/CLAUDE.md`](modules/discord/CLAUDE.md); this instance's server-specific inbound setup is [`docs/discord/inbound.md`](docs/discord/inbound.md). |
+| **Ops gotchas + recipes** (read before deploying) | [`docs/recipes/ops-gotchas.md`](docs/recipes/ops-gotchas.md) |
+| **Things stuck on the owner's input** | [`blockers/blockers.md`](blockers/blockers.md) |
+| **Why we chose what we chose** (architecture decisions — full ADR index) | [`docs/adr/README.md`](docs/adr/README.md) |
+| **Multi-agent system (MAS)** — agent hierarchy, grader, phased plan | [ADR 0024](docs/adr/<redacted>.md) (architecture + ship table) · [0026](docs/adr/<redacted>.md) (BFG) · [0027](docs/adr/<redacted>.md) (6D eval). **All four shipped** — Grader (4-worker adversarial panel + route-rank pre-pass), Conductor (`UserPromptSubmit` hook), Architect (`--scope` audits → [`docs/audits/`](docs/audits/)), BFG. Only Phase 4.5 (autonomous dispatch) is unbuilt. |
+| **Architecture audits — first-principles "what to delete" reviews feeding next-version scope** | [`docs/audits/`](docs/audits/) (produced by the Architect — MAS Phase 5; `node scripts/gds/architect-audit.js --scope … --paths …`) |
+| **Session-end handoff template** (use at every session end) | [`docs/handoff-template.md`](docs/handoff-template.md) |
+| **Discord integration** (build broadcast, channel layout, role sync — a one-way mirror, outside the trust boundary) | The **discord module** owns the mechanism → [`modules/discord/CLAUDE.md`](modules/discord/CLAUDE.md). This instance's server-specific channel config is [`docs/discord/channels.json`](docs/discord/channels.json). |
+| **Pixel-art design system** (pipeline, rubric, palette, skills) | The **art-pipeline module** owns the mechanism → [`modules/art-pipeline/CLAUDE.md`](modules/art-pipeline/CLAUDE.md) (operational ref: [`art/README.md`](art/README.md)). The pixel/Greek *style* choice itself is instance detail → [`docs/project-context.md`](docs/project-context.md). |
+| **Bongos** — the work-tracking system (formerly GDS/PMS): architecture, schema, slash commands | [ADR 0010](docs/adr/0010-pms-architecture.md); `src/bongos/` + `scripts/gds/`, API at `/api/bongos/*` (the prior `/api/gds/*` stays mounted **forever** as a permanent alias; `/api/pms/*` now 404). Read-side back-compat for the `pms_session` cookie, `PMS_GITHUB_*` env vars, and `~/.config/otb/pms-session.json` stays. |
+| **Deploying PMS-V1 + status subdomain end-to-end** | [`docs/pms-v1-deploy.md`](docs/pms-v1-deploy.md) |
+| **Public build-status dashboard (live)** | your instance's status page (`domains.statusOrigin`) — source in `modules/status-ui/public/` (carved to a module, BV1.R84) |
+
+---
+
+## 1. Project Overview
+
+> **What this instance is** — the product, company, vision, world, and visual style — is host instance context, kept in [`docs/project-context.md`](docs/project-context.md) (prose) + [`config/branding.json`](config/branding.json) (the strings code reads), **not in this portable core**. Per [ADR 0062](docs/adr/<redacted>.md) §7, moving the project identity out of CLAUDE.md *is* the core ↔ host split: CLAUDE.md is the methodology Cloud Bongos ships to any instance; `docs/project-context.md` is what an instance authors on top of it.
+
+**Work-type axis.** A task's work type comes from its **role/discipline** (engineer / artist / ideator / ui), set per task — not from a version "track." (The former two-track `product`/`internal` model was deprecated in BONGOS-V1; versions are just named scope milestones now.)
+
+---
+
+## 2. The Prompter (product owner)
+
+The product owner sets scope, direction, and the hard gates. But there is **no special "owner" entity** — an owner is just a builder with elevated permissions and an **interaction profile**. How to pitch replies to whoever you're working with — tone, technical level, local-toolchain familiarity — is *that builder's* profile, captured at onboarding and injected each session (the **builder-settings module**'s `interaction` knob, sibling of `wandering`; [`modules/builder-settings/CLAUDE.md`](modules/builder-settings/CLAUDE.md)). `/me` carries the resolved `interaction.contract`.
+
+**Portable defaults** (the fallback when a builder has set no profile — the `interaction-prefs.js` defaults): assume the reader may not be a software engineer (define jargon on first use; treat local toolchains — Homebrew, ports, env vars — as new, explained step by step); frame trade-offs as **cost, time, and what the user will see**, not framework taxonomy; ask about **outcomes and product behavior**, not implementation details (decide those yourself and present for confirmation); be concise. A builder's profile overrides these.
+
+**Turn-end sound** is builder-local ergonomics, owned by the builder-settings module (per-sound on/off + volume + per-event variant); `.claude/hooks/stop-sound.js` plays it by flag priority — raise the **triumph** flag only for genuine milestones.
+
+**Build broadcast.** On deploy, the shipped task's `--summary` is broadcast to the team chat (short, no jargon, business-owner audience); inbound flows back to `idea_inbox`. The mechanism + this instance's channels live in the **discord module** ([`modules/discord/CLAUDE.md`](modules/discord/CLAUDE.md)) — a one-way mirror, outside the trust boundary.
+
+**Subagent model routing — quality first, cost lever second.** Subagent spawns via the `Agent` tool MUST set the `model` parameter explicitly — never inherit silently — to the builder's resolved **model allocation**. The *shape* is stable methodology: the main interactive session runs the top tier (what the builder sits in front of); subagents default to the development tier; only mechanical known-path work (list claimable, fetch a row by id, log a cost entry, read a known file) drops to the cheap tier. *Why the tiers split by judgment-load, not by task:* research feeds code that ships, so a cheaper research tier degrades downstream quality more than it saves — when in doubt, pick the development tier.
+
+The tier **values** are settings-driven ([`modules/builder-settings/CLAUDE.md`](modules/builder-settings/CLAUDE.md), task 2011): instance default `config/branding.json` `models.{main,subagentDefault,subagentRoutine}` (this instance: `opus` / `opus` / `haiku`, i.e. "no Sonnet"), overridable per builder. The resolved allocation is on `/me` (`model_allocation.effective`); changing a tier is a config/settings edit, not a doc edit.
+
+---
+
+## 3. Company Context
+
+> Instance identity — company, vision, world, and visual style (the former §§3/5/6/7) — is host context in [`docs/project-context.md`](docs/project-context.md); the machine-readable strings are the branding contract ([`config/branding.json`](config/branding.json) / [`docs/branding-contract.md`](docs/branding-contract.md)). Why this lives out of the core is the §1 note + the charter. §§3/5/6/7 stay as stub headings so existing anchors/cross-refs resolve.
+
+---
+
+## 4. Financial Constraints
+
+**This instance's actual budget — the annual number and the spend target — is host context in [`docs/project-context.md`](docs/project-context.md).** The portable posture every instance inherits:
+
+- **Choose the cheapest viable option.** Bootstrapped mindset — avoid expensive architectures and premium SaaS unless there is no reasonable alternative.
+- **Document the trade-off in an ADR** ([`docs/adr/`](docs/adr/)) when a more expensive option is chosen, so the decision can be revisited.
+- **Optimize monthly recurring cost.** Any proposal that locks in a high fixed monthly cost (managed servers, large always-on databases, premium CDNs with per-GB egress at high volume) needs explicit justification and a cheaper fallback.
+- **The owner controls spend.** Nothing gets purchased without the owner's explicit go-ahead.
+
+---
+
+## 5. Goal & Vision
+
+> Host identity → [`docs/project-context.md`](docs/project-context.md) (see the §3 note).
+
+---
+
+## 6. World Design
+
+> Host identity → [`docs/project-context.md`](docs/project-context.md) — the world/setting + the trademark posture (the world name is a single config string, `identity.worldName`). See the §3 note.
+
+---
+
+## 7. Visual Style
+
+> Host identity → [`docs/project-context.md`](docs/project-context.md) — the visual style, the self-improving `art/` pipeline (palette/rubric non-negotiables), and the art skills. See the §3 note; operational reference: [`art/README.md`](art/README.md).
+
+---
+
+## 8. Versioning Methodology
+
+The project ships version-by-version. Each version is a named scope milestone — some user-facing (V1, V2, V3…), some improving *how* we build (the platform versions). There is no "track" taxonomy; a task's work type comes from its role/discipline.
+
+**Live version names, statuses, and ship dates are in the Bongos `versions` table (`/status`) — this instance's version history is host state, not portable core** (the product-roadmap framing + platform-version history are preserved in [`docs/project-context.md`](docs/project-context.md)). A key methodology rule (`feedback_new_version_review`): a new version's scope-truth archive isn't written — and the repo isn't "king" for that version — until a guided shipped-tasks + code review with a senior builder produces it. A builder claims whatever is claimable; versions ship independently.
+
+The durable artifacts of this method are folders + a database:
+
+- [`limitations/*-shipped.md`](limitations/) — the **mechanism**: one preserved scope archive per shipped version, each written only *after* a guided shipped-tasks + code review (a fresh instance ships with none). *This* instance's specific per-version archives + which versions still await their review are host state — [`docs/project-context.md`](docs/project-context.md).
+- **Bongos database** (Postgres `tasks` + `claims` + `versions`) — the live work-tracking layer; `/builder-start` shows what's claimable. `limitations/backlog.md` is a frozen pre-import archive.
+- [`docs/recipes/`](docs/recipes/) — long-form ops guides (read before similar work); short per-rule learnings go to the `learnings` table (`learning-capture.js`).
+- [`blockers/`](blockers/) — work needing the owner's input (resolve = delete). [`docs/adr/`](docs/adr/) ([index](docs/adr/README.md)) — Architecture Decision Records for any non-obvious choice.
+- [`generative-ideas.md`](generative-ideas.md) — frozen 2026-05-11 snapshot; live ideas go to `idea_inbox` via `capture.js`, triaged with `/idea-triage`.
+
+**Working rules while building:**
+
+- **Every change is backed by a claimed Bongos task. No exceptions.** This is the methodology's hard rule. If you find yourself about to commit code, edit a doc, run a DB migration, change a config, move a task between versions, or otherwise alter state — and you do not hold an active Bongos claim covering that work — stop. Create or find the task in Bongos, claim it, *then* make the change. There is no "admin work" loophole, no "meta-work" loophole, no "tiny fix" loophole, no "just a doc tweak" loophole, no "scaffolding" loophole, and no "I'm setting up to do the real work" loophole. The point of the rule is that Bongos is the complete ledger of what happened to this project — if a change isn't in it, the ledger lies. (See feedback memory: `feedback_follow_methodology.md`.)
+- **Direct DB writes are work too.** Updating `tasks`, `versions`, `blockers`, etc. via `psql` is a change to project state. It needs a claimed task just like a `git commit` does. The fact that the API doesn't yet expose an endpoint for the operation does NOT make it admin work — it just means the operation runs under a claim via SQL instead of via an HTTP call. Capture the SQL in the claim's session-log notes so the audit trail is complete.
+- **Start every session with `/builder-start`** to see claimable tasks. The API computes parallel-safety against currently-active claims so you don't have to.
+- **Claim before working.** `/builder-claim N` locks the task to your session. If the claim fails (already claimed, touches conflict, not ready, **dependencies not shipped**), pick another. If nothing exists for the work you're about to do, create the task first via `POST /api/bongos/tasks` or `node scripts/gds/capture.js`, then claim it.
+- **Dependencies gate everything.** A task declares `dependencies[]` (task IDs that must be `shipped` first); shipping a task auto-promotes its now-unblocked dependents `backlog`→`ready`, and `POST /claims` refuses with 409 `DEPS_NOT_SHIPPED` otherwise. The `V##.R##` rank prefix is decorative; deps are load-bearing. Full mechanics + CRUD endpoints in [ADR 0015](docs/adr/<redacted>.md).
+- **Ship or release at session end.** `/builder-ship` runs smoke tests, then chains `completed` → `confirmed` (**credits land here**) → `shipped` (merged + deployed). Anything left at `confirmed` is landed automatically by the server reconciler within ~5 min. `/builder-release` returns the task with no credits. `git merge` at land time is the authoritative collision detector (a wrong up-front touches[] prediction is not ship-blocking). See the `/builder-ship` skill doc.
+- **How readily you surface a tangent vs. silently capture it is your *wandering* level** — a per-builder, rank-defaulted knob (newcomers = Locked: never raise off-task tangents or investigations; file them with `capture.js` and stay on the claim). It tunes the three rules below; it does *not* limit in-task initiative. Resolved + clamped server-side, injected each session ([`modules/builder-settings/wandering-prefs.js`](modules/builder-settings/wandering-prefs.js)).
+- Idea that fits inside an existing claim → just ship it under that claim.
+- Idea that **does not** fit the active claim and is small + in current version → finish current claim first, then claim a new task for it.
+- Idea that's bigger or out of scope → create a new task via `POST /api/bongos/tasks` (status `backlog`) or capture via `node scripts/gds/capture.js` for `idea_inbox` triage.
+- Significant non-obvious decision made → write an ADR in [`docs/adr/`](docs/adr/) and link it from the shipping task's notes.
+- Discovery that took more than ~10 minutes to diagnose → capture as a learning via `node scripts/gds/learning-capture.js` (DB-backed; see `learnings` table). For longer multi-page recipes, write a file under `docs/recipes/`.
+- Stuck on something only the owner can decide/provide → write a [`blockers/`](blockers/) entry AND attach the blocker_ref to the relevant task.
+- Change touched anything the onboarding diagrams describe (ranks, task statuses, versions, currency-and-karma / architecture) → **all 5 diagrams are auto-generated** by `scripts/gds/gen-diagrams.js` (runs on deploy; `.svg`/`.png` + `assertions.json` in lockstep). **Never hand-edit a `.mmd` or `assertions.json`** — edit the template in `gen-diagrams.js`, run it, commit. Backstop in [`docs/handoff-template.md`](docs/handoff-template.md).
+- **Never write a bare `#NNN` for a Bongos record in prose you emit** (chat, reasoning, commits/PRs, docs) — a bare `#NNN` autolinks to GitHub issues and **404s** (our task/idea/blocker ids ≠ GitHub's). Write the hall link `[#NNN](<buildersOrigin>#/task/NNN)` — using your instance's hall origin (`domains.buildersOrigin`), which renders as a clean `#NNN`; plain `task NNN` is fine too. Enforced in committed Markdown by `scripts/gds/linkify-refs.js` and at turn-end by the `.claude/hooks/stop-refcheck.js` Stop hook (a genuine `PR #8` is left alone).
+
+**At end of session:** `/builder-ship` (or `/builder-release`) the active claim, then review [`generative-ideas.md`](generative-ideas.md) — promote actionable ideas into new tasks, deliver in-scope small ones, delete bad ones.
+
+---
+
+## 9. Product versions (summary)
+
+> **Product-version scope is host context + live DB state — not portable core.** The named product versions, what each shipped, the carry-forward limits, and the roadmap framing are this instance's identity: see [`docs/project-context.md`](docs/project-context.md) for the human roadmap framing and [`limitations/`](limitations/) for the preserved per-version scope archives (e.g. [`limitations/v1-shipped.md`](limitations/v1-shipped.md)). The **live source of truth is the Bongos `versions` table** — run `/status`. This heading stays a stub so existing cross-references and anchors keep resolving (see the §3 note).
+
+---
+
+## 10. Architecture — current state
+
+The full architecture detail — live infra (domain, host, TLS, hardening), application stack, networking + render model, code & deploy flow, the complete DB schema (game + Bongos tables, columns, views), and the Bongos API surface — lives in **[`docs/architecture.md`](docs/architecture.md)**, **not in this portable core**: it describes *this* instance's live system, and a fresh instance authors its own. Read the detail file for any specifics.
+
+Two anchors are always true and stay here: **the Bongos DB is the source of truth for all live work state** (this index only ever *describes* the schema), and the Bongos API is mounted at **`/api/bongos/*`**. The architecture *rules* that are portable are the trust-boundary ones below.
+
+> **Decision rationale (why we chose what):** full index at [`docs/adr/README.md`](docs/adr/README.md) — the load-bearing methodology decisions are 0010 (Bongos work-tracker), 0016 (trust boundary), 0024 (MAS), and 0061/0062 (context-layer decomposition + core↔host split); instance-specific stack and infra ADRs are indexed there too.
+
+> **Permissions / builder ranks: the DB enforces, markdown only describes.** Authority lives in `builders.rank` on the prod DB, checked server-side per request with **no caching**. A builder editing local files (CLAUDE.md, skills, `settings.json`, hooks) cannot grant themselves authority. The rank ladder, what's gated, the local-edit failure modes, and the **no-hardcoded-admin-identity rule** (enforced by `scripts/gds/audit-authorship.sh` — no rank or builder identity is ever baked into a file) are all in **[`docs/canonical-permissions.md`](docs/canonical-permissions.md)**; the decision is [ADR 0016](docs/adr/<redacted>.md).
+
+> **🔒 Product builders build the product, not the platform they stand on.** The permission/pipeline internals an instance runs on — the rank/authz machinery, the ship/grade/deploy pipeline, DB `migrations/`, `infra/`, and the trust-boundary docs — are vendored Cloud Bongos core, not instance product surface. Landing code is Bongos's job: claim a task and run `/builder-ship`, never a raw `git push`/`ssh`/deploy. **Who may modify that core, the rank floor that gates it, and the hard enforcement** (protected-path glob, pre-push hook, grader pre-pass, post-push main audit) live in [`docs/canonical-permissions.md`](docs/canonical-permissions.md) and [ADR 0043](docs/adr/<redacted>.md) — editing local files can't grant that authority.
+
+---
+
+## 11. File Map — Where Things Live
+
+The full repo tree — project root, `migrations/`, `scripts/`, `src/`, `public*/`, `art/`, `tests/`, `.claude/skills/`, `.claude/scheduled-tasks/`, and the deploy-host layout — lives in **[`docs/file-map.md`](docs/file-map.md)**, the single source for the tree. Split out of this index to keep CLAUDE.md lean.
+
+---
+
+## 12. Session Update Protocol
+
+**At the START of every session**, before doing anything else:
+
+1. **Run `/builder-start`** to see what's claimable. Confirm with the owner which task to claim.
+2. **Run `/builder-claim N`** before starting work. The claim is what makes parallel sessions safe.
+
+At the **end of every session**, before signing off:
+
+1. **Resolve your claim.** `/builder-ship` (with handoff notes + value summary) on success, `/builder-release` on abandonment. Bongos records the session log entry and awards credits.
+2. **Write a session log entry as its own file** at [`docs/session-logs/YYYY-MM-DD-<slug>.md`](docs/session-logs/) using [`docs/handoff-template.md`](docs/handoff-template.md). **Do not hand-edit the §13 index** — the recent-sessions snippet there and the full [`docs/session-log-index.md`](docs/session-log-index.md) are generated from the files and regenerate at ship (`scripts/gds/gen-session-index.js`); just drop your dated file. For single-task sessions, the Bongos `session_logs` row is sufficient and a separate file isn't needed.
+3. **Review the idea_inbox** via `GET /api/bongos/inbox` (or run the `/idea-triage` skill — recommended daily). Promote actionable ideas into new tasks; mark stale ones discarded.
+4. **Update detail files** if anything changed: new gotcha → long-form recipe under [`docs/recipes/`](docs/recipes/) OR short-form rule via `node scripts/gds/learning-capture.js`; new blocker → `POST /api/bongos/blockers` (the markdown file is frozen archive); decision made → new ADR. If a version has no king-doc yet, capture version-related notes in `idea_inbox` + that version's tasks until its guided review pass produces the scope archive.
+5. **Update [`docs/architecture.md`](docs/architecture.md)** if the live system changed (§10 here is only an orientation + link).
+6. **Update [`docs/file-map.md`](docs/file-map.md)** if files or folders were added/moved/deleted (§11 here is only an orientation + link).
+   - *These "remember to update the detail files" steps (4–6) are backstopped mechanically:* `docs/repo-map.md`'s **staleness flags** (task 2013) list docs whose internal links no longer resolve — a regenerated signal of what drifted, so the touch-up is prompted, not left to memory.
+7. **No session-log index chore.** The §13 snippet + [`docs/session-log-index.md`](docs/session-log-index.md) regenerate from the files at ship — never hand-edit them. (Compressing very old prose into [`docs/session-log-archive.md`](docs/session-log-archive.md) is optional housekeeping for the on-disk corpus, not a per-session context-budget step.)
+
+If nothing changed in a section, leave it alone — don't churn.
+
+### Daily cadence skills (run once per day, not per session)
+
+Two manual slash-commands exist to keep the methodology surfaces from accumulating drift. Run each once per day (any session can pick them up; doesn't matter which one, as long as it happens):
+
+- **`/idea-triage`** — walk the open `idea_inbox` rows. For each: promote (→ task), discard, merge with another, or defer. Keeps the inbox actionable; deferring is fine but the cadence is the discipline.
+- **`/blocker-review`** — walk the open `blockers` rows. For each: resolved (auto-promotes linked tasks via DB trigger), still blocked (with a note), or escalate (surface to the owner / external ask).
+
+Both are NOT scheduled cron tasks — they're invoked manually via slash command at the start or end of any session. If a day passes without either running, the queues quietly grow; running them is the structural cure for the markdown-graveyard pattern that Phases 0–3 dismantled.
+
+> **`/merge-mode` is *not* a daily chore — don't run it on a schedule or tell builders to.** The server lands merges itself: green PRs auto-merge, a 5-min reconciler flips `confirmed → shipped`, and the [ADR 0082](docs/adr/<redacted>.md) resolver self-heals generated-file conflicts. It's the **rare manual fallback** for a strand still stuck after the ~5-min sweep (e.g. a non-generated-file conflict the server can't resolve) — reach for it then, not before.
+
+In addition, ~17 scheduled routines under [`.claude/scheduled-tasks/`](.claude/scheduled-tasks/) run autonomously on cron (e.g. `overnight-code-review`, `idea-triage-nightly`, `overnight-builder`, `bfg`, `security-review-weekly`). They complement the manual cadence skills so every methodology surface keeps flowing without per-session tax. Each is **instance-wide** (one scheduled run per instance, not one cron per builder — per-builder effects come from iterating builders in the routine body); which are on by default, their cadence, and which need the autonomy flag armed is the portability contract [`config/scheduled-routines.json`](config/scheduled-routines.json) ([ADR 0115](docs/adr/<redacted>.md)).
+
+---
+
+## 13. Session Log
+
+Session-log **prose** lives one file per session under [`docs/session-logs/`](docs/session-logs/) — `YYYY-MM-DD-<slug>.md`, written from [`docs/handoff-template.md`](docs/handoff-template.md) (older entries compressed into [`docs/session-log-archive.md`](docs/session-log-archive.md)); the DB session corpus (`session_logs` + the BFG `session_records`) is the structured record. The index is **generated**: full history in [`docs/session-log-index.md`](docs/session-log-index.md), and the recent slice below is regenerated at ship by `scripts/gds/gen-session-index.js` (the `gen-diagrams`/`gen-repo-map` pattern — [ADR 0062](docs/adr/<redacted>.md) §8). **Do not hand-edit the list below or the index** — write your dated file and both regenerate; generating from real files means a link can never dangle (retires the recurring §13 hand-maintenance drift).
+
+<!-- BEGIN GENERATED SESSION-LOG SNIPPET (scripts/gds/gen-session-index.js — do not hand-edit) -->
+**Recent sessions** (newest 10 — full history in [`docs/session-log-index.md`](docs/session-log-index.md)):
+
+- [2026-07-07 — Branded project-creation experience on cloudbongos.com (goal 35)](docs/session-logs/<redacted>.md)
+- [2026-07-04 — Planning session: "Robust, versioned, easy-to-call public API" (BONGOS-V1 goal 36)](docs/session-logs/<redacted>.md)
+- [2026-07-03 — Roadmap tab, batch-claim bug fixes, hall UI backlog seed](docs/session-logs/<redacted>.md)
+- [2026-07-03 — Hall UI redesign: dashboard shell, neutral voice, dark mode + the Goals page](docs/session-logs/<redacted>.md)
+- [2026-07-03 — Governance planning session: <redacted> roles & permissions (BONGOS-V1)](docs/session-logs/<redacted>.md)
+- [2026-07-03 — Cloud Bongos sky-whale — foundational multi-angle turnaround (task 1743)](docs/session-logs/<redacted>.md)
+- [2026-07-03 — Claude Bongos + Gemini Bongos vanity doors → cloudbongos.com orbs](docs/session-logs/<redacted>.md)
+- [2026-07-02 — Bongo Buddha tickle animation: land seeds (1699) + solve within-clip style-drift (1710)](docs/session-logs/<redacted>.md)
+- [2026-06-26 — Land Builder 25's world-building plan into V2 (task 1569)](docs/session-logs/<redacted>.md)
+- [2026-06-26 — Cloud Bongos ↔ Example separation: gap analysis + seed the foundation tasks](docs/session-logs/<redacted>.md)
+<!-- END GENERATED SESSION-LOG SNIPPET -->

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Code of Conduct
+
+## Our pledge
+
+We — contributors, maintainers, and the owners of Cloud Bongos instances — pledge to make participation in the project and its community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socioeconomic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+> Cloud Bongos is an AI-first platform: much of the day-to-day building is done by AI agents. This Code of Conduct governs the **human** participants — owners, reviewers, and contributors — and the standards they hold themselves and the agents they direct to.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people.
+- Being respectful of differing opinions, viewpoints, and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Accepting responsibility, apologizing to those affected by our mistakes, and learning from the experience.
+- Focusing on what is best for the community and the project.
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind.
+- Trolling, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information (such as a physical or email address) without their explicit permission.
+- Directing AI agents under your control to harass, dox, deceive, or otherwise harm others.
+- Other conduct which could reasonably be considered inappropriate in a professional setting.
+
+## Enforcement responsibilities
+
+Instance owners (Archon rank) are responsible for clarifying and enforcing the standards of acceptable behavior on their instance and will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful.
+
+Owners have the right and responsibility to remove, edit, or reject contributions, comments, commits, code, and other artifacts that are not aligned with this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all project and community spaces, and also applies when an individual is officially representing the project or community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the owners of the relevant Cloud Bongos instance. All complaints will be reviewed and investigated promptly and fairly. Owners are obligated to respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at <https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>, with additions specific to an AI-first project.

package/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to Cloud Bongos
+
+Cloud Bongos is an **AI-first build platform**: AI agents write the code. A human owner sets scope, direction, and the hard gates (rank, approval, deploy); the day-to-day building — code, docs, migrations, reviews — is done by AI agents claiming tasks. This guide is written for that reader.
+
+> The governing decisions behind these norms: [ADR 0065](docs/adr/<redacted>.md) (license + non-profit + AI-first) and [GOVERNANCE.md](GOVERNANCE.md).
+
+## License of your contributions
+
+Cloud Bongos is licensed under the **GNU AGPL-3.0** ([`LICENSE`](LICENSE)). Contributions are **inbound = outbound**: by contributing, you agree your contribution is licensed under the same AGPL-3.0. There is **no CLA** — we deliberately do not ask you to assign rights to a central entity, because that is the standard path to a future relicense (the capture we are designed to prevent).
+
+## The AI-first norm
+
+The expectation is that **AI agents author the work**. This is a **documented norm, not a technical gate** — there is no machinery that detects or blocks human-authored commits. We state it as the default because the entire methodology (the task lifecycle, the quality grader, the credit economy) is built around agents as the primary authors, and a contribution that ignores that grain tends to fight the tooling. An instance owner is free to relax the norm for their own instance.
+
+## The one hard rule: every change is backed by a claimed task
+
+There is no "admin work" loophole, no "tiny fix" loophole, no "just a doc tweak" loophole. If you are about to commit code, edit a doc, run a migration, or change config, you must hold an active task claim covering that work. The task database is the complete ledger of what happened to the project — if a change isn't in it, the ledger lies.
+
+## The claim → build → ship lifecycle
+
+1. **Start** — see what's claimable (parallel-safety is computed for you against currently-active claims).
+2. **Claim** — lock a task to your session before working. If nothing fits the work you're about to do, create the task first, then claim it.
+3. **Build** — make the change under the claim. Record non-obvious decisions as an **ADR** ([`docs/adr/`](docs/adr/)); capture hard-won discoveries as learnings.
+4. **Ship** — run the smoke tests + the quality grader, which awards credits and lands the change. Release the claim if you abandon the work.
+
+**Dependencies gate everything.** A task can declare dependencies (other tasks that must ship first); you cannot claim a task whose dependencies haven't shipped. Shipping a task auto-promotes its now-unblocked dependents.
+
+Full methodology and the host-instance specifics live in [`CLAUDE.md`](CLAUDE.md) (the portable methodology core) and the per-module nested `CLAUDE.md` files.
+
+## Ranks and what you can touch
+
+Permissions are **server-enforced on the live database, per request, with no caching** — editing local files grants nothing ([ADR 0016](docs/adr/<redacted>.md)). The ladder is **Xenos → Thetes → Metic → Archon** (Newcomer → Contributor → Trusted → Owner); full detail in [`docs/canonical-permissions.md`](docs/canonical-permissions.md).
+
+- Newcomers (Xenos/Thetes) claim feature work but **stay out of the permission/methodology core** (rank/authz machinery, the ship/grade/deploy pipeline, `migrations/`, `infra/`, trust-boundary docs) and never run a raw `git push origin main`, `ssh` to prod, or a deploy script — landing code is the platform's job (claim a task and ship).
+- Metic+ may work the build pipeline and gate-surfaces.
+- Archon (the owner) controls scope, admission, rank, and deploy.
+
+## Quality expectations
+
+- **Tests** accompany behavior changes; the ship pipeline runs them and the adversarial quality grader. A change that fails the grader gets fixed and re-graded — overrides are a last resort.
+- **No bare `#NNN`** for a task/idea/blocker id in committed prose — it autolinks to a GitHub issue and 404s. Write a hall link or `task NNN`.
+- **Match the surrounding code** — comment density, naming, idiom. Read like the code already there.
+- **Architecture boundaries are CI-enforced** (the core ↔ host import boundary, the context-budget, the rank checks). Don't route around them; if a boundary is wrong, change it via an ADR.
+
+## Reporting security issues
+
+Do **not** open a public issue for a vulnerability. Security reporting and the bounty process are handled through the platform's security surface (see [`docs/security/`](docs/security/) where present). Responsible disclosure is rewarded.
+
+## Code of conduct
+
+Participation is governed by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

package/Dockerfile

@@ -0,0 +1,46 @@
+# Cloud Bongos — self-host image (V4.R63, task 1202, ADR 0062).
+#
+# Boots the GDS-ONLY platform entrypoint (src/platform-server.js): the build
+# platform + builders' hall + status dashboard, with NO game in the process.
+# A vanilla instance by default — see .dockerignore (config/branding.json and
+# config/modules.json are NOT copied in, so the image resolves to the neutral
+# Cloud Bongos brand with every feature module off). Brand/configure an instance
+# by mounting your own config/*.json (see docs/recipes/self-host.md).
+#
+# No prod topology is referenced anywhere here: no droplet IP, no amazonprimea
+# domain, no peer-auth socket. The DB is reached over TCP via PG* env vars,
+# supplied by docker-compose.yml (or your own orchestrator).
+
+FROM node:22-bookworm-slim
+
+# postgresql-client gives us `psql` for scripts/migrate.sh; bash runs it; tini
+# is a proper PID 1 so signals/zombies are handled. curl powers HEALTHCHECK.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends postgresql-client bash tini curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install runtime deps first (layer cache: only re-runs when the lockfile moves).
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+# App source. .dockerignore keeps the host brand/module packs, node_modules,
+# .git, and game/art assets out so the image is vanilla + lean.
+COPY . .
+
+ENV NODE_ENV=production \
+    HOST=0.0.0.0 \
+    PORT=3000
+
+# Run unprivileged (the `node` user ships with the base image).
+RUN chown -R node:node /app
+USER node
+
+EXPOSE 3000
+
+# Liveness: the platform server answers /healthz with no DB (see platform-server.js).
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=5 \
+    CMD curl -fsS "http://127.0.0.1:${PORT}/healthz" || exit 1
+
+ENTRYPOINT ["/usr/bin/tini", "--", "./docker-entrypoint.sh"]

package/GOVERNANCE.md

@@ -0,0 +1,44 @@
+# Governance
+
+How Cloud Bongos is governed, and the commitments that keep it a commons.
+
+Cloud Bongos is an **AI-first build platform**: a human owner sets scope and the hard gates; AI agents claim tasks and write the code. This document describes how the project is run and the promises that protect it from capture. The binding decision behind it is [ADR 0065](docs/adr/<redacted>.md).
+
+## Principles
+
+1. **Open, free, and protected from capture.** Cloud Bongos is released as open source under the **GNU AGPL-3.0** ([`LICENSE`](LICENSE)). The AGPL's §13 (Remote Network Interaction) closes the hosted-closed-fork loophole: anyone who runs a modified Cloud Bongos as a network service must offer that service's complete source to its users. This is the anti-monopoly guarantee — the platform stays a commons even when it is *operated*, not just when it is shipped.
+
+2. **Non-profit.** The project is **not monetized from its contributors**. No one pays to contribute, and no contribution is resold by the project as a proprietary add-on. The in-platform credit/drachmae economy is an **instance-internal** mechanism (an instance rewards its own builders from its own budget) — it is not the project monetizing the commons.
+
+3. **AI-first.** The expectation is that **AI agents write the code**. This is a documented norm, not a technical gate (see [CONTRIBUTING.md](CONTRIBUTING.md)). The whole methodology — the task lifecycle, the quality grader, the session economy — is designed around agents as the primary authors.
+
+4. **No capture path.** There is **no contributor license agreement (CLA)** assigning rights to a central entity, because a CLA is the standard mechanism for later relicensing — exactly the capture move the AGPL + non-profit posture are designed to prevent. Contributions are **inbound = outbound**: you contribute under the same AGPL-3.0 the project carries.
+
+## Who decides what
+
+Authority is **server-enforced**, not document-granted. A builder editing local files (including this one) gains no authority; the platform re-checks rank on the live database, per request, with no caching ([ADR 0016](docs/adr/<redacted>.md)). The rank ladder (kept as the platform's canonical permission model; full detail in [`docs/canonical-permissions.md`](docs/canonical-permissions.md)):
+
+| Rank | Role |
+|---|---|
+| **Xenos** | Newcomer — can claim starter tasks; kept out of the permission/methodology core. |
+| **Thetes** | Contributor — broader task access. |
+| **Metic** | Trusted — may touch the build pipeline and gate-surfaces. |
+| **Archon** | Owner — sets scope, approves members, controls deploy and the hard gates. |
+
+The **owner (Archon)** of an instance holds final authority over that instance: scope, member admission, rank changes, and deploy. This is per-instance — Cloud Bongos is **one project per install**; there is no central control plane that can override an instance's owner.
+
+## How work happens
+
+All work flows through the task lifecycle (the methodology core, described in [`CLAUDE.md`](CLAUDE.md) and [CONTRIBUTING.md](CONTRIBUTING.md)):
+
+> **claim → build → ship** — every change is backed by a claimed task; shipping runs the smoke + quality gates, awards credits, and lands the change.
+
+Non-obvious decisions are recorded as **ADRs** ([`docs/adr/`](docs/adr/)). Significant scope is set in **planning sessions** that define a version's done-when criteria. The database — not any markdown file — is the source of truth for live state.
+
+## Releasing to the public
+
+The public mirror is **generated** from the private instance-1 repository on a deliberate, **~6-month-delayed** cadence, carrying only the publishable subset (the portable core + platform — never a host's identity, secrets, content, or in-window development). The boundary and the delay are defined in [ADR 0065](docs/adr/<redacted>.md) §4 and implemented by the C9 export pipeline (R71/R72), with a lineage/no-leak proof (R73).
+
+## Changing this document
+
+This document and the commitments in it change the way any other governed decision does: a claimed task, an ADR recording the rationale, and the owner's approval. The license and non-profit posture are foundational — changing them would require a new ADR that explicitly supersedes [ADR 0065](docs/adr/<redacted>.md), and they exist precisely to be hard to quietly undo.