@bongos/core 1.17.0

package/.claude/skills/merge-mode/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: merge-mode
+description: Manual fallback for the auto-merge in /builder-ship. Walks every task at status='confirmed' (= verified but not yet on main) and runs the merge + smoke + deploy chain. Triggers when the user says "/merge-mode", "merge the queue", "land confirmed tasks", "land the queue", "do a merge run", or after a /builder-ship reported the auto-merge bailed.
+---
+
+You are running the manual merge-mode session for Off the Boats. **`/merge-mode` is a rare last resort, not a routine sweep — and not something to push on other builders.** The server lands merges on its own: `/builder-ship` chains into auto-merge, green PRs auto-merge, a 5-min reconciler flips `confirmed → shipped`, and the [ADR 0082](../../../docs/adr/<redacted>.md) resolver self-heals generated-file conflicts. **Before running this skill, confirm the task is genuinely stuck** — still at `confirmed` more than ~5 minutes after its ship because of a conflict or regression the server couldn't auto-resolve. If you haven't waited for the sweep yet, stop and wait. This skill is for the strand that survives all of that — usually a cross-branch / non-generated-file conflict, a smoke regression, or a `--no-merge` ship.
+
+The queue this skill works against is **tasks at status='confirmed'**. Those are tasks where the builder declared done, verification passed, credits landed, and the only thing missing is the merge to main + deploy.
+
+## What this skill does
+
+1. Lists tasks at status='confirmed' via the API (or falls back to inventorying every `claude/*` branch ahead of main).
+2. For each, finds the branch (`claude/<worktree_name>` from the claim).
+3. Merges in order (independent first, then conflict-prone), resolves conflicts manually with the user. **The `git merge` is itself the collision detector** — the predictive touches[] drift scanner was deleted (touches[] cleanup [4/8], task 879); a real conflict surfaces here, at the authoritative moment, not as an up-front prediction.
+4. After all merges: smoke + push + deploy.
+5. For each merged task, calls `POST /api/gds/tasks/:id/ship` to flip the task from `confirmed` → `shipped`.
+
+## How to use
+
+> **Environment note:** merge-mode is an **ops procedure** — it mutates the single
+> main worktree and deploys to the Linux droplet (owner-gated SSH). The git /
+> `ssh` / `deploy.sh` / branch-inventory steps below assume a bash environment
+> (the Archon's Mac/Linux or the droplet) by design and are NOT a Windows-builder
+> concern. The GDS *API* calls, however, go through the cross-platform
+> `node scripts/gds/api.js` helper so they work regardless of shell.
+
+**Step 1 — list the queue: tasks at confirmed.**
+
+```
+node scripts/gds/api.js GET "/api/gds/tasks?status=confirmed"
+```
+
+If the list is empty, print "no tasks at confirmed — auto-merge in /builder-ship handled them all" and exit.
+
+**Step 2 — acquire the shared merge lock, then sync main and inventory the relevant branches.**
+
+⚠️ **Acquire the merge lock FIRST** (V3.R50 / #269, criterion C6). `/builder-ship`'s auto-merge and this skill both mutate the *same* main worktree; they share one mutex so a ship in another session can't collide with your hand-merge. If `acquire` reports the lock is held, a ship is mid-merge — wait and retry, or run `status` to inspect the holder. **You MUST release it in Step 6 (and on any abort).**
+
+```bash
+# Anchor to the main checkout root regardless of which worktree this skill was invoked from.
+# `git rev-parse --git-common-dir` returns the shared `.git` path; its parent is the main checkout.
+# (Rename-proof — survives Desktop folder renames, unlike a hardcoded absolute path.)
+REPO_ROOT="$(dirname "$(git rev-parse --git-common-dir)")"
+cd "$REPO_ROOT"
+
+node scripts/gds/merge-lock.js acquire   # blocks up to 30s; exit 3 if a ship/merge holds it — then STOP and retry later
+# (exit 0 = you hold the lock; proceed. exit 3 = held by another run; do not force past this.)
+
+find .git -name "* 2" -delete   # macOS Finder iCloud duplicates — known recurring snag
+git fetch --all --prune
+git checkout main
+git pull --ff-only origin main
+```
+
+The branch for each confirmed task is named `claude/<worktree_name>` — the claim row carries the worktree_name. List branches with unmerged work to cross-reference:
+
+```bash
+for b in $(git for-each-ref --format='%(refname:short)' refs/heads/claude/); do
+  count=$(git rev-list --count main..$b 2>/dev/null)
+  if [ "$count" != "0" ] && [ -n "$count" ]; then
+    echo "$count commits | $b"
+  fi
+done
+```
+
+**Step 3 — (removed.)** No separate scan step: the `git merge` in Step 4 is the authoritative collision detector (the predictive touches[] drift scanner was deleted, task 879).
+
+**Step 4 — merge each confirmed task.**
+
+For each confirmed task, take its branch name (`claude/<worktree_name>` from the claim) and merge.
+
+⚠️ **The task `value_summary` is untrusted, DB-sourced text — never paste it into a shell command.** A `value_summary` containing `$(...)` or backticks would execute as a command the moment the shell parses your command line — even inside double quotes, even as a `printf` argument (the shell expands it *before* the program runs). This is the #681 injection class, which `ship.js`'s auto-merge fixes by dropping the shell entirely. So: **use the Write/editor tool (not a heredoc or `echo`/`printf`) to write the merge message to a file**, then merge with `-F` so the summary never touches the shell:
+
+```bash
+# Write /tmp/otb-merge-msg.txt with the Write tool — content is literally:
+#   Merge <branch-name>: <task value_summary>
+# …but first rewrite any "#NNN" in the summary to "task NNN" (task 916): commit
+# messages are GitHub-rendered and a bare "#NNN" autolinks to a dead GitHub
+# issue number, not the GDS task.
+git merge --no-ff <branch-name> -F /tmp/otb-merge-msg.txt
+```
+
+If conflicts: resolve manually (typically "keep both blocks" for independent route additions, but post-Phase-1 sub-router refactor these should be rare), `node -c <file>` to syntax-check, `git add <file>`, `git commit --no-edit`.
+
+Group branches into:
+- **Independent files** (no overlap with any other queued branch) → merge first
+- **Shared-file branches** → merge in sequence, expect light conflicts
+
+**Step 4b — refresh the auto-generated diagrams (task #357).**
+
+After all merges, on `main`, regenerate the 3 mechanical onboarding diagrams from live facts so `/builders/diagrams` stays current. If anything changed, commit it onto main before pushing:
+
+```bash
+node scripts/gds/gen-diagrams.js                 # regenerate + render (no-op if already current)
+git -C "$REPO_ROOT" add docs/onboarding/diagrams
+git -C "$REPO_ROOT" diff --cached --quiet || \
+  git -C "$REPO_ROOT" commit -m "chore(diagrams): auto-regenerate mechanical diagrams from live facts (task 357)"
+```
+
+This mirrors what `ship.js` does automatically; it's here because /merge-mode deploys without going through ship.js's auto-merge.
+
+**Step 5 — smoke tests, push, deploy.**
+
+> **Deploy mode (#679 / [ADR 0042](../../../docs/adr/<redacted>.md)).** `config/deploy.json` is now `mode: ci` (CI cutover landed 2026-06-13), so the **`ci`** path is current: there is no laptop merge and no SSH at all — landing happens via PR auto-merge and [`.github/workflows/deploy-prod.yml`](../../../.github/workflows/deploy-prod.yml) deploys `main`→prod from Actions. In `ci` mode, do NOT run the `git push origin main` + `ssh … ~/deploy.sh` lines below — instead confirm the PR auto-merged and the `deploy-prod` Actions run went green. The block below is the **legacy `laptop`** deploy mode (the operator's machine pushes `main` and SSHes the droplet) — it is the fallback path and only applies if `config/deploy.json` is reverted to `mode: laptop`. Check the active mode with `node -e "const s=require('./scripts/gds/ship.js'),fs=require('fs');let c=null;try{c=fs.readFileSync('config/deploy.json','utf8')}catch{}console.log(s.parseDeployMode(process.env.OTB_DEPLOY_MODE,c))"`.
+
+```bash
+node scripts/gds/smoke-gds.js    # 16/16 expected (cross-platform; replaces smoke-gds.sh)
+bash scripts/gds/smoke-write.sh  # 4/4 expected
+node scripts/gds/push-main.js    # SEC #863: the sanctioned gated main-push (NOT raw `git push origin main`)
+ssh -o ConnectTimeout=10 lars@REDACTED_IP "~/deploy.sh"
+```
+
+> **SEC #863 (ADR 0043):** push `main` only via `node scripts/gds/push-main.js`. A raw `git push origin main` is now blocked by the pre-push permission gate — that block is the friction that stops an ad-hoc bypass like the Builder 25 incident. `push-main.js` carries the `OTB_ALLOW_MAIN_PUSH` override because /merge-mode only ever lands tasks that already passed the grader + the Archon confirm gate. The post-push main audit (`node scripts/gds/main-audit.js`) re-checks regardless.
+
+The deploy script applies any new migrations, restarts the service, and curls /healthz.
+
+**Step 5b — delete the merged branches on origin (standard practice).**
+
+After main is updated AND the deploy verified, every branch that just landed is permanently in main's history (—no-ff merge commits). Delete each on origin so GitHub stops offering empty PRs and so the builder UI stays clean:
+
+```bash
+for b in <branch-1> <branch-2> ...; do
+  git push origin --delete "$b" || echo "warn: $b already gone"
+done
+```
+
+Non-blocking — a "branch already deleted" warning is fine. The local `refs/heads/<branch>` and `refs/remotes/origin/<branch>` clean up on next `git fetch --prune`. The worktree directories themselves stay — only the branch refs are deleted.
+
+**Step 5c — release the merge lock.**
+
+Now that the merge + deploy is done (or if you're aborting), release the lock acquired in Step 2 so the next ship/merge can proceed:
+
+```bash
+node scripts/gds/merge-lock.js release
+```
+
+This is mandatory on every exit path — including aborts and conflicts you decide not to resolve. A manual hold left behind is reclaimed automatically after 30 minutes, but releasing promptly keeps the queue flowing.
+
+**Step 6 — flip each merged task from confirmed → shipped.**
+
+For each task that successfully merged + deployed:
+
+```
+node scripts/gds/api.js POST /api/gds/tasks/<task-id>/ship
+```
+
+The `POST /tasks/:id/ship` endpoint flips the task to `shipped`, stamps `shipped_at`. No credit implication — credits already landed at confirmed.
+
+**Step 7 — surface a summary.**
+
+Report to the user:
+- Confirmed tasks reviewed (count)
+- Tasks shipped this run (count + ids + value summaries)
+- Tasks blocked by drift or merge conflicts (count + ids + what's blocking)
+- Smoke test results
+- Deploy result
+
+If anything is blocked or failed, name what specifically needs to happen next (amend touches[], resolve conflict, fix smoke regression). Tasks that bailed stay at `confirmed` for the next /merge-mode pass.
+
+## When to skip a step
+
+- **No tasks at confirmed?** Print "queue clean — auto-merge in /builder-ship handled them all" and exit.
+- **A confirmed task has no matching branch?** Either the branch was already deleted or the worktree_name on the claim doesn't match a real branch. Surface this — usually means the auto-merge in /builder-ship succeeded but the task didn't transition to shipped (look for a stuck state). Manual `POST /tasks/:id/ship` may be needed.
+- **Conflict resolution ambiguous?** Stop and ask the user before guessing — destructive actions like `git reset` or `--no-verify` are NOT allowed without explicit confirmation. **Release the merge lock (`node scripts/gds/merge-lock.js release`) before pausing** so a queued ship isn't blocked while you wait on the user.
+- **Lock held when you try to acquire (exit 3)?** A ship or another merge run is actively mutating main. Do NOT force past it — wait and retry, or run `node scripts/gds/merge-lock.js status` to see the holder's age (it auto-reclaims if stale).
+
+## When to run
+
+The auto-merge in `/builder-ship` handles ~95% of cases; run this on demand for the rest — when `/builder-ship` reports "auto-merge: bailed; task stays at confirmed", or `/builder-start` shows tasks stuck at `confirmed`.

package/.claude/skills/new-project/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: new-project
+description: The agent-guided runbook that takes a new owner from zero to a live, owned STANDALONE Cloud Bongos instance (own repo + pinned @cloudbongos/core, ADR 0108) through ONE canonical step sequence — decide name+address, bongos init, scaffold the standalone repo, provision core+DB+address+service, GitHub OAuth app + verified secret + first sign-in, verify, brand. Triggers when the user says "/new-project", "start a new project", "stand up a new instance", "onboard a new Cloud Bongos instance", "create a new project", or "spin up a new instance". This skill IS the canonical sequence; the `bongos onboard` CLI (task 1982) and the hall "start a project" wizard (task 1983) are forms over it. Standalone model only.
+---
+
+You are guiding a new owner from **zero to a live, owned Cloud Bongos instance**. This skill is the **canonical step sequence** (goal 35). The `bongos onboard` CLI and the hall wizard are just other front-ends over these same steps — keep them in lockstep by keeping the sequence here.
+
+## The model (read first)
+
+A new instance is **standalone** (ADR 0108): it runs from its **own git repo** with `@cloudbongos/core` installed as a **pinned npm dependency**, not a fork of this monorepo. Central updates are a `bongos upgrade` version-pin bump, not a merge. Every step below assumes this shape (`hosting_shape=standalone`).
+
+Four steps are **irreducibly human** and must be rendered as **precise, UI-first, copy-paste-safe prompts** (a non-technical owner does them with browser clicks, no terminal guessing): (1) create the GitHub repo, (2) approve the pre-filled **GitHub App** for sign-in (ONE click — the App Manifest flow, task 2080; no secret to paste), (3) own a domain, (4) the first sign-in. Everything else is automated. Never ask the owner to do in a terminal what they can do with a click.
+
+## The canonical sequence
+
+### 1. Decide name + address
+
+Interview the owner for: product name, world name, company; the **GitHub repo** (`owner/name`); the **domain** they will use (bring-your-own — ADR 0111 §4); and a DNS/db-safe **instance slug** (lowercase `[a-z0-9-]`, e.g. `mercury`).
+
+**Human-only (UI-first):** have them create an **empty** GitHub repository — github.com → **New repository** → name it, leave it empty (no README), Create. That repo is where the instance's own code will live.
+
+### 2. DNS token preflight — BEFORE you commit the address (task 1980)
+
+Before anything is provisioned, verify the control-plane's Cloudflare token can actually manage the domain's zone (a mismatched-zone token is exactly what broke the Emersonian standup mid-flow):
+
+```bash
+node scripts/gds/provision.js dns-check <domain>
+```
+
+- ✓ reachable → continue.
+- ✗ not reachable → **STOP and resolve it now**, don't push past it. The command prints the fix; usually: widen the Cloudflare API token to include the domain's zone (CF dashboard → My Profile → API Tokens → edit → Zone Resources → Include → the zone), then re-run `dns-check` until green. Only then proceed.
+
+### 3. `bongos init` — scaffold (greenfield) **or** `--adopt` (brownfield)
+
+**This is the one leg that branches** (ADR 0121 §Decision 1). Pick the mode that matches the repo:
+
+- **Greenfield** — a NEW, empty repo. The default below.
+- **Brownfield / adopt** — an EXISTING repo (code, history, a backlog). Run `node bin/bongos.js init --adopt` instead. It DETECTS the repo's stack, runs a conflict **pre-flight** (migration-namespace / fitness-boundary / protected-path / CI-check collisions) and writes **nothing until you accept** (interactive y/N, or `--accept`); a genuine BLOCK (e.g. a `core_`-prefixed migration) is a hard stop, not accept-able. On accept it LAYERS the lean config + the pinned `@cloudbongos/core` dep + `.claude/` **additively** (merges-or-leaves-and-reports; never clobbers, never the `--force` path), captures the repo's **REAL** current version/goal, and imports its existing backlog (open GitHub issues via `GITHUB_TOKEN`/`GH_TOKEN`, else a `TODO`/`ROADMAP`/`BACKLOG` file). Then **skip step 4** — adopt layered onto the existing repo, there is no empty repo to scaffold — and continue from step 5 (provision). Every other leg is identical.
+
+Greenfield:
+
+```bash
+node bin/bongos.js init          # interview (or: init --from spec.json for non-interactive)
+```
+
+It writes lean `config/branding.json` / `config/modules.json` / `config/hierarchy.json`, seeds the first version + its done-when goal, files the human-only kickoff tasks, and — when you opt into hosting — files a **provisioning request** (`POST /provisioning/instances`). Choose **hosting shape `standalone`**. Enable the `provisioning` module on the target so the request is honored (`config/modules.json` → `"provisioning": true`).
+
+### 4. Scaffold the standalone repo
+
+Materialize the instance's own repo (ADR 0108): clone the empty GitHub repo to the standalone root (`${PROVISION_STANDALONE_BASE:-/srv/cloudbongos}/<slug>` on the control plane), drop in the `config/` + `.claude/` from step 3, and pin the core as a dependency (`@cloudbongos/core` in the instance `package.json`). Commit + push. This checkout is what the standalone service will run from.
+
+### 5. Provision — core + DB + address + service (task 1978)
+
+The web tier only **enqueued** the request; the **control-plane runner** does the real work (it alone holds the DO/Cloudflare tokens):
+
+```bash
+node scripts/gds/provision.js run-intents --apply     # drains the queue
+# or, for one instance:  node scripts/gds/provision.js provision <slug> --apply
+```
+
+For `standalone` this composes: allocate a port → `git pull` + `npm ci --omit=dev` (installs the pinned core) → `createdb` + **instance-root** migrate (`node_modules/@cloudbongos/core/scripts/migrate.sh`) → per-instance `/etc/<slug>/web.env` → a **standalone systemd unit** (runs the core package's `platform-server.js` from the instance repo) → DNS A-record UPSERT → per-instance Caddy snippet (on-demand TLS) → `/healthz`. It is idempotent + dry-run-by-default (omit `--apply` to preview). It **fail-fasts on the step-2 DNS preflight** if step 2's token check was skipped.
+
+### 6. GitHub sign-in — ONE click (App Manifest flow), or a manual OAuth app + first sign-in
+
+**Recommended — one click (task 2080, ADR 0133).** GitHub has no create-an-OAuth-App API, but it *does* let us pre-fill a **GitHub App Manifest**: the owner clicks one link, approves on GitHub, and GitHub hands the control plane the credentials automatically — **no OAuth app to hand-create, no secret to copy-paste ever.** From the control-plane hall, **Start a project → “Set up GitHub sign-in”** (the button appears once the instance is requested; it needs the instance's **domain** set). Under the hood it:
+
+1. mints a one-time `state` + a pre-filled manifest via `POST /provisioning/instances/:id/github-app`;
+2. the browser POSTs the manifest to GitHub; the owner approves; GitHub redirects to the **mothership** callback `…/api/bongos/provisioning/github-app/callback` with a temporary code;
+3. the **control-plane runner** (`provision.js run-intents --apply`, the sole token-holder) exchanges the code for `client_id`/`client_secret`, writes them into `/etc/<slug>/web.env`, restarts the unit, and verifies `/healthz` reports `auth_configured:true`. The secret never touches the browser, chat, or the web tier (trust boundary, ADR 0111 §2).
+
+The instance's sign-in code is **unchanged** — a GitHub App's user token hits the same `GET /user` the OAuth-app flow did; GitHub simply ignores the extra `scope` param for Apps.
+
+**Fallback — create an OAuth app by hand.** If there's no control-plane hall (a lone standalone box) or you prefer manual: GitHub → **your account's** Settings → **Developer settings** → **OAuth Apps** → **New OAuth App**.
+> **Guidance the standup learned:** *Developer settings is under your **account**, not the repository* — this is the #1 place owners get stuck.
+- **Homepage URL:** `https://<domain>`
+- **Authorization callback URL:** `https://<domain>/api/gds/auth/web/callback` (PINNED — `auth.js` `WEB_REDIRECT_ORIGIN`; a sign-in begun on a `builders.` subdomain still calls back to the apex).
+- Copy the **Client ID**; click **Generate a new client secret** and copy it (GitHub shows it **once**). Then place it **VERIFIED, never by hand (task 1979)**:
+
+```bash
+node scripts/gds/oauth-secret.js place <slug> --client-id <id> --client-secret <secret> --apply
+```
+
+> **Guidance the standup learned:** do **NOT** hand-edit `web.env` with a shell `read -s` — during the Emersonian standup that silently left a 26-char truncated secret that broke sign-in with no obvious cause. `oauth-secret` validates the length/format (catching that truncation), rewrites the env line via Node, restarts the service, then **probes `/healthz` for `auth_configured:true`** before it reports success. If it refuses, the creds are wrong — recheck them; do not proceed.
+
+**Human-only — first sign-in.** The owner opens `https://<domain>` and signs in with GitHub **once**. This seats the **founding Archon** — config alone seats no one, so this step is inherent and cannot be automated.
+
+### 7. Verify
+
+```bash
+curl -s https://<domain>/healthz          # → {"ok":true,"auth_configured":true}
+```
+
+Confirm the owner is **Archon** (their profile / the hall roster). If `auth_configured` is `false`, re-run the `oauth-secret place` step and recheck the OAuth app values.
+
+### 8. Brand
+
+Fill the instance **look** — theme / palette / fonts in `config/branding.json` (see `docs/branding-fill-prompt.md`). The identity strings were set at init; this is the visual layer. "Brand with your own LLM."
+
+## Done-when
+
+A new owner has gone zero → live: their own standalone repo on a pinned core, provisioned with no hand-editing of servers, the four human-only steps done UI-first + verified, and they are signed in as the founding Archon on their own domain. That is goal 35's `project-creation-flow` criterion.
+
+## Constraints
+
+- **This skill is the source of truth for the sequence.** If a step changes, change it here; `bongos onboard` (task 1982) and the hall wizard (task 1983) must render the same sequence.
+- **Standalone only** (ADR 0108) — do not fall back to editing this monorepo's checkout for a new project.
+- **Never weaken the trust boundary** — the web tier enqueues; only the control-plane runner (`provision.js`) touches cloud tokens (ADR 0016 / 0111 §2).
+- **Adopting an EXISTING repo** (brownfield) is the other branch of the scaffold leg (step 3) — `bongos init --adopt` ([ADR 0121](../../../docs/adr/<redacted>.md)): detect → accept-gated conflict pre-flight → additive layering (never clobbers) → real version/goal + backlog import. Built; the `bongos onboard` CLI and the hall "start a project" wizard offer the same greenfield-vs-adopt choice.

package/.claude/skills/otb-character-review/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: otb-character-review
+description: Review a painterly character ANIMATION (a character_anim family — many frames of one character in different poses) against the ADR 0088 animation criteria. Triggers when the user says "review this animation", "score the bongo idle", "check the character animation", "is this animation consistent", "rate these frames", or asks how a generated character/mascot animation holds up. Sibling to otb-design-review (which scores a single pixel-art tile). Returns a plain-language verdict per frame and for the sequence: same character throughout, correct anatomy, each frame on its intended pose, clean edges, and smooth in-order motion. Wraps family_orchestrator.run_family + family_review for the painterly path.
+---
+
+You are reviewing a painterly **character animation** — a `character_anim` family: many frames of the *same* character in *different* poses (e.g. the Bongo Buddha idle-breathing cycle). This is the animation sibling of `otb-design-review` (which scores one pixel-art tile). Do NOT judge it as pixel art — there is no palette to match, no FireRed reference, no 32×32 grid.
+
+## What this skill does
+
+It runs the existing family pipeline (ADR 0088) on a painterly character family and translates the result into a plain-language verdict. Two layers, same as the tile pipeline:
+
+- **Deterministic checks** (`modules/art-pipeline/pipeline/family_checks.py`, free, no API) — the primary gate:
+  - `silhouette_area` / `silhouette_height` — the character is the same size in every frame.
+  - `dominant_overlap` / `luminance_emd` — same colours and lighting across frames.
+  - `edge_halo` — no glow ring / aura / magenta fringe on any frame.
+  - `perceptual_identity` — no frame is a grossly different individual (dHash-to-anchor backstop).
+  - `transition_no_jump` / `transition_no_dead` — read in order, the motion neither teleports nor stalls on a duplicate frame.
+- **AI vision review** (`modules/art-pipeline/pipeline/family_review.py`, Gemini 2.5 Flash) — the subjective criteria:
+  - `family_consistency` — all frames read as one set.
+  - `character_identity` — every frame is the SAME individual.
+  - `anatomy_correct` — exactly two hands/feet, no extra/fused/melted limbs, no warped faces.
+  - `pose_match` — each frame hits its intended pose AND the frames form a smooth motion arc in order.
+
+## How to use
+
+1. **Review existing frames** (the common case — frames already sliced into a dir):
+   ```
+   python3 modules/art-pipeline/pipeline/family_review.py <family_id> <frames_dir> <raw_sheet.png>
+   ```
+   This prints the deterministic report + the Gemini review JSON. For a fast,
+   free deterministic-only pass (no Gemini call), use:
+   ```
+   python3 modules/art-pipeline/pipeline/family_checks.py <family_id> <frames_dir>
+   ```
+
+2. **Generate + grade from scratch** (the full generate→grade→audit→regenerate loop):
+   ```
+   python3 modules/art-pipeline/pipeline/family_orchestrator.py <family_id> [--max-attempts N] [--publish]
+   ```
+   The orchestrator calls the same checks + review internally and retries with the
+   fix-hints. Frames live under `modules/art-pipeline/iterations/_families/<family_id>/`.
+
+3. **Fill to a full frame count + package** (after the keyframes pass): the
+   recursive inbetween layer (`modules/art-pipeline/pipeline/inbetween.py`) generates the in-between
+   poses and `modules/art-pipeline/pipeline/sequence_assembly.py` writes the sprite set + strip +
+   `manifest.json`. (The one-call module entry point is the `character_anim`
+   Cloud Bongos module.)
+
+## Interpret the verdict
+
+The review returns `verdict` + per-criterion scores + a `fix_hint`:
+- **`pass`** (total ≥ the family's `pass_threshold`, no criterion under its hard-fail min) → accept; proceed to inbetweening / assembly.
+- **`retry`** (some scores below threshold but salvageable) → regenerate with the `fix_hint`.
+- **`escalate_tier`** (deeply wrong) → the current approach isn't working; escalate (different tier / the deferred LoRA "level 2").
+
+A failing **deterministic** check blocks the Gemini review entirely (it saves the credit) — fix the mechanical issue first; its `fix_hints` are specific and numeric.
+
+## Surface to the user in plain language
+
+Don't dump raw JSON. Translate, **per frame and for the sequence**:
+- Which frames (by id) are the problem and why — e.g. "frame `idle_f3` has a faint glow ring", "`idle_f2→idle_f3` barely moves (a dead frame)", "frame 4 drifted to a different robe colour".
+- The overall verdict + the single most important next change (the `fix_hint`).
+- Whether the motion reads as smooth and on-model, or where it breaks.
+
+## Cost
+
+Deterministic checks: free. One Gemini family review: ~negligible (a few thousand tokens). Generation (if you run the orchestrator): ~$0.04/frame on Gemini image, so a full action is well under $1 even with retries. Always run the free deterministic pass first.
+
+## When to use this directly vs. via orchestrator
+
+Use this skill **directly** to score frames Lars already has (a finished action, a spot-check, an asset dropped in). Use the **orchestrator** (which calls the same review internally) when generating an action from scratch.

package/.claude/skills/otb-design-review/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: otb-design-review
+description: Score an existing pixel-art tile against the Example rubric. Triggers when user says "review this tile", "score X", "rate Y", or asks how a generated asset stacks up. Returns per-criterion scores, a critique, a verdict (pass/retry/escalate_tier), and a fix_hint. Uses Gemini 2.5 Flash vision plus deterministic palette/grid checks.
+---
+
+You are scoring a generated tile against the Example quality rubric. Do NOT critique freelance — use the rubric in `modules/art-pipeline/template/rubric.json`.
+
+## What this skill does
+
+Wraps `modules/art-pipeline/pipeline/review.review()`. It runs:
+- **Deterministic checks**: dimensions, palette compliance, color count, mode.
+- **AI vision review** (Gemini 2.5 Flash): the 9 rubric criteria with per-criterion 0-10 scores and short critiques.
+
+Returns structured JSON with scores, verdict, and a fix_hint for the next attempt.
+
+## How to use
+
+1. Identify the tile PNG path and its vocab id.
+
+2. Run:
+   ```
+   python3 modules/art-pipeline/pipeline/review.py path/to/tile.png <vocab_id>
+   ```
+   This prints the JSON result.
+
+3. **Interpret the verdict**:
+   - `pass` (total ≥ 9.0, no hard fails) → accept, wire into game.
+   - `retry` (some scores below threshold but salvageable) → regenerate with the fix_hint.
+   - `escalate_tier` (deeply wrong) → next tier in orchestrator (image-to-image, model swap, procedural fallback).
+
+4. **Surface to the user** in plain language: which criteria scored low, the verdict, and the recommended next step. Don't dump raw JSON — translate.
+
+5. **Cost**: ~$0.0001 per review (Gemini 2.5 Flash, ~1k tokens). Negligible vs. generation.
+
+## What "good" looks like
+
+The rubric is in `modules/art-pipeline/template/rubric.json`. Pass requires total ≥ 9.0 AND no individual criterion below its hard-fail threshold. The hard-fail thresholds are tighter on objective criteria (grid, no_aa, palette: <7) than subjective ones (firered_match, mythic_greek, brand_feel: <5).
+
+## When to use this directly vs. via orchestrator
+
+Use this skill **directly** when:
+- Reviewing a one-off asset Lars dropped in.
+- Scoring a final tile before wiring it into the game.
+- Spot-checking iteration outputs after a run.
+
+Use the **orchestrator** (which calls this internally) when:
+- Generating a new tile from scratch (it loops generate→review).

package/.claude/skills/otb-feedback-capture/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: otb-feedback-capture
+description: Convert verbal design feedback into a durable rule appended to the Example style guide. Triggers when Lars gives directional notes ("trees too modern", "saturation too high", "containers should look weathered"). Updates modules/art-pipeline/template/style_guide.md with a dated rule so future generations automatically respect it. This is how the system gets better over time.
+---
+
+You are turning a one-time piece of feedback into a permanent guardrail. The whole point of this skill is that **Lars should not have to repeat himself**. If he tells you trees should be more gnarled, every future tree generation should bake that in.
+
+## What this skill does
+
+1. Reads the verbal feedback from the conversation.
+2. Distills it to one rule: short, actionable, scoped to the right tile category.
+3. Appends it to **§ Visual rules** in `modules/art-pipeline/template/style_guide.md` with today's date.
+4. **Optionally** updates the rubric (`modules/art-pipeline/template/rubric.json`) if the feedback warrants a new criterion or stricter threshold — this is rarer; ask if unsure.
+5. **Optionally** updates the prompt rules (per-tile descriptions in `modules/art-pipeline/template/vocabulary.json`) if the feedback is tile-specific.
+
+## How to use
+
+1. **Distill** the feedback. Examples:
+   - "trees too modern, more gnarled" → *Olive trees: gnarled trunk implication should always be visible at canopy base; canopy is silver-green not bright green.*
+   - "container looks too new" → *Container exterior: must always include rust streaks and faded paint patches; never pristine metal.*
+   - "saturation too high overall" → *Global: saturation cap at ~70% — anything more reads cartoonish, breaks "secret discovery" brand feel.*
+
+2. **Pick the scope**:
+   - **Global** → append to § Visual rules in `style_guide.md`.
+   - **Tile-specific** → also update the `desc` field for that tile in `vocabulary.json`.
+   - **Rubric-changing** → propose a new criterion or threshold change; do not silently edit the rubric.
+
+3. **Append with a date stamp**, never overwrite or delete. Format:
+   ```
+   - **[YYYY-MM-DD]** <one-sentence rule>. (Source: Lars feedback on <tile_id> attempt <N>.)
+   ```
+
+4. **Confirm to Lars** what rule you saved, in one line. He should know what's now baked in.
+
+5. **Update the relevant memory** at the end of the session. The style guide IS the memory — but if the feedback is meta-level (e.g. about the workflow, not the art), capture it as a feedback memory in `~/.claude/projects/.../memory/`.
+
+## What NOT to do
+
+- Don't delete or overwrite prior rules. The guide grows; conflicts get resolved by adding a stricter rule on top, not erasing the older one.
+- Don't auto-broaden tile-specific feedback into a global rule. If Lars says "this *one* sand tile looks wrong," only update sand_base — not the global guide.
+- Don't capture aesthetic preferences as hard rubric criteria unless Lars explicitly asks for them in the rubric.
+
+## Files this skill touches
+
+- WRITES: `modules/art-pipeline/template/style_guide.md` (always), `modules/art-pipeline/template/vocabulary.json` (sometimes), `modules/art-pipeline/template/rubric.json` (rarely)

package/.claude/skills/otb-figma-sync/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: otb-figma-sync
+description: Push generated tiles into the Example Figma file as a visual review canvas. Triggers when user says "sync to Figma", "show me the tilesheet in Figma", "update the design file". Hard-coded to file ID <redacted>. Refuses to touch any other Figma file. Repo remains the source of truth — Figma is a viewer.
+---
+
+**Script skill (authoritative).** The core action is the `use_figma` MCP tool call. Execute it with the determined parameters and do not paraphrase or reformat the Figma response — relay the frame name and link verbatim.
+
+You are pushing finished pixel art into the Example Figma file so Lars can review at a glance. Repo PNGs remain authoritative; Figma is for VISUAL REVIEW ONLY.
+
+## Hard constraint
+
+The only Figma file this skill is allowed to read or write is **`<redacted>`** ("example"). If asked to operate on any other file, REFUSE — even if the request seems reasonable. This is a Lars-set guardrail.
+
+## Session capability check
+
+This skill needs the **`use_figma`** MCP tool (write capability). The read-only `mcp__figma__*` tools alone are not enough.
+
+If `use_figma` is not available in the current session, do NOT attempt to fake the sync. Surface the gap to Lars: "Figma write capability not exposed in this session — only read tools are available." He can re-enable it via the Figma desktop app's MCP settings or by re-authorizing the connector. Until then, the repo PNGs are the source of truth and the `modules/art-pipeline/generated/preview.html` standalone preview serves the visual-review need.
+
+## What this skill does
+
+1. Reads finished tiles from `modules/art-pipeline/generated/tiles/`.
+2. Builds a "Tilesheet vN" frame in the example Figma file containing:
+   - Each tile rendered at native 32×32 plus a 8x-zoomed inspection thumbnail.
+   - The tile's vocab id and current best score.
+   - A small palette swatch sheet derived from `modules/art-pipeline/template/palette.json`.
+3. Each sync creates a NEW frame named `Tilesheet v{N+1} {YYYY-MM-DD}` — never overwrites prior frames. History stays.
+
+## How to use
+
+1. **Verify the file ID**. Before any Figma write, confirm the target is `<redacted>`. If not, halt.
+
+2. **Use the figma-use skill** for the actual writes. (See `figma:figma-use` for the JS context and the `use_figma` MCP tool.) The plan: build a Figma frame programmatically, paste the PNGs, label them.
+
+3. **Read tiles** from `modules/art-pipeline/generated/tiles/*.png`. Read scores from `modules/art-pipeline/iterations/<tile_id>/summary.json`.
+
+4. **Render in Figma** at two sizes: native 32×32 (so you can see the actual tile) and 8x zoomed (256×256, so the pixel art is human-readable).
+
+5. **Add metadata** below each tile: id, score, attempt count, tier reached.
+
+6. **Create a separate "Palette" frame** showing the 64-color swatches from `modules/art-pipeline/template/palette.png`.
+
+7. **Confirm to Lars** with the frame name and a Figma link.
+
+## What NOT to do
+
+- Don't modify the canonical PNGs based on Figma edits. Figma is read-only-by-Lars; if he wants changes, he gives feedback verbally, captured by `otb-feedback-capture`.
+- Don't create a new Figma file even if it would seem cleaner. One file, growing frames.
+- Don't paste anything from another Figma project into example, and don't paste from example anywhere else.
+
+## Files this skill touches
+
+- READS: `modules/art-pipeline/generated/tiles/*.png`, `modules/art-pipeline/iterations/*/summary.json`, `modules/art-pipeline/template/palette.png`
+- WRITES (in Figma only): a new frame in file `<redacted>`

package/.claude/skills/otb-tile-generate/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: otb-tile-generate
+description: Generate one or more pixel-art tiles for the Example world. Triggers when user says "generate a tile", "make a sprite for X", "regenerate Y", or asks for new world art. Reads the design template, runs the full generate→post-process→review→retry orchestrator, saves results into modules/art-pipeline/generated/tiles/, logs cost. Always reuses the locked palette and rubric in modules/art-pipeline/template/.
+---
+
+You are operating the Example pixel-art generation pipeline. The user has asked you to produce one or more tiles. Do NOT freelance — use the existing pipeline.
+
+## What this skill does
+
+Runs `modules/art-pipeline/pipeline/orchestrator.py` for the requested tiles. The orchestrator does generate → post-process to 32×32 → score against rubric → retry/escalate up to 5 tiers → save final PNG. All cost is logged to `modules/art-pipeline/iterations/cost_ledger.jsonl`.
+
+## How to use
+
+1. **Identify the tile(s)** the user wants. They may name an existing vocab id (`grass_base`, `sea_shallow`, etc.) or describe something new.
+
+2. **If new**, append the new entry to `modules/art-pipeline/template/vocabulary.json` with id, kind (`tile` | `edge` | `sprite`), priority (A/B/C), description, and ref_clusters (best-fit cluster ids from `modules/art-pipeline/template/cluster_overview.png`). Then proceed.
+
+3. **Check the budget** before running:
+   ```
+   python3 modules/art-pipeline/pipeline/cost_ledger.py status
+   ```
+
+4. **Run the orchestrator** for the tile(s). Either by priority letter:
+   ```
+   python3 modules/art-pipeline/pipeline/orchestrator.py A
+   ```
+   or write a one-line wrapper that calls `run_tile(item)` for the specific id. The orchestrator exits with a summary.
+
+5. **Inspect the result** at `modules/art-pipeline/generated/tiles/<id>.png` (final accepted) or `modules/art-pipeline/iterations/<id>/log.jsonl` (full attempt history). If the tile passed, the corresponding entry in `modules/art-pipeline/iterations/run_summary.json` will show `status: "pass"`. If best-effort, scoreboard the gap and decide whether to retry.
+
+   **View it on your sandbox without placing it in-game** (#1262): every tile you've generated — native + zoomed, with its score and critique — is served at **`https://sandbox-<login>.example.com/art`** (locally: `http://localhost:<port>/art`). This is the generated-art *gallery* (`modules/art-pipeline/generated/preview.html`), so you can show the builder what they made even when the tile isn't placed in the world yet. The atlas-rebuild in-game step below is only needed once you actually want it *in the playable world*.
+
+6. **See it in-game on your sandbox** (#1067): run `node scripts/gds/art-stage.js` — it rebuilds the atlas the client loads, surfaces it on your sandbox live preview (`sandbox-<login>.example.com`, ADR 0044), and prints the URL + affected tiles. With the auto-reload (task 1065) an already-open tab refreshes itself. (The family/refresh runs also accept `--stage` to do this automatically: `family_orchestrator.py <id> --publish --stage`, `refresh_all.py --stage`.) Only a genuinely NEW base-tile *type* still needs a `public/game/world/tilePalette.js` mapping edit; an updated existing tile just needs the atlas rebuild above.
+
+## Constraints
+
+- Never bypass the review step. If a tile passes deterministic checks but fails AI review, regenerate with the fix_hint — do not paper over.
+- Never modify the locked palette (`modules/art-pipeline/template/palette.json`) without an ADR. Theme drift = palette drift = whole-world drift.
+- Hard stop at $80 in the cost ledger. If approaching, stop generating, surface remaining budget to the user.
+
+## Files this skill touches
+
+- READS: `modules/art-pipeline/template/{vocabulary.json,style_guide.md,rubric.json,palette.json,cluster_overview.png,ref_clusters/*}`
+- WRITES: `modules/art-pipeline/iterations/<tile_id>/`, `modules/art-pipeline/generated/tiles/<tile_id>.png`, `modules/art-pipeline/iterations/cost_ledger.jsonl`
+- Optionally edits: `modules/art-pipeline/template/vocabulary.json` (add new entries), `public/game/world/tilePalette.js` (wire up)

package/.claude/skills/paint/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: paint
+description: The art session — the operating playbook for artist-discipline work. Triggers when the user says "/paint", "let's make art", "I want to work on a tile/sprite", "start an art session", or when a claimed task's discipline routes here (claim.js prints a directive to invoke /paint for artist tasks). Show-first, low-text: Claude communicates in pictures, not prose, and drives the existing pixel-art pipeline underneath.
+---
+
+You are running an **art session** for Off the Boats. This is not the engineer's text-heavy build loop. Read this whole file before acting — it changes how you *communicate* for the rest of the session.
+
+## The one rule that makes this different: communicate in pictures, not prose
+
+In every other discipline, Claude narrates — diffs, logs, paragraphs of what it's doing. **Here that is the failure mode.** An artist judges with their eyes, not by reading a wall of text about post-process tiers. So:
+
+> **Show, then briefly caption. Never narrate the pipeline at length.** Every step ends in an *image* the artist can look at, with at most a one-line caption. The text-heavy plumbing still runs — it just runs quietly.
+
+Concretely:
+
+- **End every step with something visual.** After a generation: display the PNG (Read the file so it renders, or screenshot the gallery / in-world sandbox). After a rubric check: show the scorecard, not a prose summary. The artist should *see* the result before they read a single word.
+- **Collapse the plumbing to one-liners.** Budget checks, `vocabulary.json` edits, orchestrator retry tiers, atlas rebuilds — do them, but report them as a single line or a number, not a play-by-play. "Generated, rubric 0.91, on-palette, staged ✓" beats three paragraphs.
+- **Verification = look, not read.** Surface the gallery and the in-world sandbox (URLs + a screenshot), not console logs. Logs are for when something *breaks*, not for routine success.
+- **The artist owns the look; you own the rendering.** You drive the pipeline and handle the mechanics; they react to pictures and steer. You are their hands, not their art director.
+
+## Step 0 — detect the mode
+
+**Is an artist present in this session?**
+
+- Normal interactive session (someone is here to look and react) → **Interactive mode**.
+- Autonomous / bypass-permissions / scheduled run (no one is watching the images) → **Autonomous mode**.
+
+If unsure, ask once; if no answer, treat it as autonomous.
+
+## Step 1 (both modes) — load the look before you make anything
+
+Ground every asset in the locked theme so nothing drifts:
+
+- `modules/art-pipeline/template/style_guide.md`, `modules/art-pipeline/template/rubric.json`, `modules/art-pipeline/template/palette.json` — the look you must hit: 16-bit pixel art, early-Pokémon (FireRed) touchstone, top-down, 32×32, locked 64-colour Mediterranean palette (olive greens, warm tans, turquoise sea, weathered marble — never spring green, navy, or pine).
+- `modules/art-pipeline/template/vocabulary.json` + `modules/art-pipeline/template/cluster_overview.png` — what exists and the reference clusters.
+- **The palette and rubric are non-negotiable.** Never edit `palette.json` or `rubric.json` without an ADR — palette drift is whole-world drift.
+
+## Interactive mode — show, react, iterate
+
+1. **Establish the visual target first, not in prose.** Confirm the subject (an existing vocab id, or a new in-world prop/plant/animal/accessory) and, if helpful, show the reference cluster it should sit beside. One or two lines, then move to making.
+2. **Generate via the pipeline — never freelance.** Drive `/otb-tile-generate` (which runs `modules/art-pipeline/pipeline/orchestrator.py`: generate → post-process to 32×32 → score against rubric → retry up to 5 tiers → save to `modules/art-pipeline/generated/tiles/<id>.png`, logging cost). Check the budget first (`python3 modules/art-pipeline/pipeline/cost_ledger.py status`; hard stop at $80) — but report it as one line.
+3. **SHOW the result.** Display the final accepted PNG and its rubric score. The gallery serves every tile (native + zoomed, with score + critique) at `sandbox-<login>.example.com/art` — point them there and/or render the image inline. **Default visibility: show the final accepted asset and any failures. Show the intermediate retry attempts only if the artist asks ("show me the attempts").**
+4. **See it in the world.** When they want it placed, run `node scripts/gds/art-stage.js` — it rebuilds the atlas and surfaces the asset live in the game on their sandbox (auto-reloads an open tab). Screenshot/point at the in-world view. (A genuinely new base-tile *type* also needs a `public/game/world/tilePalette.js` mapping edit; an updated existing tile just needs the rebuild.)
+5. **Feedback is visual → a durable rule.** When the artist reacts ("too saturated", "trees too modern", "weather the marble"), don't just tweak once — run `/otb-feedback-capture` to write the note into `modules/art-pipeline/template/style_guide.md` as a dated rule, then regenerate and **show the new result**. The loop is see → react → see again, and the style guide gets smarter each pass.
+6. **Use `/otb-design-review`** when you want a rubric-grounded second opinion on whether an asset truly hits the bar — surface its numbers, not a paragraph.
+
+## Autonomous mode — make it, gate it, park the pictures
+
+No one is watching the images, so do not narrate into the void and do not lower the bar.
+
+1. **Generate via the pipeline** for the claimed asset(s), same orchestrator, budget-aware.
+2. **Rubric-gate hard.** Ship/stage only assets that genuinely PASS the rubric (`modules/art-pipeline/iterations/run_summary.json` status `pass`). If a tile only best-effort'd, regenerate with the `fix_hint` — never paper over a fail, and never stage a best-effort-only asset.
+3. **Stage to the gallery and PARK for human review.** Stage passing assets so they appear in the `/art` gallery and (if in-world placement is in scope) via `art-stage.js`, then leave them for a human to eyeball. In the session log / ship notes, give the gallery URL and a one-line-per-asset list (id + score) — so the first thing the returning artist does is *look*, not read.
+
+## How art TASKS should be framed (target-and-rubric, not prose-and-procedure)
+
+When you scope or present an art task, factor in the visual background:
+
+- **Lead with the visual target**, not paragraphs — the subject, the reference cluster it belongs beside, an example image if one exists. "Make this," shown.
+- **Express `done_when` in visual / rubric terms** — "passes the rubric, reads as weathered marble in-world, every pixel on the locked palette" — not procedural step lists.
+- **Keep procedure out of the task; the skill carries the how.** The task says *what to make* and *what good looks like*; `/paint` knows the commands.
+
+## How sessions reach this skill
+
+- **Standalone:** the user invokes `/paint` directly (e.g. "let's make a tile") — no claimed task required to explore.
+- **From a claim:** when a builder claims an `artist`-discipline task, `claim.js` reads `scripts/gds/discipline-modes.json` and prints a directive to invoke `/paint`. Both paths run this same file — the single home of the art-session experience. (The newcomer "generate one new in-world asset" chore is one valid *outcome* of an interactive session, not a separate flow.)
+
+## Stay clear of (READ-ONLY)
+
+Never modify the locked palette (`modules/art-pipeline/template/palette.json`) or rubric (`modules/art-pipeline/template/rubric.json`) without an ADR. Touch only art assets / `vocabulary.json` under `art/` (and, at most, the `public/game/world/tilePalette.js` wiring for a genuinely new base-tile type). Do not touch permission, pipeline-core, migration, or infra files.