@bongos/core 1.17.0

package/docs/onboarding/primer.md

@@ -0,0 +1,202 @@
+# The Citizen's Primer
+
+*Read this before you claim your first work. ~10 minutes.*
+
+You're about to build inside Off the Boats, a project that runs on a small purpose-built dev system. This primer is the one document that gives you enough context to ask Claude smart questions and ship your first task without getting lost. Read it linearly — it's short on purpose.
+
+When you're done, open [/builders](https://example.com/builders) and run `/builder-start`. There's no separate "I have read it" step anymore — reading the primer is on your honor, and the work queue is already open to you.
+
+---
+
+## What Off the Boats is
+
+Off the Boats is a web experience that drops visitors into a single, persistent, playable digital world set in ancient Greece. Inside the world, players can spend real money to buy **physical goods** (fulfilled by a third-party logistics company called Example) and **digital assets** that develop the shared world. The world is never wiped — every interaction is permanent. The brand is mythic and underground: prices feel like a discovered secret, and the world reads as ancient even though the inciting object is a literal shipping container washed ashore. Visit [example.com](https://example.com) to see it.
+
+## What the GDS is
+
+The **Game Development System** (GDS) is the project's internal nervous system. It's a Postgres-backed task database with a small HTTP API, a CLI (the `/builder-*` slash commands), and a public dashboard at [status.example.com](https://status.example.com). Every change to the project — code, docs, art, migrations, even direct DB writes — happens under a **claim** on a GDS task. The claim is what makes parallel work safe (no two builders editing the same files at once) and what gives credit-tracking, cost-tracking, and the karma system something concrete to hang off.
+
+You don't need to understand the GDS schema to ship work. You just need to know: *claim a task, work on it inside your worktree, ship it.* The CLI handles the rest.
+
+## The claim → ship lifecycle
+
+Every piece of work moves through this loop:
+
+```
+backlog ─────▶ ready ─────▶ active ─────▶ completed ─────▶ confirmed ─────▶ shipped
+   │             │             │              │                │               │
+   │             │             │              │                │               └─ deployed to example.com
+   │             │             │              │                └─ verification passed, credits awarded
+   │             │             │              └─ you said "done", ship.js runs the smoke tests
+   │             │             └─ you ran /builder-claim (locks the task to your session)
+   │             └─ dependencies all shipped (auto-promoted by a DB trigger)
+   └─ task exists in the queue but isn't open yet
+```
+
+You drive the middle three states. The system handles the rest.
+
+**One claim at a time** while you're a Xenos. New builders hold a single active claim — ship it (or release it) before opening another, so the first work gets carried through. The limit is keyed to your rank: it lifts automatically when you graduate to **Thetes** (after your third shipped task), after which you can hold parallel claims if you want.
+
+When you ship, `ship.js` runs the project's **smoke tests** and the quality grader. If they pass, the task auto-confirms and **credits land** (this is the `completed → confirmed` edge — *not* the final deploy). The final `confirmed → shipped` hop — landing on `main` and deploying — is then handled for you, but *what it takes to land* depends on your rank and what you changed; the next section covers it. (There used to be an up-front `touches[]` "drift scanner" here too; it was retired — `git merge` at land time is the real collision detector. See [ADR 0049](../adr/<redacted>.md).)
+
+## How work lands — and what auto-ships
+
+`confirmed → shipped` is not a person clicking "merge". When you ship, `ship.js` opens a pull request and the project lands it for you — **nobody pushes to `main` by hand**. The PR has to go green on the automated checks (the test suite, a secret scan, and the **gate-review** classifier); the server then auto-merges it and `main` deploys to production. If a green PR ever stalls, a server sweep lands it within about five minutes, and `/merge-mode` is the manual fallback.
+
+The one thing that decides whether your ship is **instant** or **waits for an Archon** is *what your change touches*, weighed against your rank by the **gate-review** step ([ADR 0058](../adr/<redacted>.md)):
+
+| What your change touches | What happens |
+|---|---|
+| **Normal work** — game code, art, docs, tests, most of `src/` | **Auto-merges on green for any rank**, Xenos included. No approval. |
+| **A protected "gate surface"** — migrations, server routes, the ship / deploy plumbing | Auto-merges **only if you are Metic or above** (rank trust). A Xenos or Thetes ship here **waits for an Archon** to approve. |
+| **The safety core** — the gate's own machinery, the deploy switch, the rank / permission enforcement | **Always** waits for an Archon, whatever your rank. |
+
+So your first tasks **ship with no approval**: the newcomer chores — a tile, a doc fix, a unit test, a batch of ideas — all sit on the safe side of that line, and a clean ship merges and deploys on its own. You only meet the Archon gate if your change reaches into the project's own safety machinery, which builders below Metic are asked to stay clear of anyway ([ADR 0043](../adr/<redacted>.md)). Landing is always the GDS's job: you never run `git push origin main`, `ssh` to the server, or deploy by hand — `/builder-ship` opens the PR and the server does the rest ([ADR 0042](../adr/<redacted>.md)).
+
+## The rank ladder
+
+Four ranks, in ancient-Greek-civilization order:
+
+| Rank       | What it means                                                          | What it unlocks                                                                  |
+|------------|------------------------------------------------------------------------|----------------------------------------------------------------------------------|
+| **Xenos**  | Default for new builders. "Sandbox" tier.                              | Can only claim tasks flagged `newcomer_friendly`. Read everything. No mutations. |
+| **Thetes** | Graduated newcomer. You reach it **automatically after your 3rd shipped task** — no one has to promote you. | Claim **any** task in the general queue (not just newcomer-friendly). Still no triage/blocker/scope powers. |
+| **Metic**  | Approved working rank. The "real builders."                            | Claim any ready task. Idea triage, blocker review. Most of the work happens here. |
+| **Archon** | Project keeper.                                                        | Scope mutations, rank changes, infra-level operations.                            |
+
+So the sandbox is short: ship three small `newcomer_friendly` tasks and the city opens the whole queue to you on its own (the jump to **Metic** — with its triage/trust powers — is still a deliberate Archon promotion). Rank lives on the `builders.rank` column in the production database and is checked server-side on every privileged request — **with no caching**. A demotion takes effect on your next request. You cannot escalate your own rank by editing local files; the server is the source of truth. See [ADR 0016](../adr/<redacted>.md) and [ADR 0034](../adr/<redacted>.md) for the full trust model.
+
+## Drachmae and karma
+
+Two parallel reputation tracks. You don't need to *do* anything special to earn either — claim a task, do good work, ship it, and the system tracks both. The full mechanics (formulas, the kind table, the budget cap, every karma source) live in **[Drachmae & karma — how you get paid](drachmae-and-karma.md)**; here's the shape of it.
+
+- **Drachmae** (called "credits" in code) are your **equity** in the project — a score and a stake, *not* a currency you spend on anything. They only go up, and they persist if you leave and come back. Most of your drachmae now come from a **cost-plus reward on each shipped session**: the server prices the LLM tokens your work actually burned and pays you that real cost **plus 20%** ([ADR 0054](../adr/<redacted>.md)). On top of that, each task pays its `credits_reward` adjusted by the *kind* of work (a captured learning or a resolved blocker is worth 1.5×; cleanup 0.8×), and capturing an idea that someone else then ships earns you a 25% bonus ([ADR 0023](../adr/<redacted>.md)). Credits land at the `completed → confirmed` edge — when verification passes, not at deploy. See the standings on [/builders](https://example.com/builders).
+
+- **Karma** is a *separate* signal that measures **peer trust** — how other builders rate the *way* you work, not how much you ship. It's earned when Metic-and-above builders upvote your confirmed work (tallied weekly), when a proposal of yours is ratified, and when you capture ideas; it can also go *down* if you break things. Karma shows up on your profile (with a 30-day trend) and as a sortable column on the leaderboard, and it feeds your "builder strength" score. **It does not gate rank promotions** — those happen automatically by ship count (Xenos → Thetes after three ships) or by an Archon's deliberate decision. A builder who ships fast but breaks things gains drachmae and loses karma; a builder who ships thoughtfully gains both.
+
+One more thing worth knowing: builders are **uncapped by default** — your spend is tracked (it's the cost side of the same coin the reward is computed from) but never blocks you. There's no default budget. An Archon *can* set a per-builder **monthly budget cap** as a manual brake on a runaway; if one is set for you, you get a warning at 80% and `/builder-ship` pauses at 100% until it's raised ([ADR 0085](../adr/<redacted>.md)).
+
+## How to ask Claude about anything
+
+Claude is your pair-programmer here, but it doesn't know the project until you point it at the right files. The cheapest way to get good answers is to **name the surface you're looking at**. Some examples that work well:
+
+- *"Read [`CLAUDE.md`](../../CLAUDE.md) — what version are we currently building and what's the next claimable thing?"*
+- *"Read [`docs/architecture.md`](../architecture.md) — explain how the WorldRoom enforces server-authoritative movement."*
+- *"My task touches `src/bongos/auth.js` — read it and `docs/canonical-permissions.md`, then tell me which routes I'd need a `requireRank` gate on."*
+- *"Look at the last 5 entries in [§13 of CLAUDE.md](../../CLAUDE.md#13-session-log) — what was the most recent V3 task that touched the builders' hall?"*
+
+What doesn't work well:
+
+- *"How does the GDS work?"* — too open. Claude will hallucinate or read everything inefficiently.
+- *"What should I work on?"* — ask `/builder-start` instead. That's the GDS's job, not Claude's.
+- *"Is this safe to ship?"* — ask `/builder-ship` (it runs the smoke tests and, when enabled, the quality grader). Or run `/code-review` if you want a second opinion.
+
+**Use slash commands for plumbing, use Claude for thinking.** The `/builder-*` skills know how to talk to the GDS. Claude knows how to read your code and reason about it. Don't ask Claude to do something a slash command already does — it's slower and less reliable.
+
+## What the system remembers for you
+
+As you work, Claude writes down durable facts — your standing preferences, a gotcha that cost real time, the current state of the project — so the next session doesn't start cold. You don't manage any of this by hand, but it's worth knowing the shape:
+
+- **The map** (`MEMORY.md`) — a short index loaded at the **start of every session**: one line per memory, just enough to know *what* is known and where the detail lives. Kept deliberately small.
+- **The drawer** — the full notes themselves. They live on your machine, sync to the server (so your memory follows you across machines and boxes), and are searchable with `/recall`. They cost nothing until something fetches them.
+
+The map stays light on its own: a session-start guard warns if it's drifting large, and an auto-tidy moves the oldest, least-relevant notes off the map into the drawer when it crosses a threshold — **nothing is deleted**, it's just no longer loaded every session (a `/recall` away when a task needs it). Your standing rules, and anything pinned, always stay on the map. Full picture: [ADR 0074](../adr/<redacted>.md) and [diagram 4 — the architecture](diagrams/).
+
+## Where to find more depth
+
+The whole project's source-of-truth index is [`CLAUDE.md`](../../CLAUDE.md). Two starting points:
+
+- **For *what's true right now*** — go to the GDS DB via `/builder-start` or [/builders](https://example.com/builders). Tasks, claims, ranks, credits, costs all live there. CLAUDE.md is *descriptive*; the DB is *authoritative*.
+- **For *why we chose what we chose*** — go to [`docs/adr/`](../adr/) (Architecture Decision Records). Each ADR is one decision with the trade-offs that drove it.
+
+Other depth, in roughly the order you'll need it:
+
+- [`docs/onboarding/drachmae-and-karma.md`](drachmae-and-karma.md) — the full reward economy: how drachmae and karma are earned, the cost-plus session reward, and the monthly budget cap
+- [`docs/architecture.md`](../architecture.md) — live system: droplet, stack, schema, API surface
+- [`docs/modules-contract.md`](../modules-contract.md) — the product is built as a small core plus swappable `modules/<key>/` (dev boxes, the game, Discord, art, and more); this is the live roster and how a task lands inside one
+- [`docs/canonical-permissions.md`](../canonical-permissions.md) — who can do what (rank gates)
+- [`docs/file-map.md`](../file-map.md) — where every folder is and what it contains
+- [`docs/recipes/`](../recipes/) — long-form ops gotchas (read before deploying)
+- [`docs/onboarding/diagrams/`](diagrams/) — pan-and-zoom maps of the task lifecycle, rank ladder, the credit economy, the complete architecture (where your work runs and how it reaches production), and versioning
+
+You don't need to read these now. Bookmark them; come back when something specific is unclear.
+
+## Get set up on your machine
+
+You don't need to be a programmer to build here. Entry to the project is **approval-gated**: a stranger can't just sign in with GitHub — you first ask for entry on the [builders' hall](https://example.com/builders) and an Archon admits you. Since you're reading this gated primer, you've already been admitted.
+
+### Where your work runs — screen, worker, brain
+
+Claude Code is **three pieces that can live in different places**:
+
+- **The screen** — the window you look at and type into. Always on *your* device (the Claude desktop app, or a browser tab). It just shows files and sends your messages.
+- **The worker** — the part that opens files, runs commands, edits code, runs the project. Runs in **one place you choose**.
+- **The brain** — the AI model itself. **Always on Anthropic's servers**, whatever else you pick.
+
+You only ever choose **where the worker goes** — and that single choice *is* your setup path.
+
+### Three ways to set up
+
+| Path | Where the worker runs | Who it's for |
+|---|---|---|
+| **Cloud box** — *the default for new builders* | A dev box we create for you on DigitalOcean; your desktop app connects to it | Anyone new on a Mac or Windows machine. Nothing to install but the app — the code never lands on your own disk |
+| **Remote Control** | The **same** cloud box, but driven from a browser tab — [step-by-step guide](browser-terminal-guide.md) | Chromebooks / iPads / phones that can't run the desktop app |
+| **Local** — *trusted builders only (Metic and up)* | Your own computer | Power users who'd rather run the code on their own hardware to save the box cost |
+
+Your **first** cloud box is created hands-off; a returning box wakes itself; you never wait on an operator. (Entry to the project is already approval-gated — an Archon admitted you when you joined — so there's no separate per-box approval step.)
+
+> **Why is Local trusted-only?** Below Metic, the project's code lives **only inside the cloud box we control** — gated, revocable, and audited. Holding a permanent copy on your own machine is a trust grant that arrives when you're promoted to Metic, not on day one. New builders work in the box.
+
+> **Where things stand today.** The cloud-box on-ramp is built *and* now verified end-to-end — the desktop on/off app, the browser terminal, the per-builder sandbox preview, and the box → production ship path (a credential-less box uploads its branch and the server merges + deploys it via a GitHub App credential) have all shipped, and the whole box → production chain has been hardware-verified on a real box ([#1027](https://example.com/builders#/task/1027), [#1028](https://example.com/builders#/task/1028)). So the **cloud box is the proven default for new builders.** The **local-clone route below is the permanent home for Metic-and-up builders** — a fully supported alternative, not a stopgap. The single map that shows the whole picture — device, dev box, the per-builder memory layer, the server (authority *and* production), and how code travels from a box to prod — is [diagram 4, *The complete architecture*](diagrams/).
+
+> **Why a copy of the code at all?** The `/builder-*` commands you'll use every session aren't a separate download — they live *inside* the project's code (in `.claude/skills/`). The moment Claude Code **starts a session on a folder (or box) that already holds the code**, all the commands appear automatically. So "get the code" and "get the commands" are the same step — there's no plugin or zip to install. (One wrinkle: if you *clone the code mid-session into a folder that started empty*, the commands won't appear until you start a fresh session on that folder — step 3 handles it.)
+
+### The steps that work today (local route)
+
+Take them in order — each one sets up the next, from "I'm admitted" to "I'm looking at work I can claim."
+
+**1. Install the Claude desktop app.** Claude Code runs in a desktop app, **not** in the website — so you can't do this from a browser tab. Download it for your computer at **[claude.com/download](https://claude.com/download)** (Mac and Windows). Install it, open it, and sign in. You'll work in its **Code** tab.
+
+**2. Accept your invitation to the code (check your email).** When the Archon admitted you, GitHub emailed you a message like *"… invited you to collaborate."* Open it, click **View invitation**, then **Accept**. GitHub then drops you on the project's repository page. That page is just the code sitting at rest — a list of folders and files. **You don't need to do anything there**; accepting the invite is the whole point of this step. (No email? Check your spam folder, or ask the Archon to (re)send the repository invite — GitHub invitations can expire after 7 days.)
+
+**3. Open the code in Claude Code.** Back in the Claude desktop app's **Code** tab, you'll start a session on a folder. The easiest path — let Claude do the technical part for you:
+   - Make a new, empty folder on your computer (anywhere — your Desktop is fine).
+   - In Claude Code, point a new session at that empty folder.
+   - Type this one plain-English message and send it:
+     > *Clone the GitHub repository I was just invited to into this folder and open it as the project.*
+   
+   Claude handles the rest (this is the "git" plumbing you may have heard about — you don't need to learn it). When Claude asks for permission to reach GitHub, say yes — the repository is private, so it needs your go-ahead. If it asks which repository, paste the web address from the repo page you landed on in step 2.
+   
+   Once it finishes, that folder **is** the project. **One catch worth knowing:** the `/builder-*` commands came down *with* the code, but Claude Code only loads them when a session *starts* on a folder that already contains them — and this session started on an *empty* folder. So before the next step, **start a fresh Claude Code session on this same folder**: end this session and open a new one pointing at the folder. (Starting fresh is the clean way — the new session scans the folder from scratch, and the `/builder-*` commands will all be there.)
+
+**4. Enrol yourself and begin.** In the **fresh** session, type `/builder-setup` — or just say *"set up builder"* in plain English — and follow the prompts. It signs you in with GitHub once and registers you in the GDS so the commands know who you are. Then type `/builder-start` to see the works you can claim right now.
+
+If a `/builder-*` command ever says "no GDS session," just run `/builder-setup` again — that re-links you. And if `/builder-setup` itself comes back **"unknown command,"** you're almost certainly still in the session that did the cloning — start a fresh session on the folder (end of step 3) and it'll be there.
+
+> **Prefer a terminal? (the quicker path if you're technical.)** Steps 3–4 above are the no-terminal route. If you're comfortable on a command line, skip them — clone the repo yourself, `cd` into it, and run the bootstrap:
+>
+> **Before you start**, have three things ready: **Git** (check `git --version`; get it from [git-scm.com](https://git-scm.com/downloads)), the **Claude Code** desktop app ([claude.com/download](https://claude.com/download)), and a **GitHub account that's been invited to this private repo** (accept the emailed invite from step 2). Node ≥ 22 and Python ≥ 3.10 are checked by the bootstrap script — it prints the install command if either is missing, so you don't need them before cloning.
+>
+> **Step 0 — get the project onto your machine.** Clone the repo and `cd` into the folder it creates:
+>
+> ```sh
+> git clone https://github.com/example-owner/example.git
+> cd example
+> ```
+>
+> **Then bootstrap** from inside that folder: `./scripts/setup-builder.sh` (macOS/Linux) — or `node scripts/setup-builder.js` (Windows, or any OS). It checks your toolchain, installs dependencies, and runs the same GitHub sign-in in one shot — no Claude-session juggling. Either route lands you in the same place.
+
+## Your first task
+
+Run `/builder-start` to see what you can claim — no acknowledgment step needed, the queue is open. New builders see only `newcomer_friendly` tasks — small, well-scoped, easy to finish in one sitting. Pick one that looks interesting, claim it with `/builder-claim N`, do the work, and ship it with `/builder-ship`.
+
+When you ship your **first** task, drachmae land in your column and you're inducted as a citizen of Example. Ship your **third** and you graduate to **Thetes** — the one-claim limit lifts and the whole general queue opens to you. Welcome.
+
+## Your own dev box
+
+Every active builder — from your very first day as a **Xenos**, and **whatever your craft** (engineer, artist, or ideator) — gets a **personal dev box and a live game preview of your own**. There's no separate Archon approval to unlock them: being admitted to the project *is* the approval. Two everyday commands put them at your fingertips:
+
+- **`/builder-box`** — your box's control panel. It shows whether your box is awake, what it has cost, and your sign-in details, and it can **wake or (re)create your box hands-off** when it's asleep — you never wait on an operator. It's also where you find your **sandbox URL** (below) and, on a Chromebook or tablet, the browser-terminal link. Reach for it whenever you're unsure your box is up or you need to get back onto it.
+- **`/builder-stage`** — your private preview. Before you ship a change that touches the game, run `/builder-stage` to push your current edits to your **sandbox** — a personal copy of the game at `sandbox-<your-login>.example.com` that reflects only *your* work-in-progress. Open the link, watch your change running for real, and only then ship it. Nothing you stage there touches the live game or anyone else's box.
+
+In short: `/builder-box` gets you a workshop; `/builder-stage` lets you see your work on the shelf before it reaches the shop floor.

package/docs/project-context.template.md

@@ -0,0 +1,67 @@
+# <Product Name> — Project Identity (host instance context)
+
+> **Neutral template — the skeleton a new Cloud Bongos instance fills in.** This is the project-context *template* Cloud Bongos ships ([ADR 0062](adr/<redacted>.md) §7, task [#1205](https://example.com/builders#/task/1205)); `cloudbongos init` ([#1204](https://example.com/builders#/task/1204)) copies it to `docs/project-context.md` and an owner's own LLM fills the placeholders. It is the prose counterpart to the neutral branding starter [`config/branding.neutral.json`](../config/branding.neutral.json). **Instance 1's filled version is [`docs/project-context.md`](project-context.md).** Do not edit this template per-instance — edit your copy.
+>
+> **Relationship to the rest of the project:**
+> - [`CLAUDE.md`](../CLAUDE.md) is the **portable methodology core** Cloud Bongos ships — working rules, session protocol, claim→ship lifecycle, the [ADR 0061](adr/<redacted>.md) content charter, the nested-`CLAUDE.md` pattern. Instance-agnostic; you do not author it.
+> - **This file is the *prose* identity** — lore, vision, the why. The **machine-readable** identity (exact strings code reads: product/world/company names, domains, cookie/OAuth origins, currency label, palette, repo binding) lives in the branding contract [`config/branding.json`](../config/branding.json) ([`docs/branding-contract.md`](branding-contract.md)). **Where a name must be exact for code, the branding contract wins** — never re-hardcode a contract-owned string here.
+
+<!--
+OWNER-LLM FILL PROMPT
+=====================
+You are filling in a new Cloud Bongos instance's project-context file. Read config/branding.json (the machine-readable
+identity already chosen for this instance) and CLAUDE.md (the portable methodology core). Then replace every
+<angle-bracket placeholder> below with this project's real identity, in the project's own voice:
+  • What the product is, in one paragraph (the elevator pitch a new contributor reads first).
+  • The company / who is behind it, and how that shapes the product's feel.
+  • The goal & vision — what "unlike anything done before" means here; what success looks like.
+  • The world / domain design — the setting, naming, tone; any trademark or naming constraints.
+  • The visual style — the look, the references, the non-negotiables, and where the asset pipeline lives.
+Keep it durable framing, not live state (live state belongs in the build platform's DB). Delete sections that
+do not apply to this project. Delete this comment block when done.
+-->
+
+&lt;One paragraph: what this product is, who it's for, and the single idea that makes it distinct. The full
+"two tracks / how work is sorted" framing lives in [`CLAUDE.md`](../CLAUDE.md) §1.&gt;
+
+---
+
+## Company Context — &lt;Company Name&gt;
+
+- **What they are:** &lt;what the company/organization does&gt;
+- **Customer base / audience:** &lt;who it serves&gt;
+- **Brand positioning:** &lt;the feeling the brand carries, and how it must show up in the product&gt;
+- **Website:** &lt;url&gt;
+
+---
+
+## Goal & Vision
+
+&lt;What this experience is trying to be — the ambition. Bullet the core promises to the user, and what makes
+the experience permanent / distinctive / worth building.&gt;
+
+---
+
+## World / Domain Design
+
+- **Setting / domain:** &lt;where the experience lives, conceptually&gt;
+- **Core named entities:** &lt;the world/product name and what it means; keep names in `config/branding.json`, not hardcoded&gt;
+- **Inciting idea:** &lt;the hook — why a user enters and what they discover&gt;
+- **Tone:** &lt;the feeling; what it is NOT&gt;
+
+> ⚠️ **Naming / trademark posture:** &lt;any protected marks or naming risks, and the contingency.&gt; **Operating rule:** any
+> rebrand-sensitive name must live as a single string in [`config/branding.json`](../config/branding.json) — never baked into
+> class names, file names, DB schema, or asset filenames — so a forced rebrand is a one-line change ([ADR 0062](adr/<redacted>.md) §3).
+
+---
+
+## Visual Style
+
+- &lt;The look and the touchstone references.&gt;
+- &lt;Resolution / tile size / format constraints, if any.&gt;
+- &lt;The palette / mood; what it is NOT (call out the easy-to-get-wrong defaults).&gt;
+
+### Asset pipeline
+
+&lt;If the instance enables an asset-generation module, describe where it lives and its non-negotiables (locked palette,
+rubric, cost ceiling). Otherwise delete this subsection.&gt;

package/docs/recipes/README.md

@@ -0,0 +1,35 @@
+# `docs/recipes/` — long-form operational recipes
+
+> **Renamed from `learnings/` in Phase 2b** (2026-05-10). The folder used to hold a mix of long-form guides and short-form rules; the dual-write with the GDS `learnings` table made the split confusing. Now: this folder = long-form recipes (multi-page operational guides); the DB `learnings` table = short-form per-rule learnings (rule + why + how-to-apply).
+
+This folder holds **things we have already discovered the hard way and need to write up at length**. Read the relevant file before you do similar work, and you will not repeat the discovery.
+
+A "recipe" is not a limitation (something the project cannot do). It is a multi-page operational guide for a workflow that's known to be tricky — the pixel-art pipeline, ops gotchas, deployment runbooks. For a one-paragraph rule like "TextEdit defaults to RTF — pass via `textutil -convert txt`," capture it via `node scripts/gds/learning-capture.js` instead; it goes into the DB and surfaces automatically on `/builder-claim` for relevant tasks.
+
+## What goes here
+
+- Ops gotchas — non-obvious behavior of a tool or service we use (Postgres, Caddy, Cloudflare, Colyseus, the Mac toolchain, etc.)
+- Recovery recipes — when X breaks in Y way, here is what to do
+- Sequencing notes — when running operation A, do B first, otherwise C happens
+- Tool-version traps — pinned versions and *why* they are pinned
+
+## What does not go here
+
+- Architectural decisions → [`docs/adr/`](../../docs/adr/)
+- Things the project cannot do → [`limitations/`](../../limitations/)
+- Things stuck on the prompter's input → [`blockers/`](../../blockers/)
+
+## Read order while working
+
+If you are about to deploy, edit infra, touch the database, or change the runtime stack — open the relevant file in this folder first. Each file is organized by topic so you can skim to the section you need.
+
+## When to add a new learning
+
+Anytime you spend more than ~10 minutes diagnosing something that turned out to have a non-obvious cause, write it down here. The cost of a 5-minute write-up is much less than the cost of the *next* session re-discovering the same thing.
+
+A good learning entry has:
+
+- **Symptom** — what looked broken
+- **Root cause** — what was actually happening
+- **Fix** — exact steps to recover
+- **Why it bites** — what about the tool's defaults makes this happen, so future-you can spot the pattern

package/docs/recipes/audit-replay.md

@@ -0,0 +1,100 @@
+---
+track: internal
+scope: shared-infra (production droplet, Postgres) — used by Archons during forensic investigation
+---
+
+# Audit replay — reconstruct everything a builder did
+
+> The forensic question this recipe answers: **"Given a builder_id and a date range, can we reconstruct every action they took against the city?"** If yes, the audit trail is complete. If no, the gap is a bug.
+
+Run by an Archon when investigating an incident, a suspected compromise, or a "what exactly happened during that 4-hour overnight session?" question. The output is one chronological feed merging six tables.
+
+## What it surfaces
+
+| Kind | Source table | What it means |
+|---|---|---|
+| `CLAIM` | `claims.claimed_at` | Builder claimed a task — task locked to this session. |
+| `CLAIM_END` | `claims.released_at` + `outcome` | Claim resolved — `outcome` says whether the work shipped, was abandoned, partially completed, or expired. |
+| `CREDIT` | `credit_log.recorded_at` | Drachmae moved (`task.confirmed`, `ship.net_negative`, rank-change audit, etc.) — `delta` is the integer amount. |
+| `COST` | `cost_log.recorded_at` | The builder logged a USD spend — `category` (api / compute / infra / domain / art / other) + `source`. |
+| `SESSION_START` / `SESSION_END` | `session_logs.started_at` / `ended_at` | Claim-scoped working session boundaries. Pair with `outcome` for "shipped / partial / abandoned." |
+| `HTTP_<METHOD>` | `audit_log.recorded_at` | Every authenticated POST / PATCH / PUT / DELETE the builder made — route, status, IP. The forensic fine-grain. |
+
+Notably absent — and worth knowing about so you can ask follow-up questions if needed:
+
+- **GET requests** are not in `audit_log` (by design; high volume, low signal). Read patterns aren't part of this replay.
+- **Builder rank changes** show up as `HTTP_PATCH route=/api/gds/builders/:id/rank` rows and as `CREDIT` rows when the rank change carries a drachmae adjustment. The new rank value lives in `audit_log.request_body_redacted`.
+- **Game-server WebSocket events** (movement, world state) live in `world_events` and are NOT included here — this script is GDS-scoped. If a game-side investigation is needed, query `world_events` separately.
+
+## Running the script
+
+```bash
+bash scripts/gds/audit-replay.sh <builder_id> <start_iso> <end_iso>
+```
+
+The builder_id is the integer from the `builders` table. Look it up with:
+
+```bash
+ssh lars@REDACTED_IP \
+  "psql -h /var/run/postgresql -d example -c \"SELECT id, github_login, rank FROM builders ORDER BY id\""
+```
+
+Timestamps are inclusive on both ends. Format is RFC 3339 / ISO 8601 — `2026-05-28T00:00:00Z` works; `2026-05-28` also works (interpreted as midnight UTC).
+
+### Two modes — automatic
+
+The script auto-detects whether it's running on the droplet (Postgres reachable on the local Unix socket) or on a builder's laptop. From a laptop it `exec`s itself over SSH to `lars@REDACTED_IP`, runs there, streams the TSV back. You don't need to think about it — but you DO need `lars@<droplet>` SSH access (Archon-only).
+
+```bash
+# laptop
+bash scripts/gds/audit-replay.sh 1 2026-05-28T00:00:00Z 2026-05-28T23:59:59Z
+# (silently SSHes to the droplet, runs psql there)
+```
+
+### Output
+
+TSV, three columns: `when_utc`, `kind`, `detail`. Already sorted chronologically. Pipe to `column -t -s $'\t'` for visual padding, or to `wc -l` for a quick activity count, or to `awk -F'\t' '{print $2}' | sort | uniq -c | sort -rn` for an event-type histogram.
+
+```bash
+# Pretty-print
+bash scripts/gds/audit-replay.sh 1 2026-05-28T00:00:00Z 2026-05-28T23:59:59Z \
+  | column -t -s $'\t' \
+  | less -S
+
+# Histogram of event kinds for the day
+bash scripts/gds/audit-replay.sh 1 2026-05-28T00:00:00Z 2026-05-28T23:59:59Z \
+  | awk -F'\t' '{print $2}' | sort | uniq -c | sort -rn
+```
+
+## Identifying gaps
+
+A "gap" is something the builder did that does NOT appear in the output. The replay is complete when every meaningful action threads through one of the six tables. Known classes of gap (file as a task and fix):
+
+- **Direct DB writes via psql.** If an Archon runs `psql … UPDATE tasks SET …` directly, that bypasses the API and produces NO `audit_log` row. Mitigation: don't do that without documenting in the corresponding claim's `session_logs.notes_md`. (See CLAUDE.md §8 working rules — direct DB writes need a claim too.)
+- **Game-server side effects** (player position updates, WorldRoom state). These intentionally live in `world_events` and are out of scope here; a separate game-side replay would be needed for that.
+- **Webhooks / scheduled tasks** that act as a builder identity. Each scheduled task runs as `example-owner` (the droplet's service identity); its actions ARE captured as that builder's audit log entries, but a forensic reader needs to know to filter them by `route` shape (e.g. routes that no human ever hits).
+- **Build-broadcast posts** to Discord `#ship-news` (`scripts/discord/`, webhook — replaced the retired Google Chat `scripts/chat/` on 2026-06-05). The broadcast itself is not in `audit_log`, but the *trigger* (which task shipped) IS, as a `POST /api/gds/tasks/:id/ship`. So the chain is reconstructable: the audit-replay shows "X shipped at T"; the Discord `#ship-news` channel shows the broadcast went out shortly after.
+
+If you find a class of action that produces NEITHER a row in any of the six tables NOR a record elsewhere, file it as a task — that's a real audit-trail gap.
+
+## Performance notes
+
+The script issues one SQL statement (a multi-CTE `UNION ALL`). Indices already in place:
+
+- `claims (builder_id) WHERE released_at IS NULL` — fast active-claim filter.
+- `credit_log (builder_id, recorded_at)` — point-in-time by builder.
+- `audit_log (builder_id, recorded_at DESC)` — same.
+
+`cost_log` does NOT have a builder_id column (cost is task-attributed); the script joins through `claims` to find cost rows for tasks this builder ever claimed. That join is the slowest leg; for a wide date range it can take seconds. For typical "one builder, one day" queries it returns in ~50ms.
+
+If a future need emerges to surface costs even when the builder didn't claim the task (e.g. an automated cost logger that ran outside any claim), we'd need a `builder_id` column on `cost_log`. File as a follow-up task at that time.
+
+## Extending the script
+
+The script is structured as one CTE per source table. To add a new table:
+
+1. Add a new `UNION ALL` clause in `all_events` selecting the same three columns (`when_utc`, `kind`, `detail`).
+2. Update the table in the "What it surfaces" section above.
+3. Re-run the script against a known date range to sanity-check the new rows appear.
+
+Don't add tables that don't carry a builder-attributable timestamp — they don't fit the replay model and should be queried separately.

package/docs/recipes/bongos-cli-release.md

@@ -0,0 +1,66 @@
+# Releasing the standalone `bongos` CLI
+
+How the compiled `bongos` binaries get built, published, and installed — the
+"no Node, no repo" on-ramp (task [#1248](https://example.com/builders#/task/1248), V4.R81).
+Mirrors the Dev Box app release flow ([`devbox-app-release.md`](devbox-app-release.md)):
+**CI builds, the operator publishes to a public releases repo, the server serves
+branded redirects.** There is no cross-repo write token in CI — publishing is a
+deliberate operator step.
+
+## The moving parts
+
+| Piece | Where | Role |
+|---|---|---|
+| Build wrapper | [`scripts/gds/build-bongos.js`](../../scripts/gds/build-bongos.js) | `bun build --compile` → per-platform binaries in `dist/` |
+| CI | [`.github/workflows/build-bongos-cli.yml`](../../.github/workflows/build-bongos-cli.yml) | runs the wrapper, uploads `bongos-cli-binaries` artifacts (no publish) |
+| Release pointer | [`config/bongos-cli.json`](../../config/bongos-cli.json) | `releases_repo` + `version` + per-target asset filenames |
+| Redirects | [`src/bongos-downloads.js`](../../src/bongos-downloads.js) → `/downloads/bongos/*` in [`serve-internal.js`](../../src/bongos/serve-internal.js) | `/downloads/bongos/<target>` 302s to the release asset; `/version` + `/latest.json` for update-checks |
+| Installer | [`infra/bongos-install.sh`](../../infra/bongos-install.sh) + [`.ps1`](../../infra/bongos-install.ps1) | served (origin-pinned) at `/downloads/bongos/install.sh` / `.ps1` |
+| Package managers | [`packaging/homebrew/bongos.rb`](../../packaging/homebrew/bongos.rb), [`packaging/scoop/bongos.json`](../../packaging/scoop/bongos.json) | brew/scoop templates (fill sha256 at release) |
+
+## What the user runs
+
+```sh
+# macOS / Linux — no Node required:
+curl -fsSL https://example.com/downloads/bongos/install.sh | sh
+# Windows (PowerShell):
+irm https://example.com/downloads/bongos/install.ps1 | iex
+# or, once the tap/bucket is published:
+brew install example-owner/bongos/bongos          # macOS/Linux
+scoop bucket add bongos https://github.com/example-owner/scoop-bongos; scoop install bongos
+```
+
+Then: `bongos login <instance-url>` → `bongos code` / `bongos shell` onto a dev box.
+
+## One-time owner setup (tracked as the open blocker on [#1248](https://example.com/builders#/task/1248))
+
+1. **Create a PUBLIC releases repo** — `example-owner/example-bongos` (matches `config/bongos-cli.json`'s `releases_repo`). Public so GitHub's release CDN serves the downloads at $0; it holds ONLY the binaries, never source.
+2. *(optional, for brew/scoop)* create the tap repo `example-owner/homebrew-bongos` and/or the bucket `lars689/scoop-bongos`.
+3. *(optional)* point `get.bongos.dev` at the instance with a DNS CNAME → `example.com`, so the branded `curl -fsSL https://get.bongos.dev | sh` works (it just proxies `/downloads/bongos/install.sh`).
+
+## Cutting a release
+
+1. **Bump** `config/bongos-cli.json`: `version` + every `assets.*` filename to the new version. (Claim a task; this rides the normal ship flow.)
+2. **Push** → `build-bongos-cli.yml` runs and produces the `bongos-cli-binaries` artifact. Wait for green.
+3. **Download** the artifacts:
+   ```sh
+   gh run download -R example-owner/example --name bongos-cli-binaries --dir dist
+   ```
+4. **Publish** them as a `v<version>` release on the public repo:
+   ```sh
+   gh release create v0.1.0 -R example-owner/example-bongos --title "bongos v0.1.0" --notes "Standalone bongos CLI" dist/bongos-*
+   ```
+   The tag and asset filenames MUST match `config/bongos-cli.json` exactly — the redirect is `releases/download/v<version>/<asset>`; a renamed asset 404s.
+5. *(package managers)* compute `shasum -a 256 dist/bongos-*`, fill the `sha256`/`hash` fields in `packaging/homebrew/bongos.rb` + `packaging/scoop/bongos.json`, and copy them to the tap/bucket repos.
+6. **Ship** the `config/bongos-cli.json` bump. The `/downloads/bongos/*` redirects follow within a minute of deploy.
+
+Verify: `curl -fsSL https://example.com/downloads/bongos/version` shows the new version, and `curl -fsSL .../install.sh | sh` installs a working binary.
+
+## The binary architecture (why some verbs aren't in it)
+
+`bin/bongos.js` is one dispatcher with two runtimes ([task 1248](https://example.com/builders#/task/1248)):
+
+- **repo / `npm i -g`** → runs under `node`; spawns each sibling `scripts/gds/*.js` (unchanged).
+- **compiled binary** → `process.execPath` is the `bongos` binary (no `node`, no scripts on disk), so it dispatches the **bundled on-ramp verbs in-process**: `login`/`setup`, `reauth`, `box`, `shell`, `code`, `init`. The heavy work verbs (`ship`/`claim`/`start`/`status`/`recall`/`cost`/`release`/`module`/`package-core`) and `doctor` are **not** bundled — they need a full repo + git to run, and pulling their dependency trees in would bloat the binary. Run those on a dev box (`bongos code`/`shell`) or in a clone (where `npm i -g` gives the full CLI). A bare-binary user who invokes one gets a clear "get onto a real environment first" message.
+
+Follow-ups (not blocking the first release): SHA-pin `oven-sh/setup-bun`, code-sign the mac/win binaries, and expand the bundled verb set if a self-host workflow needs more offline.