@bongos/core 1.17.0

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

@@ -0,0 +1,88 @@
+---
+name: builder-exit
+description: Gracefully offboard (or reactivate) a builder. Deactivating releases their active claims, seals each with a final session log, drops their rank to the sandboxed Xenos tier, blocks them from claiming new work, and archives their local memory — all while preserving their drachmae, credit history, and shipped-task attribution indefinitely. Triggers when the user says "/builder-exit N", "offboard builder N", "builder X is leaving", "deactivate builder", or "reactivate builder N". Archon-only — the offboard endpoint is Archon-gated. If a non-Archon, or anyone who just wants to end their own session, invokes it, redirect them to /builder-end (the session close-out) instead of dead-ending on a 403.
+---
+
+**Script skill (authoritative).** The core action is the `PATCH /api/gds/builders/:id/status` API call via `cli-lib.js`. Once intent is confirmed, run it and print the response verbatim — do not summarize or editorialize the claims-released list.
+
+You are gracefully offboarding a builder from the Game Development System, or reactivating one who has returned. This is a robustness operation — what happens when someone quits — and it must be **lossless**: nothing the builder earned or shipped is ever deleted.
+
+## First: is this an offboarding, or do you just want to close out your session?
+
+`/builder-exit` is **not** how you end a working session. It permanently **offboards an entire builder** — an Archon deactivating *someone else's* account (releases all their claims, drops them to Xenos, blocks new claims). "Exit" is the natural word for "log me off," so builders reach for this first ([#1448](https://example.com/builders#/task/1448)) — but it's the wrong, and gated, tool for the everyday close-out. Before touching anything, check intent:
+
+- **The caller wants to wrap up their *own* online-terminal / Claude Code session** — no builder id given, the id is their own, or they said "close out / end / sign off / I'm done" → **do not attempt an offboard.** Say plainly: *"`/builder-exit` offboards an entire builder (releases all their claims, drops them to Xenos) and is Archon-only — it isn't the session close-out. To close out your session, run **`/builder-end`**: it resolves your claim (ship or release) and, on a dev box, offers to shut the box down with `close-box`."* Then stop and hand off to `/builder-end`.
+- **The caller is not an Archon** (rank below `archon`, or you can't confirm Archon) → same redirect. The endpoint would 403 (`rank_forbidden`) anyway; don't dead-end them on the error — point them at `/builder-end` (+ `close-box` on a box).
+- **An Archon is deliberately offboarding (or reactivating) *another* builder, by id** → this is the real operation. Proceed with the steps below.
+
+Never run the destructive offboard just because someone wanted to log off — the two are different operations.
+
+## What graceful exit does (V3.R88 #307)
+
+Deactivating a builder via `PATCH /api/gds/builders/:id/status { status: 'inactive', reason }` transactionally:
+
+1. **Releases every active claim** they hold (`released_at = now`, outcome `abandoned`) and bounces each in-flight task back to `ready` so the work isn't stranded.
+2. **Seals an outstanding session log** for each released claim (a closing `abandoned`-on-exit row — the audit trail shows the work was handed back, not silently dropped).
+3. **Drops their rank to `xenos`** (the sandboxed tier) and sets `status = 'inactive'`, which **blocks them from claiming any new task** (the claim path refuses with `BUILDER_INACTIVE`).
+4. **Preserves everything else**: drachmae (`total_credits`), the full `credit_log`, their shipped tasks, and historical session logs all stay, attributed to them, indefinitely.
+5. Writes an interim audit row to `credit_log` (`delta=0`, reason carries the actor) until the dedicated `audit_log` lands (R36).
+
+Reactivation (`{ status: 'active' }`) flips them back to active. **Rank is not auto-restored** — it stays `xenos`, and an Archon re-promotes deliberately via `/builder-exit`'s sibling rank endpoint (`PATCH /api/gds/builders/:id/rank`).
+
+## Authority
+
+**Archon-only.** The endpoint is guarded by `requireRank('archon')` server-side (ADR 0016). An Archon **cannot change their own status** (`cannot_change_own_status` — the same no-last-Archon-footgun guard as rank changes), so the system can never be left with nobody in charge.
+
+## Memory archival (local-first)
+
+A builder's memory is **local-first**: it lives in their own `~/.claude/projects/<project>/memory/` on their own machine. The server never holds another builder's local memory (the server-side per-builder memory store is criterion #54's separate task).
+
+So memory archival is a **local** step, done on the exiting builder's machine — archived, never deleted:
+
+1. If you are running this on the **exiting builder's own machine**, move (don't delete) their memory dir into a dated archive:
+   ```bash
+   MEM="$HOME/.claude/projects/<project-slug>/memory"
+   if [ -d "$MEM" ]; then
+     mkdir -p "$MEM-archive"
+     cp -R "$MEM" "$MEM-archive/$(date +%Y-%m-%d)-exit" && echo "memory archived to $MEM-archive"
+   fi
+   ```
+   Keep the original in place too if the builder might return soon — archival is a snapshot, not a wipe. If they're fully leaving the machine, the archive copy is the durable record.
+2. If you are an **Archon offboarding someone remotely**, you cannot reach their local memory — note in the exit reason that local-memory archival is the departing builder's responsibility (or deferred to the #54 server sync once it exists). The server-side deactivation (steps 1–5 above) still runs and is the authoritative record.
+
+## How to use
+
+1. **Resolve the target builder id.** `/builder-exit 5` → builder #5. If given a name/login, look it up via the leaderboard or `GET /api/gds/me` patterns. Confirm the right person with the user.
+
+2. **Confirm intent.** Offboarding is significant and Archon-gated — restate what will happen ("this releases their N active claims, drops them to Xenos, and blocks new claims; their credits and shipped work are preserved") and get a clear go-ahead.
+
+3. **Archive local memory** if on the exiting builder's machine (see above).
+
+4. **Call the endpoint** (uses the current Archon's session token):
+   ```bash
+   # Deactivate
+   node -e "require('./scripts/gds/cli-lib.js').apiCall('PATCH','/api/gds/builders/<id>/status',{status:'inactive',reason:'<why>'}).then(r=>console.log(r.status, JSON.stringify(r.data,null,2)))"
+   # Reactivate
+   node -e "require('./scripts/gds/cli-lib.js').apiCall('PATCH','/api/gds/builders/<id>/status',{status:'active'}).then(r=>console.log(r.status, JSON.stringify(r.data,null,2)))"
+   ```
+
+5. **Print the API response verbatim.** The JSON shows claims released and new rank/status. If reactivating, note (from the response) that rank stays `xenos` until a `/builder-rank` promotion.
+
+## Error modes
+
+- `403 rank_forbidden` — you're not Archon. Only an Archon can offboard.
+- `403 cannot_change_own_status` — you tried to deactivate yourself. Another Archon must do it (last-Archon guard).
+- `409 already_inactive` / `409 not_inactive` — the builder is already in the target state.
+- `404 builder_not_found` — wrong id.
+
+## Constraints
+
+- **Never delete a builder row or their credit/credit_log/session_logs.** Exit is deactivation, not deletion. The whole point is that history survives.
+- **Never archive by deleting local memory.** Copy to the archive; the builder may return.
+- **Don't offboard reflexively.** A builder who's just idle isn't gone — exit is for genuine departures.
+
+## Files this skill touches
+
+- Reads: `~/.config/otb/gds-session.json`, the exiting builder's local memory dir
+- Writes: `<memory>-archive/` (local snapshot, on the builder's machine)
+- Calls: `PATCH /api/gds/builders/:id/status`

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

@@ -0,0 +1,40 @@
+---
+name: builder-key
+description: List which API keys are set/unset for the caller, render a visual "key needed" callout for anything missing, and drive the UI-first add flow (open Settings, then re-sync + confirm). Triggers when the user says "/builder-key", "/api-key", "what keys do I have set", "do I have a Gemini key", "add my art key", "my key isn't working", or when the art pipeline errors with "No image-generation key found". HARD RULE: never accept a key pasted in chat — always redirect to Settings.
+---
+
+**Script skill (authoritative).** The core action is `node scripts/gds/key-status.js [--recheck]`. Run it and relay its output — the monospace status list, plus the visual callout it emits for any missing key (rendered per the marker convention below).
+
+You are checking the current builder's API-key coverage (today: the art pipeline's Google AI Studio / Gemini key; the script is written to add more keys without new code).
+
+## HARD RULE — never accept a key in chat (idea 347 / feedback_auth_flows_ui_first)
+
+A key is **never** pasted into chat, and **never** accepted as a CLI argument. The only place a key is ever written is the Settings page (`PUT /me/art-key/own`, driven by the browser). If the user pastes what looks like a key into the conversation:
+
+- **Do not** run it through any tool, echo it back, or forward it anywhere (the transcript is uploaded — a pasted key is now compromised the moment it's typed).
+- Refuse, and point them back to Settings: `https://example.com/builders/settings#art-key`.
+- `key-status.js` also refuses defensively if a key-looking string reaches it as an argument — that is a backstop, not the primary defense. The primary defense is **you never run it there in the first place**.
+
+## How to use
+
+1. **List status.** Run `node scripts/gds/key-status.js` and relay its output verbatim (the monospace list). It hits `GET /api/gds/me/art-key` for each known key.
+
+2. **Missing key → the visual callout fires automatically.** When a key is unset, the script calls `scripts/gds/key-card.js` itself and prints `[otb-key-card-html] <path>` — the same marker the `.claude/hooks/lifecycle-card.js` PostToolUse hook scans for on ANY Bash output. The hook injects a render directive right after the tool result:
+   - If you have `mcp__visualize__show_widget`: call `mcp__visualize__read_me` once this session (modules `["interactive","mockup"]`) if you haven't, then render the HTML exactly as directed — **once**, no prose recap.
+   - If you don't have that tool: the monospace card the script already printed IS the summary — relay it as-is.
+
+3. **Drive the UI-first add flow.** Tell the user to click "Add it in Settings ↗" in the card (or open `https://example.com/builders/settings#art-key` themselves). The key syncs to their box automatically at next session start via `scripts/gds/fetch-art-key.js` — no further action needed from you.
+
+4. **Confirm it resolved.** Once the user says they added it, run `node scripts/gds/key-status.js --recheck` — this re-syncs the local session file immediately (rather than waiting for next session start) and re-checks status. Relay the result: resolved (all set) or still missing (point back to step 2/3).
+
+## Constraints
+
+- **Never** write a script, one-liner, or curl command that takes a key as an argument or env var supplied inline in chat — that's the same violation as pasting it, just automated.
+- **Don't invent new key types speculatively** — `KEYS` in `key-status.js` lists only keys that actually have a backing route (today: `gemini`/art-key). Adding a new key type is a small script edit, not a new skill.
+- If `GET /me/art-key` is unreachable (offline, API error), say so plainly — don't guess at status.
+
+## Files this skill touches
+
+- Reads: `~/.config/otb/gds-session.json`
+- Calls: `GET /api/gds/me/art-key`, `GET /api/gds/me` (widgets knob)
+- Runs: `scripts/gds/key-status.js`, `scripts/gds/key-card.js` (via the status script), `scripts/gds/fetch-art-key.js` (via `--recheck`)

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

@@ -0,0 +1,50 @@
+---
+name: builder-reauth
+description: Refresh an expired or invalid GDS CLI session the fast, UI-first way — no terminal Device Flow. Triggers when the user says "/builder-reauth", "re-auth", "refresh my session", "my GDS session expired", "re-issue my CLI token", or when any /builder-* command fails with "GDS CLI session is no longer valid". Opens the builder's Settings page in the browser, the user clicks "Re-issue CLI token" under "CLI Access" and copies the one-liner, and this skill runs it to write the new session.
+---
+
+You are refreshing the current builder's GDS CLI session. CLI bearer tokens carry a 24h idle TTL (they refresh on every use), so an actively-used session stays alive — but an idle one expires, and a revoked one dies immediately. This skill is the **fast path back in**: browser clicks plus a single copy/paste, instead of the slower terminal Device Flow.
+
+## Why expiry exists (so you can explain it if asked)
+
+The idle TTL is auth-token hygiene (GDS-V3 criterion **C9**): the CLI token lives in a plaintext file (`~/.config/otb/gds-session.json`, mode 0600), so bounding the lifetime of a leaked or abandoned token matters. It is **not** what enforces rank changes — demotion calls `revokeAllSessionsForBuilder` synchronously and rank is read fresh from the DB on every request ([ADR 0016](../../../docs/adr/<redacted>.md)). So expiry stays; the friction is what this skill removes.
+
+## The flow (guided paste)
+
+1. **Detect.** Run the helper — it checks whether the existing session is still valid and, if not, opens the hall:
+   ```bash
+   node scripts/gds/reauth.js
+   ```
+   - **Exit 0** → the session is already valid. Relay who they're signed in as and stop — there is nothing to do. Do NOT re-auth a working session.
+   - **Exit 10** → re-auth is needed. The helper has opened (or printed) the builders' hall URL and the click-path. Continue to step 2.
+   - **Exit 2** → the API was unreachable (network). Relay that, and let them retry once they're back online. The session may be fine.
+
+2. **Relay the click-path verbatim.** The helper prints the exact steps; pass them to the user clearly (don't paraphrase the URL):
+   - Open `https://example.com/builders/settings` (the helper tries to open it automatically; if not, give them the link).
+   - They are already signed in there via the browser cookie. Under the **"CLI Access"** section, click **"Re-issue CLI token"**.
+   - Click **"Copy"** — it copies a one-line command of the form `node scripts/gds/paste-token.js <token>`.
+   - Ask them to **paste that one line back into the chat**.
+
+3. **Run the pasted command.** When the user pastes `node scripts/gds/paste-token.js <token>`, run it exactly as given. `paste-token.js` verifies the token against `/api/gds/me` **before** touching the session file (a bad paste leaves the existing session intact) and preserves any `gemini_api_key`. On success it prints the builder login, rank, and confirms the session file was written.
+
+4. **Confirm.** Relay the authenticated identity + rank back to the user, and tell them they can now re-run whatever `/builder-*` command they were trying.
+
+## Edge cases
+
+- **"You are not signed in" / `cookie_required`.** The re-issue endpoint mints CLI bearers from a browser *cookie*, not a bearer — a leaked CLI token can't extend its own life. If the Settings page shows them logged out, they sign in at `https://example.com/builders` first, then return to `/builders/settings` and click Re-issue. Once signed in the button works.
+- **No session file at all (fresh machine).** The helper still guides them to the Settings page; if they've never authed on this machine, the hall sign-in + Settings → CLI Access → Re-issue path still works. The terminal Device Flow (`node scripts/gds/setup.js`) remains the fallback for a brand-new builder with no browser session anywhere.
+- **Browser can't open automatically** (headless / SSH). The helper prints the URL; relay it so they can open it on whatever machine has their browser, then paste the one-liner back.
+- **Fallback — terminal Device Flow.** If the browser path is unavailable for any reason, `node scripts/gds/setup.js --force` re-auths via GitHub Device Flow (terminal code entry). Slower and not UI-first; use only when the hall route can't be used.
+
+## Constraints
+
+- **The token briefly transits the chat — that's the known cost of guided-paste.** The user pastes `node scripts/gds/paste-token.js <token>` into the conversation, so the bearer appears in the chat (and any log/context that captures it). That's the accepted trade-off Lars chose; the deferred zero-paste loopback flow removes it. So: treat the session log as sensitive, **never echo the token beyond running that one pasted command**, and never write it to any file other than `~/.config/otb/gds-session.json` (`paste-token.js` is the only thing that should write it — let it do the write). The token rotates whenever the builder clicks Re-issue again, so re-running this flow invalidates an exposed paste's usefulness for an attacker who lacks the browser cookie.
+- **Don't re-auth a valid session.** If `reauth.js` exits 0, stop.
+- **`GDS_API_BASE`** overrides the endpoint (default `https://example.com`); for local dev `GDS_API_BASE=http://localhost:3000`.
+
+## Files this skill touches
+
+- Runs: `node scripts/gds/reauth.js` (detect + open browser + print click-path)
+- Runs: `node scripts/gds/paste-token.js <token>` (verify + write the new session)
+- Reads/Writes (via paste-token.js): `~/.config/otb/gds-session.json`
+- Calls: `GET /api/gds/me`; the Settings page (CLI Access) calls `POST /api/gds/auth/cli-token/issue`

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

@@ -0,0 +1,109 @@
+---
+name: builder-redteam
+description: File a red-team / vulnerability report against the city. Walks the builder through severity, target, title, repro, expected vs. actual, then POSTs to /api/gds/security/reports so the Archon view picks it up. Optionally drafts a follow-up idea_inbox entry for the fix. Triggers when the user says "/builder-redteam", "I found a security issue", "redteam report", "file a vuln", or describes a flaw in the system's own walls. Metic+ only — Xenos see a polite refusal.
+---
+
+You are filing a vulnerability report on the Off the Boats project. The reporter is a trusted builder who has found a flaw — in the GDS, the game server, the chat broadcast, the deploy chain, the auth model — and wants the red-team bounty surface to pick it up.
+
+This is the **bounty intake** side of V3.R63/R64/R67. Once the report is filed:
+
+- it lands in `vulnerability_reports.status='open'`;
+- the Archon view at `/builders` (R67) surfaces it for adjudication;
+- the auto-repro subagent (V3.R68, when live) will attempt to reproduce it;
+- if confirmed, the city pays out drachmae by severity.
+
+The reporter does NOT need Archon attention to file. The Archon comes to the queue, not the other way around.
+
+## Hard rules
+
+- **Metic+ only.** Xenos rank gets a 403 from the API. If you're a Xenos, the polite refusal tells you to ask the Archon to escalate or to flag the flaw through normal chat channels.
+- **Don't file against people.** Reports are about *flaws*, not behavior. If the issue is "Lars said X in chat," this is the wrong surface.
+- **Don't file duplicates.** The Archon view already deduplicates by target+title at adjudication time, but be a good citizen — search recent reports first if you suspect overlap.
+- **Don't include live secrets in the description.** The `repro_steps_md` field is captured verbatim; if your repro requires a token, refer to it as `<TOKEN>` and put the real value in a separate channel (Signal, in-person).
+
+## What this skill does
+
+1. Reads `~/.config/otb/gds-session.json` for the bearer token.
+2. Hits `GET /api/gds/me` to confirm rank ≥ Metic. Refuses with a friendly message if Xenos.
+3. Walks the user through five questions (see below).
+4. POSTs to `/api/gds/security/reports`.
+5. Echoes the report id back + a note that the auto-repro subagent will attempt reproduction within the hour.
+6. (Optional) Offers to file an `idea_inbox` entry with `kind='security-finding'` pointing back at the report id, so the fix can be triaged into a normal task on the next `/idea-triage` pass.
+
+## The five questions
+
+Ask one at a time. Don't batch — the answers feed each other.
+
+1. **Severity.** One of `low`, `medium`, `high`, `critical`. Show the bounty schedule from `GET /api/gds/public/bounty-table` if the user is unsure. Critical means "this could let an attacker forge writes as another builder or read data they're not entitled to"; high means a real attack vector with a workaround; medium is a defense-in-depth gap; low is a hardening recommendation.
+2. **Target.** One short line — the route, file, endpoint, or surface. Examples: `POST /api/gds/tasks/:id/override-request`, `src/bongos/auth.js#verifyToken`, `caddy: example.com:443`. Goes into the `target` column verbatim.
+3. **Title.** One sentence summarizing the flaw. Reads in the Archon queue first, so make it scan-friendly. Example: "OAuth state cookie has no SameSite=strict — CSRF window during auth handshake."
+4. **Description.** What's the impact? Who would notice? Why does it matter? A few sentences. Free-form Markdown.
+5. **Repro steps.** Numbered list of what an attacker (or auditor) does to demonstrate the issue. The auto-repro subagent (R68, when wired) will try to follow these exactly, so be precise. Use `<TOKEN>` or `<COOKIE>` placeholders for any sensitive values.
+
+After each answer, echo it back. If the user changes their mind, accept the revision before moving on.
+
+## POST shape
+
+Build the report JSON from the five answers above, write it to a temp file with
+your file-write tool (NOT a shell heredoc — heredocs aren't portable), then POST
+it with the cross-platform GDS API helper:
+
+```
+node scripts/gds/api.js POST /api/gds/security/reports --body-file <path-to-report.json>
+```
+
+where `report.json` is:
+
+```json
+{ "target": "<TARGET>", "severity": "<SEVERITY>", "title": "<TITLE>", "description": "<DESCRIPTION>", "repro_steps_md": "<REPRO>" }
+```
+
+`api.js` resolves your session token + API base via `cli-lib` (no manual token
+extraction) and runs on Windows/macOS/Linux — the old `jq` + `curl` form did not.
+
+Expected response: `201 { ok: true, report: { id, status: 'open', ... }, bounty_table: { ... } }`.
+
+If the response is `403 rank_forbidden`, surface the message — the user is Xenos and should not have reached this step.
+
+## Confirmation message
+
+After a successful filing, tell the user:
+
+```
+Report #<id> filed at severity=<sev>, status=open.
+Visible now in /builders → Watch of the City (Archon view).
+Bounty if confirmed: <drachmae> (see /public/bounty-table).
+An automated subagent will attempt to reproduce within the hour (R68);
+the Archon will adjudicate after that.
+```
+
+## Optional follow-up: idea_inbox entry
+
+After the report is filed, offer:
+
+> "Want me to also file an `idea_inbox` entry for the *fix*? That puts the work into the normal triage queue so the next `/idea-triage` pass can promote it to a real task."
+
+If yes — write the idea JSON to a temp file, then:
+
+```
+node scripts/gds/api.js POST /api/gds/inbox --body-file <path-to-idea.json>
+```
+
+where `idea.json` is:
+
+```json
+{ "title": "Fix: <TITLE>", "body_md": "Originates from vulnerability_report #<REPORT_ID> (severity=<SEVERITY>). Target: <TARGET>.\n\n<DESCRIPTION>", "kind": "security-finding" }
+```
+
+This is optional because some findings are "the system is fine, my mental model was wrong" — the report itself is the durable signal; an idea entry is only useful when there's actual remediation work to schedule.
+
+## What this skill does NOT do
+
+- Does NOT post anything to the team chat space — the bounty surface is intentionally Archon-private until adjudicated.
+- Does NOT create a `tasks` row directly — a vuln routes through the security-report surface (`/security/reports`) and the optional idea_inbox path above, which then becomes a fix-task via `/idea-triage`. (Authoring a task is Metic+ as of [ADR 0090](../../../docs/adr/<redacted>.md), but red-team reports deliberately use the report/idea flow, not a self-authored task.)
+- Does NOT ping the Archon. The Archon view auto-refreshes; pinging would defeat the queue's batching purpose.
+- Does NOT score or grade the report. That's R68 (auto-repro) + Archon adjudication.
+
+## When the API is unreachable
+
+If the POST fails (network, droplet down, route 5xx), do NOT silently swallow. Print the full response body and tell the user the report was NOT filed. Offer to re-try once they confirm the droplet is up — `node scripts/gds/api.js GET /api/gds/healthz` is the fastest probe (cross-platform; prints the status).

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

@@ -0,0 +1,41 @@
+---
+name: builder-release
+description: Cancel an active claim without shipping. The task returns to 'ready' status, no credits are awarded, and the work is freed for another builder. Triggers when the user says "/builder-release N", "cancel my claim", "I'm dropping this task", "give it back". Captures a brief reason in the session log.
+---
+
+**Script skill (authoritative).** The core action is `node scripts/gds/release.js <task-id> --reason "..."`. Once the task id and reason are determined, run it and print its output verbatim — do not editorialize the result.
+
+You are releasing a task on behalf of the current builder. Releasing is the honest "I started this, but I'm not finishing it right now" exit.
+
+## What this skill does
+
+Runs `node scripts/gds/release.js <task-id> --reason "..."`.
+
+The CLI hits `POST /api/gds/claims/:id/resolve` with `outcome: 'abandoned'`, which transactionally:
+1. Marks the claim `released_at = now`, outcome `abandoned`.
+2. Flips the task status back to `ready`.
+3. Inserts a `session_logs` row with the reason and timestamps.
+4. Awards no credits.
+
+The task is immediately claimable by another session.
+
+## How to use
+
+1. **Determine the task id and reason.** If the user said "/builder-release N", the task id is N. If no reason was given, ask for one phrase — even "out of time" is enough.
+   - Release vs. ship-as-partial: Release = "reset cleanly, no progress to record." Ship-as-partial = "I made progress; use `/builder-ship` with partial notes instead."
+
+2. **Run**:
+   ```bash
+   node scripts/gds/release.js <task-id> --reason "the reason"
+   ```
+   Print the output verbatim.
+
+## Constraints
+
+- **Don't release reflexively when blocked.** If the blocker is real and persistent, surface it to Lars AND promote it to a blockers entry.
+- **Don't shame.** Releasing is a normal, healthy operation.
+
+## Files this skill touches
+
+- Reads: `~/.config/otb/gds-session.json`
+- Calls: `GET /api/gds/me`, `POST /api/gds/claims/:id/resolve`

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

@@ -0,0 +1,62 @@
+---
+name: builder-setup
+description: One-time setup for a new builder on the Off the Boats project management system. Triggers when the user says "/builder-setup", "set up builder", "register me", "set up GDS", or when a builder slash command fails with "no GDS session." Authenticates the user against GitHub via Device Flow and stores a session token at ~/.config/otb/gds-session.json so future /builder-* commands work. If a valid session already exists for another account on this machine, setup.js asks whether to continue as that builder or sign in as a different one (multi-builder-on-one-device gate).
+---
+
+You are running the one-time setup that registers this Claude Code installation as a builder on the Off the Boats GDS.
+
+## Background
+
+The GDS authenticates builders against GitHub via OAuth Device Flow. The auth happens inside the terminal: the script prints a code, the user opens a URL, types the code, the script polls until it gets approval. The setup is builder-agnostic — every path is resolved from the current user's home directory, so this works on any developer's machine.
+
+Before running this skill, **two things must be true**:
+
+1. The droplet has GitHub OAuth client credentials available (env vars `GDS_GITHUB_CLIENT_ID` / `GDS_GITHUB_CLIENT_SECRET`, or `~/.config/otb/gds-github.json`). If not, the API returns `auth_not_configured` and the skill should explain that to the user and point at `blockers/blockers.md#github-oauth-app`.
+2. The user has a GitHub account.
+
+## What this skill does
+
+Runs `node scripts/gds/setup.js`. The script:
+
+1. POSTs `/api/gds/auth/device/start` → gets `user_code` + `verification_uri` from GitHub via the server.
+2. Prints a clear "open this URL, enter this code" prompt to the user.
+3. Polls `/api/gds/auth/device/poll` every few seconds until the user approves (or denies, or expires).
+4. On success, writes `~/.config/otb/gds-session.json` (resolved from the current user's `$HOME`) with the bearer token and builder profile.
+5. Prints the builder's profile.
+
+## How to use
+
+1. **(Optional) Preview first** with `--dry-run`:
+   ```bash
+   node scripts/gds/setup.js --dry-run
+   ```
+   Prints every step the real run would take — which API endpoints it would hit, where it would write the session file, which TTY prompts it would show — without doing any of them. Recommended for newcomers who want to see what's about to happen before running for real.
+
+2. **Run setup**:
+   ```bash
+   node scripts/gds/setup.js
+   ```
+   If the user has previously authenticated and just wants to re-auth, add `--force`.
+
+   **Multi-builder-on-one-device gate (#533).** The session file lives at one global path per machine (`~/.config/otb/gds-session.json`), so a device can only hold one builder's session at a time. If a *valid* session already exists, setup.js no longer silently adopts it — on an interactive shell it asks: **[1] continue as that builder** or **[2] set up as a different builder** (sign in again, replacing the saved session). **Default to [1] / continuing as the existing builder.** Do NOT proactively pitch switching accounts, suggest signing in as someone else, or imply the builder should move to a more-privileged (e.g. Archon) account — that's a decision the builder (or an Archon) raises explicitly, not something setup offers. Only pick **[2]** when the user has clearly stated they are a *different* person than the one shown. Non-interactive shells (CI/batch) keep the existing session; a caller who genuinely needs a different identity passes `--force` themselves.
+
+3. **Read the output back to the user** — relay the verification_uri and user_code clearly, since they need to act on it. Don't summarize; the user needs the literal code and URL.
+
+4. **Wait** while polling completes. The script prints dots. If the user says they've finished, it'll be picked up on the next poll within a few seconds.
+
+5. **Confirm** when authentication completes. The session file is at `~/.config/otb/gds-session.json` (chmod 600) — where `~` is the current OS user's home directory, whoever they are.
+
+6. **Suggest next step.** The Xenos path is action-only (#766) — no primer to read first. `setup.js` prints a "Newcomer path" footer (1. choose thy craft · 2. `/builder-start` · 3. `/builder-claim N` → `/builder-ship` · 4. ship three works and you rise to Thetes); relay it verbatim instead of paraphrasing. For a returning builder (rank ≥ Metic), `setup.js` prints no newcomer footer and `/builder-start` is the right immediate next step.
+
+## Constraints
+
+- **Never write the session token to chat or any file other than `~/.config/otb/gds-session.json`.** It's a bearer token equivalent to a GitHub OAuth grant for this user.
+- **If `auth_not_configured` is returned**, do NOT keep polling or trying to recover — explain to the user that an Archon needs to register the GitHub OAuth App and provide credentials on the server. Point them to `blockers/blockers.md#github-oauth-app`.
+- **`GDS_API_BASE` env var** can override the API endpoint. Default is `https://example.com`. For local dev: `GDS_API_BASE=http://localhost:3000`.
+- **`HOME` env var override** — `setup.js` (and the rest of the GDS CLI) resolves every path via `os.homedir()`, which honors `$HOME`. Tests can simulate a fresh-user setup by running the script with `HOME=/tmp/some-dir`. See `tests/setup_smoke.mjs` for the smoke test that exercises this.
+
+## Files this skill touches
+
+- Reads (potentially): `~/.config/otb/gds-session.json` (only to check if already authenticated)
+- Writes: `~/.config/otb/gds-session.json`
+- Calls: production `/api/gds/auth/device/start` and `/api/gds/auth/device/poll`

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

@@ -0,0 +1,79 @@
+---
+name: builder-ship
+description: Mark the current builder's claimed task as shipped. Awards credits, writes a session log entry, frees the claim. Triggers when the user says "/builder-ship", "I'm done", "ship it", "mark this complete". Asks for handoff notes and a public-facing value summary if the user didn't provide them.
+---
+
+You are shipping a task on behalf of the current builder. Shipping is the moment that converts in-flight work into permanent project history + credits.
+
+## What this skill does
+
+Runs `node scripts/gds/ship.js <task-id> --notes "..." --summary "..."`.
+
+The CLI drives a **three-state lifecycle** with a subagent grader between states (Phase 5, 2026-05-10):
+
+1. **`completed`** — the builder declared the work done. Always reached. Sets the task's `value_summary` (used on `status.example.com`) and the handoff notes.
+2. **`confirmed`** — smoke green + the subagent grader passed. **Credits land here**: a `credit_log` row for `credits_reward` is inserted (a trigger updates `builders.total_credits`). If the grade fails, the task stays at `completed` for human follow-up.
+3. **`shipped`** — the branch is merged into `main` + deployed (visible in production). The claim is released and the task is stamped `shipped_at` + `shipped_by`. If this step fails (conflicts, smoke red), the task stays at `confirmed` for `/merge-mode` to land later.
+
+`/builder-ship` runs steps 1 + 2 inline; on auto-confirm it chains into step 3 (push, merge on main, smoke, deploy).
+
+(Dev-box game changes, `--approved`) Persists the builder's sandbox self-approval to `tasks.sandbox_review` — `{ by, at, stamp, url, method }`, with `by`/`at` stamped server-side ([#1048](https://example.com/builders#/task/1048), ADR 0046).
+
+## How to use
+
+1. **Confirm the task id** the user is shipping (it must match their currently-active claim).
+
+   **On a dev box with game-surface changes, stage first (#927, ADR 0046 + #1048).** If the diff touches the game (`public/`, `src/world/`, `src/rooms/`, `server.js`) and the session is on a dev box, the flow is: stage → the builder reviews the change at `https://sandbox-<login>.example.com` → approve → ship. `ship.js` enforces this before the claim resolves: un-staged game work gets staged to the sandbox and the ship **aborts with a `🔍 REVIEW REQUIRED` block** carrying the URL (claim intact, nothing lost).
+
+   **When you see that block, position the sandbox link prominently for the builder.** `ship.js` also emits the deterministic lifecycle card for the `review` stage (an `[otb-card-html] <path>` marker) — if an in-feed visualization tool is available, render that card (its primary action is **Open in sandbox ↗**, the URL); it's the cleanest way to make the link impossible to miss. Either way, surface the URL as its own standalone, clickable line in chat — a clear callout, NOT buried inside a paragraph of command output — and say in one line what to look at. This is the moment the change is ready to review; the link must be impossible to miss. Let the builder open it, review, and suggest changes; iterate if needed. **Only once the builder explicitly approves, re-run with `node scripts/gds/ship.js <id> --approved`** — that records their sign-off as a durable `sandbox_review` fact on the task (who, when, and the content stamp of exactly what was reviewed). Never pass `--approved` yourself without a real human go; the pause + sign-off IS the feature. `--skip-stage` is the escape hatch (use sparingly — the gate exists so unreviewed game changes don't ride straight to prod). Laptop sessions and non-game diffs are unaffected.
+
+2. **Compose the handoff notes (`--notes`)** following the structure in `docs/handoff-template.md`:
+   - What shipped (with confidence tags: verified-prod | verified-smoke | implemented-not-verified)
+   - What's broken or unverified
+   - Manual checks the next session should run first
+   - Next obvious work
+   - New limitations / risks / blockers introduced
+   - Generative ideas captured
+   - Decisions made (linked to ADRs)
+   If the user is in a hurry, ask them for one bullet per heading and fill gaps from session context.
+
+3. **Compose the value summary (`--summary`)** — ONE LINE, written for non-engineers. This is what shows up on `status.example.com` for the team and the public. Examples:
+   - "Players can now resume at their last position after a browser refresh."
+   - "Cost dashboard backfilled with 377 art-pipeline API calls."
+   - "Sessions can claim work atomically; merge conflicts can't happen across worktrees."
+   No jargon, no file paths, no commit hashes.
+
+4. **Run**:
+   ```bash
+   node scripts/gds/ship.js <task-id> \
+     --notes "$(cat <<'EOF'
+   ...handoff markdown...
+   EOF
+   )" \
+     --summary "the one-liner"
+   ```
+
+5. **Render the completion card — it IS the summary; do NOT write a prose recap (task 1270).**
+   _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 `ship.js` runs — normally just follow that and render **once**; the detail below is the fallback if no directive appears._
+   On every ship, `ship.js` prints ONE deterministic completion card — the same shape every time, only the data changes. It always prints a monospace card to stdout, and for a shipped / confirmed / grade-failed outcome it ALSO writes a branded HTML card to a temp file and prints two marker lines:
+   ```
+   [otb-card-html] /tmp/otb-ship-card-<id>.html
+   [otb-card] builder-ship: render the HTML ... via the visualization tool ...
+   ```
+   - If the `[otb-card-html] <path>` line 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>_shipped`). The card renders in the chat feed. **Author nothing yourself** — the HTML is generated, so the card is byte-identical every ship; that determinism is the whole point.
+   - If instead you see an **`[otb-card] widgets are off …`** line (the builder disabled widgets via Settings → Rendering — task 1279), there is no HTML file by design: **relay the monospace card as plain text and do NOT call show_widget.** Don't try to "restore" the widget — the absence is the saving.
+   - If no visualization tool is available at all (headless / cron / a session without it), the **monospace card already printed IS the summary** — stop there.
+   - **Either way: do NOT add a free-form recap** of what shipped, credits, files, cost, or next steps. The card already carries all of it, and its built-in action ("Start next task" / "Land it" / "Fix & re-grade") is the next-step prompt — you don't need to restate it. This replaces the old per-ship prose summary the owner asked us to retire.
+   - The ONLY thing you may add is a single **required** action the card can't express — e.g. a sandbox `🔍 REVIEW REQUIRED` URL from a review pause (see step 1), or a blocker that needs the owner. One line, then stop.
+   - A Hero sound + Discord broadcast may still fire on a milestone (CLAUDE.md §2); that's automatic — no need to narrate it.
+
+## Constraints
+
+- **Never ship a task you don't have an active claim on.** The API will reject it (`NOT_YOUR_CLAIM`); surface clearly and run `/builder-start` to find the right state.
+- **Don't fabricate the value summary.** If you can't summarize the value in non-jargon English, the work is probably not actually shippable yet — release instead and surface the gap to the user.
+- **Be honest in handoff notes.** Use `[verified-prod]` only when a real human exercised the feature on the live site. Otherwise `[verified-smoke]` or `[implemented-not-verified]`. The whole project relies on this honesty.
+
+## Files this skill touches
+
+- Reads: `~/.config/otb/gds-session.json`
+- Calls: `GET /api/gds/me`, `POST /api/gds/claims/:id/resolve`

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

@@ -0,0 +1,51 @@
+---
+name: builder-stage
+description: Stage the builder's current working tree on their own live game preview (the sandbox) so they can review a game change in a browser BEFORE shipping it to the main game (#927, ADR 0046). On a dev box the sandbox is sandbox-<login>.example.com (ADR 0044); on a LOCAL full clone (laptop) it is a private http://localhost:<port> preview (task 1056). Triggers when the user says "/builder-stage", "stage my work", "stage this on my sandbox", "let me see it before shipping", "preview this change", "show me the change running", or right before /builder-ship when game surfaces changed. Own-scoped and machine-local — it only (re)starts the caller's own preview (box service or local process); it never touches prod or other builders' machines.
+---
+
+You are staging a builder's in-progress work on **their own** sandbox — the live game preview running on their dev box (ADR 0044) — so they can see the change in a browser, suggest fixes, and only then decide to ship it to the main game (ADR 0046).
+
+## Background
+
+The script auto-detects where it's running and (re)starts the right preview — both serve the **game-only** entry (`src/preview-server.js`, ADR 0052), degraded-DB (fully playable, no saved state, isolated from prod, no `/api/gds`):
+
+- **Dev box:** `box-game-preview.service` serves the `/workspace` tree at `https://sandbox-<login>.example.com` (ADR 0044). Staging restarts that service.
+- **Local full clone (laptop):** a private detached process serves it at `http://localhost:<port>` (default 3100, `$OTB_PREVIEW_PORT` to override), managed by `scripts/gds/local-preview.js` (task 1056). Staging (re)starts that process. No tunnel, no public URL — it never leaves your machine.
+
+Either way staging = (re)start the preview, health-check it, and record a marker of exactly what tree state was staged. `/builder-ship` checks that marker: a game-surface diff that wasn't staged at its current state triggers the sandbox review gate before the claim resolves — on a box AND on a local clone.
+
+## How to use
+
+1. **Run the stage command** from the repo root (`/workspace` on a box; your clone root on a laptop):
+   ```bash
+   node scripts/gds/sandbox-stage.js
+   ```
+   It (re)starts the preview, waits until the game answers, writes the staged marker, and prints the review URL (the `sandbox-<login>` host on a box, or `http://localhost:<port>` locally).
+
+   > **Local setup (laptop):** the preview needs the game's dependencies, so run `npm install` once in your clone. You can also drive the preview directly: `npm run preview` (start), `node scripts/gds/local-preview.js {status|restart|stop|logs}`. Reviewing via the Claude Code preview tools? A `local-sandbox` server is pre-wired in `.claude/launch.json`.
+
+2. **Hand the builder the URL** and tell them plainly: this is *their* private copy of the game running on *their* box — nothing has shipped. Ask them to open it, walk around, and check the change.
+
+   > **Generated art?** If the change was a pixel-art tile, the builder can also see it at the **`/art`** path of the same sandbox URL (`…/art`) — the generated-art gallery (#1262), which shows every tile they've made *even when it isn't placed in the game world yet*. Point them there when the work is "I made a tile" rather than "I changed the map."
+
+3. **Collect their reaction:**
+   - **Change requests** → make the edits, then re-run `node scripts/gds/sandbox-stage.js` and have them refresh the browser tab. Loop until they're happy.
+   - **Looks right** → proceed to `/builder-ship`. The ship gate sees the fresh staged marker and carries on to the main game. (If the marker went stale — the game files changed after staging — the ship stages again and pauses with the review URL; show it to the builder, then re-run.)
+
+4. **Useful sub-commands:**
+   - `node scripts/gds/sandbox-stage.js status` — is the sandbox current with the working tree, when was it last staged?
+   - `node scripts/gds/sandbox-stage.js url` — just the URL.
+
+## Constraints
+
+- **Box or local full clone.** A dev box stages to `sandbox-<login>`; a full local clone stages to `http://localhost:<port>`. The ONLY machine with no sandbox is a partial clone that lacks the game (`src/preview-server.js`) — there the script says so and exits.
+- **Named tunnel required (box only).** A quick-tunnel box has no sandbox hostname (ADR 0044); the script says so. The fix is operator-side (`BOX_NAMED_TUNNEL=1` + re-provision), not something to debug here. (Local previews have no tunnel and aren't affected.)
+- **On a dev box, the preview is the HOSTED `sandbox-<login>` URL — never localhost.** Get it from this skill (`node scripts/gds/sandbox-stage.js`) or `box-preview status`. Do **NOT** preview a box change with the Claude Code preview tools or `npm run preview`/`npm start`: those bind `http://localhost`, which the builder's own browser can't reach when the server is on a remote box — handing them a dead localhost link is the task-1443 footgun. (`sandbox-stage.js` now routes any box to the hosted URL and refuses to emit localhost; a box with no hostname gets a clear re-provision message, not a localhost link.) Localhost is correct ONLY on a laptop full clone.
+- **Never present the sandbox as prod.** No credits, no broadcast, nothing shipped — staging is review, `/builder-ship` is the decision. The local preview is private to the builder's own machine (not shareable).
+- If the preview won't come up healthy, point the builder at the logs — `box-preview logs` on a box, `node scripts/gds/local-preview.js logs` locally — rather than guessing.
+
+## Files this skill touches
+
+- Runs: `scripts/gds/sandbox-stage.js` (resolves box vs local; box → restarts `box-game-preview.service`; local → `scripts/gds/local-preview.js` + `local-preview-lib.js` (re)start `node src/preview-server.js`)
+- Reads: `/etc/otb/box.env` (a box's `BOX_PREVIEW_HOSTNAME`); `$OTB_PREVIEW_PORT` (local port, default 3100)
+- Writes: the staged marker in the OS temp dir (`otb-sandbox-staged.json`); locally, the preview pid/log in the OS temp dir (`otb-local-preview.{pid,log}`)

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

@@ -0,0 +1,46 @@
+---
+name: builder-start
+description: Start a Claude Code session by listing what tasks the builder can claim right now, filtered for parallel-safety against currently active claims across all builders. Triggers when the user says "what can I work on", "/builder-start", "show me tasks", "what's claimable", or at the start of a new session before doing other work.
+---
+
+**Script skill (authoritative).** The core action is `node scripts/gds/start.js [--widget]`. Run it and render its output verbatim — do not rebuild the table, reorder rows, or add a recap. The card is the summary.
+
+You are starting a working session on the Off the Boats project. Before any other work, you check the GDS to see what's claimable.
+
+## Background
+
+The GDS keeps a database of tasks tagged with `touches[]` — file/folder fingerprints that determine parallel-safety. The API computes "claimable for me right now" as: tasks in `ready` status, not blocked, with no `touches[]` overlap with any currently-active claim by any builder. `ready` itself is gated by **dependencies** ([ADR 0015](../../../docs/adr/<redacted>.md)): a task enters `ready` only once every task in its `dependencies[]` is `shipped`. So if a task you want isn't listed, the usual reason is "its deps haven't shipped yet" — surface that, don't offer to override.
+
+`start.js` produces a deterministic **card** (identity → quiet status line → holdings → a clean claimable table → next step), the same shape every session. It comes in two forms from the same data: an HTML widget (`--widget`) and a markdown fallback (default). Your job is to render it — not to rebuild or re-summarize it.
+
+## How to render it
+
+Delivery is now deterministic (task 1288). The **card-delivery hook** (`.claude/hooks/session-cards.js`, a UserPromptSubmit hook) runs `start.js` for you on a `/builder-start` (or "what can I work on") prompt and injects the **finished card + a one-step directive** into your context — a block that begins `[otb card — the builder start card below was pre-rendered …]`. A hook can't render UI or detect your tools itself (only you can), so the directive hands you both card forms and tells you exactly which to emit. The builder's **"render widgets" knob** (default ON; task 1279) is already resolved inside the payload — widgets off ⇒ markdown only, no HTML in play.
+
+1. **Normal path — follow the injected directive.** If that `[otb /builder-start …]` block is in your context this turn, just do what it says: call `show_widget` with the fenced HTML if you have the `mcp__visualize` tool (calling `mcp__visualize__read_me` once first, silently), otherwise output the fenced markdown **verbatim**. Render **once** — don't run `start.js` yourself, don't rebuild the table, don't add a recommendation or recap. That sameness is the feature (task 1273).
+
+2. **Fallback — no directive present** (hook disabled, an older checkout, or it failed silently). Run the script yourself, exactly as the hook would have:
+   - **If you have `show_widget`** (mcp__visualize): `node scripts/gds/start.js --widget`. Call `mcp__visualize__read_me` once this session (modules `["interactive","mockup"]`) if you haven't — silently. Then branch on stdout's **first non-whitespace character**: starts with `<` (HTML) → `show_widget` with `title: "builder_start_card"` and the stdout HTML **verbatim**; doesn't start with `<` (widgets OFF) → print stdout **verbatim** as a normal message (NOT a code fence — the feed needs to render the table).
+   - **No widget renderer** (raw terminal, cron, another client) → `node scripts/gds/start.js` and print its stdout **verbatim**.
+   - Either way, stderr may carry an `[otb-card]` **directive for you** (restates the verbatim rule) — follow it, **never** relay it; plus private one-liners (budget / next-stage) — relay *those* as a short note after the card.
+
+- If `start.js` prints **"no GDS session"**, the builder isn't signed in — route them by scenario: a **first-timer** on the project runs `/builder-setup` (one-time GitHub sign-in that also registers them); a **returning builder whose session went stale** runs `/builder-reauth` (the fast UI re-issue). `start.js` now prints both options; relay the one that fits, then retry.
+- (`--full` adds the detailed status widgets + worktree/context block; `--json` is the machine interface; `--hook` is the envelope the hook consumes — don't run these for the user unless asked.)
+
+## After rendering
+
+- The widget rows are **click-to-claim**: a click sends "Claim task N", which you handle by running `/builder-claim N` (the `builder-claim` skill). A typed number does the same.
+- **Don't claim automatically.** Wait for the user to pick — by clicking a row, giving a number, or saying "claim the top one". If they say they're **just exploring**, hold off entirely (the widget's "I'm just exploring" link sends exactly that).
+- Help them choose only when asked: shortest `Est.` for a quick win, higher `Reward` for more credit; the table is already ordered by priority (top = highest).
+
+## Constraints
+
+- **Don't compute parallel-safety yourself** — the API did it. If a task is in the card, it's claimable right now.
+- **Don't suggest tasks that aren't in the card.** If something they want is missing, it's not `ready`, it's blocked, or someone holds an overlapping claim — surface that, don't try to claim it anyway.
+- **Holding a claim already is fine.** The card lists what they hold as a calm fact (one builder can run parallel sessions) — don't treat it as an error or force a release.
+- **If nothing is claimable**, the card says so and links to `/blocker-review`.
+
+## Files this skill touches
+
+- Reads: `~/.config/otb/gds-session.json`
+- Calls: `/api/gds/me`, `/api/gds/tasks/claimable` (+ public progress/cost/recent/inbox/blockers for the status line)