@bongos/core 1.17.0

package/docs/adr/0008-family-based-tile-generation.md

@@ -0,0 +1,86 @@
+# 0008 — Family-based tile generation with deterministic-first review
+
+- **Status:** Accepted
+- **Date:** 2026-05-09
+- **Deciders:** Lars
+- **Supersedes (in part):** the per-tile generation flow described in the Phase-1 pixel-art pipeline (see [docs/recipes/pixel-art-pipeline.md](../recipes/pixel-art-pipeline.md)), which remains in service for atomic tiles that have not yet been migrated.
+
+## Context
+
+The first pixel-art pipeline ([§7 of CLAUDE.md](../../CLAUDE.md), the original `art/pipeline/orchestrator.py`) generates one tile per call. Each call to the image API has no memory of any other call. This worked acceptably for unrelated atomic tiles (a rock, a single olive tree) but failed structurally for any tile-set whose members must visually cohere:
+
+- The 4-direction player sprite produced **four different-looking characters** — different body sizes, different clothing colors, different hair. Worst-case pairwise palette overlap was 0.29; worst-case dominant-color overlap was 0.00; silhouette pixel counts ranged from 177 to 900 across the four directions.
+- The vendor was likewise produced as an unconnected one-off.
+- Transition tiles (grass-to-sand edges) and any future autotile path / road / border family would have failed the same way: tiles that *must* line up at seams cannot be generated independently and expected to fit.
+
+The review system was scoring tiles in isolation against a 9-criterion rubric. None of the criteria measured cross-tile coherence. A tile could earn 9.5/10 individually while being entirely incompatible with its declared neighbors.
+
+We needed an architecture that:
+
+1. Forces sibling tiles to be drawn together so they share a single style anchor.
+2. Mechanically validates that adjacent tiles match at their edges (and that character frames depict the same individual).
+3. Reduces — not increases — total cost per produced tile.
+4. Lets Lars approve atomic-swap publish before any tile lands in `art/generated/tiles/`.
+5. Stays inside the per-project $80 cap ($79.96 remaining at the time of this ADR).
+
+## Decision
+
+Make the **family** — not the tile — the unit of generation.
+
+A *family* is a coordinated set of members produced as a single image-gen call against a layout grid. Members are sliced out of the returned sheet and post-processed individually.
+
+Concretely:
+
+- New schema: `art/template/families.json`. Each family declares `kind`, `layout`, `members[]`, `shared_style`, and optional per-family threshold overrides. Defaults inherit from a top-level `defaults` block.
+- New pipeline modules under `art/pipeline/`:
+  - `family_loader.py` — schema loading with defaults inheritance.
+  - `family_generator.py` — sheet prompt builder, single-call generation, slicer + post-process.
+  - `family_checks.py` — deterministic family-level coherence checks (silhouette area / height CV, palette Jaccard, dominant-color overlap, luminance EMD, self-seam, edge contracts).
+  - `family_review.py` — Gemini family-coherence review, scored on family-level criteria (`family_consistency`, `character_identity`, `grid_alignment`, `firered_match`, `mythic_greek`).
+  - `family_orchestrator.py` — full retry loop with anchor-refinement on failure.
+- Review ordering: **deterministic checks run first. The Gemini review only runs if they pass.** Failures produce numeric fix-hints fed back into the next prompt.
+- Publishing is gated behind an explicit `--publish` flag — never automatic. Atomic-swap into `art/generated/tiles/` only happens when Lars approves.
+- The old per-tile pipeline is left in service for the 22 atomic tiles that have not yet been migrated. Migration happens family by family as we rebuild the affected zones.
+
+The first family migrated was `player_character` (4-direction sprite, 2×2 layout, 7.0/5.0 thresholds). Result: **passed in one attempt**, Gemini review 8.6→9.0/10, deterministic gate 5/5, total cost $0.078 across two runs (initial + publish run). All five coherence metrics improved by an order of magnitude versus the per-tile output.
+
+## Alternatives considered
+
+- **Keep per-tile generation, add a cross-tile coherence rubric criterion.** Rejected — no Gemini review can fix what's broken at generation time. The model has no way to draw "the same character" twice when called twice with no shared memory.
+- **Generate one canonical front-facing sprite, derive the other facings via prompt engineering.** Rejected — fragile, model-dependent, and can't generalize to non-character families like paths.
+- **Generate the whole tile-set in one giant sheet (all 23 tiles).** Rejected — the model cannot maintain coherence at that scale, and a single failure would invalidate every tile. Family granularity is the natural unit: small enough to coordinate, large enough to enforce sibling identity.
+- **Keep doing per-tile and live with the inconsistency.** Rejected on Lars's first feedback. The "four different characters" failure was visible in-game.
+- **Defer the architecture work and ship V1 with placeholder art.** Rejected — V1's brand promise depends on the world feeling crafted. Inconsistent characters undermine that on the first frame the visitor sees.
+
+## Consequences
+
+### Positive
+
+- **Sibling coherence is now generation-time, not review-time.** The model is forced to draw identity-consistent siblings; verification is bookkeeping.
+- **Cost per produced tile dropped.** One sheet call (~$0.04) replaces N independent calls (~$0.04 each) plus N independent Gemini reviews. Empirical: the player_character set produced for $0.04 instead of ~$0.16.
+- **Failure feedback is numeric and specific.** "Silhouette area CV 0.67 > 0.35, make the character the same size in every cell" is something the next prompt can act on. "Make the characters look more like the same person" was not.
+- **Per-family policy** lets us tune thresholds per family kind without code changes.
+- **Atomic-swap publishing** prevents half-migrated states. Old tiles stay live until the new family fully passes.
+
+### Negative / costs
+
+- **Higher prompt complexity.** Sheet prompts are longer and more constrained; small errors in the layout description waste an attempt.
+- **Sheet aspect ratio constrained by API wrappers.** Nano Banana's wrapper does not currently expose aspect-ratio control, so 1×N layouts are riskier than 2×2 / square layouts. We default to 2×2 for 4-member families until this is resolved.
+- **Schema migration must continue.** The 22 non-character tiles still live in the old `vocabulary.json` shape. Migration is incremental, not all-at-once. We carry both shapes during the transition.
+- **Threshold tuning is now its own ongoing task.** Per-family overrides need calibration data from real runs across kinds before defaults are trustworthy.
+
+### Operational rules adopted with this decision
+
+1. **The family is the unit of regeneration.** When a member of a family looks wrong, regenerate the whole family — never one cell — to preserve sibling coherence.
+2. **Deterministic checks run before Gemini.** No Gemini family-review call fires on a family that fails the deterministic gate.
+3. **Publish requires explicit human approval.** No `--publish` flag → no atomic swap into `art/generated/tiles/`.
+4. **Per-family threshold overrides live in `families.json`.** Code reads them; no ad-hoc threshold edits in pipeline modules.
+5. **Lowered thresholds during phase-1 are temporary.** The `_threshold_note` field on a family records the reason and the ramp condition. Ramp back to defaults after enough family runs to know the real ceiling.
+
+## What this does not change
+
+- The locked 64-color palette (see Phase-0 pipeline notes) remains authoritative. Palette-quantize still runs on every output cell.
+- The reference cluster overview (`art/template/cluster_overview.png`) remains the "what FireRed looks like" image passed to the reviewer.
+- The cost ledger (`cost_ledger.py`, $80 hard stop) remains the financial gate.
+- The style guide (`art/template/style_guide.md`) remains the durable accumulator of Lars's directional feedback. Sheet prompts continue to consume it.
+- The procedural fallback (`procedural_fallback.py`) remains available for ground-tile families. Character families have no procedural fallback; the recovery path is anchor-refinement instead.

package/docs/adr/0008-google-chat-oauth-user-auth.md

@@ -0,0 +1,37 @@
+# 0008 — Google Chat integration auth model: OAuth as the operator user
+
+- **Status:** Superseded by [ADR 0032](0032-discord-mirror-of-gds.md) (outbound) and [ADR 0033](<redacted>.md) (bot/inbound) — Google Chat fully retired 2026-06-05, replaced by Discord
+- **Date:** 2026-05-09
+- **Deciders:** Lars
+
+## Context
+
+The Google Chat broadcast integration needs to (a) post milestone updates to the Example team space and (b) read replies/reactions to surface them as feature requests. Google offers two distinct auth paths for the Chat API:
+
+1. **Service account / Chat App identity** — the integration speaks as a registered "bot" persona that's added to the space.
+2. **User OAuth** — the integration speaks as a real user (in our case `lars@example.com`).
+
+Both can read and post; the difference is whose name appears next to messages and reactions, and what setup is required.
+
+## Decision
+
+We will use **User OAuth (as `lars@example.com`)**.
+
+- OAuth client is a **Desktop application** type, registered under a Google Cloud project (`off-the-boats`) owned by `lars@example.com`.
+- The OAuth consent screen is configured as **Internal** (only `example.com` Workspace users can authorize), which skips Google's app-verification process.
+- A long-lived **refresh token** lives at `~/.config/otb/google-chat-token.json` on the operator's Mac (mode 600). The refresh token is exchanged for short-lived access tokens at runtime.
+- Posts and reactions appear under **Lars Kristensen** in the team chat. The team experience is "Lars is sharing build updates," not "a bot is talking."
+
+## Alternatives considered
+
+- **Service account with Chat App identity.** Cleanest separation (the bot is its own persona, posts under "Off the Boats Build Bot"). Requires registering the Chat App via Google Cloud's Chat API Configuration page, a "deployment ID," and Workspace admin permission to allow the service account into the space. More setup steps; the bot identity feels less personal for a small team chat where everyone knows Lars.
+- **Incoming webhook only (outbound, no auth dance).** Dramatically simpler — paste a URL, POST to it, message appears. Good enough for outbound milestone posts but **cannot read messages, threads, or reactions**. Rejected because the inbound feedback loop is half the value.
+
+## Consequences
+
+- **The team sees Lars as the source of every milestone post.** Friendly for a small team but means we should never post anything Lars wouldn't want under his own name. The posting rules in [`docs/google-chat-broadcast.md`](../google-chat-broadcast.md) explicitly limit content to player-visible outcomes in plain language.
+- **Reactions show as Lars's reactions.** When the integration acks a request with ✅, the team sees Lars reacting. Aligns with the "Lars relays team feedback to the build" mental model.
+- **Refresh token is a high-value secret.** Anyone with this file can post to the team chat as Lars and read everything Lars has access to in Google Chat. Lives at `~/.config/otb/google-chat-token.json` mode 600, never committed (`.gitignore` enforces). If ever leaked, revoke from [myaccount.google.com/permissions](https://myaccount.google.com/permissions) and re-run `scripts/chat/auth-once.js`.
+- **Refresh token does not expire** for Internal Workspace OAuth apps unless explicitly revoked. No periodic re-auth needed.
+- **Tied to one operator.** If Lars leaves the project (or example.com), the integration breaks. Acceptable for V1 — Lars is a single point of failure on much more than this. If/when the team grows, we can graduate to a service account, write ADR 0009 documenting the migration, and re-issue the integration as a bot identity.
+- **No Workspace admin involvement required.** Internal OAuth consent + Desktop OAuth client are both self-serve at the user level.

package/docs/adr/0009-autotile-architecture.md

@@ -0,0 +1,181 @@
+# 0009 — Autotile architecture: AI primitives + procedural compositor
+
+- **Status:** Accepted
+- **Date:** 2026-05-09
+- **Deciders:** Lars
+
+## Context
+
+V1 needs to render coherent terrain boundaries: grass islands within sand, sand
+beaches against shallow sea, marble flagstone paths through grass, cliffs.
+Earlier work in [ADR 0008](./<redacted>.md) established
+the family pipeline and produced beautiful single illustrations for continuous
+objects (containers, houses), but that pipeline could not produce a true
+autotile family — a set of tiles where every cell is a different topology
+(corner, edge, T-junction, etc.) that must connect cleanly with its neighbors
+in any combination.
+
+The stress test confirmed this: under continuous_illustration the 9-tile path
+autotile produced a "border tile set" (a square frame of flagstones) but lost
+the four-way cross and the topology variants a real autotile needs. The model
+is good at drawing single illustrations; it is not good at producing all
+distinct topology variants of a tile set as one image.
+
+We needed an architecture that:
+
+1. Produces all 47 (region) or 16 (path) topology variants for an autotile.
+2. Guarantees that adjacent tiles connect at their shared seams.
+3. Lets the model do what it is good at (texture appearance) without asking
+   it to do what it is bad at (tile-set topology).
+4. Stays cheap (the project budget is $80, currently ~$2.50 spent).
+5. Produces output that integrates with the runtime tile picker in Phaser.
+
+## Decision
+
+We will use **AI-generated primitives + procedural composition** for autotile
+families.
+
+For each autotile family, the AI generates 3–5 small primitive textures:
+
+- For region families (47-blob): an interior texture, an exterior texture,
+  and three boundary patches (horizontal-edge, concave-corner, convex-corner)
+  in their NW orientation.
+- For path families (16-path): a surrounding-terrain texture, a path node,
+  and a path arm.
+
+A pure-Python compositor (`art/pipeline/autotile_compositor.py`) then composes
+all 47 (or 16) tiles by deterministic per-quadrant masking. Each 32×32 tile is
+divided into 4 quadrants of 16×16; each quadrant's content is determined by
+3 input bits (one edge each side, plus the corner) which select among 5 patch
+types (interior, concave, horizontal edge, vertical edge, convex). Patches
+are flipped or rotated for non-NW quadrants.
+
+**Edges match by construction.** Every tile that has the same edge configuration
+samples its boundary pixels from the same primitive at the same logical
+position. So when two such tiles sit next to each other in the world, the
+seam pixels are guaranteed identical to within bounded jitter.
+
+Two standard autotile schemes are implemented:
+
+- **47-blob** (RPG Maker A2 / Cr31 / Tiled "terrain" mode standard) for
+  region terrain. 8-neighbor with corner-mask reduction. The corner-mask
+  rule: a corner-neighbor bit is meaningful only if both adjacent edges
+  are also same-terrain (otherwise the boundary along the edge occludes
+  the corner). This collapses 256 raw neighbor configurations to 47
+  distinct tiles.
+
+- **16-path** for line/path terrain. 4-cardinal-only. Each path tile is
+  identified by which of the 4 cardinal neighbors are also part of the
+  same line (path/road/wall/fence). Direct identity: tile_idx == bitmask.
+
+A new family kind in `families.json` (`autotile_blob_47` / `autotile_path_16`)
+declares the family's primitives. A new orchestrator
+(`art/pipeline/autotile_orchestrator.py`) generates the primitives via the
+existing AI pipeline and calls the compositor.
+
+Texture-style primitives (interior/exterior/terrain) get an additional
+seamless-enforcement post-step: the leftmost and rightmost columns of pixels
+are averaged to a single column applied to both, and the topmost and
+bottommost rows likewise. After re-quantizing to the locked palette, the
+texture tiles seamlessly with itself — proven by the validation harness
+(100% edge-match on all-interior compositions).
+
+The runtime tile picker is split-implementation:
+- `art/pipeline/autotile_mapping.py` (Python) — used by the compositor
+- `public/game/world/autotile.js` (JavaScript) — used by the in-game renderer
+- Cross-verified at build time: both produce identical tile indices for all
+  256 neighbor configurations.
+
+## Alternatives considered
+
+- **AI generates the whole tile set in one image (continuous_illustration
+  scaled up).** Rejected on stress-test evidence — the model produces a
+  coherent illustration but not the topology variants a real autotile needs.
+- **Cell-by-cell with image-conditioning anchors** ("Strategy A" in the
+  Pattern-C plan: generate tile 1, generate tile 2 with tile 1's matching
+  edge as a reference image, etc.). Rejected for V1 on cost (47 sequential
+  generations per family) and reliability (model interpretation of edge
+  references is fragile). Kept as a fallback if the primitives approach
+  fails for a specific family.
+- **Hand-paint each of the 47 tiles.** Rejected — V1 has no artist budget;
+  the bootstrapping spirit of the project demands a self-driving pipeline.
+- **Hand-paint a 5×3 RPG-Maker template (15 quadrants) and derive the 47
+  tiles by composition.** Equivalent quality but more manual and less
+  flexible than primitives + compositor. Skipped.
+- **Wang tiles (corner-coded) instead of blob47.** Equivalent expressive
+  power; 16 corner-coded tiles vs 47 blob tiles. Rejected because the
+  corner-coded approach forces every boundary to bend at the corner
+  (no smooth straights), which doesn't match the FireRed visual aesthetic.
+- **Skip cliffs.** Considered. Tried anyway as an experiment. Result: the
+  47-blob produces topologically correct cliff regions but stylistically
+  weak — real cliffs need direction-specific tiles (south face very
+  different from north). Documented as a Phase-D limitation; if V1 ships
+  cliffs, they need a follow-up direction-aware scheme.
+
+## Consequences
+
+### Positive
+
+- **All 47 (or 16) tiles produced from 3–5 primitive generations.** Cost per
+  autotile family is ~$0.25–0.45 vs ~$1.88 if we hand-generated each tile.
+- **Edges match by construction.** No retry loop needed for seam alignment.
+  The 100% edge-match score on all-interior compositions proves it.
+- **Standards-compliant.** Anyone familiar with RPG Maker A2, Tiled
+  "terrain" mode, or Cr31's blob convention can read the bitmask code
+  without learning a custom scheme.
+- **Renderer is data-driven.** World map stores terrain ids; runtime picks
+  tile indices via lookup. Shape change (region → autotile) is a swap of
+  the picker function.
+- **Single source of truth** for the lookup table. Python and JS
+  cross-verified at build time.
+
+### Negative / costs
+
+- **Direction-asymmetric terrain** (cliffs, where the south face looks
+  different from the north) is poorly served by 47-blob. Documented
+  limitation — cliffs ship as best-effort with stylized "shelf" look or
+  defer to V2 with a direction-aware scheme.
+- **Boundary tiles are stylistically coherent but not pixel-perfect at
+  every seam.** The corner and edge primitives are independently generated
+  and don't perfectly match each other at every transition. Acceptable for
+  V1; producing pixel-perfect transitions would require generating boundary
+  primitives in pairs with image conditioning. Defer to V2.
+- **Multiple autotile families against the same neighbor terrain** require
+  per-family primitives. We can't share an "edge between grass and sand"
+  primitive between grass_on_sand and sand_on_grass. Acceptable — terrain
+  pairs are a finite, small set in V1.
+- **Triple-junctions** (where 3 terrains meet at one tile) are not
+  representable. Standard autotile schemes punt on this; we forbid triple
+  junctions in level design. V1 world is small enough this isn't binding.
+- **Runtime data-model refactor required.** `src/world/map.js` and
+  `public/game/world/map.js` currently store tile ids. They need to store
+  terrain ids and let the runtime call the autotile picker. This refactor
+  is in V1 scope but is risky enough that it ships in a separate PR after
+  this ADR (kept as a pending Phase D in the rollout).
+
+### Operational rules adopted with this decision
+
+1. **Texture-role primitives** (interior, exterior, terrain) get the
+   seamless-enforcement post-step automatically. No exceptions.
+2. **Boundary primitives** (concave/convex/horiz patches) are generated
+   in their NW orientation only. The compositor flips/rotates them.
+   Don't generate per-orientation copies.
+3. **Per-tile sample variation** (jitter into the interior primitive based
+   on tile coordinates) is a Phase-V2 nice-to-have. Phase B–D ships without
+   it; expect visible repetition in large interior fields.
+4. **Atomic-swap rule still applies.** Autotile output sits in
+   `art/iterations/_autotile/<family>/` until Lars reviews and approves
+   atomic-swap into `art/generated/tiles/`.
+5. **Cross-verification of Python/JS tables** is a smoke-test gate. If the
+   tables disagree, the build fails. Single source of truth is the rule
+   in autotile_mapping.py; autotile.js is generated to match.
+
+## What this does not change
+
+- The locked 64-color palette is still authoritative.
+- The cost ledger ($80 hard stop) still gates all generation.
+- The per-tile pipeline still serves the 22 atomic non-autotile tiles
+  (grass_base, sand_base, container_door, etc.) until/unless those are
+  also migrated to autotiles.
+- The family pipeline (ADR 0008) still serves character families and
+  multi-tile object families. Autotiles are an addition, not a replacement.

package/docs/adr/0010-pms-architecture.md

@@ -0,0 +1,70 @@
+# 0010 — Project management system: schema-first, same-process, GitHub-auth, two surfaces
+
+- **Status:** Accepted
+- **Date:** 2026-05-09
+- **Deciders:** Lars
+- **Addendum (V3.R01, 2026-05-13):** "PMS" was renamed to "GDS" (Game Development System) when V3 opened the system to multiple builders. Folder/route/env-var renames: `src/pms/` → `src/bongos/`, `scripts/pms/` → `scripts/gds/`, `/api/pms/*` → `/api/gds/*`, `PMS_GITHUB_*` → `GDS_GITHUB_*`, `PMS_API_BASE` → `GDS_API_BASE`, `pms_session` cookie → `gds_session`, `~/.config/otb/pms-session.json` → `~/.config/otb/gds-session.json`. The version ID `PMS-V3` was also renamed to `GDS-V3` (migration `<redacted>.sql` rewrites `versions`, `tasks`, `done_when_criteria`, `idea_inbox`, plus the `pms-shipper` achievement → `gds-shipper`). Future internal-track versions ship as `GDS-V4`, `GDS-V5`, etc. The version IDs `PMS-V1` and `PMS-V2` are NOT renamed — those versions shipped under those names and their archives in `limitations/pms-v*-shipped.md` are immutable historical records.
+
+  V3.R01 also introduced a transitional `/api/pms/* → /api/gds/*` redirect surface (301 for GET/HEAD, 308 for POST/PATCH/DELETE) so old skill files and cached browser clients would keep working through the rollout. **V3.R01-followup ([#308](https://example.com/builders#/task/308), 2026-05-13) removed that redirect surface** after a repo audit confirmed no caller still hits the legacy path; `/api/pms/*` is now a 404. The read-side back-compat for the `pms_session` cookie, `PMS_GITHUB_*` env vars, and the `~/.config/otb/pms-session.json` file path **continues** (in `src/bongos/auth.js` and `scripts/gds/cli-lib.js`) — those are independent of the URL surface and protect existing local sessions.
+
+  The body of this ADR is preserved unchanged as the original 2026-05-09 decision record.
+
+## Context
+
+The project is structured to be built across many parallel Claude Code sessions, sometimes overnight, sometimes by future human collaborators. To make that work without git merge conflicts and without re-deriving "what's left" every session, we need a real project management system — not a markdown work-board.
+
+Lars wants two surfaces:
+
+1. **`/builders`** — private, gamified workspace for prompt engineers. Lists claimable tasks with explicit parallel-safety, awards in-game credits (1 USD = 1 credit, cash-equivalent), shows leaderboard.
+2. **`status.example.com`** — public dashboard for team, investors, and customers. Cost-vs-value charts, version progress, completed-work feed.
+
+Both surfaces share one task/cost/credit ledger.
+
+The system also needs to run inside Claude Code itself — slash commands so a session can claim, ship, and release tasks without leaving the terminal.
+
+## Decision
+
+Build the GDS as a parallel internal track ("PMS-V1") on top of the existing single-droplet stack, with a Postgres-first schema, same-process API and web UI, GitHub OAuth for builder identity, and atomic claim safety enforced at the database layer.
+
+**Key choices:**
+
+1. **Database in existing Postgres 16, new migration `003_pms.sql`.** No new database server. New tables (`builders`, `versions`, `tasks`, `claims`, `cost_log`, `credit_log`, `builder_sessions`, `session_logs`) live alongside `world_events` / `players` in the `example` DB. Same backup story (when backups land), same auth (peer Unix socket).
+
+2. **API in the existing Node/Express process.** New module tree under `src/pms/` mounted at `/api/pms/*`. No new deploy unit, no new systemd service, no new port. Restart cost: same ~2 seconds as a game-server change.
+
+3. **GitHub OAuth for builder identity, two flows:**
+   - **CLI** (Claude Code slash commands): GitHub **Device Flow**. No callback URL, no local HTTP server, friendly in a terminal. The CLI gets a verification code, the user pastes it into github.com/login/device, the CLI polls until approved, receives a GitHub access token, and exchanges it with our API for a long-lived session token stored at `~/.config/otb/pms-session.json`.
+   - **Web** (`/builders`): standard GitHub OAuth Authorization Code flow with callback to `https://example.com/builders/auth/github/callback`. Sets a session cookie scoped to `/builders`.
+   - Both flows produce the same `builder_sessions` row keyed by GitHub user ID. A builder using both surfaces is one builder.
+
+4. **Atomic claim safety at the DB layer.** A partial unique index on `claims (task_id) WHERE released_at IS NULL` makes it physically impossible for two sessions to hold an active claim on the same task. The race goes to whichever transaction commits first; the loser gets a clean constraint violation and picks another task. No application-layer locking, no Redis.
+
+5. **Parallel-safety via `tasks.touches[]` (text array of file/folder paths).** The `claimable_tasks_for_builder()` function returns only tasks whose `touches` array does not overlap with any currently-active claim's task. The builder never has to compute this themselves — the API tells them what is safe to claim *right now*.
+
+6. **Two web surfaces, one process.** `/builders` lives on `example.com`. `status.example.com` is a new Caddy site block on the same droplet, same Node process. Cloudflare DNS gets a new `status` record. The status site is server-rendered HTML + Chart.js, public, no auth, edge-cached.
+
+7. **Server-rendered HTML + small JS for live polling.** Both surfaces. No SPA framework. Polling interval 5 seconds for active claims; status site polls only on user action. This matches the project's existing static-page style and keeps the asset bundle tiny.
+
+8. **Cash-equivalent credits, but redemption is gated.** Phase 1 ships the credit ledger and leaderboard only. No "redeem" button, no transfer mechanism, no payout flow. Before any redemption ships (anywhere from Phase 3 onward), Lars consults a CPA on tax handling and a lawyer on securities/AML posture. The DB is designed to support either path (transfer-only-into-game-currency or cash-equivalent) — the legal posture decides which gets wired up.
+
+9. **Strategic markdown stays.** `current-version.md`, ADRs, learnings, and blockers remain markdown — they are documents, not work units. **Backlog/work tracking moves into the DB.** `limitations/backlog.md` becomes a frozen snapshot for archival once the import script runs; future backlog edits happen via API. `generative-ideas.md` stays as the no-shape capture inbox.
+
+## Alternatives considered
+
+- **Linear or GitHub Issues for internal tracking + a custom public status page.** Cheaper to operate (no schema to maintain). Rejected because the gamification (credits, leaderboard, themed builder profile) and the CLI integration (claim from inside Claude Code) are core to Lars's vision and would be awkward bolted onto Linear's webhooks.
+- **Separate microservice for the GDS.** Cleaner boundary, but adds deploy complexity, doubles the systemd unit count, and adds latency between the game server and the GDS API. Rejected — the V1 budget posture says "one process until we have to split."
+- **Application-level locking for claims (Redis or in-process).** Works, but adds a coordination layer that the existing single-Node-process architecture doesn't need. Rejected in favor of Postgres unique-constraint enforcement.
+- **JWT session tokens.** Slightly more "stateless" than DB-stored tokens, but adds a crypto dependency, key-rotation problem, and doesn't enable revocation. Rejected — random tokens in `builder_sessions` are simpler and revocable.
+- **No public status site at all (gamified internal only).** Rejected — Lars wants progress shareable with the team chat, supporters, and eventually players. The cost of `status.example.com` is one more Caddy site block + a few public-read endpoints.
+- **Defer cash-equivalent semantics until later.** Considered making Phase 1 store credits as opaque "points" with the cash equivalence decided later. Rejected — the schema cost is identical and "we'll decide later" tends to never decide. The decision is *cash-equivalent stored, redemption legally gated*.
+
+## Consequences
+
+- **Sessions can run in parallel safely.** Two sessions in two worktrees, each holding a claim with disjoint `touches[]`, will not stomp each other. The DB enforces it.
+- **One Lars-task to unblock Phase 2 web UI:** register the GitHub OAuth App and hand over Client ID + Secret. Tracked as a blocker.
+- **The system can self-bootstrap.** Once Phase 1 ships, all further GDS work is itself tracked in the GDS. The PMS-V1 track lives in `versions` as an entry alongside the game V1 track — internal track and product track run as siblings, sharing the same builder credit pool.
+- **Cost-vs-value charts depend on disciplined cost logging.** The `cost_log` table accepts entries from any source — the `art/iterations/cost_ledger.jsonl` import is one source; Anthropic API spend is another (manual until we have a real billing pipeline); droplet/Cloudflare/domain spend is a third. Phase 5 backfills.
+- **Legal/tax exposure exists the moment a non-Lars builder earns credits.** Mitigated by gating redemption — credits exist in the DB but cannot be exchanged for anything until the gate is cleared. Until that gate clears, credits are functionally a leaderboard score.
+- **Trademark posture extends into the GDS.** "Example" appears in URLs (`status.example.com`, `/builders`) and in builder profiles. Same operating rule as [ADR 0004](0004-example-name-and-trademark-acceptance.md): the civilization name is one config string. URLs are a separate decision; if the name has to change, the subdomain DNS record gets repointed and any in-DB strings that reference the name get re-templated.
+- **The methodology gets simpler from a session's perspective.** Today: read CLAUDE.md, read backlog, read blockers, cross-reference current-version, decide what to do. After Phase 1: `/builder-start` returns the answer.
+- **Session logs split.** Today the session log lives as prose in CLAUDE.md §13. Going forward, structured per-task session entries land in `session_logs` (queryable, charts-friendly), and CLAUDE.md §13 becomes a generated tail of the most recent few. Older prose continues to compress into `docs/session-log-archive.md`.

package/docs/adr/0011-terrain-id-rendering-model.md

@@ -0,0 +1,174 @@
+# 0011 — Terrain-id world map + dispatched render strategies (Phase D)
+
+- **Status:** Accepted; cell data model extended by [ADR 0012](./<redacted>.md)
+- **Date:** 2026-05-09
+- **Deciders:** Lars
+
+> **Update (same day):** [ADR 0012](./<redacted>.md)
+> splits the cell from one terrain id into two layers — ground (always
+> defined) + object (optional overlay). The dispatched render
+> strategies (`single` / `blob47` / `path16`) and the autotile cross-
+> verify gate from this ADR are unchanged; only the cell data model is
+> extended. Read 0012 for the current architecture.
+
+## Context
+
+[ADR 0008](./<redacted>.md) and
+[ADR 0009](./0009-autotile-architecture.md) established two new asset
+pipelines (family + autotile) but stopped at the asset boundary. The
+runtime renderer still treated the world as a flat 2D grid of tile-id
+strings: each cell stored a key like `'grass'` or `'container_door'`,
+`tilePalette.js` painted a single PNG per cell, and the door tile was
+literally one cell wide. Multi-tile objects had to be hand-laid in the
+map by repeating the same id, and autotile families had no way to
+contribute tiles at all — `selectBlob47` / `selectPath16` from
+[`autotile.js`](../../public/game/world/autotile.js) existed but nothing
+called them.
+
+ADR 0009 explicitly flagged this gap as **Phase D**, deferring the
+runtime data-model refactor to a separate change because it touches
+both the server's movement-validation map and the client's renderer.
+
+We needed:
+
+1. A world data model that can represent both autotile-driven terrains
+   (cells whose final tile depends on neighbors) and plain singletons
+   (vendor sprites, container panels) without the renderer having to
+   special-case each one.
+2. A way to ship the refactor before all autotile families are
+   generated, so the world keeps rendering when assets are missing.
+3. A single source of truth for "is this cell walkable?" that the
+   server uses for movement validation and the client honors for
+   prediction.
+4. Cross-verification that the JS runtime picker and the Python
+   compositor agree on tile selection — drift here means the renderer
+   would pick a different tile than the compositor produced and edge
+   matching breaks.
+
+## Decision
+
+Cells store a **terrain id**. The renderer dispatches per terrain to a
+**render strategy** declared in a single registry. Three strategies:
+
+- `single` — paint the texture registered as `tex_<game_key>`. Legacy
+  path; covers terrains we have not migrated to autotiles (sea, rock,
+  the 8 container panels).
+- `blob47` — query 8 neighbors, call `selectBlob47(myTerrain, neighbors)`,
+  paint `tex_at_<family>_<idx>` (PNG at
+  `/assets/tiles/autotile/<family>/<NN>.png`). Falls back to a declared
+  `fallbackTile` if the autotile family hasn't been generated yet.
+- `path16` — same shape but 4-cardinal-only and 16 tiles.
+
+The terrain enum, the render registry, and the walkability set live in
+two mirrored files:
+
+- [`public/game/world/terrain.js`](../../public/game/world/terrain.js)
+  (ESM, full version with autotile-picker helpers)
+- [`src/world/terrain.js`](../../src/world/terrain.js)
+  (CJS, narrow — only the enum and walkability set; the server doesn't
+  draw)
+
+Until the world becomes data-driven, these two MUST stay in sync. Same
+constraint and rationale as the existing two-copy `map.js`.
+
+The renderer's per-cell dispatch lives in
+[`tilePalette.js`](../../public/game/world/tilePalette.js) as
+`pickTextureKeyForCell(scene, grid, x, y)`, called from
+`WorldScene.drawMap()`. The 8-neighbor lookup uses `neighborsAt(grid, x, y)`
+from `terrain.js`. Off-grid neighbors resolve to `null`, which the
+"same as my terrain?" check naturally treats as exterior.
+
+The container is treated as a multi-tile placed object: each of its
+8 cells is a distinct terrain id (`CONTAINER_PANEL_TL` through
+`CONTAINER_PANEL_BR`). The map places them in row-major order at the
+container's anchor cell. All 8 are in `BLOCKING_TERRAINS`. The
+container family in [`families.json`](../../art/template/families.json)
+was respecced from 2×2 to 2×4 (door at bottom-left) so the family-
+pipeline output matches the in-game placement footprint without
+shrinking the building or moving the vendor.
+
+`wet_sand` was dropped from the data model. The tide-line foam now
+emerges from the `sand_on_sea` autotile boundary tiles — terrain is
+just `SAND` right up to where it meets `SEA`, and the autotile picker
+chooses the foam variant at the boundary. One less hand-tuned terrain
+in the map.
+
+A Python↔JS cross-verification smoke test
+([`tests/autotile_xverify.mjs`](../../tests/autotile_xverify.mjs) plus
+its emitter [`art/pipeline/autotile_xverify.py`](../../art/pipeline/autotile_xverify.py))
+asserts that all 256 blob47 inputs and all 16 path16 inputs map to the
+same tile index in both implementations. Wired into
+[`art/pipeline/smoke_test.sh`](../../art/pipeline/smoke_test.sh) so any
+drift fails the build.
+
+## Consequences
+
+### Positive
+
+- **One renderer for all terrain types.** Adding a new autotile family
+  is a families.json entry + a TERRAIN_RENDER row + a generation run.
+  No new render code per terrain.
+- **Phase D ships before the assets do.** Every autotile-strategy
+  terrain declares a `fallbackTile`. With zero autotile families
+  generated, the renderer falls back to the legacy single-tile PNGs and
+  the world looks identical to pre-Phase-D. Adding a family is a
+  visual-only change, not a code change.
+- **Walkability is a property of the terrain, not the tile artwork.**
+  The autotile picker can produce a foam-edge tile or a corner tile or
+  a fully-interior tile for the same `SAND` terrain, and movement
+  validation always says "sand is walkable." This decouples appearance
+  from gameplay rules.
+- **Cross-verify catches algorithm drift.** Any change to either
+  `autotile_mapping.py` or `autotile.js` that breaks parity fails the
+  smoke test. We can edit either side with confidence the other won't
+  silently disagree.
+- **Server-side terrain.js is narrow.** The CJS twin only carries the
+  enum and walkability — no rendering knowledge. Less surface to keep
+  in sync, less chance of accidental drift between server and client.
+
+### Negative / costs
+
+- **Terrain-id mirroring tax.** Two files (`src/world/terrain.js` and
+  `public/game/world/terrain.js`) must stay in sync. Same problem as
+  the existing two-copy map.js. Fix is the same: consolidate when the
+  map becomes data-driven from Postgres.
+- **Container placement is bound to the family layout.** Moving the
+  container to a different size (3-wide, 5-wide, etc.) means
+  re-speccing the family AND regenerating its art. We accepted this in
+  exchange for the family pipeline producing coherent multi-panel art.
+- **Per-cell autotile lookup at draw time.** `drawMap()` runs once per
+  scene init, not per frame, so the cost is trivial in V1. If the
+  world becomes large or partially streamed in the future, pre-baking
+  the lookups into a tile-index grid is a clean optimization.
+- **`fallbackTile` is a deliberate visual fib.** Until a family
+  generates, the renderer paints the same single PNG at every cell of
+  that terrain — no autotile boundaries appear. This is correct
+  behavior (Phase D ships before assets), but it means a partial
+  autotile rollout looks half-finished. Acceptable.
+
+### What this does not change
+
+- The server's movement validation in `WorldRoom.js` already calls
+  `isBlocked()` from `src/world/map.js`; that function now reads
+  `BLOCKING_TERRAINS` instead of `BLOCKING_TILES`. Same shape,
+  different source.
+- Vendor placement, dialog, and interact semantics are unchanged. The
+  vendor stands at (13, 9) — same cell as before, now typed as
+  `CONTAINER_PANEL_DOOR` instead of the old `container_door` tile id.
+- The cost ledger ($80 hard stop) and the rest of the art-pipeline
+  rules from ADR 0008 + 0009 are unchanged.
+- Per-tile families and autotile families coexist with legacy per-tile
+  vocabulary in `art/template/vocabulary.json` — `build_tilesheet.py`
+  emits one unified manifest that covers all three.
+
+## What this does not commit to
+
+- **No procedural-fallback shrinkage.** The procedural fallbacks in
+  `tilePalette.js` are the safety net when neither the family nor the
+  legacy PNG loaded. We could ship without them once the families and
+  the fallbacks are stable, but for V1 they cost nothing and make the
+  world resilient.
+- **No `wet_sand` regret.** If the `sand_on_sea` boundary tiles end up
+  too uniform (every tide cell looking identical), we can re-introduce
+  wet_sand as a dedicated terrain — it's a one-line addition to the
+  enum. Not blocking V1.