hayao 0.4.0 → 0.4.2

package/design/20-genres/roguelike.md

@@ -0,0 +1,122 @@
+---
+id: genre-roguelike
+title: Roguelike
+kind: genre
+tags: [roguelike, procgen, permadeath, runs, connectivity, discovery, turn-based]
+summary: Fair discovery through procedural dungeons that always connect and turns that always replay — variance as content, not chaos.
+use-when: You want run-based exploration where each seed is a fresh, fair puzzle and death is the loop.
+composes-with: [system-procgen-design, system-meta-progression, system-session-structure, system-enemy-archetypes, system-save-and-checkpoint]
+anchors: [anchor-nuclear-throne, anchor-dead-cells]
+verify-with: docs/FUN.md#10--traditional-roguelike
+---
+
+# Roguelike
+
+**What it is.** A run-based game of **procedural dungeons** and **permadeath**.
+Each seed generates a fresh, connected world; you descend, adapt to what you're
+dealt, and die — then run again, wiser. Variance is the content: no two runs are
+the same, and every one is fair.
+
+**Player fantasy / why it's fun.** *"I read this seed's hand and played it
+well."* The pull is fair discovery — surprise that never feels cheated, mastery
+of a system rather than a memorised map, and the "one more run" that a fresh
+seed always promises.
+
+## Pillars
+
+1. **Fairness ≈ connectivity.** Procgen that *always connects* — stairs and all
+   loot reachable — is the floor. Prove it across ~50 seeds *before* tuning any
+   number. An unreachable objective is the genre's cardinal sin.
+2. **Turns that always replay.** Deterministic, seeded, turn-based: input edge =
+   one world step. Pure-data state makes runs reproducible and bots possible —
+   the sim is its own proof engine.
+3. **Discovery, not memorisation.** The challenge is reading *this* seed's
+   items, enemies, and layout — a systemic mastery that transfers across seeds,
+   not a memorised route.
+
+## The loop stack
+
+| Scale | The beat |
+|---|---|
+| **Moment** | One turn: read the tactical situation → the move that reads it best → the world steps. |
+| **Encounter** | A room/fight: positioning, resources, and item synergies vs an archetype mix. |
+| **Session** | A run: descend floors, build from what drops, push your luck deeper, die or win. |
+| **Meta** | Between runs — unlocks, new items in the pool, knowledge of the systems. |
+
+## Essential systems
+
+| System | Why it's load-bearing |
+|---|---|
+| [[system-procgen-design]] | The engine of the genre — seeds, connectivity, variance-as-content, controlled randomness. |
+| [[system-meta-progression]] | The between-run pull; unlocks that add *options*, ideally, over raw power. |
+| [[system-session-structure]] | Run length and shape; floor count, descent pacing, the win condition. |
+| [[system-enemy-archetypes]] | The threat alphabet each room composes from — readable, beatable minds. |
+| [[system-save-and-checkpoint]] | Respecting time under permadeath: save-and-quit, run history, retry friction. |
+
+## Content & difficulty model
+
+- **Content is the pool + the generator.** Author items, enemies, and room
+  templates; the generator combines them. Depth comes from *interactions* in the
+  pool, not from more rooms.
+- **Difficulty ramps by depth.** Deeper floors mix nastier archetypes and
+  tighter resources. The generator scales the mix, not a global HP multiplier.
+- **Variance with guardrails.** Seed the RNG; clamp the range so a run is never
+  DOA (no floor with zero healing available). Prove winnability with
+  full-knowledge bots — they show a *line exists*, which is the honest claim for
+  procgen (not that a human will find it).
+- **Meta adds options, not a floor of power.** Guard against the run being
+  decided at the menu; unlocks should widen the pool, not trivialise it. See
+  [[system-meta-progression]].
+
+## Signature-mechanic seeds
+
+- **Roguelike but the dungeon is a language you edit** *(mechanic-swap)* — Baba-
+  style rule tiles you rearrange between floors; the systemic mastery becomes
+  literal. Pairs [[anchor-baba-is-you]].
+- **Roguelike but every death leaves a corpse that persists** *(structure)* —
+  Nemesis-lite memory across runs; past selves become this run's threats. Pairs
+  [[system-emergent-systems]].
+- **Roguelike but you see the whole seed once, then it's dark** *(constraint)* —
+  a memory/planning roguelike; the discovery is front-loaded.
+- **Roguelike but turns cost light** *(theme + constraint)* — a Kentō lantern
+  descent; every step spends a finite glow, making exploration a resource.
+- **Roguelike but two heroes on one seed, alternating turns** *(perspective)* —
+  co-op descent; connectivity must serve two paths.
+
+## Common pitfalls
+
+- **Unreachable objectives.** A seed where stairs or required loot are walled off
+  is unshippable. Connectivity sweep, always, first.
+- **Memorisation over mastery.** If the "best" play is learning fixed seeds, the
+  procgen is decorative. Variance must matter.
+- **Meta decides the run.** If a menu unlock makes runs trivial, discovery dies.
+  Options over power.
+- **Variance that punishes randomly.** A seed with no healing or an unwinnable
+  drop feels cheated. Clamp the generator's worst case.
+
+## Anchors
+
+- [[anchor-nuclear-throne]] — the tight run-based mastery loop; steal its
+  legible enemies and instant-restart momentum.
+- [[anchor-dead-cells]] — the roguelite structure of permanent unlocks over
+  impermanent runs; steal its meta-progression shape.
+
+## Verify
+
+Prove it in **[FUN.md §10 · Traditional
+roguelike](../../docs/FUN.md#10--traditional-roguelike)**: seeded
+reproducibility, a connectivity sweep, a full-knowledge bot wins 10/10 random
+seeds, and turn-log replay determinism.
+
+## Composes with
+
+- [[system-procgen-design]] — the connectivity-proven generator at the core.
+- [[system-meta-progression]] — the between-run hook that keeps runs coming.
+- [[system-enemy-archetypes]] — the threat alphabet each seed spells with.
+
+## See also
+
+- [`sandboxes/procgen-lab`](../../sandboxes/procgen-lab) — seeded generation and
+  connectivity wiring in isolation.
+- [`examples/sokoban`](../../examples/sokoban) — the pure `Puzzle<State,Move>`
+  logic/view split; a roguelike turn is the same shape at scale.

package/design/20-genres/rts.md

@@ -0,0 +1,169 @@
+---
+id: genre-rts
+title: Real-Time Strategy
+kind: genre
+tags: [rts, strategy, factions, asymmetry, macro, micro, pathfinding, spectacle]
+summary: Mass under command — hundreds of wall-aware units, three asymmetric-but-fair factions, and battles that read as spectacle.
+use-when: You want a game of commanding armies where economy, tech, faction identity, and positioning decide impressive battles.
+composes-with: [system-faction-asymmetry, system-unit-rosters, system-economy, system-enemy-ai, system-tech-tree, system-counter-systems, system-difficulty-and-dda]
+anchors: [anchor-starcraft, anchor-age-of-empires]
+verify-with: docs/FUN.md#9--rts-lite
+---
+
+# Real-Time Strategy
+
+**What it is.** You command an army — not a unit. You **gather → build → tech →
+army → engage**, all in real time, against an opponent doing the same. The game
+is *macro* (economy and tech decisions) layered over *micro* (positioning a
+fight), with faction identity coloring every layer.
+
+**Player fantasy / why it's fun.** *"I out-thought them — my build read theirs,
+my army answered it, and the battle was glorious."* RTS is the fantasy of
+command: hundreds of units obey one intent, and a well-composed army crashing
+into a bad one is the payoff shot.
+
+## Pillars
+
+1. **Mass under command.** Hundreds of units path around walls and answer
+   orders as one. Flow fields (one BFS per goal tile, cached *outside* state)
+   give wall-aware mass pathing cheaply — pathing is the genre's hardest tech
+   and its most load-bearing.
+2. **Asymmetry that balances.** Factions are *different, not reskinned* — and
+   still fair. Distinct rosters, one balance. This is the deep well; get it
+   right and every matchup is a new game.
+3. **The intended line beats attack-move.** Strategy is the balance test. A
+   thinking plan (turtle → tech → counterpush) must beat brute attack-move, or
+   there is no strategy — just a bigger blob.
+
+## The loop stack
+
+| Scale | The beat |
+|---|---|
+| **Moment** | Issue an order — a group micro (focus fire, retreat, flank); units path and arrive. |
+| **Encounter** | An engagement: your composition vs theirs, terrain and positioning decide it in seconds. |
+| **Session** | A match: opening build → scout → adapt tech to the enemy → the decisive push. |
+| **Meta** | Learn each faction's build orders, matchup counters, and timing windows. |
+
+## Essential systems
+
+| System | Why it's load-bearing |
+|---|---|
+| [[system-faction-asymmetry]] | The genre's soul. Different-but-fair identities; the design of asymmetric balance. |
+| [[system-unit-rosters]] | A legible roster of roles and tiers per faction — the vocabulary of composition. |
+| [[system-economy]] | Gather/faucet-sink macro; the eco-vs-army tension every decision trades against. |
+| [[system-tech-tree]] | The ramp of options and power spikes; branch choices commit you to a plan. |
+| [[system-enemy-ai]] | The AI opponent (and unit behaviour): readable, beatable, order-obeying minds. |
+| [[system-counter-systems]] | The NvN duel matrix that makes composition a real decision. |
+
+## Strategic depth — where the game lives
+
+Depth is the *stack of layered decisions*, each with tension:
+
+- **Economy vs army.** Every worker is delayed military. The eco/army/tech
+  triangle (AoE ages, StarCraft supply timings) is the core macro tension.
+- **Build order as a plan.** An opening commits you — greedy-eco vs early
+  pressure vs tech rush. Scouting is the info that lets you punish or adapt.
+- **Composition as a puzzle.** Counters ([[system-counter-systems]]) make army
+  mix a rock-paper-scissors under fog. No unit is unconditionally best.
+- **Timing windows.** A power spike (age-up, a tech completing) opens a window
+  where you're temporarily ahead — attacking on-spike is the skill.
+- **Positioning micro.** Terrain, high ground, concave/surround, focus-fire.
+  Same armies, different outcomes by *how* they meet.
+
+## Faction asymmetry — go deep here
+
+The flagship difference. See [[system-faction-asymmetry]] for the full design;
+the genre-level rules:
+
+| Axis of difference | Example |
+|---|---|
+| **Economy shape** | One faction gathers faster but caps lower; another snowballs late. |
+| **Roster identity** | Swarm-and-remax vs elite-and-expensive vs defensive-and-teched. |
+| **Tech philosophy** | Wide/cheap upgrades vs deep/spiky ones. |
+| **Signature mechanic** | One unique verb per faction (a build mechanic, a resource) that only they play. |
+
+Balance them not by making them equal but by making each **strong at a different
+timing** — asymmetry balances *across* the game clock, not within a single stat.
+Ground every faction's fiction in [[world-faction-identity]] so the mechanics
+*read* as a culture, not a stat block.
+
+## Battle spectacle — the payoff shot
+
+The reason to watch: two armies colliding must look *impressive* and stay
+*readable*.
+
+- **Legibility first.** Silhouette and color-code unit roles so a 100-unit fight
+  parses at a glance — [[pattern-readability]]. Spectacle that can't be read is
+  noise.
+- **Choreography is cosmetic.** The sim resolves the fight; the view replays hit
+  flashes, death animations, dust, screen-shake — all deletable without changing
+  a sim bit (FUN.md law 6). Never let spectacle touch `world.hash()`.
+- **Scale legibly.** Pooled sprites and flow-field movement keep hundreds of
+  units cheap; the *mass* is the spectacle.
+
+## Content & difficulty model
+
+- **Balance is the content.** Matchups, not levels. The intended line beating
+  attack-move (law 2 skill-delta) is the health check.
+- **AI tiers = economy handicaps + better build orders**, not stat cheats the
+  player can't see. See [[system-difficulty-and-dda]].
+- **Skirmish maps** are the container; procedural or hand-made, they must be
+  symmetric-fair (equal resources, mirrored expansions).
+
+## Signature-mechanic seeds
+
+- **RTS but you ARE one hero in the battle** *(perspective)* — Shadow-of-War
+  scale flip; command from inside the fight, morale as your reach.
+- **RTS but no base — the army is all you get** *(constraint)* — one-loop
+  attrition; every unit lost is permanent, forcing preservation micro.
+- **RTS but time advances in pulses you trigger** *(structure)* — semi-turn-based
+  mass tactics; a bridge to [[genre-tactics]] at army scale.
+- **RTS but the map is a living tide** *(theme + mechanic-swap)* — terrain
+  floods/regrows on a clock; positioning fights the map, not just the enemy.
+- **RTS but one faction plays the economy and one plays the army** *(perspective
+  + coop)* — asymmetric two-player command. Pairs
+  [[system-coop-and-competition]].
+
+## Common pitfalls
+
+- **Attack-move wins.** If a-move beats every plan, macro and composition are
+  decorative — the whole game collapses. This is the first thing to disprove.
+- **Reskin factions.** Same units, different colors = no asymmetry, no replay.
+  Differentiate the *economy and roster*, not the palette.
+- **Pathing that clumps or stalls.** Units that pile at walls or block each other
+  break "mass under command." Flow fields, cached outside state, are the fix.
+- **Unreadable battles.** A gorgeous fight you can't parse is a loss for the
+  player. Legibility gates spectacle.
+- **Snowball with no comeback.** A single lost fight ending the match kills
+  tension — leave comeback vectors (defensive tech, eco recovery). See
+  [[pattern-feedback-loops]].
+
+## Anchors
+
+- [[anchor-starcraft]] — three rosters, one balance; the reference for asymmetry
+  done right. Steal the "strong at different timings" balance philosophy.
+- [[anchor-age-of-empires]] — the eco/tech ramp and age-up power spikes; steal
+  build orders and the economy-as-tension model.
+
+## Verify
+
+Prove it in **[FUN.md §9 · RTS-lite](../../docs/FUN.md#9--rts-lite)**: every
+counter edge wins its NvN duel, the commander/intended-line bot beats
+attack-move, a walled-off unit routes around, and ms/step holds at peak unit
+count.
+
+## Composes with
+
+- [[system-faction-asymmetry]] — the different-but-fair identities that give the
+  genre its replay value.
+- [[system-economy]] — the macro tension every strategic decision trades against.
+- [[system-enemy-ai]] — the order-obeying, beatable minds behind the mass.
+
+## See also
+
+- [`sandboxes/pathfinding-demo`](../../sandboxes/pathfinding-demo) — flow-field
+  mass pathing; the load-bearing tech for hundreds of wall-aware units.
+- [`sandboxes/particle-studio`](../../sandboxes/particle-studio) — pooled sprites
+  and effects for cheap, legible battle spectacle (cosmetic, law 6).
+- [docs/JUICE.md](../../docs/JUICE.md) — impact feel for the payoff shot without
+  touching the sim.

package/design/20-genres/stealth.md

@@ -0,0 +1,125 @@
+---
+id: genre-stealth
+title: Stealth
+kind: genre
+tags: [stealth, vision-cone, patrol, noise, plan, heist, guard, route]
+summary: Plannable danger — vision cones and noise you can read, so the tension is the gap between a route you can see and a route you can execute.
+use-when: Designing a game where the fun is reading enemy perception and routing through it, not out-shooting it.
+composes-with: [system-enemy-ai, system-telegraphs, system-encounter-design, system-save-and-checkpoint, system-onboarding, system-difficulty-and-dda]
+anchors: [anchor-shadow-of-mordor]
+verify-with: docs/FUN.md#5--stealth
+---
+
+# Stealth
+
+**What it is.** Guards with legible **vision cones** and **noise** radii patrol a
+space. You are weak in the open and safe in the seams. The game is a live routing
+puzzle: read perception, find the gap, move through it, don't be seen.
+
+**Player fantasy / why it's fun.** *"I threaded the needle."* The held breath of
+slipping behind a guard whose cone you *watched*, timing your dash to the exact
+beat his back turns. Power fantasy inverted: you win by being unseen, and the
+world is more dangerous than you.
+
+## Pillars
+
+1. **Perception is legible.** Cones, hearing radii, and alert states are drawn or
+   inferable. The player plans against *visible* danger — a threat you can't read
+   is a cheap death, not tension (FUN.md §5 demands both-ways affordance proofs).
+2. **Concealment actually conceals.** Shadows hide, cover blocks sight, a distraction
+   pulls a gaze — reliably, through a full patrol loop. If hiding is a coin flip,
+   planning is pointless (pillar 1's dual).
+3. **Exposure is punished fast.** Being seen escalates quickly — an alert, a hunt,
+   a fail-or-flee. The knife-edge between hidden and caught is where the genre
+   lives.
+
+## The loop stack
+
+| Scale | The loop |
+|---|---|
+| **Moment** | Watch a cone sweep; time a move through the gap it leaves. |
+| **Encounter** | Cross one guarded room: read the patrol, find the safe pocket, chain single-guard windows. |
+| **Session** | A level/heist: string encounters into a route to an objective and back out. |
+| **Meta** | Optional ghost (0-alert) runs, alternate routes, tools that reshape perception — mastery of the space. |
+
+## Essential systems
+
+| System | Why it's needed |
+|---|---|
+| [[system-enemy-ai]] | Patrols, gaze, alert-state escalation, aggro/threat — readable, beatable minds; the danger *is* the AI. |
+| [[system-telegraphs]] | The alert ramp (suspicion → search → chase) must be telegraphed so the player can react before it's terminal. |
+| [[system-encounter-design]] | Composing cones and pockets; the safe-pocket-at-midpoint and chained-single-guard rules live here. |
+| [[system-save-and-checkpoint]] | Getting caught should rewind to a fair, recent checkpoint — long re-stealth is punishment tax, not tension. |
+| [[system-onboarding]] | Teach cone-reading and noise in a no-fail room before the first real guard. |
+| [[system-difficulty-and-dda]] | Difficulty = cone density and window tightness; assist options widen windows or slow patrols. |
+
+## Content & difficulty model
+
+- **Balance on cone-shadow duration, not guard distance.** The real constraint is
+  *how long* the safe gap in a guard's sweep stays open along your path — the chord
+  of shadow, not raw spacing (FUN.md §5). Compute it against the actual route.
+- **A safe pocket at every long traversal's midpoint.** No open crossing longer
+  than a player can hold under one window; give a place to breathe (FUN.md §5).
+- **Chain single-guard windows; never require joint phases.** Waiting for two
+  patrols to align by chance explodes combinatorially into unfair wait times —
+  design so each step depends on *one* guard's timing (FUN.md §5).
+- **Prove affordances both ways.** Exposure punished fast AND hiding conceals
+  through a full loop. "The bot got through" proves neither on its own — you need
+  the punished-exposure and concealment-holds assertions.
+
+Reference wiring: [`examples/veilstep`](../../examples/veilstep) — the canonical
+stealth sim: cones drawn from `world.state`, the heist-bot 0-alarm run plus the
+punished-exposure and concealment-holds proofs. Grep [`docs/API.md`](../../docs/API.md)
+for the raycast/FOV and audio primitives.
+
+## Signature-mechanic seeds
+
+"X but Y" ([[process-the-twist]]) — bend *what perceives you* or *what you control*.
+
+- **Stealth but you control the guards' distractions, not the thief** — you route
+  an AI thief by pulling gazes. (perspective)
+- **Stealth but light is your resource** — you carry the only lamp; every step lit
+  is a step seen, so you ration your own visibility. (constraint — pairs with survival-horror light)
+- **Stealth but the guards remember and adapt** — patrol a room twice the same way
+  and they pre-empt it. (mechanic-swap — see [[anchor-shadow-of-mordor]])
+- **Stealth but sound is the only sense** — no cones; guards are blind and you hide
+  in silence, routing by noise alone. (constraint)
+- **Stealth but you're the guard hunting an invisible intruder** — read *their*
+  noise, cut off *their* route. (perspective)
+
+## Common pitfalls
+
+- **Illegible perception.** Cones you can't see or infer make stealth a save-scum
+  lottery. Draw the danger.
+- **Concealment that doesn't.** If shadow only *sometimes* hides, the player stops
+  trusting the map and starts fleeing — the loop collapses. Prove it holds a full
+  loop.
+- **Joint-phase gates.** Requiring two patrols to align is an unfair wait. Chain
+  single-guard windows.
+- **Pocketless marathons.** A long open crossing with no midpoint refuge is a
+  memorisation gauntlet, not a plan.
+- **Combat as the out.** If fighting your way through is easier than sneaking, it's
+  a shooter with cones. Make exposure genuinely costly.
+
+## Anchors
+
+- [[anchor-shadow-of-mordor]] — systemic guard memory; enemies that adapt to your
+  routes turn stealth into an evolving rivalry.
+
+## Verify
+
+Prove it with **[FUN.md §5 · Stealth](../../docs/FUN.md#5--stealth)** —
+heist bot 0-alarm run + a punished-exposure assertion + a concealment-holds
+assertion, balanced on cone-shadow duration with a midpoint pocket per long
+traversal. Design the plannable danger here; prove both affordances there.
+
+## Composes with
+
+- [[system-enemy-ai]] — readable, beatable patrol minds are the danger.
+- [[pattern-pacing-and-tension]] — the hidden/caught knife-edge is a tension curve.
+- [[system-encounter-design]] — cones and pockets composed into a route.
+
+## See also
+
+- [`examples/veilstep`](../../examples/veilstep) — the reference stealth sim + proofs.
+- [`docs/FUN.md §5`](../../docs/FUN.md#5--stealth) — the proof playbook.

package/design/20-genres/survival-horror.md

@@ -0,0 +1,124 @@
+---
+id: genre-survival-horror
+title: Survival Horror
+kind: genre
+tags: [survival-horror, dread, resource, fuel, light, darkness, tension, scarcity]
+summary: Scarcity-driven dread where difficulty lives in resource arithmetic — dread you can budget, not monster stats you can't.
+use-when: Designing a survival-horror game whose fear is scarcity you must ration, with light/dark and a fuel economy as the pressure.
+composes-with: [system-economy, system-grace, pattern-pacing-and-tension, system-resource-loops]
+anchors: [anchor-outer-wilds]
+verify-with: docs/FUN.md#16--survival-horror
+---
+
+# Survival Horror
+
+**What it is.** A hostile dark you must cross with too little to cross it. Fuel, light,
+ammo, and health are scarce; the monster is a pressure, not a stat-check. You budget
+your way to dawn — every lit second spends a resource you can't get back.
+
+**Player fantasy / why it's fun.** *"I can survive this if I spend right — and I'm not
+sure I can afford it."* The fear is **dread you can budget**: horror that lives in
+arithmetic, so the player is always calculating, never merely reacting. Tension is a
+ledger with a monster leaning over it.
+
+## Pillars
+
+1. **Difficulty is resource arithmetic.** The night is hard because the **fuel economy**
+   is tight, not because the monster hits for more. Balance lives in a spreadsheet you
+   expose to the player as scarcity.
+2. **Camping is impossible; the night is winnable — from the same numbers.** One fuel
+   inequality must prove *both*: you cannot hide until dawn, and dawn is reachable if
+   you spend well. That single arithmetic sets the whole difficulty.
+3. **Wound before death; grace over instadeath.** One grab is a story; two is a death.
+   The genre's mercy is a [[system-grace]] system — a wound state and buffered intent —
+   not a coin-flip kill.
+
+## The loop stack
+
+| Layer | The beat |
+|---|---|
+| **Moment** | Spend light to see → move through danger → the meter drops. |
+| **Encounter** | A room/threat: cross it on a fuel budget, take a wound or spend to avoid it. |
+| **Session** | A night: reach dawn before the economy runs dry. |
+| **Meta** | Nights, upgrades, map knowledge; scarcity eases as mastery grows. |
+
+## Essential systems
+
+| System | Why this genre needs it |
+|---|---|
+| [[system-economy]] | Fuel/light/ammo faucets and sinks ARE the difficulty; a tight, honest ledger is the whole tension. |
+| [[system-grace]] | The wound-before-death mercy; one grab buffers, two kills — grace as a system, unit-tested to the frame. |
+| [[pattern-pacing-and-tension]] | Dread needs valleys (safe rooms, saved light) to make the peaks (a chase, a dark corridor) land. |
+| [[system-resource-loops]] | Gather light/fuel → spend to survive → find more; the bottleneck is the pacing. |
+| [[system-save-and-checkpoint]] | Horror respects the player's time between dread spikes; a punishing retry loop turns fear into resentment. |
+| [[system-enemy-ai]] | The monster must be readable and beatable — a pressure with tells, not an invisible dice roll. |
+
+## Content & difficulty model
+
+- **Prove both halves of the fuel inequality.** From one arithmetic: a **keeper/camping
+  bot must die** (you can't hide to dawn) AND a diligent bot **survives to dawn** (the
+  night is winnable). If camping survives, there's no threat; if nothing survives, it's
+  unfair.
+- **Light must collide with the world.** Anything that interacts with light must collide
+  with the light's occluders — or shadows hide invisible, unfair killers. Prove
+  *light-repels* and *darkness-kills* each as a rule, against the actual geometry.
+- **Difficulty = tighter budget, not bigger numbers.** A harder night gives less fuel,
+  a longer dark, fewer safe rooms — never a monster with more HP. Scarcity scales; the
+  monster stays a pressure.
+- **Wound honesty.** A grab wounds visibly and buffers; the next is lethal. Assert the
+  grace window frame-exactly (same shape as any grace system).
+- **Content is nights + map.** New nights add a new arithmetic wrinkle (a new sink, a
+  darker map); knowledge of the map is the real progression.
+
+## Signature-mechanic seeds
+
+- **Survival horror but cozy by day, dread by night** — you tend and rebuild in light,
+  then defend on a fuel budget in the dark (tonal + structure; splices
+  [[genre-farming-sim]]'s calm against the night's ledger).
+- **Survival horror but knowledge is the only weapon** — no combat; you survive by what
+  you've learned about the monster's rules (mechanic-swap toward [[anchor-outer-wilds]];
+  dread becomes deduction).
+- **Survival horror but the light is a shared resource in coop** — two players, one fuel
+  ledger, forced communication in the dark (perspective + constraint; pairs with
+  [[system-coop-and-competition]]).
+- **Survival horror but every death rewrites the house** — the map remembers and mutates
+  around your failures (structure; systemic memory à la [[system-emergent-systems]]).
+- **Survival horror but one candle, one screen, sixty seconds** — a hard constraint that
+  makes every second of light a decision (constraint).
+
+## Common pitfalls
+
+- **Difficulty in monster stats.** Scaling HP/damage makes horror a stat-check, not a
+  budget; the fear evaporates into a health bar. Scale scarcity instead.
+- **Light without occlusion.** Shadows that don't collide become invisible killers — the
+  single most unfair bug the genre invites.
+- **Campable nights.** If hiding survives to dawn, there's no threat; the fuel inequality
+  exists to forbid it.
+- **Instadeath.** A coin-flip kill reads as unfair and breaks the budgeting fantasy; wound
+  first, buffer intent, then kill.
+- **Relentless dread.** Unbroken tension goes numb; without safe valleys the peaks stop
+  spiking. [[pattern-pacing-and-tension]] is load-bearing here.
+
+## Anchors
+
+- [[anchor-outer-wilds]] — knowledge as the only progression; the reference for the
+  no-combat, dread-as-deduction bend, and for a curiosity-gated dark to explore.
+
+## Verify
+
+Keeper bot survives to dawn; light-repels and darkness-kills each proven; fuel solvency
+inequality; golden night → **[docs/FUN.md §16 · Survival horror](../../docs/FUN.md#16--survival-horror)**.
+Author the ledger and the mood-predicate here; prove the inequality there.
+
+## Composes with
+
+- [[system-economy]] — the fuel/light ledger that IS the difficulty.
+- [[system-grace]] — the wound-before-death mercy that keeps dread fair.
+- [[pattern-pacing-and-tension]] — the valleys that make the dread spikes land.
+
+## See also
+
+- [docs/FUN.md §16](../../docs/FUN.md#16--survival-horror) — mechanical truth + verify recipe.
+- [docs/JUICE.md](../../docs/JUICE.md) — feel gates for the light/shadow and wound choreography.
+- [`sandboxes/`](../../sandboxes/) — the light/physics lab to prove occlusion and a fuel
+  budget before building a night.

package/design/20-genres/tactics.md

@@ -0,0 +1,123 @@
+---
+id: genre-tactics
+title: Turn-Based Tactics
+kind: genre
+tags: [tactics, turn-based, grid, telegraphs, perfect-information, puzzle, positioning]
+summary: Rewriting a telegraphed future — perfect information, honest tells stored as directions, and every fight a solvable positioning puzzle.
+use-when: You want a grid combat game where you see the enemy's plan and the fun is redirecting it, not out-rolling it.
+composes-with: [system-telegraphs, system-enemy-archetypes, system-encounter-design, system-combat-model, system-difficulty-and-dda]
+anchors: [anchor-into-the-breach]
+verify-with: docs/FUN.md#12--turn-based-tactics-into-the-breach-like
+---
+
+# Turn-Based Tactics
+
+**What it is.** Grid combat where the enemy **shows you their whole plan**, then
+you act. No hidden rolls, no fog — the fun is *rewriting a telegraphed future*
+with positioning: push an enemy so its attack hits another enemy, block a spawn,
+bump a unit off a ledge. Each fight is a solvable puzzle, not a dice game.
+
+**Player fantasy / why it's fun.** *"I saw the disaster coming and turned it
+against them."* Perfect information makes you feel like a chess master: the win
+is *found*, not *rolled*, and a clean multi-enemy redirect is pure satisfaction.
+
+## Pillars
+
+1. **Rewrite the telegraph.** Store telegraphs as **directions on units**, not
+   target tiles — so pushing a unit *re-resolves* what it hits. The telegraph is
+   a live plan you edit, which is the entire game.
+2. **Perfect information, perfect honesty.** What's shown is exactly what
+   resolves. No hidden variance. The genre's trust is that the display is the
+   truth (law 6).
+3. **Both proofs, every scenario.** A scenario needs a *winning line* AND a
+   *losing do-nothing*. If passivity survives, there's no threat; if no line
+   exists, it's unfair. The first cut's bug is usually "can't even reach the
+   objective."
+
+## The loop stack
+
+| Scale | The beat |
+|---|---|
+| **Moment** | Read a telegraph → move/push a unit → watch the future re-resolve in your favor. |
+| **Encounter** | A scenario: protect an objective from telegraphed threats over N turns using positioning. |
+| **Session** | A mission chain / island: escalating scenarios, limited resources carried between them. |
+| **Meta** | Unlock squads, mechs, and mechanics; learn the redirect vocabulary. |
+
+## Essential systems
+
+| System | Why it's load-bearing |
+|---|---|
+| [[system-telegraphs]] | The whole loop. Stored as directions, resolved after your move — the editable future. |
+| [[system-enemy-archetypes]] | The threat roles whose telegraphs you redirect — melee, artillery, spawner, boss. |
+| [[system-encounter-design]] | Composing archetypes + objectives into a scenario with a findable line and a losing null. |
+| [[system-combat-model]] | Push, bump, redirect resolution — the deterministic rules a scenario is built on. |
+| [[system-difficulty-and-dda]] | Threat density and turn count as the ramp; harder = tighter lines, not hidden rolls. |
+
+## Content & difficulty model
+
+- **Content is scenarios, not stats.** A scenario is a board + objective + a
+  telegraphed threat sequence with a *provable* solution. Hand-authored or
+  generated, each must pass the two proofs.
+- **Difficulty = tighter solution space.** More threats, fewer turns, harder
+  objectives — the line still exists but demands more precision. Never add hidden
+  variance to raise difficulty.
+- **Every mechanic proven in isolation.** Push, bump, redirect, spawn-block each
+  get a unit test before they combine (law 3 / derive-don't-vibe).
+- **Bots are real defenders.** A 1-ply greedy planner over `structuredClone`
+  scoring is a genuine baseline — it should perfect-clear a solvable scenario and
+  the do-nothing bot should lose everything.
+
+## Signature-mechanic seeds
+
+- **Tactics but you command the enemies too** *(perspective)* — set both sides'
+  telegraphs, then a rival edits yours; a duel of redirects.
+- **Tactics but the grid is a deck you draft** *(structure)* — Into-the-Breach
+  meets Slay-the-Spire; your moves are cards. Bridges [[genre-deckbuilder]].
+- **Tactics but one push ripples through a chain** *(mechanic-swap)* — dominoes:
+  every shove can cascade, turning the board into a physics puzzle.
+- **Tactics but you protect a city that remembers** *(theme + structure)* —
+  Kentō town rebuilt between missions; buildings saved persist as bonuses.
+- **Tactics but the future is shown only for one turn** *(constraint)* — a memory
+  variant; you plan several moves against a telegraph you can no longer see.
+
+## Common pitfalls
+
+- **Telegraphs stored as tiles.** If a tell targets a *tile*, pushing the
+  attacker doesn't rewrite it — and the core verb (redirect) silently breaks.
+  Store directions on units.
+- **Hidden variance.** Any concealed roll violates the perfect-information trust;
+  a "miss" the player couldn't foresee feels like a betrayal.
+- **Passive survives.** A scenario a do-nothing bot lives through has no threat.
+  Always assert the losing null.
+- **No line exists.** An unsolvable scenario is unfair. Prove the winning line
+  before shipping (greedy bot perfect-clears).
+- **Objective unreachable.** The classic first-cut bug — the plan can't even
+  touch the goal. Test reachability.
+
+## Anchors
+
+- [[anchor-into-the-breach]] — the definitive reference: perfect information,
+  telegraphed grid, redirect-the-future. Steal the whole model.
+- [[genre-deckbuilder]] — a natural blend (moves-as-cards); shares the
+  telegraph-honesty and skill-delta discipline.
+
+## Verify
+
+Prove it in **[FUN.md §12 · Turn-based
+tactics](../../docs/FUN.md#12--turn-based-tactics-into-the-breach-like)**: the
+greedy bot perfect-clears, the do-nothing bot loses everything, each mechanic
+(push/bump/redirect) is proven in isolation, and a golden end-state replays.
+
+## Composes with
+
+- [[system-telegraphs]] — the editable future that IS the loop.
+- [[system-enemy-archetypes]] — the threat roles you redirect.
+- [[system-encounter-design]] — scenarios with a findable line and a losing null.
+
+## See also
+
+- [`examples/sokoban`](../../examples/sokoban) — the pure `Puzzle<State,Move>`
+  logic/view split and clone-and-score bot; tactics is that pattern with
+  telegraphs (laws 6, 7).
+- [docs/FUN.md](../../docs/FUN.md) Part 1 — laws 3, 6, 7 underwrite this genre's
+  determinism and honesty.