@bongos/core 1.17.0

package/docs/recipes/pixel-art-pipeline.md

@@ -0,0 +1,411 @@
+---
+scope: art *pipeline* (code, design system, review loops) — the tooling builders use to make tiles, plus the tile PNGs it produces that ship into `public/assets/tiles/`.
+---
+
+# Pixel-art generation pipeline — recipes and gotchas
+
+**TL;DR**: AI image models will NOT produce true 32×32 pixel art on demand. The pipeline survives this by post-processing every output (median-downsample → palette quantize → snap) and by falling back to procedural Python when the AI repeatedly misses the subject. Self-review via Gemini 2.5 Flash vision against a structured rubric is what makes the loop autonomous.
+
+## Critical recipes
+
+### Generating a 32×32 tile from Nano Banana / Imagen
+
+Both models output ~1024×1024. We don't ask for 32×32 directly — they ignore that constraint. Instead we:
+
+1. **Ask for "32×32 logical pixels rendered at 1024×1024"** in the prompt — i.e., each "logical pixel" should appear as a clear ~32-pixel block in the output.
+2. **Center-crop to a square** (Imagen sometimes pads).
+3. **Median-downsample by block** (32×32 blocks → one output pixel per block via `np.median`). NOT nearest-neighbor — too noisy. NOT bilinear — introduces AA.
+4. **Palette-quantize** every pixel to the nearest of the 64 colors in `modules/art-pipeline/template/palette.json`.
+
+Code: `modules/art-pipeline/pipeline/post_process.py:process()`.
+
+### When the AI refuses to produce the right subject
+
+Empirically, Nano Banana frequently generates **sand-colored textures even when prompted explicitly for grass**. Multiple retries with stronger prompts didn't help. Imagen 4 had similar failure modes but on different subjects.
+
+**The fix that worked**: a **Tier 5 procedural fallback** in `procedural_fallback.py`. For each common ground-tile id, we have a hand-coded Python generator that scatters palette colors at controlled density. Always palette-correct, always 32×32, always tileable. Score reliably ≥9 on objective criteria.
+
+The orchestrator escalates to T5 only after T1–T4 fail twice each. So we burn AI cost first (looks more authentic when it works), and fall back to procedural only when stuck.
+
+### Python TLS on macOS Python.org installer
+
+Default Python from python.org doesn't trust system CAs. `urllib.request` against Google APIs throws `CERTIFICATE_VERIFY_FAILED`. Fix: install certifi (`pip install --user certifi`) and pass an SSL context built from `certifi.where()`. See top of `gen_api.py` and `review.py`. **Windows:** native Windows Python usually trusts the system CA store, so this often isn't needed; if it is, run `py -m pip install certifi` (`python3`/`--user` semantics differ on Windows).
+
+### Output buffering during long runs
+
+Python's `print()` is line-buffered when stdout is a TTY but fully buffered otherwise. Long-running orchestrator runs show no live output unless launched with `python3 -u …` or `PYTHONUNBUFFERED=1`. Per-attempt state IS persisted to `modules/art-pipeline/iterations/<tile>/log.jsonl` regardless, so progress is observable even without live stdout. (**Windows:** `python3` is usually `py`/`python`; the `PYTHONUNBUFFERED=1 python3 …` inline-env form is bash-only — set it separately first: `set PYTHONUNBUFFERED=1` in cmd / `$env:PYTHONUNBUFFERED=1` in PowerShell, or just use `py -u …`.)
+
+## Structural insights
+
+### The reference clusters carry the style
+
+Slicing the 24 Pokemon FireRed reference maps on a 16×16 grid yields ~8,800 unique tiles. K-means on RGB histograms collapses them into 64 visual clusters. The **cluster overview sheet** (`modules/art-pipeline/template/cluster_overview.png`, 8×8 grid of representative tiles) is what we pass to the AI reviewer as the "what FireRed looks like" reference. It carries more style information than any prose description.
+
+Each vocab item in `vocabulary.json` lists `ref_clusters` — the cluster ids most relevant to that tile (e.g. grass tiles reference c19, c04, c21). Tier 2 generation passes representative tiles from those clusters as image-conditioning, which improves style match.
+
+### The locked palette is non-negotiable
+
+64 colors extracted from the Pokemon reference corpus via weighted k-means. **Every output pixel must snap to one of these colors.** This guarantees:
+- Coherent visual world (no two tiles fight each other).
+- AA-free outputs (palette is small enough that quantization snaps blurry edges hard).
+- Diff-able tile evolution: if a tile changes, the change is in pixel choices, not subtle color drift.
+
+If we ever want to expand the palette (e.g. add cooler marble tones), it's an ADR-worthy decision and a one-line update to `palette.json` — but every existing tile needs re-quantizing.
+
+### The rubric is the memory
+
+Lars feedback ("trees too modern, more gnarled") becomes a rule appended to `style_guide.md`. The rule influences every subsequent generation because the reviewer reads the style guide on every call. **The system improves over time without manual prompt-engineering** — feedback is durable, not conversational.
+
+## What does NOT work (do not waste time on these)
+
+- **Asking the model directly for 32×32 output.** Models output 1024×1024 regardless of prompt. Always post-process.
+- **Generating sprites with transparent backgrounds via prompt.** Gemini fights this. Use solid magenta (#FF00FF) background, then color-key it out in post-process.
+- **Using `nearest-neighbor downsample` for the AI→32×32 step.** Picks up too much per-pixel noise. Median is consistently better.
+- **Trusting the AI's own "this is pixel art" claim.** It will produce pixel-art-styled outputs that have soft edges, wrong-grid alignment, and 1000+ colors. Always run deterministic checks before AI review.
+- **Generating siblings independently.** Per-tile generation cannot produce sibling coherence (same character in different facings, paths that connect, transitions that line up). The model has no cross-call memory. See "Family pipeline" below for the fix.
+
+---
+
+## Family pipeline (Phase 1+ architecture)
+
+The original per-tile pipeline produced character sprites where each direction looked like a different person. Root cause: independent generations have no shared style anchor. The family pipeline (`modules/art-pipeline/pipeline/family_*.py`) fixes this by making the **family** — not the tile — the unit of generation.
+
+For decision rationale and alternatives considered, see [ADR 0008](../adr/<redacted>.md).
+
+### What good looks like (numerically)
+
+After migrating the player character to a family:
+
+| Metric | Per-tile pipeline | Family pipeline |
+|---|---|---|
+| Silhouette area CV across frames | 0.67 (177→900 px) | 0.11 (213→282 px) |
+| Silhouette height CV | 0.08 | 0.00 (all 27 px) |
+| Palette Jaccard, worst pair | 0.29 | 0.74 |
+| Dominant-color overlap, worst pair | 0.00 | 0.60–0.80 |
+| Luminance EMD, worst pair | 71.97 | 12–16 |
+| Generations to a passing result | 4 separate calls | 1 sheet call |
+| Cost per character set | ~$0.16 | ~$0.04 |
+
+### Recipe: generating a family
+
+1. **Define the family** in `modules/art-pipeline/template/families.json`. A family has `kind` (taxonomy), `layout` (e.g. `2x2`, `1x4`), `members` (each with a cell coordinate), `shared_style` (one paragraph that every member must respect), and optional per-family threshold overrides.
+2. **One image-gen call** per family. The sheet prompt instructs the model on the cell layout *and* the cross-cell coherence rules. Code: `family_generator.build_sheet_prompt()`.
+3. **Slice** the returned sheet by the family's layout. Each cell becomes a 32×32 PIL image after median-downsample + palette-quantize. Code: `family_generator.slice_sheet()`.
+4. **Run deterministic family checks** on the sliced cells. These compute numeric coherence metrics (silhouette area CV, height CV, palette Jaccard, dominant-color overlap, luminance EMD). Hard-fail if any is below its threshold. Code: `family_checks.run_all()`.
+5. **Only if step 4 passes**, run the Gemini family-coherence review. The review is told which deterministic checks already passed, so it focuses on subjective criteria (`family_consistency`, `character_identity`, `grid_alignment`, `firered_match`, `mythic_greek`). Code: `family_review.review_family()`.
+6. **Atomic-swap to publish.** The orchestrator does NOT auto-publish. Run with `--publish` to copy sliced cells into `modules/art-pipeline/generated/tiles/`. Default behavior is "save under `iterations/_families/<id>/` and let the human approve."
+
+### Recipe: composing the sheet prompt
+
+The prompt is built in three blocks:
+- **Header**: "Generate ONE pixel-art sheet for a 16-bit RPG tile-set in the style of Pokemon FireRed, restyled for ancient Mediterranean Greece. Output a single image laid out as a {rows}-row by {cols}-column grid of {n} cells."
+- **Discipline**: "REQUIREMENTS for every cell: top-down view, hard pixel edges, NO anti-aliasing, NO blur, NO frame, NO border between cells, NO text, NO labels, NO arrows, NO numbering."
+- **Coherence**: "CRITICAL coherence rules across cells: every cell uses the SAME palette of colors, the SAME lighting direction (top-left), the SAME saturation level, and the SAME dithering density. The sheet must read as ONE coordinated set."
+
+Per-cell descriptions then go in. For character families, an additional rule: *"All cells depict the SAME individual: identical body shape, identical clothing colors, identical hair, identical proportions. Only the facing direction changes."*
+
+### Why deterministic-first ordering matters
+
+Putting deterministic checks **before** the Gemini review changes the cost shape entirely:
+
+- Old loop (per-tile): every retry burned a Gemini review call to discover failure.
+- New loop (family): a failing family fails the deterministic gate for free, and the failure produces a *numeric* fix-hint ("CV 0.67 > 0.35, make characters same height") that's far more actionable than prose critique.
+
+Gemini becomes a polish check, not a failure detector. On the player_character run, Gemini was called once. Old per-tile equivalent would have been 4–24 review calls.
+
+### Anchor refinement (failure recovery)
+
+The orchestrator's tier 5 (`t5_anchor_refine`) is the recovery move when the first attempt has *one* good cell but family coherence fails:
+
+1. After every attempt, `family_checks.find_anchor_member()` picks the member whose silhouette + palette is most representative of the family.
+2. That member's PNG is saved as `iterations/_families/<id>/_anchor.png`.
+3. On the next attempt, `t5_anchor_refine` passes the anchor as a reference image to nano-banana, with the prompt: *"The first attached image is the locked anchor. Every cell must match the anchor's clothing colors, hair, body proportions, and palette. Only the facing direction changes."*
+
+In the player run this never fired (first attempt passed). It exists as the recovery path for harder families.
+
+### Thresholds: per-family, not global
+
+`families.json` has a top-level `defaults` block (currently 9.0/7.0 with default deterministic thresholds) and per-family overrides. Why per-family:
+
+- A character family tolerates more palette variation than a ground-tile family (different shading per facing is expected).
+- A ground-tile family must self-seam tightly (column 0 ≈ column 31), but characters have no self-seam concept at all.
+- A path autotile must satisfy edge contracts that don't apply to characters.
+
+Override only what differs. Inherited keys flow from `defaults.deterministic_thresholds` to the family.
+
+### Phase 1 calibration: lower threshold to bootstrap, ramp later
+
+For player_character we set `pass_threshold: 7.0`, `min_individual: 5.0` to get to a first pass cheaply and validate the architecture. The actual run scored 8.6 then 9.0 — well above the 7.0 bar, suggesting the architecture had more headroom than the lowered bar required. **Operating rule: leave the threshold at 7.0 until enough families have run that we have data on real ceiling.** Ramping prematurely just creates noise.
+
+### Family-pipeline pitfalls observed
+
+- **`.env.local` does not propagate to git worktrees.** It's gitignored, lives only in the worktree where it was created. When working in a new worktree, copy it from a sibling worktree before running anything that touches the Google API.
+- **The Gemini reviewer can be flattering when the deterministic block tells it everything passed.** Stay vigilant: read at least one Gemini critique JSON per session to confirm the prose tracks the numbers.
+- **Cell magenta-keying still has occasional residue** at the seam between sprite and the cell's magenta border. Same fix as the per-tile pipeline: ensure the model's magenta is pure (no shading, no dithering on the magenta) and trust the post-process keying.
+- **Sheet aspect ratio matters.** A 2×2 layout produces a square output (good — both Imagen and Nano Banana prefer 1:1). A 1×4 layout produces 4:1, which Imagen's `aspect` parameter supports but Nano Banana's wrapper does not control. Prefer 2×2 over 1×4 for 4-member families until that's resolved.
+
+### When to migrate an existing tile into a family
+
+The old per-tile pipeline still works for the 22 non-character tiles. We migrate when:
+1. The existing per-tile output is unsatisfactory (e.g., the four player frames).
+2. The tile has natural siblings (transitions, autotiles, multi-tile objects, character spritesheets).
+3. We're rebuilding the area for some other reason and might as well do it right.
+
+Otherwise leave existing tiles alone — they're published and working.
+
+---
+
+## Stress test (Phase 1.5) — 8 families, three generation patterns
+
+After the player_character family validated the architecture for one pattern, we ran a stress test against 8 families spanning every shape of family we could think of: characters, transitions, multi-tile objects, paths, cliffs, houses, boats, coastlines. Round 1 surfaced an architecture gap; Round 2 fixed the prompt strategy; Round 3 fixed the check dispatch. Final result: 7 of 8 families pass, with the 8th failing on a real subjective style judgment (not architecture).
+
+Total stress-test cost: **$1.44 of $80**. Three rounds, ~30 image-gen calls, ~20 Gemini reviews.
+
+### The three patterns (this is what we learned)
+
+What initially looked like one architecture is actually **three**. Each needs different prompt language and different check dispatch.
+
+#### Pattern A — coordinated variants
+Each cell is a different *view of one concept*. Cells never sit adjacent in-game — different cells get placed at different world locations. Coherence = identity (same character, same boundary style, same foam color).
+
+Examples: `player_character` (4 facings), `vendor_hyperion` (1 pose), `transition_grass_sand` (4 directional boundaries), `coastline_sand_sea` (4 directional shorelines), `small_boat` (1 sprite).
+
+- Prompt: describe each cell separately with strong cross-cell coherence rules ("identical clothing, identical hair, identical foam color across all cells").
+- Deterministic checks that apply: cross-cell color coherence (palette Jaccard, dominant overlap, luminance EMD) + sprite silhouette CV for character kinds.
+- Edge contracts: do NOT apply (cells aren't placed adjacent in-game).
+- Gemini family-review: judges identity coherence + style match.
+
+#### Pattern B — continuous illustration
+The family is **one object** drawn as a single illustration that we slice on a virtual grid afterward. The model is NOT told about cells at all. Cells are different *parts of one drawing*; their palettes are *naturally* different (a roof and a foundation are different colors, by design).
+
+Examples: `container` (one shipping container in 4 cells), `small_house` (one Mediterranean dwelling in 9 cells), `cliff_face` (one cliff in 3 cells, vertically).
+
+- Prompt: describe the whole subject as a single illustration filling the image edge-to-edge. Explicitly forbid "cell borders, panel separators, frames, grid lines." Tell the model: *"the image will be sliced afterward, but you do not need to think about that."*
+- Deterministic checks that apply: only per-cell post-processing (palette quantize, dimensions, AA). NO cross-cell coherence (false negatives — different parts have different palettes by design). NO edge contracts (tautological — the slicer guarantees adjacency by construction).
+- Gemini family-review: judges whether the assembled illustration reads as one coherent thing AND matches the project style.
+
+#### Pattern C — true autotile family (not yet validated)
+A set of tiles where each cell is a different *topology* (NW corner, straight, T-junction, cross, etc.) that must connect cleanly at specific edges. Pattern A doesn't work (the model can't keep the path width identical across separate variant generations). Pattern B doesn't work either — the path autotile we tried produced a "border tile set" (square frame with no interior cross) when the model drew it as one continuous loop, which is not the same as a 9-topology autotile.
+
+Best evidence: `path_autotile` under continuous_illustration produced usable tiles for paths-along-borders but lost the four-way cross that a full autotile needs.
+
+**Pattern C likely requires a third strategy not yet built**: cell-by-cell generation with the previously-generated cell's edge as an image-conditioning reference. This is the academic "Wang tile" / image-conditioning approach. We have not yet implemented it. **Open architectural question.**
+
+### How to set the strategy
+
+`families.json` field: `slice_strategy`. Values:
+
+```json
+"slice_strategy": "coordinated_variants"   // Pattern A (default if absent)
+"slice_strategy": "continuous_illustration" // Pattern B
+```
+
+Per-strategy required fields:
+- Pattern A: per-member `desc` describing each cell.
+- Pattern B: top-level `continuous_description` describing the whole subject as one illustration. Per-member `desc` becomes a label-only field used for the slice filename.
+
+### What was wrong with our first attempt
+
+Round 1 used Pattern A's prompt for everything. For continuous-object families this was wrong because:
+- The model interpreted "grid of cells" as a sprite-sheet brief and drew **black panel borders between every cell**, even when explicitly told "no border between cells."
+- Each cell was treated as an independent painting, so palette and lighting drifted dramatically (e.g. a 3×3 house had 3 different palettes, one per row, with luminance EMD = 84).
+- Edge contracts measured 0–50% match.
+
+Round 2 fixed the prompt strategy. Edge contracts immediately jumped (some hit 100%). Round 3 fixed the check dispatch (skip cross-cell + edge contracts for Pattern B). All four continuous-illustration families passed Gemini review.
+
+### Round-by-round measurements (durable record)
+
+| Family | Pattern | R1 result | R2 result | R3 result | Final Gemini |
+|---|---|---|---|---|---|
+| vendor_hyperion | A (singleton) | ✅ pass | — | — | 8.0 |
+| transition_grass_sand | A (variants) | ✅ pass | — | — | 9.0 |
+| small_boat | A (singleton) | ✅ pass | — | — | 9.25 |
+| coastline_sand_sea | A (variants) | ❌ palette/dominant fail | ✅ pass (tightened anchor) | — | 8.5 |
+| container | B (continuous) | ❌ edge 9–50% | partial (50–100%) | ✅ pass | 8.25 |
+| small_house | B (continuous) | ❌ all 15 checks fail | worse (luminance EMD 116) | ✅ pass | 8.5 |
+| cliff_face | B (continuous) | ❌ edge 0–25% | ❌ edge 0–60% | ⚠️ style fail (Gemini 6.25 — "too painterly, not FireRed enough") | 6.25 |
+| path_autotile | B (continuous) | ❌ edge 0–50% | partial (50–90%) | ✅ pass (as border tile set, not full autotile) | 8.0 |
+
+### Insights worth keeping
+
+1. **Different patterns need different prompt language AND different check dispatch.** Conflating them makes the architecture appear broken when only the prompt strategy is wrong.
+
+2. **The model can draw beautiful single illustrations** when not constrained to a "grid of cells" brief. Round 2's container, house, cliff, and path images were genuinely good art — the original problem was framing.
+
+3. **Edge contracts are a Pattern-A concept misapplied to Pattern B.** For continuous illustrations, the slicer guarantees adjacency by construction. Checking pixel-match at slice lines is meaningless and misleading.
+
+4. **Cross-cell color coherence is a Pattern-A concept.** For continuous illustrations, different parts naturally have different palettes (roof ≠ foundation, sky ≠ ground). The check correctly flagged this as "incoherent" but in fact it was a feature, not a bug.
+
+5. **Gemini's right role is subjective polish, not failure detection.** When the deterministic gate is appropriately scoped, Gemini reliably catches subjective style problems (cliff_face's "too painterly, blended transitions instead of hard pixel edges" was a real, useful critique). When the deterministic gate is wrongly scoped, Gemini calls get wasted on false positives.
+
+6. **The fix from 4/8 to 7/8 was small.** Two contained changes: (a) add a `slice_strategy` field with a new prompt builder branch; (b) skip cross-cell + edge-contract checks for `continuous_illustration` in `family_checks.run_all()`. About 60 lines of Python plus the schema field. The architecture core (family schema, generator pipeline, retry logic, Gemini review prompt) was unchanged.
+
+7. **Stress-testing surfaces gaps cheaply.** Each round was ~$0.50. The full 3-round stress test cost ~$1.44 to identify and validate fixes for an architectural assumption that would have shipped silently broken if we'd kept moving on player_character → vendor → next-family.
+
+### Open questions surfaced (not yet resolved)
+
+- **Pattern C strategy (true autotile families).** Path autotile under Pattern B produced a usable border-tile set but lost the topology variants a full autotile needs. Solution likely involves cell-by-cell generation with image-conditioning anchors. Defer until V1 actually needs an autotile path.
+- **Cliff style failure.** Gemini consistently scored cliff at 6.25 across attempts, citing "too painterly, soft transitions, blended dithering." The model produces beautiful illustrations but they don't match FireRed's hard-pixel-edge discipline. Possible fixes: (a) tighter style-specific prompt for vertical structures, (b) post-processing to flatten dithering, (c) accept that cliff is a V2 problem. Not yet decided.
+- **"Object-as-asset" vs "object-as-tile-set" question.** Pattern B continuous illustrations might be better used as a single sprite asset placed across multiple grid cells in-game, rather than as 4 / 9 independent tiles. Either model works visually; the choice is about the game-engine integration. **Defer to whenever we're ready to place a multi-tile object in the world map.**
+
+### Pattern B operational rule
+
+When adding a new continuous-illustration family:
+
+1. Set `slice_strategy: "continuous_illustration"`.
+2. Provide a top-level `continuous_description` describing the whole subject as ONE illustration. Use language like *"filling the entire image edge-to-edge,"* *"NO cell borders,"* *"the image will be sliced afterward."*
+3. Pick a layout that matches the natural orientation (e.g. 3×1 for a vertical cliff, 3×3 for a building front, 2×2 for a square object).
+4. Per-member `desc` becomes label-only — describe what each slice will contain post-hoc, but don't expect the model to read these.
+5. Don't define `edge_contracts` — they're skipped anyway.
+6. Trust the slicer + Gemini family-review.
+
+---
+
+## Pattern C — autotile families (Phase A–D)
+
+For a region of one terrain surrounded by another (grass islands in sand, sand
+beaches against sea) and for line/path topology (marble flagstones threading
+through grass), neither Pattern A nor Pattern B works. We hit this in stress
+testing: the path autotile under Pattern B produced a usable border tile set
+but lost the topology variants a real autotile needs. The model is good at
+texture appearance; it is not good at producing all the topology variants of
+a tile set as one image.
+
+The fix: **AI generates 3–5 small primitive textures; a pure-Python compositor
+deterministically composes the 47 (or 16) tiles by per-quadrant masking.**
+Standards-compliant: 47-blob (RPG Maker A2 / Tiled / Cr31 / Godot blob) for
+region terrain, 16-path (4-cardinal) for line terrain. For decision rationale
+see [ADR 0009](../adr/0009-autotile-architecture.md).
+
+### Why this works
+
+**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. We didn't need a
+retry loop for seam alignment — the compositor produces correct seams on the
+first pass. Validated by 100% edge-match on the all-interior composition test.
+
+**The model only does what it's good at.** The AI generates 3–5 small texture
+chunks (interior, exterior, edge, concave-corner, convex-corner). These are
+within the model's competence — they're each a small piece of a coherent
+texture. The model is not asked to plan tile-set topology, which is what
+breaks down.
+
+**Cost is dramatically lower.** A 47-tile family from 5 primitive generations
+is ~$0.20–0.45 vs ~$1.88 if every tile were generated independently. Per
+final tile this is ~$0.005–0.010 vs ~$0.040 — about 4–8× cheaper.
+
+### Recipe: building a region autotile family (47-blob)
+
+1. **Define the family** in `modules/art-pipeline/template/families.json` with
+   `kind: "autotile_blob_47"`. Required fields: `interior_terrain`,
+   `exterior_terrain`, `interior_short`, `exterior_short`, `shared_style`,
+   and a `primitives` array of 5 entries with roles
+   `interior` / `exterior` / `patch_horiz_NW` / `patch_concave_NW` /
+   `patch_convex_NW`. Each primitive has its own `id`, `desc`, and `size_px`
+   (32 for interior/exterior textures, 16 for boundary patches).
+2. **Run the orchestrator**:
+   `python3 modules/art-pipeline/pipeline/autotile_orchestrator.py <family_id>`.
+3. The orchestrator generates each primitive with retries (up to 3 attempts
+   for texture-role primitives, 1 attempt for non-texture primitives), applies
+   seamless-enforcement to texture roles, calls
+   `autotile_compositor.compose_blob47()`, and saves all 47 tiles.
+4. The validation harness renders three test compositions (all-interior,
+   island, organic) and reports edge-match scores.
+
+### Recipe: building a path autotile family (16-path)
+
+Same as region but with `kind: "autotile_path_16"` and a 3-primitive bundle:
+`terrain` / `path_node` / `path_arm_N`. The path_arm_N primitive is anchored
+at the top edge with the path running vertically; the compositor rotates it
+for the other 3 cardinal directions.
+
+### Recipe: seamless texture enforcement (the trick that made it work)
+
+AI-generated textures don't naturally tile seamlessly — col 0 ≠ col 31 in the
+raw output. The seamless-enforcement step in
+`autotile_orchestrator._make_seamless()` averages the leftmost and rightmost
+columns of pixels, applies the average to both columns, repeats for top/bottom
+rows, then re-quantizes to the locked palette. Result: col 0 == col 31 and row
+0 == row 31 by construction. The visible cost: the 4 outermost pixels of every
+edge are slightly blended versions of opposite-edge content. For texture-style
+primitives (grass, sand, sea) this is invisible.
+
+Without this step, even a "seamless" prompt produces ~50–70% edge match in
+all-interior compositions. With the step, 100%.
+
+### Why we still split silhouette / color / luminance / edge-contracts
+
+The deterministic-checks framework (Pattern A/B) doesn't apply to autotiles:
+- Cross-cell color coherence: primitives are independent; we don't compare them.
+- Edge contracts: tautological for autotiles (the compositor produces matching
+  edges by construction).
+
+The autotile validation harness uses a different scoring metric: **edge-match
+score on rendered test compositions**. For each adjacent tile pair in a
+rendered composition, count how many seam pixels match within a perceptual
+tolerance. 100% means the composition is seamless when displayed.
+
+### Pattern C results — Phase B/C run
+
+| Family | Primitives | all_interior | island | organic / winding | cost |
+|---|---|---|---|---|---|
+| grass_on_sand | 5 | 100.0% | 85.7% | 77.2% | $0.47 |
+| sand_on_sea | 5 | 100.0% | 85.7% | 74.7% | $0.23 |
+| marble_path | 3 | n/a | n/a | winding 99.2% / cross 99.1% | $0.16 |
+| cliff_top | 5 | 100.0% | 86.2% | 74.7% | $0.27 |
+
+**100% match on all-interior compositions** validates the seamless-tile
+approach. The 75–86% scores on boundary compositions (island, organic) reflect
+the boundary primitives being independently generated — they're stylistically
+coherent but not pixel-identical at every transition. Acceptable for V1;
+generating boundary primitives in pairs with image conditioning would close
+this gap and is a V2 candidate.
+
+The marble_path 99% score is dramatically higher because path tiles are stamps
+on a uniform background — most seams are terrain-to-terrain (perfectly
+tileable), only a few are path-to-terrain.
+
+### Pattern C pitfalls observed
+
+- **Direction-asymmetric terrain breaks 47-blob.** Cliffs need different tiles
+  for north-facing vs south-facing edges (the south edge shows a stone face;
+  the north edge is just grass). 47-blob produces the same edge tile on all
+  four sides of a cliff region. Result: cliff_top is topologically correct
+  but stylistically weak. **For real cliffs, V1+ needs a direction-aware
+  cliff scheme** (per-edge tile selection or a 4-orientation autotile
+  variant). Document and defer.
+- **Per-tile interior repetition.** Without per-tile sample-offset jitter,
+  every interior tile looks identical. Visible in large interior fields.
+  Phase A–D ships without jitter; V2 candidate.
+- **Triple junctions are unrepresentable.** Where 3 terrains meet at one
+  tile, the 47-blob convention can't pick a tile. Forbid triple junctions
+  in level design (this is the standard solution in the industry).
+- **Two-way terrain pairs need two families.** `grass_on_sand` does not
+  serve `sand_on_grass` — the boundary direction matters. For V1, declare
+  the families you need.
+
+### Runtime architecture
+
+The autotile picker is split-implementation:
+- `modules/art-pipeline/pipeline/autotile_mapping.py` — Python source of truth, used by the
+  compositor at build time.
+- `public/game/world/autotile.js` — JavaScript mirror, used by the in-game
+  renderer. Cross-verified against the Python table at build time (a
+  smoke-test compares all 256 inputs).
+
+When the runtime data-model refactor lands (Phase D, deferred for review):
+the world map stores terrain ids per cell; the renderer iterates cells and
+calls `selectBlob47(myTerrain, neighbors)` or `selectPath16(neighbors)` to
+pick the tile index, then loads the corresponding PNG from the family's
+tile set.
+
+### Open question
+
+**Cliffs deserve a direction-aware scheme.** The 47-blob approach gives a
+stylized "shelf" look on all four edges of a cliff region. Real cliff
+autotiles in RPG Maker (A4 layer) and similar systems use a strip-based
+scheme where the south-facing edge is drawn as a vertical wall while other
+edges are flat transitions. If V1 ships cliffs, this needs to be built.
+Otherwise defer to V2. Decision pending Lars.

package/docs/recipes/private-npm-distribution.md

@@ -0,0 +1,79 @@
+# Recipe — private-first npm distribution (core + client)
+
+> Implements [ADR 0134](../adr/<redacted>.md). Pre-launch, `@cloudbongos/core` and `@cloudbongos/client` publish as **private, scoped** npm packages on a paid `cloudbongos` npm org; at launch they flip to public. The daily command is `bongos` regardless of package name.
+>
+> **Why private must be scoped:** on npm, *unscoped* names (like `cloudbongos`) are always public — only *scoped* names (`@cloudbongos/…`) can be private, and only on a paid plan. The repo already uses the `@cloudbongos` scope, so no rename is needed now.
+
+## The pieces
+
+| Package | What it is | Built by |
+|---|---|---|
+| `@cloudbongos/core` | the platform an instance installs + the `bongos` CLI (`bin`) | `bongos package-core` (`scripts/gds/package-core.js`) — synthesizes the package.json + a pruned lockfile, redacts, and packs a `.tgz` |
+| `@cloudbongos/client` | the generated typed API client | `node scripts/gds/gen-api-client.js` (regenerates `clients/bongos-client/`) |
+
+Both carry `publishConfig: { access: "restricted" }`, so **publishing them is private by default** — no public leak if a flag is forgotten.
+
+## One-time owner setup (only the owner can do these)
+
+These involve payment and permanent, account-level actions. They are **not** done inside a build session.
+
+1. **Put the `cloudbongos` npm org on a paid plan.** Private scoped publishing requires it. On npmjs.com → your org → Billing → upgrade to a plan that allows private packages (npm Teams, ~$7/member/month). Add as members only the people who need to publish or install during pre-launch — each is a billed seat.
+2. **Create an access token.** npmjs.com → Access Tokens → *Generate New Token* → **Granular/Automation**, with **read-write** on the `@cloudbongos` packages (for publishing) — a **read-only** token is enough for machines that only install. Store it as an environment variable, never in a committed file:
+   ```sh
+   export NPM_TOKEN=<redacted>
+   ```
+
+## Publish (the real, permanent step — owner)
+
+Always preview with a dry-run first (no upload, no login needed):
+
+```sh
+# Core — build the tarball and DRY-RUN the private publish:
+node scripts/gds/package-core.js --publish
+```
+
+Look for `restricted access` and the `@cloudbongos/core@<version>` line. When it looks right, publish for real (this is **permanent** — npm can't delete a name after 72h):
+
+```sh
+npm login                                         # once per machine (+ 2FA)
+node scripts/gds/package-core.js --publish --live # actually publishes, still private
+```
+
+For the client (note the `./` — without it, npm reads the path as a git package spec, not a folder):
+
+```sh
+node scripts/gds/gen-api-client.js                # ensure it's fresh
+npm pack ./clients/bongos-client --dry-run        # token-free content preview
+npm publish ./clients/bongos-client               # real (publishConfig makes it restricted; needs npm login)
+```
+
+## Install a private package (any consumer machine or instance)
+
+Add a one-line `.npmrc` (repo-root or `~/.npmrc`) that reads the token from the environment:
+
+```
+//registry.npmjs.org/:_authToken=<redacted>
+```
+
+Then, with `NPM_TOKEN` set in the environment:
+
+```sh
+npm install -g @cloudbongos/core   # global → the `bongos` command, then `bongos init`
+npm install @cloudbongos/client    # in a project that calls the API
+```
+
+Without a valid token + org membership the install 404s — that is the private gate working.
+
+> Provisioning still installs the core from a **vendored tarball** committed into each instance repo (task 2053) — that path is unchanged and needs no token. Wiring provisioning to pull the pinned core from the private registry instead is a tracked follow-up.
+
+## Going public at launch
+
+Pick either — both keep the daily `bongos` command working:
+
+- **Flip the same scoped packages public** (simplest):
+  ```sh
+  npm access public @cloudbongos/core
+  npm access public @cloudbongos/client
+  ```
+  (Or change `publishConfig.access` to `"public"` and republish.) Public installs need no token; the paid seats can be dropped.
+- **Also publish the unscoped vanity name** for `npm install -g cloudbongos` — that is [task 2025](https://example.com/builders#/task/2025) (rename in `package-core.js`/`upgrade.js` + docs), done at launch.

package/docs/recipes/search-index-ingestion.md

@@ -0,0 +1,67 @@
+# Recipe — GDS search-index ingestion (repo markdown)
+
+How the `search_chunks` index (the recall layer, [ADR 0060](../adr/0060-gds-retrieval-layer.md)) gets populated from repo markdown, and how to operate it. Read before touching `scripts/gds/search-ingest-md.js` or the deploy hook.
+
+> The query side is [`src/bongos/search.js`](../../src/bongos/search.js) + [`POST /api/gds/search`](../../src/bongos/routes/search.js) ([#949](https://example.com/builders#/task/949)); rank/owner scoping + its isolation suite are [#950](https://example.com/builders#/task/950). Ingestion has two halves: **repo markdown** (this recipe's first sections — [#947](https://example.com/builders#/task/947), the deploy hook) and **DB prose** (the [DB-prose nightly](#db-prose-nightly-timer) section below — [#948](https://example.com/builders#/task/948), a systemd timer).
+
+## What it does
+
+`node scripts/gds/search-ingest-md.js` walks the repo's markdown (~226 files), chunks each file via the heading-aware chunker ([`src/bongos/search-chunker.js`](../../src/bongos/search-chunker.js)), and upserts the chunks into `search_chunks`:
+
+- **Delta-driven.** Each chunk's `content_hash` (sha256 of its body) is the change key. The upsert's `ON CONFLICT … DO UPDATE … WHERE content_hash IS DISTINCT FROM EXCLUDED.content_hash` makes an unchanged chunk a **no-op** (no row rewrite). A re-run over an unchanged tree writes nothing.
+- **Prunes shrinkage.** If a file loses sections, chunks beyond the new count are deleted; if a file is removed from the tree entirely, all its chunks are deleted (`source_kind='doc' AND source_ref NOT IN (present)`).
+- **Scopes by rank.** Most docs are `min_rank='xenos'` (shared). Read-sensitive documentation surfaces are tagged `min_rank='metic'` so a sub-Metic search can never surface them ([ADR 0060](../adr/0060-gds-retrieval-layer.md) §6 / [ADR 0043](../adr/<redacted>.md)). The metic set is curated in `SENSITIVE_DOC_GLOBS`: `docs/canonical-permissions.md`, `docs/security/`, `docs/audits/`, and the two trust-boundary ADRs (0016, 0043). **`CLAUDE.md` is deliberately `xenos`** — it's write-protected but the universal read-public onboarding index. Docs are never owner-scoped (`owner_builder_id` stays NULL); per-builder private content is the DB-prose ingester's job (memory rows).
+
+## When it runs
+
+A **non-blocking step in the prod deploy** ([`scripts/deploy/deploy-prod.sh`](../../scripts/deploy/deploy-prod.sh), mirrored in the droplet's hand-maintained `~/deploy.sh`), after the code update + migrations + healthz, where the new markdown and the DB are both on disk. It's wrapped `timeout 60 … || echo "…deploy unaffected"` — **an ingest failure never fails a deploy**; the next deploy (or a manual run) catches up.
+
+> ⚠️ `scripts/deploy/deploy-prod.sh` is a **byte-faithful mirror** of the droplet's `~/deploy.sh`, which is **hand-maintained and NOT auto-installed** (the ci deploy key is forced-command-locked — [ADR 0042](../adr/<redacted>.md)/[0043](../adr/<redacted>.md)). When you change the mirror, **re-apply the same edit to `~/deploy.sh` on the droplet by hand** (`ssh lars@REDACTED_IP`), or the deploy hook won't actually run there. (Same caveat as the [prod deploy-script mirror](../../docs/recipes/ops-gotchas.md) note.)
+
+## Operating it
+
+```bash
+# Dry-run: report file/chunk counts + which sources are metic-tagged. No DB, no writes.
+node scripts/gds/search-ingest-md.js --dry-run
+
+# Full ingest (writes to search_chunks). Idempotent — safe to re-run; unchanged
+# chunks are skipped. Run on the droplet (DB on the local socket) or anywhere the
+# GDS Postgres env (PGHOST/PGDATABASE) resolves.
+node scripts/gds/search-ingest-md.js
+
+# Initial backfill after first deploy of the recall layer: just run the full
+# ingest once on the droplet — it indexes the whole corpus from empty.
+```
+
+Output reports `inserted / updated / unchanged / pruned / deleted_sources_chunks` so you can see the delta. A first run over an empty index inserts everything; subsequent runs over an unchanged tree report all-unchanged.
+
+## DB prose (nightly timer)
+
+`node scripts/gds/search-ingest-db.js` indexes the prose that lives in the DB, not in git, as `source_kind='db'`: task descriptions + value summaries (`task:<id>`), learnings (`learning:<id>`), idea inbox (`idea:<id>`), done-when criteria (`criterion:<id>`), blockers (`blocker:<id>`), session-log notes (`session_log:<id>`), grade notes (`grade:<id>`), per-builder memory (`memory:<builder>:<path>`), and recent git commit subjects (`commit:<sha>`). Same delta-by-content_hash + prune-vanished behavior as the repo-md ingester.
+
+Security ([ADR 0060](../adr/0060-gds-retrieval-layer.md) §6 / [ADR 0016](../adr/<redacted>.md) / [ADR 0022](../adr/0022-secrets-policy.md)):
+
+- **`builder_memory` is owner-scoped** — each chunk carries `owner_builder_id`, so a builder's private memory only ever surfaces to that builder (the search route's owner filter, [#950](https://example.com/builders#/task/950)).
+- **`security_sensitive` tasks are tagged `min_rank='metic'`**.
+- **`vulnerability_reports` + `security_reports` are excluded entirely** — raw security findings don't belong in a broadly-searchable index.
+- **Session/memory/grade text is scrubbed** through `ship.js` `scrubSecrets` (known shapes + high-entropy) before storage — the index must never hold a leaked credential.
+
+It runs on a **nightly systemd timer** ([`infra/search-index-db.timer`](../../infra/search-index-db.timer) → [`infra/search-index-db.service`](../../infra/search-index-db.service), 03:30 UTC, 30 min before the pg_dump so they don't contend), modeled on `gds-db-backup`. DB prose changes more slowly than docs, so nightly is fresh enough; the repo-md half stays intra-day via the deploy hook.
+
+**Operator install (one-time, on the droplet):**
+
+```bash
+# Copy the units into place, reload, enable + start the timer, then run once.
+sudo cp /home/lars/example/infra/search-index-db.{service,timer} /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now search-index-db.timer
+systemctl list-timers search-index-db.timer          # confirm it's scheduled
+sudo systemctl start search-index-db.service          # initial backfill now (don't wait for 03:30)
+journalctl -u search-index-db.service -n 20 --no-pager # check the run
+```
+
+## Gotchas
+
+- **`node` must be on PATH** in the deploy shell (it is — systemd runs the app via node). The script connects via the shared `src/db.js` pool (the same Postgres the app uses), so it needs the GDS env, not a token.
+- **The index lags the merge by one deploy** for any doc changed in a PR that doesn't itself trigger a deploy — acceptable; the deploy hook re-indexes on every prod deploy, and the [staleness monitor + /watch tile](https://example.com/builders) (`#972`) surfaces a stalled index.
+- **Don't lower the chunk size** without re-checking the eval set ([#939](https://example.com/builders#/task/939)) — chunk granularity affects recall quality and (later) embedding cost.

package/docs/recipes/self-host.md

@@ -0,0 +1,60 @@
+# Self-hosting Cloud Bongos (Docker)
+
+Bring up a vanilla Cloud Bongos instance — the build platform + builders' hall + status dashboard, with no game — on any machine with Docker. Shipped by V4.R63 ([task #1202](https://example.com/builders#/task/1202), [ADR 0062](../adr/<redacted>.md)).
+
+> **Relation to configurable-root ([ADR 0108](../adr/<redacted>.md)):** this is the **single-checkout** self-host shape — the whole repo (core + config) is baked into one image, so `resolveCoreRoot()` and `resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js)) both resolve to `/app` inside the container. ADR 0108 does not deprecate this path — it stays the cheap, supported shape for a quick reskin (this is how `cloudbongos.com` runs). The *installed-as-a-dependency* shape (a consumer repo running `npm install @cloudbongos/core`) is the separate, heavier path ADR 0108 targets for a project that wants its own repo and its own upgrade cadence — see [`docs/recipes/packaging-the-core.md`](packaging-the-core.md).
+
+## One command
+
+```bash
+docker compose up
+```
+
+That builds the image, starts Postgres, applies the build-system migrations (game-module migrations are skipped — this is a GDS-only instance), and serves the builders' hall at **http://localhost:3000**.
+
+- The instance is **vanilla** by default: the neutral Cloud Bongos brand, every feature module (game, art pipeline, Discord, dev boxes) **off**. `.dockerignore` keeps the host's `config/branding.json` and `config/modules.json` out of the image, so it resolves to `config/branding.neutral.json` + `config/modules.neutral.json`.
+- **No OTB scope-truth is seeded.** OTB/product data (game versions, goals, done-when criteria) lives in opt-in seed migrations under `migrations/instance/` (plus a few guarded blocks in the mixed files 003/006). `scripts/migrate.sh` skips them unless `GDS_APPLY_INSTANCE_SEEDS=1`, so a fresh DB comes up with only the schema and platform-universal defaults (ranks, achievements) — no crash, no foreign-key failures, no leftover versions. Platform system principals (`bfg-system`, `discord-bot-system`) are generic and remain. See task 1704 / [ADR 0105](../adr/<redacted>.md).
+- **No prod topology** is referenced: the database is a local container, the credentials are local demo values, and the app reaches Postgres over TCP via `PG*` env (see `docker-compose.yml`).
+
+To stop and wipe: `docker compose down -v` (the `-v` drops the `cloudbongos-db` volume).
+
+## Branding / configuring your instance
+
+The image is intentionally vanilla. To make it yours, supply your own config at runtime by mounting it over the build:
+
+```yaml
+# docker-compose.override.yml
+services:
+  app:
+    volumes:
+      - ./config/branding.json:/app/config/branding.json:ro
+      - ./config/modules.json:/app/config/modules.json:ro
+```
+
+Author `config/branding.json` from the neutral starter — see [the branding contract](../branding-contract.md) and [`docs/branding-fill-prompt.md`](../branding-fill-prompt.md). Choose which features to enable in `config/modules.json` — see [the module contract](../modules-contract.md). Both resolve **over** the neutral starters, so you only specify what differs.
+
+**Or scaffold it with `bongos init`** ([task #1204](https://example.com/builders#/task/1204)): a short interview (or `bongos init --from spec.json` for a hands-free / CI run) that writes both config files, **seeds your first version + its done-when goal**, and **files the human-only kickoff steps** (register a GitHub OAuth app, first owner sign-in, repo binding, admission) as real tracked tasks — so a fresh instance has a claimable queue on day one instead of an empty hall. It never invents your branding (it points you at the fill prompt for that). Preview the whole plan with `bongos init --dry-run`.
+
+**Production hosting, optional (the `provisioning` module — [ADR 0111](../adr/<redacted>.md) §3).** If you enable the `provisioning` module and answer the interview's hosting questions (shape — co-tenant `$0` or a dedicated droplet — bring-your-own domain, credential ref, tier), init turns those answers into a real **provisioning request** (a queued `provision` intent the control-plane runner drains) instead of only filing a manual "production topology" task. The two irreducibly-human legs — the GitHub OAuth app and the first owner sign-in — stay guided/manual. If the module isn't enabled on the target instance, init falls back to the manual production-topology task, so nothing is silently skipped.
+
+## Configuration surface
+
+| Env var | Meaning | Compose default |
+|---|---|---|
+| `PGHOST` / `PGPORT` / `PGUSER` / `PGPASSWORD` / `PGDATABASE` | Postgres connection (read by both the app pool and the migration runner) | the local `db` service |
+| `HOST` / `PORT` | bind address inside the container | `0.0.0.0` / `3000` |
+| `MEDUSA_GDS_ONLY` | `1` = hard force-skip the OTB **instance-seed** migrations (`migrations/instance/`) — belt-and-suspenders over the default. A vanilla instance never wants OTB's versions/goals/criteria (task 1704 / [ADR 0105](../adr/<redacted>.md)). | `1` |
+| `GDS_APPLY_INSTANCE_SEEDS` | `1` = opt IN to applying the bundled OTB instance-seed migrations. Default (unset) = **skip** — so a self-host never inherits OTB scope-truth. Only the owning instance sets this, and only when rebuilding its DB from scratch (DR). | unset |
+| `CLOUDBONGOS_PUBLIC_ORIGIN` | public origin for OAuth callbacks etc. | `http://localhost:3000` |
+
+(The env prefix is the instance's `envPrefix` from its branding pack — `CLOUDBONGOS` for vanilla.)
+
+## What the image contains
+
+- `node src/platform-server.js` — the GDS-only entrypoint (no Colyseus, no game rooms, no game assets).
+- `postgresql-client` (for `scripts/migrate.sh`) + `tini` as PID 1.
+- Runs as the unprivileged `node` user; a `HEALTHCHECK` polls `/healthz`.
+
+## Production notes
+
+For a real deployment, put a TLS-terminating reverse proxy (Caddy/Cloudflare/nginx) in front, point `CLOUDBONGOS_PUBLIC_ORIGIN` (and the builders/status origins) at your domain, and use managed or backed-up Postgres rather than the bundled container volume. The bundled `db` service is for a self-contained local instance, not a production database.