@bongos/core 1.17.0

package/clients/bongos-client/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@cloudbongos/client",
+  "version": "0.0.2",
+  "description": "Generated typed client for the Bongos API (ADR 0118). Do not edit by hand.",
+  "type": "module",
+  "main": "index.mjs",
+  "types": "index.d.ts",
+  "browser": "./bongos-client.global.js",
+  "unpkg": "./bongos-client.global.js",
+  "jsdelivr": "./bongos-client.global.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "browser": "./bongos-client.global.js",
+      "import": "./index.mjs",
+      "require": "./index.cjs",
+      "default": "./index.mjs"
+    }
+  },
+  "files": [
+    "index.mjs",
+    "index.cjs",
+    "index.d.ts",
+    "bongos-client.global.js",
+    "README.md"
+  ],
+  "license": "AGPL-3.0-or-later",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "sideEffects": false
+}

package/config/branding.neutral.json

@@ -0,0 +1,60 @@
+{
+  "_note": "Cloud Bongos vanilla brand pack — customer 0, the identity Cloud Bongos itself runs on (Amazonprimea is customer 1). The neutral starter every instance resolves over. Light + joyful — 'playing in the clouds', where building software is laying down a beat (ADR 0064). The LOOK ships via theme.ui, injected by src/bongos/serve-internal.js (R57): a Lion-King sunrise backdrop, warm palette, Baloo 2 (display/wordmark) + Quicksand (interface) + Fira Code (code) type, and a bongo-pair favicon. To brand a NEW instance, copy this to config/branding.json and fill it in (docs/branding-fill-prompt.md). Authored by task 1216 / V4.R74. See docs/branding-contract.md.",
+  "identity": {
+    "productName": "Cloud Bongos",
+    "worldName": "Cloud Bongos",
+    "company": { "name": "", "site": "" }
+  },
+  "llmProjectName": "this project",
+  "domains": {
+    "publicOrigin": "http://localhost:3000",
+    "buildersOrigin": "http://localhost:3000",
+    "statusOrigin": "http://localhost:3000",
+    "cookieDomain": "",
+    "oauthOrigin": "http://localhost:3000",
+    "devBoxBase": "",
+    "sshBoxBase": "",
+    "sandboxPrefix": "sandbox-",
+    "termPrefix": "term-"
+  },
+  "repo": { "owner": "", "name": "" },
+  "db": { "database": null },
+  "configDir": "cloudbongos",
+  "firstAdmin": "",
+  "currency": { "label": "credits", "symbol": "" },
+  "reward": { "marginPct": 20, "usdPeg": 1 },
+  "models": { "main": "opus", "subagentDefault": "opus", "subagentRoutine": "haiku" },
+  "theme": {
+    "palette": "",
+    "mode": "cloud-bongos",
+    "ui": {
+      "colors": {
+        "bg": "#fff7ed", "bgCard": "#ffffff", "bgDeep": "#ffedd5", "bgFrame": "#fde4c8",
+        "ink": "#2a1f17", "inkSoft": "#6b5d52", "inkFaint": "#857567",
+        "rule": "#fdba74", "ruleSoft": "#fed7aa",
+        "accent": "#f97316", "accentDeep": "#ea580c", "sea": "#38bdf8", "terracotta": "#fb7185"
+      },
+      "fonts": {
+        "display": "\"Baloo 2\", \"Quicksand\", system-ui, sans-serif",
+        "body": "\"Quicksand\", system-ui, -apple-system, \"Segoe UI\", sans-serif",
+        "links": ["https://fonts.googleapis.com/css2?family=Baloo+2:wght@500;600;700&family=Quicksand:wght@400;500;600;700&family=Fira+Code:wght@400;500&display=swap"]
+      },
+      "favicon": "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><circle cx='12' cy='17' r='8' fill='%23f97316'/><circle cx='22' cy='17' r='6' fill='%23fb7185'/><circle cx='12' cy='17' r='3.5' fill='%23fff7ed'/><circle cx='22' cy='17' r='2.5' fill='%23fff7ed'/></svg>",
+      "backdrop": "linear-gradient(180deg, #fde8c8 0%, #fff4e6 45%, #fffdfa 100%)"
+    }
+  },
+  "rankLabels": { "xenos": "Newcomer", "thetes": "Contributor", "metic": "Trusted", "archon": "Owner" },
+  "copy": {
+    "tagline": "Building software is laying down a beat.",
+    "hallName": "Builders' Hall",
+    "notFound": "This page skipped a beat.",
+    "authError": {
+      "titleSuffix": "sign-in failed",
+      "epigraph": "— access —",
+      "heading": "Sign-in failed",
+      "subtitle": "The sign-in didn't complete. Try again, or contact the owner.",
+      "ctaLabel": "Try signing in again"
+    }
+  },
+  "envPrefix": "CLOUDBONGOS"
+}

package/config/design-tokens.neutral.json

@@ -0,0 +1,51 @@
+{
+  "_note": "Cloud Bongos neutral design tokens — the baseline every instance resolves over. To override, copy values into config/design-tokens.json (the instance pack). These match config/branding.neutral.json theme.ui so a vanilla instance with no instance pack still renders correctly. See docs/design-contract.md.",
+
+  "colors": {
+    "bg":         "#fff7ed",
+    "bgCard":     "#ffffff",
+    "bgDeep":     "#ffedd5",
+    "bgFrame":    "#fde4c8",
+    "ink":        "#2a1f17",
+    "inkSoft":    "#6b5d52",
+    "inkFaint":   "#857567",
+    "rule":       "#fdba74",
+    "ruleSoft":   "#fed7aa",
+    "accent":     "#f97316",
+    "accentDeep": "#ea580c",
+    "sea":        "#38bdf8",
+    "terracotta": "#fb7185"
+  },
+
+  "fonts": {
+    "display": "\"Baloo 2\", \"Quicksand\", system-ui, sans-serif",
+    "body":    "\"Quicksand\", system-ui, -apple-system, \"Segoe UI\", sans-serif",
+    "mono":    "\"Fira Code\", \"Cascadia Code\", \"JetBrains Mono\", monospace",
+    "links": [
+      "https://fonts.googleapis.com/css2?family=Baloo+2:wght@500;600;700&family=Quicksand:wght@400;500;600;700&family=Fira+Code:wght@400;500&display=swap"
+    ]
+  },
+
+  "scale": {
+    "xs":  "4px",
+    "sm":  "8px",
+    "md":  "16px",
+    "lg":  "24px",
+    "xl":  "40px",
+    "2xl": "64px"
+  },
+
+  "radius": {
+    "sm":   "4px",
+    "md":   "8px",
+    "lg":   "12px",
+    "pill": "9999px"
+  },
+
+  "motion": {
+    "fast":   "80ms",
+    "normal": "160ms",
+    "slow":   "320ms",
+    "easing": "cubic-bezier(0.4, 0, 0.2, 1)"
+  }
+}

package/config/design-tokens.schema.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "cloud-bongos/design-tokens",
+  "title": "Cloud Bongos design tokens",
+  "description": "Canonical design-token schema for a Cloud Bongos instance. Extends config/branding.json theme.ui. Validated by scripts/gds/validate-design.js. See docs/design-contract.md.",
+  "type": "object",
+  "required": ["colors", "fonts"],
+  "additionalProperties": false,
+  "properties": {
+    "_note": { "type": "string" },
+
+    "colors": {
+      "type": "object",
+      "description": "Surface and semantic color tokens. All values must be CSS color strings.",
+      "required": ["bg", "bgCard", "ink", "accent"],
+      "additionalProperties": false,
+      "properties": {
+        "bg":          { "$ref": "#/$defs/colorToken", "description": "Page background" },
+        "bgCard":      { "$ref": "#/$defs/colorToken", "description": "Card / panel background" },
+        "bgDeep":      { "$ref": "#/$defs/colorToken", "description": "Deeper tinted background" },
+        "bgFrame":     { "$ref": "#/$defs/colorToken", "description": "Frame / sidebar background" },
+        "ink":         { "$ref": "#/$defs/colorToken", "description": "Primary text" },
+        "inkSoft":     { "$ref": "#/$defs/colorToken", "description": "Secondary / muted text" },
+        "inkFaint":    { "$ref": "#/$defs/colorToken", "description": "Placeholder / hint text" },
+        "rule":        { "$ref": "#/$defs/colorToken", "description": "Strong border / divider" },
+        "ruleSoft":    { "$ref": "#/$defs/colorToken", "description": "Subtle border / divider" },
+        "accent":      { "$ref": "#/$defs/colorToken", "description": "Primary action / highlight" },
+        "accentDeep":  { "$ref": "#/$defs/colorToken", "description": "Hover / pressed state of accent" },
+        "sea":         { "$ref": "#/$defs/colorToken", "description": "Link / info tint" },
+        "terracotta":  { "$ref": "#/$defs/colorToken", "description": "Warning / alert tint" }
+      }
+    },
+
+    "fonts": {
+      "type": "object",
+      "description": "Typeface stacks and external stylesheet links.",
+      "required": ["display", "body"],
+      "additionalProperties": false,
+      "properties": {
+        "display": { "type": "string", "description": "CSS font-family for headings and wordmarks" },
+        "body":    { "type": "string", "description": "CSS font-family for running text and UI labels" },
+        "mono":    { "type": "string", "description": "CSS font-family for code and monospaced content" },
+        "links":   {
+          "type": "array",
+          "description": "URLs of external stylesheets to load (e.g. Google Fonts). Loaded in document head.",
+          "items": { "type": "string", "format": "uri" }
+        }
+      }
+    },
+
+    "scale": {
+      "type": "object",
+      "description": "Optional spacing and sizing scale. Values must be valid CSS lengths (px, rem, em).",
+      "additionalProperties": false,
+      "properties": {
+        "xs":  { "type": "string" },
+        "sm":  { "type": "string" },
+        "md":  { "type": "string" },
+        "lg":  { "type": "string" },
+        "xl":  { "type": "string" },
+        "2xl": { "type": "string" }
+      }
+    },
+
+    "radius": {
+      "type": "object",
+      "description": "Optional border-radius tokens.",
+      "additionalProperties": false,
+      "properties": {
+        "sm":  { "type": "string" },
+        "md":  { "type": "string" },
+        "lg":  { "type": "string" },
+        "pill": { "type": "string" }
+      }
+    },
+
+    "motion": {
+      "type": "object",
+      "description": "Optional motion / animation tokens.",
+      "additionalProperties": false,
+      "properties": {
+        "fast":   { "type": "string", "description": "CSS duration for micro-interactions" },
+        "normal": { "type": "string", "description": "CSS duration for standard transitions" },
+        "slow":   { "type": "string", "description": "CSS duration for page-level transitions" },
+        "easing": { "type": "string", "description": "Default CSS easing function" }
+      }
+    }
+  },
+
+  "$defs": {
+    "colorToken": {
+      "type": "string",
+      "description": "A CSS color value (hex, rgb, hsl, color-mix, etc.)"
+    }
+  }
+}

package/config/modules.neutral.json

@@ -0,0 +1,9 @@
+{
+  "_note": "Feature-module selection — the VANILLA (customer-0) default: every optional feature OFF. A fresh Cloud Bongos instance is the methodology core only (builders/tasks/claims/credits/grading/memory/recall) with the engineer discipline. To enable a module on an instance, copy this to config/modules.json and flip flags (or set <ENVPREFIX>_MODULE_<NAME>=1). Sibling of config/branding.neutral.json. Owned by R54 / task 1193 (src/modules.js, ADR 0062 §4). Known modules: game, art-pipeline, discord, dev-box.",
+  "modules": {
+    "game": false,
+    "art-pipeline": false,
+    "discord": false,
+    "dev-box": false
+  }
+}

package/docker-compose.yml

@@ -0,0 +1,52 @@
+# Cloud Bongos — one-command self-host (V4.R63, task 1202, ADR 0062).
+#
+#   docker compose up
+#
+# Brings up Postgres + a vanilla Cloud Bongos instance (GDS-only, no game,
+# neutral brand, all feature modules off) and serves the builders' hall on
+# http://localhost:3000. No prod topology is referenced: the database is a
+# local container, credentials are local-only demo values, and the app reaches
+# the DB over TCP via PG* env. To brand/configure your instance, see
+# docs/recipes/self-host.md (mount your own config/branding.json + modules.json).
+
+services:
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: cloudbongos
+      POSTGRES_PASSWORD: cloudbongos
+      POSTGRES_DB: cloudbongos
+    volumes:
+      - cloudbongos-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U cloudbongos -d cloudbongos"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+    restart: unless-stopped
+
+  app:
+    build: .
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      # DB connection — pool.js (else branch) + scripts/migrate.sh both read PG*.
+      PGHOST: db
+      PGPORT: "5432"
+      PGUSER: cloudbongos
+      PGPASSWORD: cloudbongos
+      PGDATABASE: cloudbongos
+      # Bind to all interfaces inside the container so the published port works.
+      HOST: 0.0.0.0
+      PORT: "3000"
+      # GDS-only instance: skip game-module migrations (ADR 0062 §5).
+      MEDUSA_GDS_ONLY: "1"
+      # Public origin for OAuth callbacks etc. — localhost for a local self-host.
+      CLOUDBONGOS_PUBLIC_ORIGIN: http://localhost:3000
+    ports:
+      - "3000:3000"
+    restart: unless-stopped
+
+volumes:
+  cloudbongos-db:

package/docker-entrypoint.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Cloud Bongos self-host container entrypoint (V4.R63, task 1202).
+#   1. wait for Postgres to accept connections,
+#   2. apply migrations (game module skipped automatically — it is off in a vanilla instance),
+#   3. exec the GDS-only platform server.
+# No prod topology: every connection detail comes from PG* env (docker-compose.yml).
+set -euo pipefail
+
+: "${PGHOST:?PGHOST must be set (the Postgres service host)}"
+: "${PGDATABASE:?PGDATABASE must be set (the instance database name)}"
+PGPORT="${PGPORT:-5432}"
+
+echo "cloud-bongos: waiting for Postgres at ${PGHOST}:${PGPORT}/${PGDATABASE} ..."
+for i in $(seq 1 60); do
+  if pg_isready -h "$PGHOST" -p "$PGPORT" -d "$PGDATABASE" >/dev/null 2>&1; then
+    echo "cloud-bongos: Postgres is ready."
+    break
+  fi
+  if [ "$i" = "60" ]; then
+    echo "cloud-bongos: Postgres did not become ready in time" >&2
+    exit 1
+  fi
+  sleep 1
+done
+
+echo "cloud-bongos: applying migrations ..."
+bash scripts/migrate.sh
+
+echo "cloud-bongos: starting platform server (GDS-only) ..."
+exec node src/platform-server.js

package/docs/adr/0001-stack-choice-single-vps.md

@@ -0,0 +1,45 @@
+# 0001 — Stack choice: single VPS + Node + Postgres + Colyseus + Caddy + Phaser
+
+- **Status:** Accepted
+- **Date:** 2026-05-08
+- **Deciders:** Lars
+
+## Context
+
+Off the Boats V1 needs a persistent shared world for up to 100 concurrent players, browser-played, tile-based, with real-money purchases. The total budget for build + first year is $5,000. Monthly recurring cost must stay low and bootstrap-friendly.
+
+We needed an architecture that:
+
+1. Could host a real-time multiplayer game without a dedicated managed game-server SaaS
+2. Could persist world state durably
+3. Could be operated by one non-software-engineer with Claude as the pair-programmer
+4. Would not lock us into per-MAU pricing or per-GB egress at high volume
+
+## Decision
+
+We will run the entire V1 stack on a **single VPS** with the following components:
+
+- **Hosting:** DigitalOcean droplet, Ubuntu 24.04 LTS (see [0002](./<redacted>.md))
+- **Reverse proxy / TLS:** Caddy (originally for Let's Encrypt; superseded by [0003](./<redacted>.md))
+- **Runtime:** Node.js 22 LTS
+- **Database:** PostgreSQL 16 (system package)
+- **Game server:** Colyseus 0.16 — open-source authoritative-server framework over WebSockets
+- **Web framework:** Express 4 — for static file serving + healthz; shares the Node process with Colyseus
+- **Browser engine:** Phaser 3 — tile-based 2D game engine with broad community support
+
+Everything runs on one droplet behind one Caddy instance. Same Node process serves Express HTTP and Colyseus WebSockets. Postgres is local on the same machine over a Unix socket.
+
+## Alternatives considered
+
+- **Managed game server (Photon, PlayFab, Hathora).** Per-CCU pricing scales linearly with success and is opaque at the budget level we need. Rejected on cost predictability.
+- **Serverless (Lambda + DynamoDB + API Gateway WebSockets).** No native long-lived game-room concept; Lambda cold starts are hostile to a tile-tick game; DynamoDB pricing is hard to predict at the access patterns a world event log generates. Rejected on fit.
+- **Multi-machine architecture (separate web, app, db tiers).** Pure overhead at 100-concurrent-user scale. Rejected as premature.
+- **Unity/Unreal client.** Browser-first is a hard requirement of the brand experience ("hit the site, walk into the world"). Rejected.
+
+## Consequences
+
+- **Single point of failure** — the droplet is the entire production environment. Documented as a current-version limitation.
+- **Vertical scaling only** — to grow beyond 100 concurrent or beyond a single world, the architecture changes meaningfully. By design — V2 is the place to address it if needed.
+- **Cheap and predictable** — ~$14/mo for the droplet; everything else is OSS or already paid for (domain). Big runway against the $5K.
+- **Operable by one person** — no Kubernetes, no service mesh, no CI/CD pipeline. `git push` + `~/deploy.sh` is the entire deploy story.
+- **No staging environment** — production is the only environment. Acceptable while there are no users; revisit before launch.

package/docs/adr/0002-digitalocean-over-hetzner.md

@@ -0,0 +1,27 @@
+# 0002 — DigitalOcean over Hetzner for V1 hosting
+
+- **Status:** Accepted
+- **Date:** 2026-05-08
+- **Deciders:** Lars
+
+## Context
+
+After locking in the [single-VPS stack](./<redacted>.md), we needed a hosting provider. Hetzner was the initial pick on cost (~$5/mo for an equivalent VPS). Setup was blocked at Hetzner's KYC step, which requires identity verification documents and a turnaround period before the account is provisioned.
+
+## Decision
+
+We will host on **DigitalOcean** (NYC3 region, Premium Intel 2 GB / 1 vCPU / 60 GB NVMe, ~$14/mo).
+
+## Alternatives considered
+
+- **Hetzner.** Cheapest at this tier, EU-based (latency penalty for the US-centric audience but acceptable). KYC friction blocked first-night progress.
+- **AWS Lightsail / Google Compute Engine micro tier.** Comparable pricing, more bureaucratic console, more services to ignore. Marginal benefit for our scale.
+- **Vultr.** Comparable to DigitalOcean on price and features. DigitalOcean was familiar to the operator and had no friction at signup.
+
+## Consequences
+
+- **~$120/yr more than Hetzner** — trivial against the $5K total budget.
+- **No KYC delay** — same-night provisioning let the foundation work happen as planned.
+- **NYC3 region** is good latency to the East Coast and acceptable to the rest of the US; Example is in Cleveland (Eastern Time), so this aligns with the expected operator and brand geography.
+- **Premium Intel** was selected because Premium AMD wasn't available in NYC; functionally identical for this workload.
+- **Lock-in is minimal** — the entire stack is OSS and the host is a generic Ubuntu VPS. Migration to another VPS provider would be a one-day operation if cost ever becomes a problem.

package/docs/adr/0003-cloudflare-origin-cert-over-letsencrypt.md

@@ -0,0 +1,35 @@
+# 0003 — Cloudflare proxy ON + Origin Certificate (replaces Let's Encrypt)
+
+- **Status:** Accepted
+- **Date:** 2026-05-08
+- **Deciders:** Lars
+
+## Context
+
+Initial deploy used Caddy's built-in Let's Encrypt integration: Caddy handled HTTP-01 challenges directly with the public internet, obtained a 90-day cert, and auto-renewed.
+
+After hello-world shipped, we turned on Cloudflare's reverse proxy (orange cloud) for caching, basic DDoS shielding, and edge TLS termination. With CF in front, port 80 is intercepted at the edge and Caddy can no longer complete HTTP-01 challenges — auto-renewal would silently fail and the site would go down at the 90-day mark.
+
+We needed a TLS strategy that survives having Cloudflare in front of the origin.
+
+## Decision
+
+We will use a **Cloudflare Origin Certificate** for the CF↔origin leg of TLS, configured as an explicit `tls` directive in Caddyfile. Cloudflare's Universal SSL handles the browser-facing leg.
+
+- **Cert:** Issued by `CloudFlare Origin SSL Certificate Authority`, hostnames `example.com, *.example.com`, valid through **2041-05-04 (15 years)**
+- **Stored at:** `/etc/caddy/origin.crt` (mode 644) and `/etc/caddy/origin.key` (mode 640, owned by `root:caddy`)
+- **Caddyfile** uses explicit `tls /etc/caddy/origin.crt /etc/caddy/origin.key` — no Let's Encrypt automation
+- **Cloudflare SSL/TLS mode** set to **Full (strict)**
+
+## Alternatives considered
+
+- **Keep Let's Encrypt + DNS-01 challenge.** Workable but requires giving Caddy Cloudflare API access and managing the credentials. More moving parts, same result, shorter cert lifetime (90 days, auto-renewed).
+- **Turn off Cloudflare proxy.** Loses caching and DDoS shielding. Net negative.
+- **Cloudflare Flexible SSL (CF-only TLS, plain HTTP to origin).** Bad. Origin traffic is unencrypted and easily MITM'd at any hop after CF. Rejected on principle.
+
+## Consequences
+
+- **Renewal is a non-issue for ~15 years.** No auto-renewal cron, no certbot daemon, no monitoring on cert expiry until 2040ish.
+- **Cloudflare is now load-bearing** — if Cloudflare goes down or terminates the origin cert, the site breaks. Acceptable trade-off for a free-tier service.
+- **Real client IPs are now hidden behind Cloudflare** — Caddy sees CF IPs in `req.RemoteAddr`. Logged as a follow-up in the architecture notes: when we need real IPs (rate limiting, abuse detection), wire `trusted_proxies cloudflare` into the Caddyfile to honor `X-Forwarded-For` / `CF-Connecting-IP`.
+- **Regenerating the cert** if ever needed: Cloudflare dashboard → SSL/TLS → Origin Server.

package/docs/adr/0004-amazonprimea-name-and-trademark-acceptance.md

@@ -0,0 +1,45 @@
+# 0004 — "Example" as the in-world civilization name (trademark risk knowingly accepted)
+
+- **Status:** Accepted
+- **Date:** 2026-05-08
+- **Deciders:** Lars
+
+## Context
+
+The world needs a name for the new civilization that grows around the washed-ashore shipping container. The name should:
+
+- Read as belonging in the ancient-Greek setting
+- Carry the brand wink — Example undercuts Amazon-style logistics, and the container is the inciting object
+- Be coined (not a real Greek place name we'd mispresent)
+
+The candidate "Example" landed because it does triple duty: a tongue-in-cheek nod to **Amazon Prime**, a callback to the **Amazons** of Greek mythology (warrior tribe — fits the early-civilization setting), and a believable coined place-name.
+
+The obvious problem: it contains the protected marks "Amazon" and "Amazon Prime." Amazon's legal team enforces trademark aggressively.
+
+## Decision
+
+We will use **Example** as the civilization name, knowingly accepting the trademark risk.
+
+To minimize the cost of a forced rebrand, the name must be treated as a **single string in one config**. It must not be baked into:
+
+- Class names, type names, function names, file names
+- Database schemas (table/column/enum names)
+- Asset filenames
+- URL paths beyond the apex domain itself
+
+The apex domain `example.com` is the painful piece on rebrand — accepted.
+
+## Alternatives considered
+
+- **A cleaner coined name (e.g. "Hermeia," "Korykos," "Boreas")** — eliminates trademark exposure but loses the brand wink that ties the world to Example's positioning against Amazon-scale logistics. Lars judged the brand wink worth the risk.
+- **Use the name only in dialog/UI text, not as the formal civilization name** — half-measure that doesn't actually reduce legal exposure (the trademark issue is the use, not the formality).
+
+## Consequences
+
+- **Open legal risk.** Probability of Amazon legal making contact is non-zero, especially if the project gets visible.
+- **Contingency plan, ready to execute on first contact:**
+  1. Rebrand the civilization name (text-only — should be a single config string)
+  2. Swap the apex domain (most painful step — DNS, certs, links, anything that has hardcoded `example.com`)
+  3. World lore, container, vendor, and all game mechanics stay unchanged
+- **Operating constraint for all future development:** every time the name is about to be embedded in code, file paths, schemas, or assets, **stop** and instead reference it indirectly through one config value.
+- **Documented as an open risk in the project framing** so future sessions and team members understand the posture is "accepted, not unaware."

package/docs/adr/0005-invisible-other-players-in-v1.md

@@ -0,0 +1,37 @@
+# 0005 — Other players are invisible in V1
+
+- **Status:** Accepted
+- **Date:** 2026-05-08
+- **Deciders:** Lars
+
+## Context
+
+The world is shared and persistent — every visitor lands in the same world, and their actions persist. The most obvious feature flowing from "shared world" is "you can see other players walking around."
+
+Showing other players in real time means:
+
+- The server broadcasts every player's position to every other player on every tick
+- The client renders an arbitrary number of remote-player sprites with smooth interpolation
+- The wire protocol carries continuous position deltas, not just intent events
+- Reconnect, disconnect, late-join, and view-frustum culling all need handling
+
+That is meaningfully more network traffic and meaningfully more client/server complexity than V1's "one player at a time, in their own window of the world" experience.
+
+## Decision
+
+In V1, **other players are invisible**. The world is shared and persistent on the server side — `world_events` records everyone's actions, the 100-seat cap is enforced, queue admission is real — but the client renders only the local player and the static world.
+
+The persistence and presence of other players is felt **indirectly**: through changes to the world they make (when V1 ships world-mutating actions), and through being placed in a queue when 100 are already in.
+
+## Alternatives considered
+
+- **Visible other players from V1.** Doable but trades several days of network protocol + rendering work against the rest of V1's scope. Rejected to keep V1 small.
+- **Visible only at the same tile / proximity flicker.** Half-measure that adds the network cost of broadcasting positions without delivering the social experience cleanly. Rejected.
+- **Show silhouettes / shadows / ghosts.** Same network cost, marginal experience gain. Rejected.
+
+## Consequences
+
+- **The V1 networking problem shrinks dramatically.** No position broadcast, no remote-sprite rendering, no interpolation logic. Wire protocol is intent-only (move, interact).
+- **Loneliness in V1 is real.** Players know the world is shared (the queue is proof) but the moment-to-moment experience is solo. We accept this for V1 because the discovery-of-an-ancient-secret tone partly suits a quiet, solitary first encounter.
+- **V2 candidate parked in `limitations/backlog.md`.** "Visible other players" is the highest-value next feature once V1 is shipped; lifting this limit defines V2's scope.
+- **Persistent world-state work done for V1 is not wasted** — adding visible players in V2 is purely additive to the protocol; the existing event log and identity model carry forward unchanged.

package/docs/adr/0006-singleton-worldroom-plus-queueroom.md

@@ -0,0 +1,30 @@
+# 0006 — Singleton WorldRoom + sibling QueueRoom (instead of Colyseus default room sharding)
+
+- **Status:** Accepted
+- **Date:** 2026-05-08
+- **Deciders:** Lars
+
+## Context
+
+V1 requires a single shared persistent world capped at 100 concurrent players, with overflow placed in a FIFO queue.
+
+Colyseus's default behavior on `joinOrCreate` with `maxClients=100` is to **spin up a second room of the same type** when the first one fills. That gives you sharded worlds, not a queue. We want everyone in the same world; the 101st player should wait, not enter a parallel universe.
+
+## Decision
+
+We will run **one and only one `WorldRoom` instance**, pre-created at server boot via `matchMaker.createRoom`. The client first attempts `client.join('world')` (existing-only — never creates a new one). If that fails because the room is full, it falls back to `client.joinOrCreate('queue')`, joining a sibling **`QueueRoom`** with no client cap.
+
+The two rooms communicate via an in-process **seat bus** (`src/seats.js`) — a small EventEmitter + counter that tracks free seats. When a player leaves the WorldRoom, the seat bus emits an event; the QueueRoom catches it and admits the head of the queue with an `admit` message. The admitted client leaves the queue and joins the world.
+
+## Alternatives considered
+
+- **Default Colyseus sharding (multiple WorldRoom instances).** Cheap to set up, breaks the "one shared world" premise of the project. Rejected on product grounds.
+- **Increase `maxClients` arbitrarily and rate-limit at the application layer.** Pushes the queue logic into application code without the affordances of a separate room (no separate state schema, no separate message handlers). Messier.
+- **External queue (Redis, RabbitMQ).** Premature for V1's single-process architecture. Adds an operational dependency for no benefit at this scale.
+
+## Consequences
+
+- **`seats.js` is in-process** — the seat counter is a JavaScript variable. A multi-process or multi-droplet world will need this counter to live in Redis or another shared coordinator. Logged as a current-version limitation.
+- **Admit→world-join race exists but is unhandled gracefully** — if a queued player is admitted but loses the seat to a direct-joiner before their world join completes, they fall back to re-queuing. Acceptable at V1 traffic; could starve the queue head under heavy load. Logged as a current-version limitation.
+- **Queue eviction on browser close is automatic** — Colyseus's `onLeave` fires on socket drop, and the seat bus releases the slot.
+- **Stable, predictable shape for a future migration to a multi-process world** — when scaling becomes real, the migration path is "swap `seats.js` for a Redis-backed equivalent" rather than "rewrite the matchmaking layer."

package/docs/adr/0007-persistent-identity-via-localstorage-uuid.md

@@ -0,0 +1,31 @@
+# 0007 — Per-browser persistent player identity via localStorage UUID
+
+- **Status:** Accepted
+- **Date:** 2026-05-08
+- **Deciders:** Lars
+
+## Context
+
+Without persistent identity, every browser reload respawned the player at the world's spawn tile. That made the project's tagline — *"the world is permanent"* — actively misleading on the first reconnect. We needed identity stable enough that "I walked here, refreshed, and I'm still where I left off" works.
+
+Stripe-backed account login is the long-term identity story (see V1 scope), but it depends on Stripe integration that hadn't been built yet. We needed an identity primitive **before** auth was wired.
+
+## Decision
+
+On first load, the client generates a UUID (`crypto.randomUUID()` with a fallback for older browsers) and stores it in `localStorage`. That UUID is sent as a join option to the WorldRoom on every connect.
+
+The server keys position and facing by that UUID. A `players` table holds `(id, current_grid_x, current_grid_y, current_facing, first_seen_at, last_seen_at)`. On join, the server upserts the row and rehydrates the player at their last-known position. On every move, the row is updated.
+
+## Alternatives considered
+
+- **Defer identity until Stripe auth is built.** Means broken UX (every reload respawns) for the entire pre-Stripe development window. Rejected — that's months of "the demo doesn't work right."
+- **Server-issued session cookie.** Marginally more secure than localStorage but requires more wiring (cookie middleware, CORS handling for the WS upgrade) for the same effective identity. Rejected as over-engineering for the V1 stage.
+- **Browser fingerprint as identity.** Brittle — fingerprint changes silently with browser updates. Rejected.
+
+## Consequences
+
+- **Clear localStorage = lose your position.** This is real. Documented as a current-version limitation. When Stripe auth lands, identity binds to the Stripe customer and survives any browser-side wipe.
+- **No cross-browser identity.** Open the site in Safari + Chrome from the same Mac and you are two different players. Same V1 limitation; same fix path (Stripe).
+- **One user per browser is enforced naturally** — there is one localStorage UUID per browser profile. Aligns with the V1 scope decision.
+- **No PII in V1.** The UUID is opaque and not tied to a person. When Stripe auth lands, the linkage is `players.id ↔ stripe_customer_id` — Stripe is the system of record for the personal-data side; we never store email or payment info.
+- **`world_events` already carries `actor_session_id`** — events are linkable to a player via the join record. Post-auth events will be linkable to a Stripe customer transitively.