@bongos/core 1.17.0

package/.claude/skills/blocker-review/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: blocker-review
+description: Daily review of open GDS blockers — surface each, prompt the user to resolve, escalate, or note continued blockage. Resolving a blocker auto-promotes any linked tasks from blocked → ready (DB trigger). Triggers when the user says "/blocker-review", "review blockers", "what's stuck on me", "what's stuck on Lars", "check blockers", or runs as a scheduled daily task. Metic+ rank only (Metic and Archon; not Xenos).
+---
+
+You are running the daily blocker-review session for Off the Boats. Open blockers in the GDS `blockers` table get surfaced one-at-a-time, with prompts for the user to take action — resolve, escalate, or confirm still-blocked.
+
+This is the structural cure for the old "task #3 sat in `blocked` for days because nobody flipped it after the blocker was resolved" pattern. Phase 2a's BEFORE-UPDATE trigger auto-promotes linked tasks the moment a blocker is marked resolved. This skill is what makes sure resolutions actually get marked.
+
+## Rank gate — Metic+ only
+
+This skill is **gated to Metic and above** (Metic, Archon). It is **not** available to Xenos, the lowest rank. Resolving a blocker auto-promotes every linked task from `blocked` → `ready` via the BEFORE-UPDATE trigger — that's a write that reshapes what the whole team can claim next, so it's a trusted-builder operation. A Xenos can still **file** a blocker (`POST /api/gds/blockers`) — that path stays open to any authenticated builder — they just can't resolve or link them.
+
+This mirrors GDS-V3 criterion C2 (`three-ranks-gate-everything`), which names "blocker review" explicitly as a Metic privilege alongside full claim/ship, idea triage, and planning/priority sessions (see [`docs/canonical-permissions.md`](../../../docs/canonical-permissions.md) and [ADR 0018](../../../docs/adr/<redacted>.md)).
+
+**Enforce the gate at the very top of the session, before reading anything else:**
+
+1. Call `GET /api/gds/me` and read `builder.rank`. Compare case-insensitively (lowercase it before testing).
+2. **If `rank` is present and lowercases to `xenos`** → stop immediately. Tell the builder: *"Blocker review is a Metic+ operation — resolving a blocker auto-promotes every task linked to it, which reshapes the whole team's ready queue. You're currently Xenos. You can still file a new blocker via `POST /api/gds/blockers`; ask an Archon to promote you if you need to resolve them."* Do not list open blockers, do not propose resolutions.
+3. **If `rank` lowercases to `metic` or `archon`** → proceed with the steps below.
+4. **If `rank` is absent** (the GET /me response has no `rank` field — only possible against a deployment where the three-rank model hasn't shipped yet): treat the session as available, exactly as `/planning-session` and `/priority-session` do in their pre-rank passthrough mode. Note in the session log that the gate ran in pre-rank passthrough mode.
+
+> The gate is **belt-and-braces**: the server already rejects `/blockers/:id/resolve` and `/blockers/:id/link` with `403 rank_forbidden` for any non-Metic+ caller (#360 / ADR 0018), and markdown never grants authority (criterion C7). This frontmatter + check is the *intent surfaced to the operator*; the server is the *enforcement*. The skill stops early so a Xenos doesn't read the whole open-blocker list and walk through verdicts only to hit a 403 on every POST.
+
+## What this skill does
+
+1. Lists open blockers via `GET /api/gds/blockers`.
+2. For each, prompts: **resolved**, **still blocked** (with brief status update), or **escalate** (surface to Lars or generate an external ask).
+3. Resolves accordingly via `POST /api/gds/blockers/:id/resolve`. The trigger handles the linked-task flip.
+
+## How to use
+
+**Step 1 — fetch open blockers.**
+
+```
+node scripts/gds/api.js GET /api/gds/blockers
+```
+
+(No auth needed — `/blockers` is read-public so the build dashboard can show what's stuck on Lars. `api.js` is the cross-platform GDS API helper — runs on Windows/macOS/Linux, unlike the old `curl | python3` form.)
+
+If the list is empty, print "no open blockers — nothing to review today" and exit.
+
+**Step 2 — walk the list, blocker by blocker.**
+
+Present each blocker with:
+- id + title
+- body_md (full)
+- created_at
+- blocking_task_ids[] — the tasks that auto-promote on resolution
+
+Then ask the user (concise, plain-language; Lars is the prompter — frame around the product outcome):
+
+> Blocker #N: "{title}". This is blocking {N} task(s): {task titles}. Status today — **resolved, still blocked, or escalate**?
+
+**Step 3 — apply the verdict.**
+
+**Resolved** → ask for a one-line resolution note (what unblocked it), then post
+(api.js signs the request with your session token automatically):
+
+```
+node scripts/gds/api.js POST /api/gds/blockers/<id>/resolve --body '{"resolution_note":"<one-line summary>"}'
+```
+
+(If the note has characters awkward to quote in your shell, write the JSON to a temp file and use `--body-file <path>` instead.)
+
+The response includes `promoted_tasks` — the tasks the trigger just flipped from `blocked` → `ready`. Surface these to the user so they know what's now claimable.
+
+**Still blocked** → ask the user for a one-line "what's the latest" status. Don't write it to the DB (no field for that today — flag for a future column if useful). Just note it for the session log.
+
+**Escalate** → ask whether the right move is:
+- A team Discord broadcast via `node scripts/discord/post.js` (Discord replaced Google Chat in both directions — outbound per ADR 0032 / #607, inbound per ADR 0033 F6; `scripts/chat/` was removed 2026-06-05)
+- An email/Slack/etc. that needs Lars's identity to send (in which case write a one-line ask the user can copy)
+- An ADR if the blocker reflects an architectural decision someone needs to make
+
+**Step 4 — surface a summary.**
+
+Report to the user:
+- Total reviewed
+- Resolved (count + ids + the tasks each unblocked)
+- Still blocked (count + brief status notes)
+- Escalated (count + ids + the action being taken)
+
+If anything was resolved, encourage the user to consider claiming one of the now-`ready` tasks if they have time today (`/builder-start` to see them).
+
+## Why we run this daily
+
+A blocker that resolves silently and never gets propagated keeps multiple tasks artificially stuck. Phase 2a's trigger fixes the propagation, but only IF resolutions get recorded. Daily cadence is the keep-honest mechanism — even when the answer is "still blocked," the user has a fresh data point that the situation hasn't changed (which sometimes turns into "this has been blocked too long, time to escalate").
+
+## Tone for the user
+
+Lars is the prompter (see CLAUDE.md §2). Some blockers are external (Stripe creds from a lawyer, fulfillment intake from Example partners). Don't pressure. The skill's job is to ask cleanly, record the answer, and surface what would unlock if Lars decided to push on a particular item today.

package/.claude/skills/blocker-solve/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: blocker-solve
+description: Start a blocker-scoped working session that drives ONE GDS blocker to done and auto-closes it. Unlike /blocker-review (which walks the whole list to record status), this points at a single blocker, gathers its context, does the parts it can itself, hands the owner-only parts back as precise step-by-step instructions, verifies the fix actually landed, then auto-resolves — which auto-promotes any task waiting on it (DB trigger). Triggers when the user says "/blocker-solve N", "solve blocker N", "work blocker N", "drive blocker N to done", "let's clear blocker N", or "fix the thing blocking task M". Metic+ rank only (Metic and Archon; not Xenos).
+---
+
+You are running a **blocker-solve session** — a session scoped to exactly one GDS blocker, whose goal is to drive that blocker to resolution and close the loop automatically. Where `/blocker-review` is a daily list-walk that records status, this is a *working* session that actually moves one blocker toward done and, when the fix is verified, resolves it — which promotes every linked task `blocked → ready` via the migration-009 trigger.
+
+The session **always works the same way**, whether the fix is something you can do or something only the owner can do:
+
+> **gather context → do what you can / guide the rest → verify → auto-resolve → report.**
+
+A blocker that "needs the owner's hands" (a Cloudflare login, a billing change, a payment, a yes/no decision) is **not a different mode** — the human action is just a *pause inside this same flow*. You produce exact instructions, the owner performs the step, you verify it landed, and you resolve. The point is to kill the gap that bites today: the owner finishes the real-world action but the GDS never hears about it, so the blocker sits open forever and its tasks stay stuck.
+
+## Rank gate — Metic+ only
+
+Resolving a blocker auto-promotes every task linked to it — a write that reshapes the whole team's `ready` queue — so this is a trusted-builder operation, gated to **Metic and Archon** (not Xenos). Enforce it at the very top, before reading anything else:
+
+1. Call `node scripts/gds/api.js GET /api/gds/me` and read `builder.rank`. Lowercase before testing.
+2. **If `rank` lowercases to `xenos`** → stop immediately: *"Blocker-solve is a Metic+ operation — resolving a blocker auto-promotes every task linked to it. You're currently Xenos. You can still **file** a blocker (`POST /api/gds/blockers`); ask an Archon to promote you if you need to solve them."* Do not read the blocker or propose a fix.
+3. **If `rank` lowercases to `metic` or `archon`** → proceed.
+4. **If `rank` is absent** (pre-rank deployment) → proceed in passthrough mode, exactly as `/blocker-review` does, and note it.
+
+> Belt-and-braces only: the server already rejects `/blockers/:id/resolve` with `403` for non-Metic+ ([ADR 0018](../../../docs/adr/<redacted>.md), [`docs/canonical-permissions.md`](../../../docs/canonical-permissions.md)). Markdown never grants authority (criterion C7) — this check just stops a Xenos before they walk a whole solve only to 403 on the resolve.
+
+## Guardrails — read before you touch anything
+
+These are what keep a "solve" honest. Violating them turns a helpful session into a lying ledger or an untracked change.
+
+- **Verify before you resolve. Never resolve on assumption.** Resolve **only** when either (a) a programmatic probe confirms the fix is live, or (b) the item is genuinely un-probeable and the owner explicitly attests it's done. Write *how* you verified into the `resolution_note`. If you can't verify, the blocker stays **open** — say so plainly. Resolving something to look productive is the one unforgivable move here.
+- **Don't smuggle code through a blocker-solve.** Performing **operator / external / config actions** to clear a blocker (set a repo secret, flip a prod env var, add a Cloudflare rule, change a non-code setting, record a decision) *is* the blocker's purpose and is in-scope for this cadence, claim-free — same standing as `/blocker-review` resolving a blocker. **But if clearing the blocker requires net-new _code_, stop** and route that through a normal claimed task (`/builder-start` → claim → `/builder-ship`). Every code change is backed by a claimed task — there is no blocker-solve loophole.
+- **Sensitive or outward-facing actions need the owner's explicit go-ahead in this session before you execute them** — SSH to the prod droplet, `git push`, rotating a credential, anything that spends money or is hard to reverse. Present the exact command and wait for "yes."
+- **Server enforces rank, not this skill.** You only ever *call* the rank-gated endpoints; you never reimplement or bypass the gate.
+
+## The flow
+
+### 1. Gather context
+Read the blocker fully, then enrich it:
+
+```
+node scripts/gds/api.js GET /api/gds/blockers/<id>
+```
+
+Fields: `title`, `body_md` (often already contains a numbered "Steps (owner): …" plan — lean on it), `source`, `source_ref`, `status`, plus `blocking_task_ids` from the list view (`GET /api/gds/blockers`). These linked tasks are exactly what will auto-promote when you resolve.
+
+- Read any linked task's notes (`GET /api/gds/tasks/<task-id>`) — the source task usually explains what "done" means.
+- Pull project knowledge so you're not re-deriving: `node scripts/gds/recall.js "<the blocker's topic>"` (add `--kind doc` for ADRs/recipes). This surfaces the ADR, recipe, or past session that already documents how to do this thing.
+
+If the blocker is already `status: resolved`, stop — there's nothing to solve; tell the user and exit.
+
+### 2. Plan and split the steps
+Turn the blocker into a concrete checklist, and label every step **[I can do]** or **[needs you]**:
+
+- **[I can do]** — anything reachable from this session: a repo secret via `gh`, a prod env flip via SSH (with go-ahead), a config/DNS/Cloudflare change via an available API token, regenerating a doc, running a script.
+- **[needs you]** — anything that only the owner can perform: logging into a third-party dashboard, a billing/plan change, a payment, granting an API-token scope, or a business/architectural decision.
+
+Present the checklist to the user before acting, so they see what you're about to do and what you'll need from them.
+
+### 3. Execute or guide
+- For each **[I can do]** step: do it. For sensitive/outward steps, show the exact command and get the explicit go-ahead first (see guardrails).
+- For each **[needs you]** step: write **precise, click-by-click** instructions (Lars is non-technical — name the dashboard, the menu, the exact field; see CLAUDE.md §2). Then **pause** and wait. This pause is the whole point of "needs manual attention" — the flow is identical, you just don't perform that one step.
+
+### 4. Verify the fix actually landed
+Pick the cheapest real check for the step's kind — examples:
+
+| Blocker kind | How to verify |
+|---|---|
+| Repo secret / branch protection / Actions | `gh secret list`, `gh api repos/:owner/:repo/branches/main/protection`, or confirm the relevant workflow run went green |
+| Cloudflare rule / token scope | probe the live behavior — `curl` the affected URL and assert the header/cookie/cache behaves; or read it back via the CF API if a token is in env |
+| Prod env var / service config | with go-ahead, SSH the droplet and `grep` the EnvironmentFile, or hit a health/echo endpoint that reflects the setting |
+| DNS / domain | `dig`/`curl` the host and confirm it resolves/serves as expected |
+| Business or architectural decision | not probeable — take the owner's explicit attestation, and if it's an architectural call, capture it in an ADR or the source task's notes |
+
+If verification **fails or is impossible and the owner won't attest**, do **not** resolve. Leave it open, and report exactly what's still needed.
+
+### 5. Auto-resolve and report
+Once verified, resolve it. Write the note as *what unblocked it + how you verified* — that's the durable audit trail. Use a temp file to dodge shell-quoting:
+
+```
+node scripts/gds/api.js POST /api/gds/blockers/<id>/resolve --body-file <path-to-note.json>
+```
+
+where the file is `{ "resolution_note": "<what was done> — verified via <how>." }`.
+
+The response includes `promoted_tasks` — the tasks the trigger just flipped `blocked → ready`. **Surface them**: tell the user what's now claimable (and offer `/builder-start` if they have time). If `promoted_tasks` is empty, say so — it means nothing downstream was waiting, the blocker was just cluttering the "stuck on you" list.
+
+## Tone for the user
+
+Lars is the prompter (CLAUDE.md §2). Frame around the outcome, not the plumbing. For **[needs you]** steps, be a precise guide — exact clicks, no jargon — never a nag. Some blockers are genuinely external and may stay open; that's fine. Your job is to do everything you can, make the rest a clean one-step ask, verify honestly, and close the loop the moment it's real.
+
+## Where this fits
+
+This skill is the **reusable core** of the blocker-solve idea. Future entry points call into this same flow rather than reinventing it:
+- a hall **"Solve this"** button on the Archon blocker card (records an intent), and
+- a **cloud / autonomous runner** that spins the session up server-side (mirroring the `box_intents` control-plane pattern, [ADR 0031](../../../docs/adr/<redacted>.md)), pinging the owner only for the **[needs you]** steps.
+
+Both reuse the gather → do/guide → verify → auto-resolve loop above. (Filed under GDS-V4; see the task that shipped this skill.)

package/.claude/skills/builder-backup/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: builder-backup
+description: Check the status of GDS database backups or trigger a fresh one. Use before risky changes (migrations, destructive SQL, large refactors) to ensure a recent restore point exists. Triggers when the user says "/builder-backup", "take a backup", "check backup status", "trigger a backup", "backup before migrating", or asks about the last backup.
+---
+
+You are helping the builder interact with the GDS database backup system.
+
+## What this skill does
+
+Runs `node scripts/gds/backup.js` (status check) or `node scripts/gds/backup.js --trigger` (fire a fresh dump + wait for it to land).
+
+The backup infrastructure runs on the production droplet:
+- **Nightly local dump** — `pg_dump` to `/var/backups/gds/` as `<db>-<timestamp>.sql.gz`, 30-day retention (task [#412](https://example.com/builders#/task/412))
+- **Weekly offsite copy** — latest local dump uploaded to DigitalOcean Spaces, 4-week retention (task [#415](https://example.com/builders#/task/415), ADR 0025)
+
+This skill lets a Metic+ builder check on backups and take a fresh one — no SSH, no systemctl, no server access.
+
+## When to use
+
+- **Before a risky change** — before running a DB migration, writing destructive SQL, or shipping a large schema change. `--trigger` gives you a restore point dated seconds ago instead of up to ~24 hours ago (nightly window).
+- **Restore readiness check** — after a trigger, confirm the dump landed and looks sane (filename, size, timestamp) before proceeding.
+
+## How to use
+
+### Check status (no action, just info)
+
+```bash
+node scripts/gds/backup.js
+```
+
+Outputs the latest dump filename, timestamp, size, and count of retained dumps.
+
+### Trigger a fresh backup
+
+```bash
+node scripts/gds/backup.js --trigger
+```
+
+Fires a fresh local dump on the server. Polls until the new dump lands (up to ~60 s) and prints its details on success.
+
+## Rank gate
+
+Both commands require **Metic or Archon** rank. The server enforces this per-request.
+
+## Restore
+
+If you need to restore from a backup, follow the restore drill in `docs/recipes/gds-db-backup.md`. Restore is a destructive Archon-only operation — do NOT attempt it without Lars's explicit sign-off.
+
+## After using this skill
+
+If you triggered a backup before a migration:
+1. Confirm the new dump landed (skill prints this on success).
+2. Note the dump filename in your session log so the restore point is traceable.
+3. Proceed with the risky operation.

package/.claude/skills/builder-box/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: builder-box
+description: Show the builder their own dev box — state, IP/hostname, cost, and their registered SSH keys — and help them get (back) on it: (re)connect, queue a hands-off auto-provision/wake (POST /box/ensure, #701), fetch the browser-terminal URL + password for a Chromebook (ADR 0038, #760), or find their live game-preview "sandbox" URL (ADR 0044, #898). Triggers when the user says "/builder-box", "what's my box doing", "is my box up", "my dev box status", "show my box", "list my ssh keys", "wake my box", "create my box", "how do I get back on my box", "what's my sandbox URL", or "preview my game". Own-scoped — the only mutation it may trigger is queuing an auto-provision/wake of the caller's OWN box; it never parks or destroys (that is the operator's `node scripts/gds/box.js`).
+---
+
+You are showing a builder the status of **their own** dev box and helping them get (back) onto it. This is a read-only, own-scoped helper — it never mutates infrastructure (provision / park / wake / deprovision live on the operator control plane, `node scripts/gds/box.js`, gated by rank).
+
+## Background
+
+The per-builder box lifecycle (ADR 0031 §2) auto-suspends when idle (snapshot-and-park) and recreates on demand, so a builder's box is often `parked` between sessions — that's normal and cheap, not a problem. The read API:
+- `GET /api/gds/box/me` → the caller's box: `state`, `scope`, `ip`, `hostname`, cost, activity timestamps.
+- `GET /api/gds/box/ssh-key` → the caller's registered SSH keys (fingerprints + labels).
+- `GET /api/gds/box/terminal` → the caller's active box's browser-terminal `url` + basic-auth `credential` (the Chromebook/browser on-ramp, ADR 0038), once the box has published them.
+
+**The hands-off on-ramp (#701).** A builder no longer needs an operator to get or wake a box. `POST /api/gds/box/ensure` is the "make my box ready" button: it **auto-provisions** if they have no box, or **wakes** a parked one — by queuing a request the control plane runs within ~1 min (the web server never touches DigitalOcean directly). For a Chromebook, after `ensure` reports `active`, `GET /box/terminal` returns the terminal `url` + `credential` (ADR 0038) to open in the browser.
+
+## How to use
+
+1. **Fetch the box + keys** (own-scoped; uses the builder's session token):
+   ```bash
+   node -e 'const{apiCall}=require("./scripts/gds/cli-lib");(async()=>{for(const p of ["/api/gds/box/me","/api/gds/box/ssh-key"]){const r=await apiCall("GET",p);console.log(p,r.status,JSON.stringify(r.data));}})()'
+   ```
+   (If the script returns "no GDS session", run `/builder-setup` first.)
+
+2. **Relay it in plain language:**
+   - **state = `none`** → they have no box yet. On a Mac/Windows: run `/builder-connect` (registers their SSH key + installs the Desktop file). To actually create the box hands-off, `POST /api/gds/box/ensure` queues the auto-provision (no operator CLI needed). *(The old path — ask an operator to `box.js onboard <login>` — still works but is no longer required.)*
+   - **state = `active`** → box is up at `hostname` (`ip`). They can connect from Claude Desktop → Code → Environment → "Example Dev Box". For a browser/Chromebook (ADR 0038), the terminal comes from the web: `GET /api/gds/box/terminal` returns a `url` + a basic-auth `credential` (username `otb`, password = <redacted>; open the url, enter them, then type `claude` in the terminal. No SSH needed.
+     - **Live game preview — the sandbox (ADR 0044).** If `/box/terminal` returns a `url` (i.e. the box is on the named tunnel), the builder also has a private live preview of the game running on their own box, at the **same hostname with `term-` swapped for `sandbox-`** — e.g. terminal `https://term-<login>.example.com` → preview `https://sandbox-<login>.example.com`. It serves their working copy of the game (degraded — fully playable, no saved state), so they can review changes in a browser **without shipping to prod**. The loop: edit in the terminal → run **`/builder-stage`** (or `box-preview restart`) → refresh the preview tab. Staging via `/builder-stage` also records the review marker that `/builder-ship`'s sandbox-first gate checks (#927, ADR 0046) — on a dev box, game changes are staged + reviewed on the sandbox before they ship to the main game. `box-preview status` shows whether it's up + the URL; `box-preview logs` tails the server. (No preview on a quick-tunnel box — that path can't carry the game port; it needs the named tunnel.)
+   - **state = `parked`** → idle-suspended (cheap, expected). It wakes on demand: `POST /api/gds/box/ensure` queues the wake and it's back in ~1 min (no operator needed). Reassure them their data is safe in the snapshot.
+   - **state = `provisioning` / `waking`** → in flight; check back in a minute.
+   - **state = `error`** → flag it to an operator (don't try to fix infra from here).
+   - **SSH keys** → list the fingerprints + labels. If empty, they haven't connected yet → `/builder-connect`. They can remove a stale key with `DELETE /api/gds/box/ssh-key/:id` (own-scoped).
+
+3. **Cost framing (if asked):** a box only bills compute while `active`; parked costs ~$0.30/mo (just the snapshot). The number in `compute_cost_usd` is their box's running total.
+
+## Constraints
+
+- **`POST /box/ensure` is the only mutation a builder may trigger** — and it only *queues* an auto-provision/wake of their **own** box (rank-gated, one open request at a time); the web server never touches DigitalOcean. Never call provision/park/wake/**deprovision** directly — those are operator control-plane commands (`node scripts/gds/box.js`), rank-gated. If the builder wants their box destroyed, that's an operator action.
+- **Own resource only.** `/box/me` and `/box/ssh-key` are scoped to the caller. The full roster (`GET /api/gds/boxes`) is Archon-only — don't try it for a regular builder.
+- **Don't print the SSH private key** — these endpoints only ever return public fingerprints, never private material. Keep it that way.
+
+## Files this skill touches
+
+- Calls: `/api/gds/box/me`, `/api/gds/box/ssh-key` (read), `/api/gds/box/terminal` (read), optionally `POST /api/gds/box/ensure` (queue auto-provision/wake) or `DELETE /api/gds/box/ssh-key/:id`
+- Reads: `~/.config/otb/gds-session.json` (the session token, via cli-lib)

package/.claude/skills/builder-claim/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: builder-claim
+description: Atomically claim a GDS task by id so this session has exclusive control over it. Triggers when the user says "/builder-claim N", "claim task N", "I'll work on N", or after `/builder-start` when the user picks one. Refuses if the task is already claimed, not ready, or has unshipped dependencies. (touches[] overlap with another active claim is ADVISORY for an interactive claim — it warns, it does not refuse; task 880.)
+---
+
+**Script skill (authoritative).** The core action is `node scripts/gds/claim.js <task-id> [--worktree NAME]`. Once the args are determined, run it and relay its output verbatim — do not paraphrase error messages or reformat the claimed card.
+
+You are claiming a task on behalf of the current builder. The claim is atomic — either it succeeds (and the task is locked to this session) or it fails with a clear reason and the user picks differently.
+
+## What this skill does
+
+Runs `node scripts/gds/claim.js <task-id> [--worktree NAME]`. The CLI hits `POST /api/gds/claims`, which transactionally:
+
+1. Verifies the task exists and is `ready`.
+2. Verifies all declared `dependencies[]` are in `shipped` status (V3.R02 / migration 020).
+3. Checks `touches[]` overlap (prefix-aware) against active claims. This is **advisory** for an interactive claim — it returns an `overlap_warning` and the claim still succeeds. It is a hard `TOUCHES_CONFLICT` refusal **only** when `--enforce-touches` is passed (the autonomous `--parallel` runner). (task 880)
+4. Inserts the claim row (the unique partial index gates concurrent attempts on the *same* task).
+5. Flips the task to `active`.
+
+Any failure mode comes back as a JSON error code (`TASK_NOT_FOUND`, `TASK_NOT_READY`, `DEPS_NOT_SHIPPED`, `TOUCHES_CONFLICT`, `ALREADY_CLAIMED`, the session-scoped one-claim guard `session_already_has_active_claim` (task 1642), plus V3.R13 #237's newcomer gates: `stage_required`, `newcomer_must_ship_first`). The CLI surfaces these clearly.
+
+## One claim per session / one worktree per claim (task 1642)
+
+A CLI session may hold **at most one active claim at a time**, and that claim should run in its **own dedicated worktree**. This is structural, not a style preference: working two tasks from one worktree lands every commit on the single branch that worktree owns, so `/builder-ship` publishes the whole branch and drags the other task's commits into the wrong ship (a *commingled ship*). One claim → one worktree → one clean branch keeps every ship isolated.
+
+The server now **enforces** the one-claim half (task 1642): `POST /api/gds/claims` refuses a second claim when the **same session** already holds an active one, returning `409 session_already_has_active_claim` (the body names the in-flight task id + title). This is session-scoped (a builder may still run several sessions in parallel, each with its own worktree and its own single claim) and fail-closed. So the **default claim flow must put the task in a fresh worktree** — never reuse a worktree that already owns a claim.
+
+**Default flow — claim into a dedicated worktree:**
+
+1. **Ensure a dedicated worktree for this task** before claiming. If the harness exposes a worktree primitive (e.g. `EnterWorktree` named `task-N`), enter a worktree named for the task id so this claim gets its own branch and never reuses a busy worktree. If you are already in a clean, claim-free worktree dedicated to this task, stay in it. If the current worktree already holds another active claim, do **not** claim here — open a new worktree/session first (the server will refuse otherwise).
+
+2. **Then claim** following the steps below, passing the worktree's leaf-folder name via `--worktree`.
+
+## How to use
+
+1. **Confirm the task id with the user** if they didn't give a number directly.
+
+2. **Determine the worktree name** (cross-platform). If we're inside a worktree, the worktree name is the leaf folder of the current path. Resolve it portably with node (works on Windows/macOS/Linux — no `basename`/`$PWD` shell-isms):
+   ```
+   node -e "console.log(require('path').basename(process.cwd()))"
+   ```
+   Then pass it via `--worktree`.
+
+3. **Run**:
+   ```
+   node scripts/gds/claim.js <task-id> --worktree <worktree-name>
+   ```
+
+4. **On success**, relay the claim id, task title, version, priority, credit reward, and the `touches[]` to the user. Treat `touches[]` as an **advisory hint** at the expected blast radius — NOT an editing fence. Code legitimately wanders into files nobody predicted; that is fine and no longer ship-blocking (the grader reads the real committed diff, and `git merge` is the authoritative collision detector). If the claim returned an `overlap_warning`, relay it too — it just means another active claim declares overlapping files; the user self-serializes only if it's genuinely the same code.
+
+   **Render the claimed card (task 1275).** _As of task 1288 the lifecycle-card `PostToolUse` hook (`.claude/hooks/lifecycle-card.js`) reads this card and injects a one-step render directive right after `claim.js` runs — normally just follow that injected directive and render **once**; the detail below is the fallback if no directive appears._ `claim.js` prints the deterministic lifecycle card for the `claimed` stage — a monospace card plus, when the builder has widgets on (the default), an `[otb-card-html] <path>` marker. If that marker is present **and** an in-feed visualization tool is available (e.g. `show_widget`), **Read that file and pass its exact contents** to the tool as `widget_code` (title like `task_<id>_claimed`); it shows the scope (priority / estimate / touches), the brief in its dropdown, and an "Open the work" action routed to the task's discipline session. **Author nothing yourself and don't restate the claim in prose** — the card is the summary. If instead you see an `[otb-card] widgets are off …` line (the builder disabled widgets via Settings → Rendering, task 1279) — or no visualization tool is available — the monospace card already printed IS the summary; relay it as-is and do not call show_widget.
+
+5. **On `ALREADY_CLAIMED`**: another session beat us to it. Run `/builder-start` again to get a fresh list and let the user pick something else.
+
+6. **On `TOUCHES_CONFLICT`** (only when `--enforce-touches` was passed — the autonomous `--parallel` path): the API tells us which task titles are conflicting. For a parallel run, drop this task and take the next disjoint one. (An interactive claim never hits this — it gets an `overlap_warning` and succeeds.)
+
+7. **On `TASK_NOT_READY`**: the task has been moved to a different status. Surface the current status. The user may need to `promote` it or pick a different task.
+
+8. **On `DEPS_NOT_SHIPPED`**: the API returns the list of unshipped deps. Surface them and tell the user to ship those first (or pick a different task whose deps are clear). Do NOT promote the dep or override — the dep system exists precisely to gate this case.
+
+9. **On `stage_required`**: a generic onboarding-stage gate (no specific stage gates claims today — the primer gate was removed in #766). Surface `what_to_do` verbatim; don't try to force the claim.
+
+10. **On `newcomer_must_ship_first`** (#766 newcomer focus rule): the builder is a Xenos who already holds one active claim and is trying to open a second. They must ship (or release) the current work before claiming again. The API response includes the active claim's task id and title — surface them and suggest `/builder-ship N` (or `/builder-release N` to abandon). The rule lifts automatically once they graduate to Thetes (after their 3rd shipped task).
+
+11. **On `session_already_has_active_claim`** (task 1642 — applies to **all ranks**): this *session* already holds an active claim, and a session may hold only one (one worktree → one branch → no commingled ships). The body names `active_task_id` + `active_task_title`. Surface them with `what_to_do`: either `/builder-ship N` (or `/builder-release N`) the in-flight task first, **or** open a fresh worktree/session for this new task and claim there. Do not retry in the same worktree — the refusal is the guard working. (`session_claim_check_failed` is the rare fail-closed variant when the server couldn't verify the session state; same remedy — retry, or use a fresh session/worktree.)
+
+## Constraints
+
+- **Don't retry on conflict.** Failures here are intentional — they protect us from race conditions.
+- **Don't claim multiple tasks in one go.** A **session** holds at most one active claim at a time (task 1642, server-enforced). If this session already has one, surface it and either ship/release it first or open a fresh worktree/session for the new task.
+- **Don't bypass the API.** Direct DB writes would skip the touches-conflict check.
+
+## Files this skill touches
+
+- Reads: `~/.config/otb/gds-session.json`
+- Calls: `POST /api/gds/claims`

package/.claude/skills/builder-connect/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: builder-connect
+description: One-command connect of the builder's Claude Desktop to their Example dev box (ADR 0031, #685). Triggers when the user says "/builder-connect", "connect me to the dev box", "set up my dev box", "connect Claude Desktop to the box", or "onboard me to the box". Runs the self-contained bootstrap that signs the builder in with GitHub, creates + registers their SSH key, and installs the Claude Desktop connection file — then tells them to restart Desktop and pick "Example Dev Box". This is the BUILDER side; the OPERATOR side is `node scripts/gds/box.js onboard <login>`.
+---
+
+You are guiding a builder through connecting their **own machine's** Claude Desktop to their org dev box. The audience is often non-technical — narrate each step in plain language, and never make them hand-edit files or paste keys around. One command does everything.
+
+## Background (the mental model — ADR 0031)
+
+Claude Code is three pieces: the **screen** (their device — always local), the **worker** (the dev box — where the repo + work live), and the **brain** (Anthropic's servers). This skill wires the screen to the box. The box itself is provisioned by an operator with `node scripts/gds/box.js onboard <login>`; this skill is the builder's half — it registers their SSH key and installs the Desktop connection file so the box shows up as a one-click "Environment".
+
+What the bootstrap does, in order:
+1. **GitHub sign-in** (device flow against the GDS — it prints a short code + a URL to open).
+2. **Creates an SSH key** at `~/.ssh/otb_builder` if absent (the private half never leaves their machine).
+3. **Registers the public key** with the GDS (`POST /box/ssh-key`). The box pulls it into `authorized_keys` itself — no operator SSH round-trip.
+4. **Downloads + installs** the Claude Desktop connection file (`managed-settings.json`) at the OS path.
+
+## How to use
+
+1. **Decide which command to run.** Both do the same thing; pick by where you're running:
+   - **Repo is present locally** (you can see `infra/box-connect.sh`): run the local copy —
+     ```bash
+     bash infra/box-connect.sh
+     ```
+   - **No repo** (a bare laptop with only Claude Desktop): run the hosted bootstrap —
+     - macOS / Linux:
+       ```bash
+       curl -fsSL https://example.com/api/gds/box/connect.sh | bash
+       ```
+     - Windows (PowerShell):
+       ```powershell
+       irm https://example.com/api/gds/box/connect.ps1 | iex
+       ```
+   (For staging, swap the host — or set `GDS_API_BASE` before the local script.)
+
+2. **Relay the GitHub code + URL verbatim.** The script prints a short user code and a `https://github.com/login/device` URL. The builder must open the URL and enter the code. Do not summarize — they need the literal values. The script also tries to pop the URL open automatically.
+
+3. **Wait while it polls.** After they approve in the browser, the script registers the key and installs the connection file. On macOS the install step needs **one `sudo` prompt** (the file lives under `/Library/Application Support/ClaudeCode` — the dir Claude Code actually reads managed settings from; `…/Claude/` is silently ignored).
+
+4. **Confirm the finish state and give the next steps:**
+   - Tell their operator they're registered (so the operator runs `box.js onboard <login>` to provision the box, if not already done).
+   - **Restart Claude Desktop.**
+   - Open **Code → Environment → "Example Dev Box"** to connect.
+
+5. **Once they're on the box**, the first thing to do there is authenticate the GDS CLI (`/builder-setup` or `node scripts/gds/setup.js`) so the box can pull rank-scoped source and keep their SSH keys in sync.
+
+## Constraints
+
+- **Never print or save the SSH private key or the GDS token anywhere except where the script puts them.** The private key stays at `~/.ssh/otb_builder`; the token is held only in memory on the laptop for the two authenticated calls (it is NOT persisted there — the box gets its own session when they authenticate Claude Code on it).
+- **Don't re-generate a key if `~/.ssh/otb_builder` already exists** — the script reuses it. Overwriting would break an existing box connection. (The script handles this; don't override it.)
+- **If `auth_not_configured` comes back**, the GDS has no GitHub OAuth app — stop and point them to an Archon (`blockers/blockers.md#github-oauth-app`). Don't loop.
+- **Memory + credits are server-side** (ADR 0024) — reassure the builder that nothing about which box they land on affects their history.
+
+## Files this skill touches
+
+- Runs: `infra/box-connect.sh` (or the hosted `GET /api/gds/box/connect.sh` / `.ps1`)
+- Reads/creates: `~/.ssh/otb_builder` (+ `.pub`)
+- Writes (macOS): `/Library/Application Support/ClaudeCode/managed-settings.json`; (Windows): `%ProgramFiles%\ClaudeCode\managed-settings.json` — the dir Claude Code reads managed settings from. **Not** `…/Claude/` or `%ProgramData%\Claude\`, which the app ignores (the box then never appears in the Environment picker).
+- Calls: `/api/gds/auth/device/{start,poll}`, `/api/gds/box/ssh-key`, `/api/gds/box/managed-settings`

package/.claude/skills/builder-cost/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: builder-cost
+description: Log a cost entry to the GDS — API spend, infra cost, art-pipeline credits, etc. Triggers when the user says "/builder-cost", "log cost", "I just spent X on Y", or after a session that consumed billable credits. Categories are api | compute | infra | domain | art | other.
+---
+
+**Script skill (authoritative).** The core action is `node scripts/gds/cost.js <amount-usd> <category> [--task-id N] [--description "..."] [--skill <name>]`. Once the args are determined, run it and print its output verbatim.
+
+You are logging a cost entry on behalf of the current builder. The GDS keeps a running ledger that powers the cost-vs-value charts on `status.example.com`.
+
+## What this skill does
+
+Runs `node scripts/gds/cost.js <amount-usd> <category> [--task-id N] [--description "..."] [--source "..."] [--skill <name>]`.
+
+The CLI hits `POST /api/gds/cost`, which inserts a `cost_log` row.
+
+## How to use
+
+1. **Determine the amount in USD.** Round to four decimals (the column accepts numeric(10,4)). For Anthropic API spend, use the API response's `usage` block × the model's pricing.
+
+2. **Pick a category**:
+   - `api` — Anthropic API, Google AI Studio, GitHub paid features, etc.
+   - `compute` — droplet upgrades, ad-hoc cloud spend
+   - `infra` — backups, monitoring, CDN paid plans
+   - `domain` — Cloudflare Registrar renewals
+   - `art` — direct art commissions or stock-asset purchases
+   - `other` — when none fit, with a clear description
+
+3. **Attach to a task if one applies** — `--task-id <N>`. This is what makes the cost-vs-value chart per-task accurate.
+
+4. **Attach to a skill if this cost was incurred by a skill invocation** — `--skill <skill-name>` (e.g. `--skill idea-triage`). This populates the `skill_name` column for per-skill spend measurement (ADR #304).
+
+5. **Run** and print the output verbatim:
+   ```bash
+   node scripts/gds/cost.js 0.42 api --task-id 12 --description "Anthropic API: 4.2k input + 1.1k output"
+   ```
+
+## Constraints
+
+- **Don't log speculative cost.** Only log spend that has actually been incurred (or is committed and irreversible).
+- **Don't log Lars's personal time** — credits are how that's accounted for, not USD.
+- **Don't double-count.** Before logging an art-pipeline cost manually, verify it isn't already in the DB from the one-time cost-ledger backfill (those rows use `source: 'art-cost-ledger'`).
+- **Don't log without a description for `other` category.**
+
+## Files this skill touches
+
+- Reads: `~/.config/otb/gds-session.json`
+- Calls: `POST /api/gds/cost`

package/.claude/skills/builder-end/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: builder-end
+description: One command to safely close out a Claude Code session — resolve the active claim (ship or release), verify the git tree is clean so nothing is lost, tear down this session's worktree, and (on a dev box) offer to shut the box down. Triggers when the user says "/builder-end", "close out my session", "close out my online terminal session", "end my session", "sign off", "wrap up and clean up", "I'm done for now, clean up", or "ship/release this and tear down the worktree". This is the session close-out a builder reaches for via /builder-exit — that one offboards a whole builder and is Archon-only; this is the everyday own-scoped close-out. Own-scoped: only this session's own claim + own worktree + own box.
+---
+
+You are closing out the current Claude Code **session** safely: resolve the held claim, confirm no work is stranded uncommitted, and clean up the session's git worktree. It is the bookend to `/builder-start` — one command so a session ends in a known-clean state instead of leaving a half-shipped claim and an orphaned worktree behind.
+
+This is **not** `/builder-exit` — that deactivates an entire builder (releases all claims, drops rank to Xenos). `/builder-end` is the everyday "I'm done with this session" close-out for one session's one claim.
+
+## What this skill does
+
+Composes operations that already exist, in a safe order, with the destructive ones gated last:
+
+1. **Resolve the claim** — `/builder-ship` when there's committed, shippable work; `/builder-release` when there isn't. (It calls the sibling skills; it does not re-implement shipping.)
+2. **Clean-git verify** — refuse to go further if any *tracked* file is uncommitted. This is the same guard `scripts/gds/ship.js` enforces (`trackedDirty` in [`src/bongos/ship-preflight.js`](../../../src/bongos/ship-preflight.js)): untracked scratch is ignored, but a modified/staged/deleted tracked file means real work isn't committed — stop before anything is lost.
+3. **Worktree teardown** — from the main checkout, `git worktree remove` this session's linked worktree, `prune`, and delete the now-merged `claude/<name>` branch.
+4. **Box close-out (dev box only)** — if running on a dev box (`/etc/otb/box.env` exists), offer to `close-box` so the box stops billing. Optional and gated on a yes; declining just lets the box idle-park. On a laptop this step is skipped — there's no box to close.
+
+It never pushes to `main`, never `ssh`-es, never runs a deploy — landing is `/builder-ship`'s job (server-mediated). It only ever touches the caller's **own** claim, **own** worktree, and **own** box.
+
+## How to use
+
+### 0. Snapshot the session state — read, don't mutate yet
+
+- **Held claim(s):** `node scripts/gds/api.js GET /api/gds/me` → `active_claims`. (A builder can hold parallel claims across sessions; resolve only the one this session worked.)
+- **Are we in a linked worktree?** `git rev-parse --git-dir` differs from `git rev-parse --git-common-dir` ⇒ yes (`--git-dir` is the per-worktree `<main>/.git/worktrees/<name>`; `--git-common-dir` is the shared `<main>/.git`); they're equal ⇒ main checkout (skip step 3). Test `--git-dir`, **not** `--git-common-dir` — the latter always returns the shared `<main>/.git` even inside a worktree, so checking *it* for `/worktrees/` never matches.
+- **Are we on a dev box?** `/etc/otb/box.env` exists ⇒ yes. This is the codebase's canonical "am I on a box?" marker — written by `box.js provision`, the same presence-check `scripts/gds/sandbox-stage.js` (`isDevBox`) uses. On a box the close-out has an extra step: the box keeps billing until it's shut down or idle-parks (step 4). On a laptop there's no box — skip step 4.
+- **Working-tree state:** `git status --porcelain`.
+- **Commits ahead of main:** `git rev-list --count main..HEAD` (fall back to `origin/main..HEAD`). Real commits ⇒ likely shippable; zero ⇒ likely a release.
+
+### 1. Resolve the claim
+
+- **Commits ahead AND clean tree ⇒ shippable.** Confirm with the user, then run the **`builder-ship`** skill with honest handoff `--notes` and a one-line non-jargon `--summary`. Don't fabricate the summary — if you can't state the value plainly, it isn't shippable; release instead.
+- **No commits / no shippable progress ⇒** run the **`builder-release`** skill with a one-phrase reason.
+- **No active claim ⇒** nothing to resolve; go to step 2.
+- **Ship strands at `confirmed`** (merge conflict or a failing check — the box ships, the merge doesn't): **stop here.** The branch still needs to land via `/merge-mode`. Surface that and do NOT tear down the worktree — its branch isn't merged yet (step 3's `git branch -d` would correctly refuse it).
+
+### 2. Clean-git verify
+
+Re-run `git status --porcelain`. Apply the `trackedDirty` rule: ignore `??` untracked lines, but if **any** tracked file is modified/staged/deleted/renamed/unmerged, **stop** and surface those files so the user can commit or discard them. Never tear down a worktree that still holds uncommitted tracked work — that is exactly how work gets lost.
+
+### 3. Worktree teardown — gated, and last
+
+Proceed only when **all** hold: we're in a linked worktree, the claim is resolved, the tree is clean, and (for a ship) the branch is merged into `main`.
+
+You can't remove the worktree you're standing in, so run the removal **from the main checkout** — resolve its path the way `ship.js` does (`findMainWorktree`: parse `git worktree list --porcelain` for the block whose `branch` is `main`). From there:
+
+```bash
+git worktree remove <this-worktree-path>   # refuses if dirty — that's the safety net; do not --force
+git worktree prune
+git branch -d claude/<worktree-name>        # -d (not -D): git refuses an unmerged branch, by design
+```
+
+Removing this session's worktree ends its filesystem — do it last, and tell the user the session is closed and they can start fresh from `/builder-start` anytime. **On a dev box, settle step 4 first:** if the builder is going to `close-box`, skip teardown entirely — deprovisioning destroys the whole `/workspace` disk, so removing one worktree first is wasted effort. Only tear the worktree down if they're keeping the box.
+
+**On the main checkout (not a worktree):** skip the teardown above — there's nothing to remove. On a **laptop** that means resolving the claim + clean-git verify is the whole close-out. On a **dev box** (step 0 found `/etc/otb/box.env`) the box itself is still up — continue to step 4.
+
+### 4. Box close-out — dev box only, gated, after the claim is resolved
+
+Skip this entirely if step 0 found no `/etc/otb/box.env` (a laptop — there's no box to close). On a box, resolving the claim does **not** stop the box billing; only closing it (or the idle-suspend sweep) does. Once the claim is resolved and the tree is clean, ask plainly:
+
+> *"Close the box down too? `close-box` deprovisions it — anything in `/workspace` you haven't shipped is gone. Or leave it: closing the tab keeps your session, and the box idle-parks on its own (cheap)."*
+
+- **Yes, shut it down** → run the **`close-box`** skill (`node scripts/gds/api.js POST /api/gds/box/close`). It enqueues a deprovision that runs within ~a minute. This **subsumes** worktree teardown — the whole box disk is going away, so step 3 was moot.
+- **No, keep the box** → leave it; it idle-parks automatically. The close-out is complete (claim resolved, worktree torn down in step 3 if applicable). Tell them they can reopen the terminal to resume, or `/builder-box` to check/wake it later.
+
+`close-box` is **own-scoped** — it only ever deprovisions the caller's own box. Never another builder's.
+
+## Constraints
+
+- **Own-scoped.** Only this session's claim, this session's worktree, and the caller's own box — never another builder's claim, never another worktree, never `git worktree remove` a path you didn't create, never another builder's box.
+- **Never destroy uncommitted work.** The clean-git verify gates teardown; `git worktree remove` (no `--force`) and `git branch -d` (not `-D`) are the load-bearing safety nets — keep them as written.
+- **Box close is opt-in and destructive.** On a box, never `close-box` without an explicit yes — it deprovisions the box and any unshipped `/workspace` work is gone. Declining is always fine; the box idle-parks on its own.
+- **Never push / ssh / deploy.** Landing goes through `/builder-ship` (server-mediated); this skill stays local to the builder's machine (its one possible API write is the opt-in own-scoped `close-box`).
+- **The destructive steps (teardown, box-close) never run unattended without a clear go.** Ship vs. release can be inferred from state (commits ⇒ ship, none ⇒ release) and proceed; removing the worktree ends the session and closing the box destroys it, so wait for an explicit yes before steps 3 and 4.
+- **Don't tear down a branch that isn't merged.** A released task or a ship stuck at `confirmed` still has an un-landed `claude/*` branch — `git branch -d` will refuse it; respect that and leave the worktree for `/merge-mode`.
+
+## Files this skill touches
+
+- Reads: `~/.config/otb/gds-session.json`; `/etc/otb/box.env` (presence check only — "am I on a box?")
+- Runs: the `builder-ship` / `builder-release` skills (`scripts/gds/ship.js` · `release.js`), `node scripts/gds/api.js GET /api/gds/me`, and local `git worktree` / `git status` / `git branch` commands. On a dev box, if the builder opts in, it runs the `close-box` skill (`POST /api/gds/box/close`) — the one own-scoped API write it can make; otherwise it makes no API writes of its own.