@bongos/core 1.18.0 → 1.18.18

package/docs/onboarding/primer.md

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

package/docs/onboarding/slash-commands.md

@@ -0,0 +1,124 @@
+# Slash commands: which are Claude's, which are this project's
+
+*A reference page. Skim it once, come back when a command surprises you.*
+
+When you type `/` in Claude Code you get one list, but the commands in it come from **two different places** and are maintained by two different people. Claude Code ships some of them; this project ships the rest. They look identical in the menu, which is why a few of them trip people up — see [Easy mix-ups](#easy-mix-ups) at the bottom.
+
+## The 10-second rule
+
+| | **Claude Code's own** | **This project's** |
+|---|---|---|
+| Who ships it | Anthropic, inside the Claude Code app | This repository |
+| Where it lives | Inside the app — nothing in this repo | [`.claude/skills/<name>/`](../../.claude/skills/) |
+| What it acts on | Your *session* — context, model, config, account | The *build system* — tasks, claims, ships, ideas |
+| Works in any repo? | Yes, everywhere | No — only in a folder that holds this code |
+| Authoritative list | Type `/help` | The folder listing linked above |
+
+**The short version:** if it changes your Claude session, it's Claude's. If it changes project state — a task, a claim, a ship — it's ours. If you can run it in an unrelated repo, it's Claude's.
+
+> This is also why the commands "appear by magic" when you clone: they aren't a plugin or a download, they're files in `.claude/skills/` that Claude Code reads when a session **starts** on the folder. Clone mid-session and they won't show up until you start a fresh session — the wrinkle the [primer](primer.md) calls out in step 3.
+
+## This project's commands
+
+Every one of these talks to the build system. They're grouped by when you'd reach for them, not alphabetically.
+
+### The work loop — the ones you'll use every session
+
+| Command | What it does |
+|---|---|
+| `/builder-start` | List the tasks you can claim right now, filtered for parallel-safety |
+| `/builder-claim N` | Lock task N to your session |
+| `/builder-ship` | Grade, merge, and deploy your claimed task (credits land here) |
+| `/builder-release` | Cancel a claim — the task returns to `ready`, no credits |
+| `/builder-stage` | Preview your work-in-progress on your own sandbox before shipping |
+| `/builder-end` | Close out the session safely — resolve the claim, seal the log |
+| `/status` | Version / criterion progress — "what's left for C8?" |
+| `/recall` | Search the docs + project knowledge before re-solving something |
+
+### Your account and your machine
+
+| Command | What it does |
+|---|---|
+| `/builder-setup` | One-time enrolment — signs you in and registers you |
+| `/builder-reauth` | Refresh an expired session |
+| `/builder-key` | Check / set your own API key status |
+| `/builder-box` | Your dev box control panel — wake, create, check cost |
+| `/builder-connect` · `/builder-sync` · `/close-box` | Connect to, re-sync, and tear down that box |
+| `/builder-cost` | Log a cost entry against your claim |
+| `/builder-backup` | Check or trigger a database backup before risky work |
+| `/builder-exit` | Offboard or reactivate a builder *(Archon only)* |
+
+### Triage and planning *(Metic and above)*
+
+| Command | What it does |
+|---|---|
+| `/idea-triage` | Walk the idea inbox — promote, discard, or merge each |
+| `/blocker-review` · `/blocker-solve` | Walk open blockers, or drive one to done |
+| `/goal-create` | Plan and create one goal — scope wall, criteria, seed tasks |
+| `/goal-review` | Confirm criteria that are flagged met-pending-review |
+| `/planning-session` | Scope an upcoming version and seed its task list |
+| `/priority-session` | Reweight the inbox from a few plain-speech answers |
+| `/merge-mode` | Manual fallback when a confirmed task didn't land |
+
+### Discipline modes
+
+`/dev` (engineering — the default loop), `/paint` (art), `/ideate` (ideation). A claimed task's discipline routes you to one of these.
+
+### Design and art pipeline
+
+`/design-sync` and `/figma-design-sync` round-trip the UI design system. The `/otb-*` family — `otb-tile-generate`, `otb-design-review`, `otb-character-review`, `otb-feedback-capture`, `otb-figma-sync` — is the reference instance's pixel-art pipeline; it's only meaningful on an instance that runs that pipeline.
+
+### Session and meta
+
+| Command | What it does |
+|---|---|
+| `/session-handoff` | Emit a paste-ready prompt to start a fresh session with |
+| `/read-session-export` | Read a past session's `/export` zip |
+| `/feedback` | Pull in the latest recorded walkthrough bundle |
+| `/new-project` | Zero-to-live runbook for a brand-new instance |
+| `/builder-redteam` | File a security / vulnerability report |
+
+## Claude Code's own commands
+
+These work in **any** repository — they have nothing to do with this project. `/help` prints the live, authoritative list for your version; the ones below are simply the ones you'll actually meet.
+
+| Command | What it does |
+|---|---|
+| `/help` | List every command available right now — **the authoritative list** |
+| `/clear` · `/compact` | Wipe or condense the conversation context |
+| `/model` · `/config` | Switch model; change app settings |
+| `/login` · `/logout` | Sign in to your **Anthropic** account |
+| `/init` | Write a `CLAUDE.md` for the current codebase |
+| `/cost` · `/usage` · `/context` | Token spend, plan usage, context window |
+| `/doctor` | Diagnose the **Claude Code install** |
+| `/memory` | Edit Claude's memory files |
+| `/mcp` · `/agents` · `/hooks` · `/permissions` | Configure MCP servers, subagents, hooks, tool permissions |
+| `/export` · `/resume` · `/rewind` | Save the transcript; resume or roll back a session |
+| `/review` | Review a GitHub pull request |
+| `/status` | **Claude Code's** session/auth status — see the warning below |
+
+## Easy mix-ups
+
+These are the ones that actually cause confusion.
+
+**`/status` — the genuine collision.** Both sides define it. Claude Code's `/status` shows your session and auth state; this project's shows version and criterion progress. Which one wins depends on your Claude Code version and how it resolves the name. If you get the wrong one, say *"what's left for C8"* in plain English, or run `node scripts/gds/status.js` directly.
+
+**`/login` is Anthropic, not us.** It signs you into your Claude account. To sign into a Cloud Bongos instance, use `bongos login <instance-url>`, or `/builder-setup` for a first-time enrolment.
+
+**`/init` writes a `CLAUDE.md`.** It does *not* scaffold a new instance — that's `bongos init`, wrapped by `/new-project`. Running `/init` in this repo would overwrite the project's own `CLAUDE.md`.
+
+**`/doctor` checks Claude Code.** For the build system's health — your session, toolchain, git plumbing, environment — run `node scripts/gds/doctor.js`.
+
+**`/cost` is Claude's token spend.** To record a project cost against your claim, that's `/builder-cost`.
+
+**`/export` vs `/read-session-export`.** Claude's `/export` *writes* a transcript zip; our `/read-session-export` *reads* one back.
+
+**`/review` reviews a GitHub PR.** The project's review commands are `/goal-review`, `/blocker-review`, and `/idea-triage` — different jobs entirely.
+
+## Two more things worth knowing
+
+**Every command has a plain-English twin.** Each skill lists trigger phrases, so *"what can I work on"* reaches `/builder-start` and *"ship it"* reaches `/builder-ship`. You never have to memorise the slash form.
+
+**Same commands, outside Claude.** The work-loop commands are also a terminal CLI: `bongos start`, `bongos claim N`, `bongos ship`. Same actions, same API — usable from any terminal, a Chromebook, or CI. Run `bongos help` for the verb list.
+
+**Rank gates are real.** Some commands above refuse below a certain rank — that's enforced by the server on every request, not by the presence of the file on your disk. See [`canonical-permissions.md`](../canonical-permissions.md).

package/docs/recipes/builder-box-lifecycle.md

@@ -138,6 +138,29 @@ These spend money and are intentionally manual.
    > **`box-drift-reconcile.timer` (task [#1289](https://example.com/builders#/task/1289)/[ADR 0071](../adr/<redacted>.md)) is the zombie backstop.** It runs `box.js reconcile-drift --apply` hourly, reading the live DO droplet list and repairing DO⇄DB drift both ways — force-deleting **zombie** droplets (running but no live box row claims them) and marking **ghost** rows destroyed (droplet gone from DO). Reads the SAME `/etc/example/box.env` (needs `DO_API_TOKEN` to enumerate droplets). Without it, the confirm-before-destroyed teardown still prevents *new* zombies, but a pre-existing one (or an out-of-band DO change) only heals on the next manual `reconcile-drift`. Confirm with `journalctl -u box-drift-reconcile.service`.
    > **Chromebook / browser terminal ([#760](https://example.com/builders#/task/760)/[ADR 0038](../adr/<redacted>.md), superseding the old `claude rc` pairing).** Research proved `claude rc` cannot run headless, so the box instead serves its OWN browser terminal — **ttyd** (127.0.0.1:7681, per-box basic-auth, drops into `/workspace`) exposed over an outbound-only **Cloudflare Tunnel** — where the builder runs normal interactive `claude`. A browser/Chromebook builder gets the URL + credential from `GET /api/gds/box/terminal` after their box is active — no SSH needed. The terminal/cloudflared units are inlined in cloud-init and start at first boot ([#774](https://example.com/builders#/task/774)). The deleted RC bits (`claude-rc.service`, `box-report-pairing.sh`, `/box/pairing(-link)`) are gone.
 
+## Cloudflare token: the edge cookie-strip rule (ADR 0053 / SR#11)
+
+`provision` applies two zone **rulesets** best-effort: the **cookie-strip Transform Rule** (removes the `Cookie` request header on `term-*`/`sandbox-*`, so the apex session cookie never rides the tunnel onto a box — a host outside the trust boundary) and the **sandbox cache-bypass Cache Rule**. Both need scopes beyond Tunnel + DNS, and a token that lacks them fails **silently** — the box provisions fine and the security control simply isn't there.
+
+Since task 1002511, `box.js provision` **read-probes** the ruleset phase before spending a cent (dry-run included) and prints a `⚠⚠ SECURITY` block naming the fix. Read the probe honestly: it is a `GET`, so it can only prove the scope is **missing** (401/403). A readable phase means *readable* — edit scope is not proven until the rule PUT actually runs, which is why the summary line after `✓ named tunnel ready` is the authoritative signal.
+
+**Fix — widen the token** (account owner only):
+
+> CF dashboard → **My Profile → API Tokens** → edit the token used as `CLOUDFLARE_API_TOKEN` → **Permissions** → add **Zone → Transform Rules → Edit** and **Zone → Cache Rules → Edit** → **Zone Resources → Include → Specific zone → `<your apex zone>`** → Continue → Save. Then re-run `node scripts/gds/box.js provision <login> --apply`.
+
+**Fallback — apply the rule by hand** (no token change; do it once per zone):
+
+> CF dashboard → the zone → **Rules → Transform Rules → Modify Request Header** → Create rule. Custom filter expression: `starts_with(http.host, "term-") or starts_with(http.host, "sandbox-")` (the exported `COOKIE_STRIP_EXPRESSION`). Action: **Remove** header `Cookie` (phase `http_request_late_transform`). Deploy. Give it the same description the code uses (`COOKIE_STRIP_RULE_DESC`) so a later widened-token run recognises and replaces it instead of adding a duplicate.
+
+**Verify:**
+
+```bash
+node scripts/gds/box.js provision <login>          # dry-run — prints the probe verdict, spends nothing
+curl -sI https://term-<login>.<apex>/ -H 'Cookie: x=1'   # from a box-facing check, confirm the origin sees no Cookie
+```
+
+> `/user/tokens/verify` is **not** a valid check here — an IP-locked token answers "Invalid API Token" there even when it is valid (see the [#725](https://example.com/builders#/task/725) note above). Always probe the real operation.
+
 ## Boundaries (other ADR-0031 tasks)
 
 - **[#596](https://example.com/builders#/task/596)** (done) — the devcontainer (box-as-code) this provisions.

package/docs/recipes/devbox-app-release.md

@@ -10,7 +10,10 @@ releases repo → a one-line config bump re-points the branded
 - **Source:** `devbox-app/` in the main (private) repo.
 - **CI:** `.github/workflows/build-devbox-app.yml` — builds on every push
   touching `devbox-app/**` (mac dmg arm64+x64 on macos-14, NSIS exe x64+arm64 on
-  windows-latest) and uploads workflow artifacts. No publishing from CI.
+  windows-latest). **Only `main` keeps the artifacts** (3-day retention); a
+  `claude/**` run builds both platforms as a CI signal and uploads nothing —
+  ~500MB per run had filled the shared Actions storage cap and blocked uploads
+  repo-wide. No publishing from CI either way.
 - **Public releases repo:** named in `config/devbox-app.json`
   (`releases_repo`). Assets live on GitHub releases there; GitHub's CDN
   serves the downloads, $0.
@@ -43,13 +46,20 @@ releases repo → a one-line config bump re-points the branded
 
 1. Bump `devbox-app/package.json` version (e.g. `1.1.0`) and regenerate
    icons only if they changed (`npm run icons`).
-2. Push the branch; wait for `build-devbox-app` to go green.
-3. Download the artifacts:
+2. Land the bump on `main` through the normal GDS flow, then wait for
+   `build-devbox-app` to go green **on the `main` run** — that is the run that
+   carries the installers.
+3. Download the artifacts (they expire after 3 days — re-run the workflow on
+   `main` via `gh workflow run build-devbox-app.yml --ref main` if they aged out):
    ```
    gh run download -R example-owner/example -n devbox-app-mac -D /tmp/devbox-rel
    gh run download -R example-owner/example -n devbox-app-win -D /tmp/devbox-rel
    ```
-   (or build the mac side locally: `cd devbox-app && npm run dist:mac`).
+   **These commands only work against a `main` run.** Pointing them at a
+   `claude/**` run fails with nothing to download — the upload steps are gated to
+   `refs/heads/main` (see §0). To get an installer out of an unmerged branch,
+   build it locally instead: `cd modules/dev-box/app && npm run dist:mac` (or
+   `npm run dist:win` on Windows).
 4. Publish to the public releases repo (tag = `v<version>`, must match what
    `src/devbox-downloads.js` composes):
    ```

package/docs/recipes/instance-first-run.md

@@ -35,6 +35,22 @@ npx bongos start
 
 That's it — `bongos claim <id>` / `bongos ship` now work, scoped to this instance.
 
+## If the instance isn't hosted yet — a freshly-created, LOCALHOST project
+
+The steps above assume the instance is already **running** at a reachable origin. A project
+straight out of the creation flow is different: its `config/branding.json` `publicOrigin`
+is `http://localhost:<port>`, and **nothing is serving it yet** — so step 2's
+`bongos login http://localhost:<port>` fails with `fetch failed`. That repo is configured
+to run on *your own machine*; stand it up with one command instead:
+
+```bash
+npm install
+npx bongos dev        # Postgres → createdb → migrate → server → sign-in, in one step
+```
+
+Full guide: [`docs/recipes/local-dev.md`](local-dev.md) (ADR 0149). Prefer a cloud dev box
+over running locally? Use `bongos box` + `bongos code`.
+
 ## Notes
 
 - **Sign in to the RIGHT instance.** `bongos login <url>` writes a per-instance session

package/docs/recipes/local-dev.md

@@ -0,0 +1,81 @@
+# Run a project on your own machine — `bongos dev`
+
+> The one-command path from a freshly-cloned **standalone instance repo** (one whose
+> `config/branding.json` points at `http://localhost:<port>`) to a running, signed-in
+> instance on your Mac. This is the local counterpart of `bongos onboard` (which
+> stands an instance up in the **cloud**) — see [ADR 0149](../adr/<redacted>.md).
+
+## TL;DR
+
+```bash
+gh repo clone <owner>/<project>
+cd <project>
+npm install
+npx bongos dev
+```
+
+`bongos dev` starts the database, creates this project's database, builds its tables,
+launches the server on the port in `config/branding.json`, and signs you in. Re-running
+it is safe (idempotent). Stop it with `bongos dev stop`.
+
+## Prerequisites (one-time, per machine)
+
+- **Node.js ≥ 22** — `node --version`
+- **PostgreSQL 16** — `psql --version`. Install on a Mac with Homebrew:
+  ```bash
+  brew install postgresql@16
+  brew services start postgresql@16   # bongos dev will also try to start it for you
+  ```
+- macOS or Linux (migrations use `bash`). On **Windows**, use WSL, or the Docker path in
+  [`self-host.md`](self-host.md).
+
+## What `bongos dev` does (and why it's needed)
+
+A cloned project ships the code but nothing *running*. The server reads its port from an
+env var and **not** from branding, the migrator and the server default to **different**
+database names, and node-pg defaults to a Linux socket that doesn't exist on a Mac — so a
+by-hand standup is a six-step assembly with three silent mismatches. `bongos dev` does all
+of it from one source of truth (your `config/branding.json`):
+
+1. Ensures Postgres is running (starts it if it isn't).
+2. Creates the project's database if it doesn't exist.
+3. Runs migrations to build/refresh the tables.
+4. Starts the server on the branding port (e.g. `http://localhost:3006`).
+5. Signs you in to this instance (`--no-login` to skip).
+
+## Commands
+
+```bash
+npx bongos dev                 # stand it up (idempotent) + sign in
+npx bongos dev status          # is it running? what URL? is sign-in configured?
+npx bongos dev stop            # stop the background server this launched
+npx bongos dev --foreground    # run attached instead (Ctrl-C stops it)
+npx bongos dev --no-login      # stand it up but don't sign in
+npx bongos dev --skip-migrate  # skip the migration step (already migrated)
+npx bongos dev --port 3011 --db my_scratch   # override the port / database name
+```
+
+The server runs in the **background but managed** — `bongos dev status`/`stop` always find
+it, and a second `bongos dev` is a no-op if it's already up. (This is deliberate: an
+*unmanaged* leftover server is how you end up accidentally signing a new project into an
+old one's server.)
+
+## The one step that can need you: a GitHub OAuth App
+
+Sign-in uses a GitHub OAuth App. If your machine already ran another Cloud Bongos instance,
+the credentials are usually already present and `bongos dev` just works. If not, it prints
+exact steps: create an OAuth App (Homepage `http://localhost:<port>`, callback
+`http://localhost:<port>/api/gds/auth/web/callback`, tick **Enable Device Flow**), then save
+the Client ID + secret to `~/.config/<configDir>/gds-github.json` as
+`{ "client_id": "…", "client_secret": "…" }` and re-run `bongos dev`.
+
+## Notes
+
+- **Sign in as the owner.** `config/branding.json`'s `firstAdmin` is the GitHub account
+  auto-seated as owner on first sign-in — `bongos dev` tells you which one.
+- **Switching instances.** Signing in to a local project points your CLI session at it; to
+  go back to a hosted instance later, `bongos login https://<that-instance>`.
+- **Multiple projects at once** each get their own database + port, so their `bongos dev`
+  servers don't collide.
+- **Prefer the cloud?** `bongos box` + `bongos code` give you a remote dev box instead — no
+  local database or server to run.

package/docs/recipes/ops-gotchas.md

@@ -147,11 +147,29 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 
 ---
 
+## Windows / local dev (PowerShell)
+
+### PowerShell 5.1 turns a clean `node scripts/gds/*.js` exit into a false failure
+
+- **Symptom:** Running `node scripts/gds/api.js GET /api/gds/me 2>&1` (or the same on `claim.js`/`ship.js`) inside a PowerShell 5.1 session reports failure — `$?` is `$false` and the stderr line surfaces as a `NativeCommandError` — even though node exited 0 and the JSON on stdout is exactly right.
+- **Root cause:** `api.js` prints its status banner to stderr unconditionally, by design (stdout stays clean JSON for piping); `claim.js`/`ship.js` also write diagnostics to stderr during a normal run. PS 5.1 wraps any stderr output from a native command into an `ErrorRecord` once the two streams are merged with `2>&1`, and sets `$?` false regardless of the actual exit code.
+- **Fix:** Never merge streams on these calls. Prefer `scripts/gds/api.ps1` (a thin wrapper that discards stderr and writes clean JSON to stdout, safe to pipe into `ConvertFrom-Json`), or call `node scripts/gds/api.js ...` plain, with no `2>&1`.
+- **Why it bites:** The exit code and JSON body are both fine — only the redirection is wrong — so the failure looks like a real API error and wastes time chasing a phantom bug in the call itself.
+
+### `Out-File`/`>` writes a UTF-8 BOM that breaks `JSON.parse` on re-read
+
+- **Symptom:** A JSON body file written from PowerShell (`... | Out-File body.json` or `... > body.json`) and then read back with `--body-file` fails to parse, or parses with an invisible extra character before the first key.
+- **Root cause:** PowerShell's `Out-File`/`>` redirection default to UTF-8 **with a byte-order-mark**. `JSON.parse` does not strip a leading BOM, so the file's first byte is invisible garbage as far as the parser is concerned.
+- **Fix:** Don't write CLI JSON body files with `Out-File`/`>`. Use the Write tool, or `[IO.File]::WriteAllText($path, $json, (New-Object Text.UTF8Encoding($false)))` (explicit no-BOM encoding). `scripts/gds/api.js`'s `--body-file` reader now also strips a leading BOM defensively, but the safest fix is to never write one.
+- **Why it bites:** The file looks completely normal in an editor — the BOM is invisible — so the parse failure looks like a JSON syntax problem, not an encoding one.
+
+---
+
 ## GDS build pipeline
 
 ### Two deterministic routines run as in-process server timers, not external cron
 
-- **What:** `peer-vote-tally` (weekly) runs inside the always-on Node process via the autonomy module's poller `modules/autonomy/pollers/routine-timers.js` (ADR 0078 amendment, task 1382; carved into `modules/autonomy/` at BV1.R83) — no `claude -p`, no external cron, no token. The loader's `startModulePollers` starts it (on the game/droplet boot only); it reaches `tallyPeerVotes` through the doorway. It's a no-op anywhere the DB is unreachable (builder machines), so it only does work on the prod droplet.
+- **What:** `peer-vote-tally` (weekly) runs inside the always-on Node process via the autonomy module's poller `modules/autonomy/pollers/routine-timers.js` (ADR 0078 amendment, task 1382; carved into `modules/autonomy/` at BV1.R83) — no `claude -p`, no external cron, no token. The loader's `startModulePollers` starts it from `src/platform-server.js` at boot (task 1002419 — before that fix the call site had been lost with the retired `server.js` and no module poller started at all); it reaches `tallyPeerVotes` through the doorway. It's a no-op anywhere the DB is unreachable (builder machines), so it only does work on the prod droplet.
 - **Disable / move it out-of-process:** set `ROUTINE_TIMERS_DISABLED=1` in `/etc/example/web-source.env` and restart. Also set it on any **second** always-on instance that shares the `example` DB so the tally can't double-fold (the `FOR UPDATE OF pv` row lock is the hard guard if you forget).
 - **Run it manually now:** `node scripts/gds/run-routine.js peer-vote-tally` (the dispatcher front door still works). The cadence is boot-anchored ("~90s after boot, then weekly"), not a wall-clock Monday job — frequent deploys re-anchor it, which is harmless (the tally is idempotent).
 

package/docs/recipes/overnight-builder.md

@@ -33,7 +33,7 @@ curl -sS -X PATCH -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: applicat
   -d '{"parallel_safe": true}' https://example.com/api/gds/tasks/<id>
 ```
 
-In parallel mode each worker stops at `confirmed` (credits land) and the runner lands the merges **one at a time** — concurrent merges to `main` are never allowed.
+In parallel mode each worker stops at `confirmed` (verified, not yet paid — [ADR 0120](../adr/<redacted>.md) books credits at land) and the runner lands the merges **one at a time** — concurrent merges to `main` are never allowed. Credits land as each merge completes.
 
 ## Reading the morning report
 

package/docs/recipes/packaging-the-core.md

@@ -26,12 +26,25 @@ Every file is **redacted** through the same fail-closed pipeline the public mirr
 bongos package-core                 # from HEAD, version = platform CORE_VERSION
 bongos package-core --ref origin/main --version 1.13.0
 node scripts/gds/package-core.js --droplet-ip <ip>   # add the prod IP as an exact gate literal
+bongos package-core --self-verify   # after building, prove the artifact reproduces its pin
+bongos package-core --self-verify --self-verify-boot   # ALSO npm-install the .tgz + boot /healthz
 ```
 
 `--ref` chooses the source commit (default `HEAD`), `--out-dir` the output dir (default `dist`), `--version` overrides the stamped version. `stdout` carries a one-line JSON pin (`{ core_version, source_commit, tree_sha256, tarball }`) for CI/scripts to capture; human detail goes to `stderr`.
 
+`--self-verify` (task [#1002218](https://example.com/builders#/task/1002218), audit H3) closes the produce-side of the integrity loop: after writing the artifact it **unpacks the built `.tgz` and recomputes `tree_sha256`, asserting it equals the manifest** (+ the on-disk `.tgz` bytes vs `tarball.sha256`) — proving the packager's own output reproduces its pin before it is trusted or published (a mismatch exits non-zero, ahead of the `--publish` leg). It is deterministic and network-free. Add `--self-verify-boot` to *also* `npm install` the tarball into a throwaway consumer and boot `/healthz` (reuses [`tests/consumer_layout_boot.mjs`](../../tests/consumer_layout_boot.mjs); needs npm/registry access — the deeper standing CI gate is task [#1002221](https://example.com/builders#/task/1002221)).
+
 If the no-leak gate fails, it names the file + the residual literal. Fix the redaction rules ([`scripts/gds/mirror-redact.js`](../../scripts/gds/mirror-redact.js)) or the manifest exclusions ([`scripts/gds/publish-manifest.js`](../../scripts/gds/publish-manifest.js)) and re-run — do not weaken the gate to force a pass.
 
+**The neutral floor** (task [#1002217](https://example.com/builders#/task/1002217), audit H4). Because the trunk carries no `config/branding.json`, the *branding-derived* redaction would strip nothing — so `package-core.js` always injects a fixed **`PRIOR_INSTANCE_FLOOR`** (prior-instance tokens/owners) into the doc-redaction + no-leak gate. Published **docs** are de-branded against it and the gate **fails closed** if a floor literal survives, even with no branding.json. **Functional** files still ship verbatim (the R88 fix) and are instead surfaced by the non-fatal `[leak-scan]` (task 1002220). To retire a new prior-instance token, add it to `PRIOR_INSTANCE_FLOOR` (kept in `package-core.js`, never in `mirror-redact.js` — that file's self-leak invariant forbids hardcoded literals).
+
+## Prove it boots (the standing PROVE-PUBLISH gates)
+
+Two standing gates keep "a published core boots clean from a bare install" honest (task [#1002221](https://example.com/builders#/task/1002221), audit H1/H2):
+
+- **`node scripts/gds/run-unit-tests.js --integration`** — the integration-smoke gate. Runs the heavier integration set (longer per-test budget), including [`tests/consumer_layout_boot.mjs`](../../tests/consumer_layout_boot.mjs), which packages the core, `npm install`s the `.tgz`, and boots `/healthz` from the real consumer layout. Run it per release / on a schedule in an env that provides the services (network, and — for the deeper DB leg tracked as a follow-up — Postgres). The default `run-unit-tests.js` (no flag) stays the fast DB-free unit gate and *excludes* this set.
+- **[`tests/pruned_lockfile_integrity.mjs`](../../tests/pruned_lockfile_integrity.mjs)** — a network-free unit guard (runs in the default gate every PR) that rebuilds the shipped pruned lockfile and asserts every registry package keeps a **well-formed, verbatim `integrity` hash**. This is the exact R88 regression (redaction once blanked those base64 hashes → `npm ci` could no longer verify) caught before a consumer's install ever fails.
+
 ## Consume + pin it (the R85 side)
 
 A downstream instance repo: