@bongos/core 1.17.0 → 1.17.2

package/docs/design/container-interior.md

@@ -1,77 +0,0 @@
-# Container building — interior atmosphere design (V2)
-
-- **Task:** [#645](https://example.com/builders#/task/645) (V2 · product · creative). Promoted from idea_inbox [#164](https://example.com/builders#/idea/164) (builder 25 art/design brief, 2026-06-04).
-- **Date:** 2026-06-21
-- **Builds on:** [`container-exterior.md`](container-exterior.md) — this is the **interior** counterpart of that structure-level brief. The granular interior layers it calls out are the **layout** ([#642](https://example.com/builders#/task/642)) and the **floor-tile pixel spec** ([#644](https://example.com/builders#/task/644)); palette is governed by [ADR 0044](../adr/0044-mediterranean-palette-replacement.md).
-- **Status:** Atmosphere direction locked. Colour reconciled to ADR 0044 (below). Tile generation waits for [#640](https://example.com/builders#/task/640) / ADR 0044, same sequencing rule as the exterior.
-
-## ⚠️ Colour: the source brief is superseded — Mediterranean palette, not Poke-Mart blue
-
-idea_inbox [#164](https://example.com/builders#/idea/164)'s brief (this task's source, 2026-06-04) built the interior on a **saturated Pokémon "Poke Mart" blue wave-scale floor** and **orange-red container walls** as the nostalgia anchor. That was written **before** the palette was locked. The authoritative decisions win (exactly as the exterior briefs defer):
-
-- **[ADR 0044](../adr/0044-mediterranean-palette-replacement.md)** (2026-06-10): the world has **one Mediterranean palette**, and it states explicitly — *"there is no 'Poke Mart interior' context that needs the temperate palette."* So the interior is **not** a palette exception; it shares the world's hues.
-- **Blocker [#7](https://example.com/builders#/blocker/7)** (2026-06-10, locked `style_guide.md` rule): the container body is **weathered black/charcoal corrugated metal**, not red/orange. The interior-facing walls are the same shell.
-- **Lars (2026-06-21, this session):** Mediterranean governs the interior. The layered *geometry* survives untouched — only the hues are corrected.
-
-Concretely (geometry preserved, hue corrected — the exact move [`container-exterior-tiles.md`](container-exterior-tiles.md) made for the facade):
-
-| Source brief's colour | Corrected (Mediterranean) |
-|---|---|
-| Saturated Poke-Mart **blue** wave floor | **Aqua / turquoise** wave-scale, from the palette's turquoise-sea steps — the *pattern* is the nostalgia anchor; the *hue* matches the sea just outside the glass |
-| **Orange-red** container walls | **Weathered charcoal** corrugated (blocker [#7](https://example.com/builders#/blocker/7)) — warmth comes from the *lighting*, not the paint |
-| Lush **forest-green** featured rug | Deep **olive / sage** rug (the palette's darkest greens) — still "rich and set apart," in-palette |
-| Pure-**white** shelving | **Cream / pale-stone** (warm-neutral steps); no white edge rim, 1-px darker object outline (style rules) |
-
-> **[#642](https://example.com/builders#/task/642) / [#644](https://example.com/builders#/task/644) note:** both still say "blue" floor; [#644](https://example.com/builders#/task/644)'s title already hedges to "aqua-tinted." Read their "blue" as this brief's Mediterranean turquoise/aqua — this doc is the colour authority for the interior, the way `container-exterior.md` is for the facade.
-
-## The unified interior — a layered space
-
-Three layers on three surfaces, none fighting because each owns a different plane:
-
-1. **Shell (walls):** raw weathered-charcoal corrugated container — the industrial bones are never hidden. Double-height: tall wall columns, a second-floor balcony railing along the top of the map, pendant lamps on cables from a high ceiling.
-2. **Floor (the centerpiece):** aqua/turquoise wave-scale tile — the nostalgia geometry underfoot, in Mediterranean hue.
-3. **Retail layer (objects + light):** boutique principles — items displayed like sculpture with as much negative space as product; warm directional track lighting makes the illuminated patches the brightest things in the room.
-
-You walk into a space that *feels* like a game (the floor pattern), *looks* like a container (the charcoal shell), and *shops* like a boutique (the sculptural, warm-lit display). That triple recognition in the first two seconds is the emotional design goal — unchanged by the palette correction, because it lives in **pattern, material, and light**, not in saturation.
-
-## Architecture extracted from the references (geometry — all survives)
-
-The source brief studied four interior reference images (idea_inbox [#164](https://example.com/builders#/idea/164)); the *geometry* below is the durable takeaway, independent of hue.
-
-- **Double-height shell** (Interior1/2): two storeys of open vertical space → taller wall columns, a balcony-railing band at the top of the map, pendant lamps on cables from a high ceiling.
-- **Symmetrical industrial staircases** (Interior1): black-metal flights on the left/right walls — key navigation + vertical drama. Visual/blocking in V2; walkable upper floor is a later version.
-- **Warm pooled light** (Interior2): tall warm lamps and track lights pool on the floor — 2–3 shade steps radiating from each source. This is where *all* the warmth now comes from, since the walls are charcoal.
-- **Sculptural display** (interior3): freestanding display tables (gallery plinths, not Poke-Mart shelves), few items, generous spacing. Negative space ≈ product — the single biggest luxury signal.
-- **Featured "room within a room"** (interiorShelving1): an architecturally framed VIP zone with a deep olive/sage rug and warm ochre/gold fixtures — the inner sanctum / featured-product zone.
-- **Rear glass panel** (Interior1): full-width north-wall glass showing the coast beyond — ties the interior back to the Mediterranean exterior (and reuses the facade's glass language).
-
-## Key tile assets (priority order)
-
-1. **Aqua wave-scale floor tile** — the foundational tile; pixel spec is [#644](https://example.com/builders#/task/644).
-2. **Interior container wall tile** — weathered charcoal corrugated (interior-facing variant of the exterior wall family).
-3. **Cream shelving unit** — wall-mounted, pale-stone, items displayed; no white rim, 1-px outline.
-4. **Track-light tile** — small dark ceiling/beam fixture + a warm cone splashing onto the surface below.
-5. **Display-table object overlay** — freestanding wood top, few items, spaced.
-6. **Deep olive/sage featured rug** — the premium-zone floor (alpha-tile overlay over the wave floor).
-7. **Industrial pendant lamp** — hung from above, warm light source.
-8. **Balcony railing** — dark metal, top of the map (second-storey read).
-9. **Polished-concrete floor** — grey, smooth, for back-of-house / secondary areas.
-10. **Rear glass panel** — full-width north wall, coast visible through it.
-
-## Pipeline mapping (generate after [#640](https://example.com/builders#/task/640) / ADR 0044)
-
-Per [ADR 0008](../adr/<redacted>.md) (families, not per-tile calls):
-
-1. **`interior_container_shell`** family — wall · balcony railing · staircase · pendant lamp.
-2. **`interior_floor`** family — aqua wave-scale + polished-concrete, with the olive/sage rug as an alpha-tile overlay (the `marble_path` technique, [ADR 0013](../adr/<redacted>.md)).
-3. **Display singletons** — table, shelving, track light, glass panel — per-tile.
-
-**Nothing generates until the palette swap ([#640](https://example.com/builders#/task/640) / ADR 0044) lands** — every tile would re-quantize against the old palette and be redone, the same sequencing rule the exterior brief states.
-
-## Mood target
-
-Walk in and feel like you discovered something — not a supermarket, not an unaffordable boutique, not a video-game shop, but all three at once. The charcoal shell says *industrial secret*; the aqua wave floor says *I know this place*; the spaced, warm-lit display says *this is worth something*. The floor now reads as a **sun-bleached aqua wave** rather than an arcade-saturated blue, which is the point: it belongs to the same coast you can see through the rear glass.
-
-## Engineering follow-up (not this task)
-
-A walkable interior needs a second world map / room and a door transition (the `container-exterior.md` entrance door leads here), plus interior OBJECT ids in **both** `map.js`/`terrain.js` twins (server + client). File as an engineering task once the interior layout ([#642](https://example.com/builders#/task/642)) and floor tile ([#644](https://example.com/builders#/task/644)) are final.

package/docs/design/world-map-scroll.md

@@ -1,41 +0,0 @@
-# World map — the "Sealed Ruins Chart" (diegetic artifact, V2)
-
-- **Task:** [#648](https://example.com/builders#/task/648) (V2 · product). Promoted from idea_inbox [#169](https://example.com/builders#/idea/169) (builder 25 art/design brief, 2026-06-04).
-- **Date:** 2026-06-18
-- **Status:** Art + design spec ready. Two follow-ups it implies are separate tasks: the **diegetic-item mechanic** (engineering) and **tile generation** (waits on the palette swap, [#640](https://example.com/builders#/task/640)/[ADR 0044](../adr/0044-mediterranean-palette-replacement.md)). See *Follow-ups* below.
-
-## Concept
-
-The world map is **not a UI overlay or menu** — it is a **diegetic in-game artifact**: an ancient sealed chart the player *discovers*. This reframes navigation from a game mechanic into a story beat. The in-world item name is the **"Sealed Ruins Chart"** — "sealed" is load-bearing: the map is a mystery; not everything is visible from the start.
-
-> Reference concept art (builder-25 planning input): `art/references/concept-art-original/world-map/Map Item Pop Up Concept.webp` + `Shipping container Concept.png`. **NB:** these planning images are not committed to the repo (the `art/references/concept-art-original/` tree is empty here); this written spec is the durable, self-contained source.
-
-## Behaviour (the "diegetic" part — engineering follow-up, not this art task)
-
-- The player does **not** open a menu. They find / are given the scroll — an inventory item, like the FireRed Town Map received from a character.
-- Examining it plays an **unroll animation**.
-- It is **progressive / fog-of-war**: sealed areas begin as blank parchment and fill in as the player explores. (This is the "sealed" mystery made mechanical.)
-
-## Scroll art spec (pixel art)
-
-- **Rollers (top + bottom):** dark mahogany brown, visible wood grain (2–3 horizontal pixel lines per plank); cylindrical implied by a lighter highlight strip along the top edge.
-- **Corner accents:** round emerald-green gemstone insets, 8×8px each, single light highlight pixel upper-left.
-- **Parchment:** aged warm tan, **not uniform** — subtle darker age/wear patches; slight edge vignette.
-- **Title banner:** a rectangular banner at the top, slightly darker parchment, **"SEALED RUINS CHART"** in a serif pixel font (dark brown, not black).
-- **Footer:** bottom roller repeats the title left + right with a centred **emblem** between — a 32×32 pixel creature (dragon / sea-monster), dark-outline style.
-
-### Map surface — the swirling currents (what makes it feel ancient)
-The parchment is densely covered in hand-drawn-style arrows + curved flowing lines — **ocean-current / wind notations**, the language of old nautical charts (NOT paths):
-- thin 1px dark-brown curved, directional lines; arrow tips = simple 2–3px chevrons;
-- density ≈ one arrow/curve segment per 16×16 area over **sea**; **land** areas sparser;
-- this texture — organic, dense, directional — is what reads as *ancient + discovered*, not *designed*.
-
-## Colour note (palette)
-The hexes in the source brief (mahogany, emerald, #D4A96A parchment) are **targets, not literals**: when generated, every pixel quantizes to the locked 64-colour palette — and that palette is being **replaced** ([#640](https://example.com/builders#/task/640) / [ADR 0044](../adr/0044-mediterranean-palette-replacement.md)). The replacement must carry warm-tan / mahogany / emerald steps for this artifact; flag if it doesn't. This is a UI/item artifact (not a world ground tile), so it is less palette-constrained than terrain, but it should still read in-world.
-
-## Mood target
-The player should feel they found something they were **not supposed to find** — a real object from another time, not a game menu. First unroll = one of the most memorable moments in the game.
-
-## Follow-ups (separate tasks, not this art spec)
-1. **Diegetic-item mechanic** (engineering): inventory item + examine→unroll animation + progressive fog-of-war reveal keyed to discovered areas. File when the inventory/item system exists (relates to the V3 purchase-loop / bag work, e.g. [#635](https://example.com/builders#/task/635)).
-2. **Scroll tile/sprite generation** (art pipeline): produce the scroll frame + parchment + emblem assets — **after** the palette swap ([#640](https://example.com/builders#/task/640)) so it isn't re-quantized + redone.

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

@@ -1,155 +0,0 @@
-# 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

@@ -1,139 +0,0 @@
-# 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.

package/docs/recipes/cloudbongos-standup.md

@@ -1,111 +0,0 @@
-# Recipe — stand up cloudbongos.com (Customer 0, the vanilla dogfood instance)
-
-> Brings **cloudbongos.com** live as a real Cloud Bongos instance: the vanilla brand, its own database, no game code — Cloud Bongos running on Cloud Bongos (the C8 proof, [ADR 0062](../adr/<redacted>.md) §2, task [#1374](https://example.com/builders#/task/1374) + the proof ship [#1206](https://example.com/builders#/task/1206)). Owner-only inputs are tracked in blocker [#40](https://example.com/builders#/blocker/40).
-
-## Architecture (what we're building)
-
-Same droplet as OTB (`REDACTED_IP`), **separate process + separate database**, no new monthly cost. One checkout (`/home/lars/example`) runs **two** processes:
-
-| Instance | Entrypoint | Brand | Port | DB | Domain |
-|---|---|---|---|---|---|
-| OTB (game) | `server.js` | `config/branding.json` (default) | 3000 | `example` | example.com |
-| **Cloud Bongos** | `src/platform-server.js` | `config/branding.cloudbongos.json` (via `GDS_BRANDING_FILE`) | **3002** | **`cloudbongos`** | **cloudbongos.com** |
-
-The only difference between the two processes is **environment** — no divergent clone. The brand switch is `src/branding.js`'s `GDS_BRANDING_FILE` knob (task 1374). The landing page is served at the apex by `platform-server.js`; the Hall + status ride `builders.`/`status.` (host routing in `src/bongos/serve-internal.js`).
-
-## Phase ① — DNS  ✅ done
-
-Domain on Cloudflare (Free plan), nameservers switched, **SSL/TLS = Full (strict)**, three **proxied** A records → `REDACTED_IP`:
-`cloudbongos.com` (`@`), `builders`, `status`. (Until the origin cert + process are up, the site shows a TLS error — expected.)
-
-## Phase ② — GitHub OAuth App (builder sign-in)
-
-GitHub → Settings → Developer settings → **OAuth Apps** → **New OAuth App**:
-- **Application name:** `Cloud Bongos`
-- **Homepage URL:** `https://cloudbongos.com`
-- **Authorization callback URL:** `https://cloudbongos.com/api/gds/auth/web/callback` (PINNED — `auth.js` `WEB_REDIRECT_ORIGIN`; sign-in begun on `builders.` still calls back to the apex)
-- **Enable Device Flow:** ✅ (the CLI login uses it)
-
-Copy the **Client ID** + generate a **Client Secret** → they go in `/etc/cloudbongos/web.env` as `CLOUDBONGOS_GITHUB_CLIENT_ID` / `CLOUDBONGOS_GITHUB_CLIENT_SECRET` (resolved as `<ENVPREFIX>_GITHUB_*`; vanilla envPrefix = `CLOUDBONGOS`).
-
-## Phase ③ — Cloudflare Origin Certificate (own domain → own cert)
-
-cloudbongos.com is a different domain, so it needs its **own** Origin Cert (the example cert's SANs don't cover it). Cloudflare → **SSL/TLS → Origin Server → Create Certificate**:
-- Hostnames: `cloudbongos.com` **and** `*.cloudbongos.com`
-- 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 and loop (the OTB site keeps serving the old config, but the new site never comes up — seen during the first bring-up). The `.crt` can be world-readable.
-```bash
-sudo install -m 644 -g caddy /dev/stdin /etc/caddy/cloudbongos-origin.crt   # paste cert, Ctrl-D
-sudo install -m 640 -g caddy /dev/stdin /etc/caddy/cloudbongos-origin.key   # paste key,  Ctrl-D
-```
-
-## Phase ④ — Droplet bring-up (operator)
-
-```bash
-# 1. The instance database (peer auth via the local socket, same as OTB)
-createdb cloudbongos
-
-# 2. GDS-only schema (skips migrations/game/*.sql — no game tables on this instance)
-cd /home/lars/example
-PGDATABASE=cloudbongos MEDUSA_GDS_ONLY=1 ./scripts/migrate.sh
-
-# 3. Secrets file (from infra/cloudbongos.env.example)
-sudo mkdir -p /etc/cloudbongos
-sudo cp infra/cloudbongos.env.example /etc/cloudbongos/web.env
-sudo $EDITOR /etc/cloudbongos/web.env       # fill the OAuth client id + secret
-sudo chmod 600 /etc/cloudbongos/web.env && sudo chown lars:lars /etc/cloudbongos/web.env
-
-# 4. systemd service (from infra/cloudbongos.service)
-sudo cp infra/cloudbongos.service /etc/systemd/system/cloudbongos.service
-sudo systemctl daemon-reload
-sudo systemctl enable --now cloudbongos
-curl -sS http://127.0.0.1:3002/healthz        # → "ok"
-
-# 5. Caddy — the three cloudbongos blocks are in infra/Caddyfile; apply + reload
-sudo cp infra/Caddyfile /etc/caddy/Caddyfile  # or merge the cloudbongos blocks in
-sudo systemctl reload caddy
-```
-
-## Phase ⑤ — Verify + first sign-in
-
-```bash
-curl -sS https://cloudbongos.com/healthz              # "ok" (through Cloudflare now)
-curl -sS https://cloudbongos.com/ | grep -o 'cloud bongos'   # the landing
-```
-- `https://cloudbongos.com` → the buddha landing.
-- `https://builders.cloudbongos.com` → the Hall. **Sign in with GitHub.** Because the pack sets `firstAdmin: "example-owner"`, that first sign-in auto-seats example-owner as **Owner/Archon** on the (empty) cloudbongos DB — no manual step (`auth.js` `maybeSeatFirstAdmin`).
-- `https://status.cloudbongos.com` → the dashboard.
-
-## Deploy automation (important — updated for the dedicated box)
-
-> **This changed with [ADR 0126](../adr/<redacted>.md).** cloudbongos.com no longer runs co-tenant on the OTB box. It runs on its **own dedicated droplet** (`REDACTED_IP`, checkout `/home/lars/cloudbongos`) and tracks `main` via a **pull-based `systemd` timer** — [ADR 0129](../adr/<redacted>.md), task [#2064](https://example.com/builders#/task/2064). The co-hosting box's CI deploy no longer touches it. (The historical "wire `sudo systemctl restart cloudbongos` into `~/deploy.sh`" note applied only while it was a co-tenant.)
-
-Once the box exists, the deploy is [`scripts/deploy/deploy-cloudbongos.sh`](../../scripts/deploy/deploy-cloudbongos.sh) fired by [`infra/cloudbongos-deploy.timer`](../../infra/cloudbongos-deploy.timer) every ~2 min: `git fetch` + reset `origin/main` → `npm ci` (if the lockfile changed) → `PGDATABASE=cloudbongos MEDUSA_GDS_ONLY=1 ./scripts/migrate.sh` → `sudo systemctl restart cloudbongos` → 3002 healthz. After the first install it **self-heals** (each run refreshes `/home/lars/deploy.sh` + the units from the checkout).
-
-**One-time bootstrap** (operator, over SSH to the box — the box can't install its own first deploy automation). Run once the deploy files are on `main`:
-```bash
-# Executed as a STABLE copy outside the checkout (so `git reset --hard` can't
-# corrupt the running script — see ADR 0129):
-sudo -u lars install -m 0755 /home/lars/cloudbongos/scripts/deploy/deploy-cloudbongos.sh /home/lars/deploy.sh
-sudo install -m 0644 /home/lars/cloudbongos/infra/cloudbongos-deploy.service /etc/systemd/system/
-sudo install -m 0644 /home/lars/cloudbongos/infra/cloudbongos-deploy.timer   /etc/systemd/system/
-sudo systemctl daemon-reload
-sudo systemctl enable --now cloudbongos-deploy.timer
-# Verify: one forced run brings the box current + smokes the chain
-sudo -u lars FORCE_DEPLOY=1 /home/lars/deploy.sh
-systemctl list-timers cloudbongos-deploy.timer --no-pager
-curl -sS https://cloudbongos.com/healthz     # → "ok"
-```
-
-## The C8 proof (task 1206) — ✅ DONE 2026-06-21
-
-With the instance live, **one real task** went through the full lifecycle **on cloudbongos.com** — claim → grade (the real 4-worker panel, PASS) → merge → ship, credits awarded — carrying zero game code: **cloudbongos task [#1](https://example.com/builders#/task/1)** (under version CB-V1), the `GDS_MODULES_FILE` fix that made Customer-0 advertise its modules correctly all-off. That shipped task is the C8 acceptance ("the GDS builds itself"). Full record + the operational mechanics for driving cloudbongos.com's GDS from the CLI: [2026-06-21 — C8 self-build proof](../session-logs/<redacted>.md). Closes task [#1206](https://example.com/builders#/task/1206).
-
-## Files this recipe uses
-
-- `config/branding.cloudbongos.json` — the customer-0 brand pack (deltas over `config/branding.neutral.json`).
-- `src/branding.js` — the `GDS_BRANDING_FILE` selector.
-- `src/platform-server.js` — GDS-only entrypoint + the apex landing mount.
-- `public-landing/index.html` — the landing page (mascot at `public-landing/buddha.png`).
-- `infra/cloudbongos.service`, `infra/cloudbongos.env.example`, `infra/Caddyfile` (the cloudbongos blocks).

package/docs/recipes/parallel-load-results-2026-05-30.md

@@ -1,63 +0,0 @@
-# Parallel-load test results — 2026-05-30 ([#272](https://example.com/builders#/task/272), criterion C6)
-
-> **Harness:** [`tests/parallel-load.mjs`](../../tests/parallel-load.mjs) · **Procedure:** [parallel-load-test.md](parallel-load-test.md) · **Target:** seeded staging ([#262](https://example.com/builders#/task/262)) at `http://127.0.0.1:3001` on the droplet (direct, bypassing Cloudflare).
-
-This is the live run that closes **[#272](https://example.com/builders#/task/272) (V3.R53)** and satisfies criterion **C6 — parallel-safe-under-load**. It exercises the deterministic claim concurrency audited in [#269](https://example.com/builders#/task/269) (the `claimTask()` transaction + `uniq_active_claim_per_task` index) against a real running server under concurrent load.
-
-## Bottom line
-
-**Across both runs: ZERO `server_error` (5xx), ZERO races, ZERO anomalies.** Every claim resolved to exactly one of: `success`, `collision` (409 — exactly-one-wins), or `throttled` (429 — the rate limiter cleanly shedding excess writes). Staging's journal logged **0** 5xx responses over the full window. C6's bar — "all claims succeed or 409 cleanly; no 500s, no race conditions" — holds, with the added finding that excess write load is shed cleanly via 429 rather than ever degrading into a race or crash.
-
-## Run A — sustained 30-minute run (the [#272](https://example.com/builders#/task/272) acceptance run)
-
-`--workers 5 --duration 1800 --work-ms 150` (natural claim→work→release→repeat loop across distinct tasks):
-
-| metric | value |
-|---|---|
-| wall | 1800.1s (30 min) |
-| claim attempts | 144 |
-| success | 13 |
-| collision (409, exactly-one-wins) | 8 (5.6%) |
-| throttled (429) | 123 |
-| **server_error (5xx)** | **0** |
-| client_error / other | 0 / 0 |
-| anomalies | 0 |
-| staging 5xx in journal | 0 |
-
-The system stayed healthy (`/healthz` 200) for the entire 30 minutes with no degradation. Low attempt volume is expected: the per-IP rate limiter (below) caps writes, and releases that get throttled leave tasks `active`, draining the claimable pool — so workers spend most cycles idling on an empty queue rather than hammering. That's the system behaving correctly under its own backpressure.
-
-## Run B — high-intensity contention burst (forces collisions)
-
-`--workers 5 --duration 25 --work-ms 100 --contend` (all 5 workers race the SAME task — the canonical "two builders, one task" case):
-
-| metric | value |
-|---|---|
-| claim attempts | 2733 |
-| success | 8 |
-| collision (409, exactly-one-wins) | 17 |
-| throttled (429) | 2708 |
-| **server_error (5xx)** | **0** |
-| anomalies | 0 |
-
-This is the direct demonstration of the C6 invariant: when multiple workers race the same task row, **exactly one wins and the rest get a clean 409 `ALREADY_CLAIMED`** — never two winners, never a 5xx.
-
-## The rate limiter (a relevant, healthy finding)
-
-`src/bongos/middleware/rate-limit.js` enforces **30 writes / 60s per-IP** and **60 writes / 60s per-session** on write methods (GET is unlimited). Because all simulated workers run from the droplet's single IP, the per-IP limit binds first, so most write attempts under load return **429** (`throttled` above). For a parallel-safety test this is a *positive* result: under sustained overload the server sheds excess writes cleanly (429 + `Retry-After`) instead of racing or 500ing. To exercise the claim logic at higher volume in a future run, raise the limit on staging or distribute workers across IPs.
-
-## Harness fixes made while running this (committed under [#272](https://example.com/builders#/task/272))
-
-Running against the real server surfaced live-path bugs the self-test (mock) couldn't:
-
-- **claimable parsing:** the harness read `.data.tasks`, but `GET /tasks/claimable` returns `{ claimable: [...] }` → it saw 0 tasks and never claimed. Fixed to read `.claimable` (with `.tasks` fallback).
-- **429 classification:** 429 was bucketed as `other` / flagged as a release anomaly. Added a dedicated `throttled` outcome (clean) so the report and the pass/fail conclusion are accurate.
-- **`--contend` mode:** added so workers can be pointed at one task to demonstrate exactly-one-wins collisions on demand (Run B).
-
-## Reproduce
-
-```bash
-# On the droplet (staging seeded per #262, service running, alphanumeric token minted):
-cd /home/lars/example-staging
-BASE_URL=http://127.0.0.1:3001 TOKEN=<redacted> node tests/parallel-load.mjs --workers 5 --duration 1800 --work-ms 150
-# add --contend to force same-task collisions
-```

package/docs/recipes/parallel-load-test.md

@@ -1,32 +0,0 @@
-# Parallel-load test — exercising claim concurrency under N builders
-
-> **Harness:** [`tests/parallel-load.mjs`](../../tests/parallel-load.mjs) (built under prep task [#472](https://example.com/builders#/task/472)).
-> **Live run:** criterion **C6** task **[#272](https://example.com/builders#/task/272)** (V3.R53) — a 30-min, 5-builder run against **staging**, gated on **[#262](https://example.com/builders#/task/262)** (staging data seeding).
-
-The harness spawns N concurrent simulated "builder" loops that hammer the GDS claim lifecycle (claim → simulated work → release → repeat) and classifies every claim outcome into `success` / `collision` (clean 409/refusal) / `server_error` (the anomaly we hunt) / `client_error` / `other`. It validates the deterministic claim concurrency C6 requires — the same `claimTask()` transaction + `uniq_active_claim_per_task` index audited in [multi-builder-merge.md](multi-builder-merge.md).
-
-## Self-test (CI-safe, no network)
-
-```bash
-node tests/parallel-load.mjs                      # defaults: 5 workers, 60s
-node tests/parallel-load.mjs --workers 5 --duration 3 --work-ms 50
-```
-
-With no `BASE_URL`, the harness drives an **in-process mock server** whose claim semantics mirror the DB (one active claim per task; touches-overlap → conflict). The board deliberately has two tasks sharing a path so collisions are *forced*, then asserts: ≥1 success, ≥1 collision, **zero** server_error, no invariant violation, and that attempts == sum of classes. Exit 0 = harness accounting proven correct. This runs in CI without a droplet.
-
-## Live run against staging ([#272](https://example.com/builders#/task/272) — once [#262](https://example.com/builders#/task/262) has seeded staging)
-
-```bash
-# Get builder tokens (one or more simulated builders share the load).
-# NEVER point this at production — it mutates real claim/task state. The
-# harness refuses a prod example.com host unless you pass --i-know.
-BASE_URL=https://staging.example.com \
-TOKENS=$tokA,$tokB,$tokC,$tokD,$tokE \
-  node tests/parallel-load.mjs --workers 5 --duration 1800
-```
-
-`#272` acceptance: run 30 min (`--duration 1800`); **every claim resolves to `success` or a clean `collision` — zero `server_error`, no races**; the report's throughput + collision-rate are the deliverable. A single anomaly (any 5xx, thrown error, or invariant violation) exits 1 and fails the run.
-
-## Why the split (prep [#472](https://example.com/builders#/task/472) vs live [#272](https://example.com/builders#/task/272))
-
-`#272`'s done-when explicitly requires a seeded staging environment, which `#262` (backlog) provides. Rather than block the runnable harness behind infra, [#472](https://example.com/builders#/task/472) built + self-validated the harness now; [#272](https://example.com/builders#/task/272) stays the live-staging run. When [#262](https://example.com/builders#/task/262) ships, point the harness at staging per above to close [#272](https://example.com/builders#/task/272) and satisfy C6.