@bongos/core 1.17.0

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

@@ -0,0 +1,152 @@
+# Recipe — per-builder dev box lifecycle (provision · auto-suspend · reclaim)
+
+> **Task [#598](https://example.com/builders#/task/598) · [ADR 0031](../adr/<redacted>.md) §2/§5/§9.3.** This is the operator guide for the per-builder DigitalOcean dev boxes. The code ships in the repo; **going live is a deliberate, money-spending operator action** (like `provision-staging.sh`) — nothing here runs until you set `DO_API_TOKEN` and pass `--apply`.
+
+## The shape
+
+Each builder gets **one** box (ADR 0031 §2). Its lifecycle is a small state machine tracked in the `builder_boxes` table:
+
+```
+                  idle > BOX_IDLE_MINUTES (auto, every 15m)      task 804:
+none ─provision─▶ active ──────────────────────────────▶ destroyed   destroys
+                   ▲  │                                    ▲          droplet
+        wake(manual) │  park(manual)                       │          + snapshot
+                   │  ▼                                    │
+                  parked ── parked > BOX_DORMANT_DAYS ──────┘
+                            (auto, daily)
+```
+
+- **provision** — create + boot a droplet running the [#596](https://example.com/builders#/task/596) devcontainer. **Rank-gated.**
+- **idle deprovision** (auto, every 15 min) — when an `active` box is idle > `BOX_IDLE_MINUTES`, **destroy the droplet AND its snapshot** ([#804](https://example.com/builders#/task/804)). Compute billing stops; nothing is kept. **Not reversible** — the next connect re-provisions a fresh box, and any uncommitted work on the old box is lost (spike [#837](https://example.com/builders#/task/837)).
+- **park** (manual Archon CLI only) — snapshot the droplet then **destroy** it. A powered-off DO droplet still bills; only a destroyed one stops. The snapshot (~$0.30/mo) is the cheap residual you can `wake` from. **No longer automatic** — the idle sweep deprovisions instead of parking ([#804](https://example.com/builders#/task/804)).
+- **wake** (manual, on demand) — recreate the droplet from its snapshot. New IP; the `hostname` is repointed via `BOX_DNS_HOOK`.
+- **dormant reclaim** (auto, daily) — destroy the snapshot of a box `parked` > `BOX_DORMANT_DAYS`. Since idle no longer parks, this only catches boxes an Archon **manually** parked.
+
+### How "idle" is detected
+
+The idle sweep **deprovisions** a box when its `last_activity_at` (else `active_since`) is older than `BOX_IDLE_MINUTES` **and** `claude_active` is not true. Both signals are set by **`infra/box-heartbeat.sh`**, which runs **inside the box** every ~5 min and POSTs `/api/gds/box/heartbeat` *only while the box is in use* — an interactive login session, an established SSH connection, an **open browser terminal** (ttyd websocket, [#1161](https://example.com/builders#/task/1161)), or non-trivial CPU load. Silence = the sweep is free to destroy it.
+
+> ⚠️ **The idle sweep's correctness depends on the box-side heartbeat reaching the server.** If it isn't pinging — no GDS token on the box yet, a pre-[#1161](https://example.com/builders#/task/1161) script that can't see a browser terminal, or the cron not installed — `last_activity_at` never advances and the sweep falls back to `active_since`, i.e. it measures **uptime**, not activity, and will **destroy** a box someone is actively using. Because the idle path is now a full deprovision (no park to wake from), that wrongly-reaped box also loses uncommitted work (spike [#837](https://example.com/builders#/task/837)).
+>
+> **Live mitigation (2026-06-16):** `BOX_IDLE_MINUTES` is raised to **120** in `/etc/example/box.env` as a soak margin until [#1161](https://example.com/builders#/task/1161)'s browser-terminal heartbeat is verified on a newcomer box; lower it back toward the 10-min default once that's proven.
+
+Two sweeps automate the middle (both mirror `stale-claim-release` — dry-run first, idempotent, capped):
+
+| Sweep | Cadence | What it does | Threshold |
+|---|---|---|---|
+| `box-idle-suspend` | every 15 min | **deprovision** `active` boxes with no activity — destroy droplet **and** snapshot ([#804](https://example.com/builders#/task/804)); not a park | `BOX_IDLE_MINUTES` (default 10; **currently 120 live**) |
+| `box-dormant-reclaim` | daily | destroy the snapshot of long-`parked` boxes (pings builder). Since idle no longer parks, only catches **manual** Archon parks | `BOX_DORMANT_DAYS` (14) |
+
+## Why a self-built sweep (not Coder)
+
+ADR 0031 §9.3, resolved 2026-06-04: Coder needs an always-on control-plane droplet (~$12–24/mo fixed) + ops; a self-built sweep has ≈ $0 fixed cost and rides the existing sweep/timer pattern. See the ADR for the full rationale. (The original sweep snapshotted-and-parked idle boxes; [#804](https://example.com/builders#/task/804) simplified the idle path to a direct deprovision — the snapshot/wake machinery now serves only the manual `park`/`wake` commands.)
+
+## The CLI — `node scripts/gds/box.js`
+
+**Dry-run is the default. Nothing touches DigitalOcean or the DB without `--apply`.** Run any command once without `--apply` to see the plan.
+
+```bash
+node scripts/gds/box.js status                  # roster + cost (read-only)
+node scripts/gds/box.js provision <login|id>    # plan a provision
+node scripts/gds/box.js provision <login|id> --apply
+node scripts/gds/box.js park   <login|id> --apply
+node scripts/gds/box.js wake   <login|id> --apply
+node scripts/gds/box.js deprovision <login|id> --apply
+node scripts/gds/box.js sweep-idle              # plan; add --apply to act
+node scripts/gds/box.js sweep-dormant           # plan; add --apply to act
+node scripts/gds/box.js reconcile-drift         # DO⇄DB drift; add --apply to act
+```
+
+`<builder>` is a GitHub login or a numeric builder id.
+
+### Drift reconcile — `reconcile-drift` (task [#1289](https://example.com/builders#/task/1289), [ADR 0071](../adr/<redacted>.md))
+
+The teardown is now **confirm-before-destroyed**: `deprovision` only marks a box `destroyed` AFTER DigitalOcean confirms the droplet is deleted (idempotent + retried). A delete that genuinely fails parks the box at `state='error'` with `droplet_id` preserved and **throws** — it never silently leaves a running droplet behind a `destroyed` row (the old "zombie" bug).
+
+`reconcile-drift` is the backstop. It lists the real fleet droplets (a live read — needs `DO_API_TOKEN`, present in `box.env`) and reconciles against the GDS rows **both ways**:
+
+- **Zombie** — a droplet no live box row claims → force-delete the droplet + its tunnel/DNS.
+- **Ghost** — a live row whose `droplet_id` vanished from DO → mark it `destroyed`.
+
+A droplet younger than 30 min is never killed (it may be a provision in flight). It runs hourly on the control plane via `box-drift-reconcile.timer` (see *Going live* below). Run it by hand (dry-run first) any time you suspect drift:
+
+```bash
+node scripts/gds/box.js reconcile-drift          # show the plan
+node scripts/gds/box.js reconcile-drift --apply  # repair
+```
+
+### Rank gate (ADR 0016 trust boundary)
+
+`provision` reads the builder's **live DB rank** (the same value `requireRank` reads — uncacheable, server-side) and refuses below `BOX_PROVISION_MIN_RANK`. Default floor is `xenos`: per ADR 0031 §5(b) even an onboarded newcomer gets an org-funded **starter** box. The **scope** differs by rank, not the right to a box:
+
+- **xenos → `scope='starter'`** — the box is tagged for the scoped surface [#600](https://example.com/builders#/task/600) will enforce.
+- **metic / archon → `scope='full'`** — full private-repo access (also [#600](https://example.com/builders#/task/600)).
+
+Raise the floor (e.g. boxes for Metic+ only) by setting `BOX_PROVISION_MIN_RANK=metic`.
+
+## Config (environment)
+
+Put these in `/etc/example/box.env` (chmod 600 — **secrets never go in the repo**, [ADR 0022](../adr/0022-secrets-policy.md)). The systemd units load it via `EnvironmentFile=`.
+
+| Var | Default | Meaning |
+|---|---|---|
+| `DO_API_TOKEN` | — | DigitalOcean API token. **Required for `--apply`**; absent ⇒ live calls throw clearly. |
+| `BOX_PROVISION_MIN_RANK` | `xenos` | provisioning rank floor |
+| `BOX_REGION` | `nyc3` | droplet region |
+| `BOX_SIZE` | `s-2vcpu-4gb` | droplet size (4 GB floor — the devcontainer sets a 4 GB Node heap) |
+| `BOX_BASE_IMAGE` | `ubuntu-24-04-x64` | first-provision base image (cloud-init installs Docker + the devcontainer) |
+| `BOX_IDLE_MINUTES` | `10` | idle-**deprovision** threshold (minutes). **Currently overridden to `120` live** as a soak margin — see "How idle is detected". |
+| `BOX_DORMANT_DAYS` | `14` | dormant-reclaim threshold |
+| `BOX_SSH_KEY_IDS` | — | comma-list of DO SSH key ids/fingerprints to inject (so you can SSH in) |
+| `BOX_REPO_URL` | — | git URL the cloud-init clones into `/workspace`. The scoped **credential** is [#600](https://example.com/builders#/task/600); no identity is hardcoded. |
+| `BOX_DNS_HOOK` | — | optional shell command run on provision/wake with `BOX_HOSTNAME`/`BOX_IP` in env, to repoint the per-builder hostname |
+| `BOX_DNS_ZONE` | `dev.example.com` | the per-builder hostname zone (`box-<login>.<zone>`) |
+| `BOX_TAG` | `otb-builder-box` | DO tag applied to every box droplet |
+
+## Cost (Criterion C1 / cost)
+
+A box accrues compute cost **only while `active`**. At park/deprovision the CLI computes `active hours × the size's hourly rate` and writes it to both the `box_events` ledger and `cost_log` (category `compute`, builder-attributed) — so the public status dashboard's per-builder split sees real box spend. `box.js status` prints the active monthly run-rate + total spent. The **rebill to drachmae/earnings** (org-funded starter → self-fund) is a separate task, [#602](https://example.com/builders#/task/602).
+
+## Going live (one-time operator steps)
+
+These spend money and are intentionally manual.
+
+> **Hardware-verified end-to-end (2026-06-06, [#720](https://example.com/builders#/task/720)).** The lane now boots a *usable* box: auto-provision by draining the intent queue (`box.js run-intents` / `box-intent-runner.timer`), wake-on-connect from snapshot via `POST /box/ensure`, and SSH connect with the injected key. **`box-intent-runner.timer` is installed + enabled on the control plane as of [#720](https://example.com/builders#/task/720).** That run also found **[#724](https://example.com/builders#/task/724)**: the cloud-init template carried non-ASCII characters (em-dash, §) that cloud-init's strict YAML loader silently rejected — so *every* box before [#724](https://example.com/builders#/task/724) (including the [#699](https://example.com/builders#/task/699) lifecycle test) booted as a bare Ubuntu image with no devcontainer. **Keep `infra/builder-box-cloud-init.yaml` ASCII-only** (scan with `LC_ALL=C grep -nP '[^\x00-\x7f]' infra/builder-box-cloud-init.yaml`) and assert `cloud-init status` is `done` (not `degraded`) on the box after any provision change. Still deferred to **[#725](https://example.com/builders#/task/725)** (needs `BOX_SOURCE_*` GitHub tokens): the rank-gated source-fetch ([#600](https://example.com/builders#/task/600)) leg, full RC pairing, the fresh-account dry-run, plus the `box-source-fetch.sh` `HOME`-unbound fix. The idle/dormant sweeps are now LIVE — wired on the control plane 2026-06-15 ([#1101](https://example.com/builders#/task/1101)); they depend on the box-heartbeat, which needs the source clone (leg 1).
+
+> **Source + DNS verified (2026-06-06, [#725](https://example.com/builders#/task/725)).** **Leg 1 ✅** — `BOX_SOURCE_*` is wired on the **web** tier via `/etc/example/web-source.env` (a systemd drop-in `EnvironmentFile`, deliberately separate from `box.env` so the internet-facing web process never holds `DO_API_TOKEN`); `GET /box/source-access` issues a rank-scoped credential and the box clones into `/workspace` with the credential **scrubbed from `.git/config`**. **[#599](https://example.com/builders#/task/599) hostname cutover ✅ DONE** — in `box.env`: `CLOUDFLARE_API_TOKEN` (Zone:DNS:Edit, IP-locked to the droplet) + `BOX_DNS_HOOK=/home/lars/example/infra/box-dns-cloudflare.sh`; `box.js` runs it on every provision/wake so `box-<login>.dev.example.com` tracks the box IP (verified live: a park→wake gave a new IP and DNS auto-updated with no manual step; SSH via the hostname works). **The hook forces `curl -4`** — the control-plane droplet has IPv6 egress that would otherwise bypass an IPv4 token allow-list. Gotcha: a Cloudflare token IP-locked to the droplet's IPv4 returns "Invalid API Token" from `/user/tokens/verify` (and from any IPv6-sourced call) — test against the real op (`GET /zones`), not the verify endpoint, especially for account-scoped `cfat_`-prefixed tokens. Still partial: leg 5 (RC pairing needs a `claude` login on the box) + leg 6 (fresh-account needs a 2nd GitHub account). **DNS reliability hardened ([#1180](https://example.com/builders#/task/1180), 2026-06-16):** the hook now RETRIES every Cloudflare call with backoff — a transient auth blip during the provision call-burst used to leave the A record pinned at the prior (now-dead) IP while reporting a misleading "zone not found"; it now self-heals and, on a genuine failure, surfaces the real CF error code. `runDnsHook` no longer swallows a hook failure (it records a `box_events` `error` row and flags the box DNS-stale instead of logging a clean "✓ active"). The browser terminal is independent of this record (it rides the outbound tunnel). _(Root cause: @kingaonline's Claude Desktop hit "handshake timeout" SSHing to a hostname pinned at a dead IP.)_ **DNS teardown refined ([idea 309](https://example.com/builders#/idea/309) → task [#1234](https://example.com/builders#/task/1234)):** on deprovision `deprovisionOne` **repoints** the A record to a non-routable blackhole sentinel (`192.0.2.1`, TEST-NET-1 / RFC 5737) via `runDnsHookBlackhole` instead of **deleting** it. 1180 originally deleted the record on teardown so it couldn't dangle at a recycled DO IP — but delete-then-recreate across a reap→rebuild opened a window where the name returned `NXDOMAIN`, which resolvers negative-cache for the zone's SOA neg-TTL (~30 min on the Cloudflare `example.com` zone, not builder-editable); a client that queried mid-gap (e.g. an open Claude Desktop) then kept getting `ENOTFOUND` long after the box was back. A record that always resolves (to a guaranteed-dead sentinel) has nothing to negative-cache, yet still can't dangle at a recycled IP; the next provision/wake `PUT`s it straight to the live IP at the 60s record TTL, no gap. (Lowering the neg-TTL — the other lever floated in idea 309 — isn't used: Cloudflare's per-zone SOA neg-TTL isn't builder/API-editable, and the repoint makes it moot.) The hook's `BOX_DNS_DELETE=1` / `--delete` mode is retained for **manual** operator cleanup.
+
+1. **Token + config.** Create `/etc/example/box.env` (chmod 600) with at least `DO_API_TOKEN` and `BOX_SSH_KEY_IDS`. Apply migration 067 on the prod DB (`bash scripts/migrate.sh`).
+   > **`DO_API_TOKEN` must carry `tag:create` scope.** The first 2026-06-04 hardware run failed with `DO POST /droplets … missing the required permission tag:create` (the CLI applies `BOX_TAG` to every box). Use a **Full-Access** token, or a custom token that includes **tag write** alongside droplet + snapshot read/write.
+   > **Hardware-verified (2026-06-04, [#699](https://example.com/builders#/task/699)):** the full `provision → park → wake → deprovision` cycle has run on real DigitalOcean droplets (`box_events` ledger). Still unverified on hardware: the rank-gated source-fetch ([#600](https://example.com/builders#/task/600)) leg and the live Claude Desktop connect.
+2. **Try one box in dry-run, then live.**
+   ```bash
+   node scripts/gds/box.js provision <login>          # read the plan
+   node scripts/gds/box.js provision <login> --apply  # create it
+   node scripts/gds/box.js status
+   ```
+   SSH in (DO assigns the IP shown), confirm the devcontainer came up, then `park`/`wake` it once to confirm the snapshot round-trips.
+3. **Wire the box-side heartbeat** (so the idle sweep measures activity, not uptime). On the box, schedule `infra/box-heartbeat.sh` every ~5 min — e.g. `*/5 * * * * /workspace/infra/box-heartbeat.sh >> /tmp/box-heartbeat.log 2>&1` (or hang it off [#599](https://example.com/builders#/task/599)'s box service supervisor). Confirm `GET /api/gds/box/me` shows `last_activity_at` advancing while you're connected.
+4. **Wire the sweeps + the onboarding intent runner** (systemd units ship in `infra/`):
+   ```bash
+   sudo cp infra/box-idle-suspend.{service,timer} infra/box-dormant-reclaim.{service,timer} infra/box-intent-runner.{service,timer} infra/box-drift-reconcile.{service,timer} /etc/systemd/system/
+   sudo systemctl daemon-reload
+   sudo systemctl enable --now box-idle-suspend.timer box-dormant-reclaim.timer box-intent-runner.timer box-drift-reconcile.timer
+   systemctl list-timers 'box-*'        # confirm next-run times
+   ```
+   Tail `journalctl -u box-idle-suspend.service` for a day to confirm boxes park + wake cleanly.
+   > **`box-intent-runner.timer` ([#701](https://example.com/builders#/task/701)) is the on-ramp's responsiveness knob.** It runs `box.js run-intents --apply` every minute, draining the `box_intents` queue that `POST /api/gds/box/ensure` writes — so a builder who hits "connect" gets their box **auto-provisioned** (no box yet) or **woken** (parked) within ~1 min, with no operator CLI. It reads the SAME `/etc/example/box.env` as the sweeps. Without it installed, `ensure` still queues intents — they just sit pending until someone runs `box.js run-intents --apply` by hand. Confirm with `journalctl -u box-intent-runner.service` after a test `ensure`.
+   > **`box-drift-reconcile.timer` (task [#1289](https://example.com/builders#/task/1289)/[ADR 0071](../adr/<redacted>.md)) is the zombie backstop.** It runs `box.js reconcile-drift --apply` hourly, reading the live DO droplet list and repairing DO⇄DB drift both ways — force-deleting **zombie** droplets (running but no live box row claims them) and marking **ghost** rows destroyed (droplet gone from DO). Reads the SAME `/etc/example/box.env` (needs `DO_API_TOKEN` to enumerate droplets). Without it, the confirm-before-destroyed teardown still prevents *new* zombies, but a pre-existing one (or an out-of-band DO change) only heals on the next manual `reconcile-drift`. Confirm with `journalctl -u box-drift-reconcile.service`.
+   > **Chromebook / browser terminal ([#760](https://example.com/builders#/task/760)/[ADR 0038](../adr/<redacted>.md), superseding the old `claude rc` pairing).** Research proved `claude rc` cannot run headless, so the box instead serves its OWN browser terminal — **ttyd** (127.0.0.1:7681, per-box basic-auth, drops into `/workspace`) exposed over an outbound-only **Cloudflare Tunnel** — where the builder runs normal interactive `claude`. A browser/Chromebook builder gets the URL + credential from `GET /api/gds/box/terminal` after their box is active — no SSH needed. The terminal/cloudflared units are inlined in cloud-init and start at first boot ([#774](https://example.com/builders#/task/774)). The deleted RC bits (`claude-rc.service`, `box-report-pairing.sh`, `/box/pairing(-link)`) are gone.
+
+## Boundaries (other ADR-0031 tasks)
+
+- **[#596](https://example.com/builders#/task/596)** (done) — the devcontainer (box-as-code) this provisions.
+- **[#599](https://example.com/builders#/task/599)** — Claude Desktop managed-settings + the stable-hostname cutover the lifecycle records. (The browser-on-ramp is now the ttyd web terminal over a Cloudflare Tunnel — [#760](https://example.com/builders#/task/760)/[ADR 0038](../adr/<redacted>.md) — not the retired `claude rc` Remote-Control service.)
+- **[#600](https://example.com/builders#/task/600)** — rank-gated **source access**: the scoped GitHub credential the box holds, granted/revoked by rank. [#598](https://example.com/builders#/task/598) records `scope`; [#600](https://example.com/builders#/task/600) enforces it.
+- **[#602](https://example.com/builders#/task/602)** — cost passthrough (org-funded starter → self-fund via the `costs`/drachmae system). [#598](https://example.com/builders#/task/598) logs the cost; [#602](https://example.com/builders#/task/602) rebills it.
+
+## Safety properties
+
+- **No HTTP provisioning — the web process never touches the DO API.** Lifecycle mutations (provision/park/wake/deprovision) run only on the control-plane CLI; `DO_API_TOKEN` lives only in `/etc/example/box.env`, never the web tier. The API surface is read (`GET /box/me`, `GET /boxes`, `GET /box/terminal`) plus own-scoped writes that **record a request, not an action**: `POST /box/heartbeat` and — [#701](https://example.com/builders#/task/701) — `POST /box/ensure`, which only writes a `box_intents` row. The control-plane `box.js run-intents` is what actually calls DO. A stolen builder token can, at most, queue a provision/wake of **its own** box (rank-gated, one open intent max) — it can never create, destroy, or reach another builder's infrastructure.
+- **Dry-run default + token-required-for-live.** You cannot accidentally spend money; a live call without `DO_API_TOKEN` throws rather than silently no-op'ing.
+- **Audited.** Every transition writes a `box_events` row (`provision`/`park`/`wake`/`deprovision`/`cost`/`error`) with the actor (`cli:<login>` / `sweep:idle` / `sweep:dormant`).

package/docs/recipes/claude-design-loop.md

@@ -0,0 +1,143 @@
+# Recipe: Claude Design loop
+
+> End-to-end guide for the repo ↔ Claude Design sync cycle.
+> ADR: [ADR 0081](../adr/<redacted>.md).
+> Adapter: `src/ui/adapters/claude-design/index.js`.
+> CLI: `scripts/gds/design-sync.js`.
+> Skill: `.claude/skills/design-sync/SKILL.md`.
+
+---
+
+## When to use this
+
+- Starting a UI sprint and want Claude Design to prototype from real tokens, not approximations.
+- Tokens or surfaces changed and the Claude Design project is stale.
+- A Claude Design prototype is done and you want to land the generated code as a GDS task.
+
+---
+
+## Prerequisites
+
+- **Rank: Metic+** (design-sync routes are Metic-gated server-side).
+- **Claimed GDS task** — use this for the handoff step. If you're just exporting, no claim is required; a claim is required when you `export()` and commit the generated code.
+- **DesignSync MCP** — the `mcp__DesignSync__*` tools must be available in your session.
+
+---
+
+## 1. Build the token bundle
+
+```bash
+node scripts/gds/design-sync.js
+```
+
+Output (JSON on stdout):
+
+```json
+{
+  "bundlePath": "/tmp/otb-design-bundle-XXXXX",
+  "files": [
+    "tokens/colors.html",
+    "tokens/typography.html",
+    "tokens/spacing.html",
+    "tokens/radii.html",
+    "tokens.css",
+    "tokens.json",
+    "surfaces.json"
+  ],
+  "surfaceIds": ["hall-ui", "status-ui"],
+  "summary": "bundle → /tmp/otb-design-bundle-XXXXX · 2 surface(s) · tokens: colors, typography, spacing, radii"
+}
+```
+
+**To scope to one surface:**
+```bash
+node scripts/gds/design-sync.js --surface hall-ui
+```
+
+---
+
+## 2. Push to Claude Design
+
+Use the DesignSync MCP tool in your Claude Code session:
+
+```
+list_projects      → pick the OTB project (or create "Off the Boats — Design System")
+finalize_plan      → stage all files from manifest.files, rooted at bundlePath
+write_files        → push the bundle
+```
+
+After the push:
+- Token preview cards appear under **Design System** → **Tokens** (colors / typography / spacing / radii).
+- `tokens.css` is available for prototype stylesheets as `--dt-<group>-<key>` CSS vars.
+- `surfaces.json` tells Claude Design which surfaces exist.
+
+---
+
+## 3. Prototype in Claude Design
+
+Claude Design can now reference the token cards. Typical workflow:
+
+1. Open Claude Design → select the OTB project.
+2. Describe the UI: "Build a task-card component matching the token palette."
+3. Claude Design generates HTML/CSS/JS using `--dt-*` vars.
+4. Iterate until the prototype is ready.
+
+---
+
+## 4. Land the handoff as a GDS task
+
+When Claude Design's output is ready:
+
+**a. Claim a GDS task** (if not already done).
+
+**b. Run the export step** — either via the skill or directly:
+
+```js
+const adapter = require('./src/ui/adapters/claude-design/index.js');
+const result = await adapter.export({
+  repoRoot: process.cwd(),
+  surfaceId: 'hall-ui',
+  toolOutput: { files: [
+    { path: 'components/TaskCard.js', content: '...' },
+    { path: 'components/TaskCard.css', content: '...' },
+  ]},
+  taskId: '1234',
+});
+// result: { filePaths, commitMessage, designSourcesUpdated, warnings }
+```
+
+The adapter writes files to `src/ui/<surfaceId>/` and updates `config/design-sources.json` with the sync timestamp.
+
+**c. Commit + ship.**
+
+```bash
+git add src/ui/hall-ui/ config/design-sources.json
+git commit -m "ui(hall-ui): Claude Design export (task 1234)"
+node scripts/gds/ship.js 1234 --notes "..." --summary "..."
+```
+
+---
+
+## Iterating
+
+- Re-run `node scripts/gds/design-sync.js` + re-push whenever tokens change.
+- The `export()` call is **idempotent** — files with identical content are skipped.
+- `config/design-sources.json` tracks which surface was last synced, by which tool, and when.
+
+---
+
+## Coexisting with Figma
+
+If a surface is Figma-canonical, its `config/design-sources.json` entry will have `"tool": "figma"`. The Claude Design adapter will still work on that surface, but treat the result as an experimental branch — the Figma-canonical surface won't round-trip cleanly. For code-canonical surfaces (the default), Claude Design is the right tool.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `design-sync: repoRoot is required` | Run from the repo root: `node scripts/gds/design-sync.js` |
+| `design-tokens.neutral.json` missing | Run from a checkout that includes `config/`. |
+| `path-escape` error from `export()` | Claude Design sent a path with `../` — reject that output and re-prompt. |
+| Bundle is stale after token edit | Re-run `node scripts/gds/design-sync.js` and re-push. |
+| DesignSync MCP not available | The MCP tool is session-specific — check your Claude Code session config. |

package/docs/recipes/claude-gemini-bongos-doors.md

@@ -0,0 +1,155 @@
+# Recipe — stand up claudebongos.com + geminibongos.com (vanity doors → cloudbongos.com)
+
+> Brings **claudebongos.com** and **geminibongos.com** live as public "vanity
+> doors": each shows the exact Cloud Bongos landing **gate** (`brand/cloud-bongos/gate`),
+> rebranded to **"Claude Bongos" / `> claude`** (resp. **"Gemini Bongos" / `> gemini`**)
+> at runtime — the visitor still types `bongos`, and on enter the gate redirects
+> to **cloudbongos.com**, landing straight on the orbs. Same task also **promotes
+> the gate onto the cloudbongos.com apex** (it replaces the buddha placeholder,
+> which is what makes the redirect land "on the orbs"). Task
+> [#1746](https://example.com/builders#/task/1746).
+
+## Architecture (what we're building)
+
+One gate bundle, three domains, a runtime switch — **no forked copies**. `space.js`
+reads `location.hostname`; a door rebrands the entry + redirects on enter, and the
+default (cloudbongos.com) reveals the orbs in place. Any future change to the gate
+shows up on all three automatically.
+
+| Domain | Serves | On typing `bongos` + enter |
+|---|---|---|
+| **claudebongos.com** | the gate, rebranded "Claude Bongos" / `> claude` | `→ https://cloudbongos.com/?entered=1` (orbs) |
+| **geminibongos.com** | the gate, rebranded "Gemini Bongos" / `> gemini` | `→ https://cloudbongos.com/?entered=1` (orbs) |
+| **cloudbongos.com** | the gate, "Cloud Bongos" (**was** the buddha page) | reveals the orbs in place |
+
+Hosting is the **cheapest possible**, same as the staging gate:
+
+| Thing | Value |
+|---|---|
+| Served by | Caddy `file_server`, web root `/home/lars/example/brand/cloud-bongos` |
+| The two doors | **pure static** — no app process, no port, no password |
+| cloudbongos.com apex | static gate for `/` + gate assets; **still proxies** `/api`, `/healthz`, etc. to the platform app (`:3002`) so sign-in keeps working |
+| TLS | **one new Cloudflare Origin Cert per new domain** — the cloudbongos cert's SANs do NOT cover claudebongos.com / geminibongos.com |
+| Cost | **$0/mo** — same droplet, no new process/port |
+
+Why static (not a reverse-proxy block): the gate is plain HTML/CSS/JS + PNGs.
+There is nothing to run. The `?entered=1` query flag is how a door hands off — the
+gate honors it (only on non-door hosts) to skip its own entry and open the orbs.
+
+Everything in the repo (`space.js`, the `infra/Caddyfile` blocks, the gate art)
+auto-deploys to the droplet checkout on merge. What is **NOT** automatic — and is
+this recipe — is the per-domain **DNS + Origin Cert** and the **live Caddyfile
+merge + reload**. Until those are done, the two domains show a TLS error (expected).
+
+## Phase ① — DNS (Cloudflare, ~1 min per domain)
+
+Both domains are already on Cloudflare. For **each** zone (claudebongos.com,
+geminibongos.com):
+
+1. Cloudflare → pick the zone → **DNS** → **Add record**.
+2. Type **A**, Name **`@`**, IPv4 **`REDACTED_IP`**, Proxy status **Proxied**
+   (orange cloud ON), TTL Auto. Save.
+3. Cloudflare → **SSL/TLS** → **Overview** → set encryption mode to **Full (strict)**.
+
+(Optional: add a **`www`** A record → same IP, proxied, if you want `www.` to work.
+The Caddyfile blocks are apex-only today; add `www.claudebongos.com` to the site
+line if you add the record.)
+
+## Phase ② — Origin Certificate (own domain → own cert)
+
+Each new domain needs its **own** Origin Cert. For **each** zone:
+
+Cloudflare → **SSL/TLS → Origin Server → Create Certificate**:
+- Hostnames: `claudebongos.com` **and** `*.claudebongos.com` (resp. the gemini pair)
+- Let Cloudflare generate the key; **copy both** the certificate and the private key.
+
+Install on the droplet (operator). Caddy runs as user `caddy` and **must be able to
+READ the key** — match the existing `origin.key` ownership (`640 root:caddy`). A
+root-only `600` key makes Caddy's reload fail (learned during the cloudbongos
+bring-up). The `.crt` can be world-readable.
+
+```bash
+# claudebongos
+sudo install -m 644 -g caddy /dev/stdin /etc/caddy/claudebongos-origin.crt   # paste cert, Ctrl-D
+sudo install -m 640 -g caddy /dev/stdin /etc/caddy/claudebongos-origin.key   # paste key,  Ctrl-D
+# geminibongos
+sudo install -m 644 -g caddy /dev/stdin /etc/caddy/geminibongos-origin.crt   # paste cert, Ctrl-D
+sudo install -m 640 -g caddy /dev/stdin /etc/caddy/geminibongos-origin.key   # paste key,  Ctrl-D
+```
+
+## Phase ③ — apply the Caddy blocks + reload
+
+Three blocks ship in `infra/Caddyfile`: the two new **door** blocks
+(`claudebongos.com`, `geminibongos.com`) and the **modified `cloudbongos.com`
+apex** block (now serves the gate + proxies functional paths). The live
+`/etc/caddy/Caddyfile` has drifted slightly from the repo copy, so **do not blindly
+`cp` the whole file** — apply the two pieces by hand:
+
+```bash
+cd /home/lars/example
+git pull   # or wait for the auto-deploy; the brand/ bundle + infra/Caddyfile land here
+
+# 1. Append the two door blocks (idempotent: skip if already present).
+grep -q '^claudebongos.com {' /etc/caddy/Caddyfile || \
+  awk '/^# ── Claude Bongos \+ Gemini Bongos — vanity DOORS/{p=1} p' infra/Caddyfile \
+    | sed '/^# ── Cloud Bongos — STAGING/,$d' >> /etc/caddy/Caddyfile
+#   (or just open the file and paste the two blocks from infra/Caddyfile — the
+#    awk above copies from the DOORS comment to end-of-file.)
+
+# 2. Modify the LIVE cloudbongos.com apex block. Open the file, find the
+#    `cloudbongos.com {` block, and replace its body — the single
+#    `reverse_proxy 127.0.0.1:3002 { … }` — with the gate-serving body from
+#    infra/Caddyfile (root + @hidden + @gate handle + the catch-all reverse_proxy).
+#    Leave builders.cloudbongos.com and status.cloudbongos.com UNTOUCHED.
+sudo nano /etc/caddy/Caddyfile
+
+# 3. Validate (as root — it must read the 640 origin keys), then reload.
+sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
+sudo systemctl reload caddy   # fails closed on a bad config
+```
+
+> A bad config makes `reload` error out and **keep serving the old config** — the
+> live sites never go down. If a cert path is wrong, that one site fails to come
+> up while the others keep serving.
+
+## Phase ④ — verify
+
+```bash
+# from anywhere — the two doors:
+curl -sSL https://claudebongos.com/  | grep -o 'space.css\|gate'      # gate HTML served ✓
+curl -sSL https://geminibongos.com/  | grep -o 'space.css\|gate'      # gate HTML served ✓
+curl -sS -o /dev/null -w '%{http_code}\n' https://claudebongos.com/   # 200 (via the /gate/ redirect) ✓
+
+# cloudbongos.com apex now serves the gate, and the app still answers:
+curl -sSL https://cloudbongos.com/   | grep -o 'space.css\|gate'      # gate served at apex ✓
+curl -sS  https://cloudbongos.com/healthz                            # "ok" — app still reachable ✓
+```
+
+Then open each in **Chrome or Edge** (the live-glass refraction needs Chromium
+`backdrop-filter` + SVG displacement; Safari falls back to a plain frost, still
+fine):
+
+- `https://claudebongos.com` → gate reads **"Claude Bongos" / `> claude`**. Type
+  `bongos`, press enter → you land on **cloudbongos.com showing the orbs**.
+- `https://geminibongos.com` → same, **"Gemini Bongos" / `> gemini`**.
+- `https://cloudbongos.com` → gate reads "Cloud Bongos"; type `bongos` → orbs in place.
+- **Sign-in still works:** `https://builders.cloudbongos.com` → sign in with GitHub
+  (the OAuth callback is on the apex, `/api/gds/auth/web/callback`, which the
+  catch-all still proxies to `:3002`). If sign-in breaks, the apex `@gate`/`handle`
+  split is wrong — recheck step ③.2.
+
+## Rollback
+
+- **Take a door down:** delete its block from `/etc/caddy/Caddyfile`,
+  `sudo systemctl reload caddy`, remove the Cloudflare `@` A record.
+- **Revert cloudbongos.com to the buddha page:** restore the apex block to the
+  single `reverse_proxy 127.0.0.1:3002 { … }` body, reload. The buddha landing
+  (`public-landing/index.html`) is untouched in the repo and served again
+  immediately.
+
+## Files this recipe uses
+
+- `infra/Caddyfile` — the two door blocks + the modified `cloudbongos.com` apex block.
+- `brand/cloud-bongos/gate/space.js` — the runtime hostname switch (branding +
+  redirect + `?entered` auto-open).
+- `brand/cloud-bongos/` — the gate bundle + the world art it refracts (shared by all three).

package/docs/recipes/cloudbongos-staging-gate.md

@@ -0,0 +1,139 @@
+# Recipe — stand up staging.cloudbongos.com (password-locked landing-page preview)
+
+> Brings up **staging.cloudbongos.com** — a password-locked preview of the Cloud Bongos
+> landing **gate** (`brand/cloud-bongos/gate`, the cel-glass + `> cloud bongos` terminal
+> prototype from tasks [#1532](https://example.com/builders#/task/1532) +
+> [#1534](https://example.com/builders#/task/1534)). This is the future
+> cloudbongos.com landing page, parked behind a shared password so it can be shared for
+> review before it goes public. Task [#1540](https://example.com/builders#/task/1540).
+
+## Architecture (what we're building)
+
+The **cheapest possible** host: no app process, no new port, no new certificate. Caddy
+**static-serves** the brand-art folder that already ships in the checkout, behind HTTP
+basic auth (the password lock).
+
+| Thing | Value |
+|---|---|
+| URL | `https://staging.cloudbongos.com` (redirects to `/gate/`, where the gate is served) |
+| Served by | Caddy `file_server`, web root `/home/lars/example/brand/cloud-bongos` |
+| Lock | HTTP basic auth — username `bongos` + a shared password |
+| TLS | the existing `*.cloudbongos.com` origin + Cloudflare edge certs (already cover it) |
+| Cost | **$0/mo** — same droplet, no process, no port |
+
+Why static (not a reverse-proxy block like the others): the gate is plain HTML/CSS/JS +
+PNGs. There is nothing to run. Caddy serves the files directly.
+
+## Why the web root is the brand folder, not `gate/`
+
+The gate page lives at `gate/index.html` but references its art **relative to `/gate/`** —
+sprites **beside it** (`sprites/…`, `dispmaps/…`) and the world **one level up**
+(`../world/…`). So the folder that must be the web root is `brand/cloud-bongos/` (the
+parent), and the page must actually be served **at `/gate/`** for those relative paths to
+resolve. The Caddy block therefore **redirects the apex `/` → `/gate/`** (`redir / /gate/`)
+rather than serving the gate's HTML at the apex.
+
+> History (task 1545): the block first tried to serve the gate AT the apex via
+> `rewrite / /gate/index.html` plus per-folder rewrites (`/dispmaps/*` → `/gate/dispmaps/*`).
+> That was fragile — when the gate gained `sprites/` (task 1541) those 404'd at the apex
+> (the browser asked `/sprites/*`, not `/gate/sprites/*`). The redirect serves the gate at
+> its native path so **all** relative folders resolve, with nothing to keep in sync.
+
+## Phase ① — DNS (Cloudflare dashboard, ~30 s)
+
+cloudbongos.com is on Cloudflare. Add **one** record:
+
+1. Cloudflare → pick the **cloudbongos.com** zone → **DNS** → **Add record**.
+2. Type **A**, Name **`staging`**, IPv4 **`REDACTED_IP`**, Proxy status **Proxied** (orange cloud ON), TTL Auto.
+3. Save.
+
+No new certificate is needed — the cloudbongos origin cert is already
+`cloudbongos.com, *.cloudbongos.com`, and Cloudflare's edge cert covers
+`staging.cloudbongos.com` too.
+
+## Phase ② — the password (droplet, one-time)
+
+The `staging.cloudbongos.com` block ships in `infra/Caddyfile` with a **dummy** bcrypt hash,
+so no real secret is in git. Generate the real hash and keep it handy for Phase ③:
+
+```bash
+caddy hash-password --plaintext 'YOUR_PASSWORD'
+#  → prints  $2a$14$………   (copy the whole thing)
+```
+
+Username is `bongos`; the password is whatever you hashed. The real hash lives **only** in
+the live `/etc/caddy/Caddyfile` — never committed.
+
+## Phase ③ — apply the Caddy block + reload
+
+The `staging.cloudbongos.com` block is already in `infra/Caddyfile`. The live
+`/etc/caddy/Caddyfile` has drifted slightly from the repo copy (comment wording + block
+order), so **do not blindly `cp` the whole file** — append just the new block, swap the
+dummy hash for the real one, then reload:
+
+```bash
+cd /home/lars/example
+# 1. append only the staging.cloudbongos.com block (idempotent: skip if present)
+grep -q 'staging.cloudbongos.com {' /etc/caddy/Caddyfile || \
+  awk '/^# ── Cloud Bongos — STAGING/{p=1} p' infra/Caddyfile >> /etc/caddy/Caddyfile
+
+# 2. replace the dummy hash: open the file, find the staging.cloudbongos.com
+#    block's `basic_auth { bongos … }` line, and paste the real $2a$… hash from
+#    Phase ② in place of the dummy one.
+sudo nano /etc/caddy/Caddyfile          # or any editor
+
+# 3. let the caddy user READ the static files. Caddy runs as user `caddy`, which
+#    cannot traverse the 750 home dir — without this, authenticated requests get
+#    403. Everything under /home/lars/example is already world-readable, so
+#    ONLY the home dir itself needs to be traversable (one-time, persists):
+sudo setfacl -m u:caddy:x /home/lars 2>/dev/null \
+  || sudo chmod o+x /home/lars          # fallback if the `acl` package is absent
+#    o+x allows traverse, not listing. For strict least-privilege instead of the
+#    broad o+x, `sudo apt-get install -y acl` first so the setfacl path is taken.
+
+# 4. validate (as root — it must read the 640 root:caddy origin key), then reload
+sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
+sudo systemctl reload caddy             # fails closed on a bad config
+```
+
+> A bad config makes `reload` error out and **keep serving the old config** — the live
+> sites never go down. Leaving the dummy hash in place is also safe: it just means no one
+> can log in (fail-closed) until you paste the real one.
+
+## Phase ④ — verify
+
+```bash
+# from anywhere:
+curl -sS -o /dev/null -w '%{http_code}\n' https://staging.cloudbongos.com/          # 401 (locked) ✓
+curl -sS -u bongos:YOUR_PASSWORD https://staging.cloudbongos.com/ | grep -o 'cloud bongos'   # matches ✓
+curl -sS -o /dev/null -w '%{http_code}\n' -u bongos:YOUR_PASSWORD \
+     https://staging.cloudbongos.com/world/assets/plates/scene-establishing.png      # 200 (art loads) ✓
+```
+
+Then open `https://staging.cloudbongos.com` in **Chrome or Edge** (the live-glass
+refraction needs Chromium `backdrop-filter` + SVG displacement; Safari falls back to a
+plain frost, which still looks fine). The browser shows a username/password box — enter
+`bongos` + the password — and the gate appears.
+
+## Rotating / removing the password
+
+- **Change the password:** regenerate the hash (Phase ②), edit the `bongos …` line in the
+  `staging.cloudbongos.com` block of `/etc/caddy/Caddyfile`, `sudo systemctl reload caddy`.
+- **Take the site down:** delete the `staging.cloudbongos.com` block from
+  `/etc/caddy/Caddyfile`, `sudo systemctl reload caddy`, and remove the Cloudflare
+  `staging` A record.
+
+## Later — promote to the real public landing page
+
+When the gate is approved as the public landing page, that is a **separate task**: fold the
+gate into `public-landing/index.html` (served at the cloudbongos.com apex by
+`platform-server.js`), bring the world art it needs under a served path, and drop the basic
+auth. Until then, this staging block is the review surface and `public-landing/index.html`
+stays the minimal buddha placeholder.
+
+## Files this recipe uses
+
+- `infra/Caddyfile` — the `staging.cloudbongos.com` block (ships with a dummy hash; the
+  live file carries the real one).
+- `brand/cloud-bongos/gate/` — the gate prototype (`index.html` + `dispmaps/`).
+- `brand/cloud-bongos/world/assets/` — the art the gate refracts.