hayao 0.4.0 → 0.4.2

package/design/20-genres/city-builder.md

@@ -0,0 +1,124 @@
+---
+id: genre-city-builder
+title: City / Colony Builder
+kind: genre
+tags: [city-builder, colony, placement, adjacency, synergy, score, zoning, optimization]
+summary: Placement-optimization builder where the exposed live score under the cursor IS the UI, and negative synergies make the only real decisions.
+use-when: Designing a city/colony builder where the fun is placing tiles for adjacency payoff, guided by a live score and real tradeoffs.
+composes-with: [system-economy, system-resource-loops, pattern-feedback-loops, system-procgen-design]
+anchors: [anchor-factorio, anchor-rimworld]
+verify-with: docs/FUN.md#17--citycolony-builder
+---
+
+# City / Colony Builder
+
+**What it is.** A grid or map you fill with buildings whose value depends on what
+sits next to them. Placement is the whole verb: each tile scores from its neighbours,
+and a live **"+N" under the cursor** tells you exactly what a spot is worth before you
+commit. You optimize a growing layout against its own synergies.
+
+**Player fantasy / why it's fun.** *"That corner is worth +7 — but it'd waste the river
+tile."* The pull is a legible optimization space where good placement is visibly
+rewarded and greed has a cost. Fun is **the exposed score**: the decision is on screen,
+quantified, and yours.
+
+## Pillars
+
+1. **The exposed score is the UI.** One pure `placementScore` serves the sim, the bot,
+   the tests, *and* the "+N" label under the cursor. The live number is not decoration —
+   it's the entire interface between intent and system.
+2. **Negative synergies create the only real decisions.** If every placement is
+   strictly additive, the greedy move is always right and there's no game. Tradeoffs —
+   this bonus costs that one — are what make a layout a puzzle.
+3. **The layout is a standing feedback loop.** Each building reshapes the value of its
+   neighbours, so the map's optimum drifts as it grows. You're steering a system, not
+   filling a form.
+
+## The loop stack
+
+| Layer | The beat |
+|---|---|
+| **Moment** | Hover a tile → read the "+N" → place for the payoff (or the tradeoff). |
+| **Encounter** | A wave/queue of buildings to place well before space or budget runs out. |
+| **Session** | A map/island: raise the total score against its synergy constraints. |
+| **Meta** | Unlocks, larger/varied maps, new building types with new adjacency rules. |
+
+## Essential systems
+
+| System | Why this genre needs it |
+|---|---|
+| [[system-economy]] | Resources produced and consumed by buildings; the sinks that stop pure additive sprawl. |
+| [[system-resource-loops]] | Extract→process→consume chains give buildings reasons to cluster and compete for space. |
+| [[pattern-feedback-loops]] | Adjacency synergies are the loop; negative synergies are the damping that keeps it a decision. |
+| [[system-procgen-design]] | Varied maps/queues as content; seeds give replay and a fairness sweep (queue always fits). |
+| [[system-onboarding]] | Teach one adjacency rule at a time; the "+N" label is itself the tutorial. |
+| [[system-collectibles]] | Milestones, cosmetics, layout goals — optional pull past hitting the target. |
+
+## Content & difficulty model
+
+- **One pure scorer, four consumers.** `placementScore` must be the *single* source of
+  truth for sim, bot, tests, and the on-screen "+N". A score the label computes
+  differently from the sim is a lie the audit must catch (score-honesty audit).
+- **Prove the greedy bot faces tradeoffs.** Assert **greedy ≈ 2× random** — skill
+  separates from luck. If greedy never faces a negative synergy, neither does the
+  player; the tradeoffs aren't real.
+- **Queue-always-fits sweep.** Over N maps/seeds, assert the placement queue can always
+  be legally placed — the builder's connectivity/fairness proof (a solvability guarantee
+  like the match-3 board's).
+- **Difficulty = tighter space / sharper tradeoffs.** Harder maps give less room or
+  stronger negative synergies, not just bigger targets. The optimization gets meaner,
+  the score honest.
+- **Content is building vocabulary.** Each new building type should add an adjacency
+  *relationship* (a new synergy or anti-synergy), not just a new sprite.
+
+## Signature-mechanic seeds
+
+- **City builder but it's a colony of people with needs and moods** — placement serves a
+  simulated populace and an AI director authors drama around it (mechanic-swap +
+  structure toward [[anchor-rimworld]]; the score becomes lives).
+- **City builder but the layout is a factory graph** — buildings are machines, adjacency
+  is throughput, the bottleneck is the puzzle (mechanic-swap toward [[anchor-factorio]]).
+- **City builder but you place from a drafted hand** — each turn deals building options;
+  the bend fuses [[genre-deckbuilder]] draft-of-N onto placement (structure).
+- **City builder but every tile is one screen and permanent** — a hard spatial + no-undo
+  constraint makes each "+N" a commitment (constraint).
+- **City builder but it's a garden, not a metropolis** — tonal bend toward
+  [[genre-farming-sim]] calm; adjacency is companion planting, growth is the score.
+
+## Common pitfalls
+
+- **Two scores.** A label that computes value differently from the sim breaks trust
+  invisibly; enforce one pure `placementScore`.
+- **All-additive synergies.** With no tradeoffs the greedy move always wins and the game
+  is a formality. Negative synergies are non-optional.
+- **A queue that can't fit.** An unplaceable building is an unfair softlock; the
+  queue-fits sweep exists to forbid it.
+- **Score with no meaning.** A number that doesn't gate anything is wallpaper; tie it to
+  progression or a target the player is chasing.
+- **Building bloat.** New types that don't add a relationship dilute the read; every one
+  should change an adjacency decision.
+
+## Anchors
+
+- [[anchor-factorio]] — adjacency-as-throughput, the layout as the toy, complexity
+  scaling with the build; the factory-graph seed's reference.
+- [[anchor-rimworld]] — the colony sim as a story generator, an AI director over the
+  placement; the reference for the people-with-needs bend.
+
+## Verify
+
+N-island queue-always-fits sweep; greedy ≈ 2× random skill delta; scoring-honesty
+audit; golden → **[docs/FUN.md §17 · City/colony builder](../../docs/FUN.md#17--citycolony-builder)**.
+Design the synergy space and the exposed score here; prove the delta and the audit there.
+
+## Composes with
+
+- [[system-economy]] — the sinks and resources that keep placement from pure sprawl.
+- [[system-resource-loops]] — the extract→process→consume chains that make buildings compete for space.
+- [[pattern-feedback-loops]] — the adjacency loop and the negative-synergy damping.
+
+## See also
+
+- [docs/FUN.md §17](../../docs/FUN.md#17--citycolony-builder) — mechanical truth + verify recipe.
+- [`sandboxes/`](../../sandboxes/) — the procgen/economy lab to prototype a scorer and a
+  queue-fits sweep before authoring buildings.

package/design/20-genres/coop-chaos.md

@@ -0,0 +1,124 @@
+---
+id: genre-coop-chaos
+title: Coop Chaos
+kind: genre
+tags: [coop, couch-coop, party, overcooked, communication, chaos, shared-task, local-multiplayer]
+summary: Couch-coop chaos — escalating shared tasks that force communication under time pressure; the friction between players IS the fun.
+use-when: The design is a local/party coop game where players juggle interdependent tasks against a clock and must talk to survive.
+composes-with: [system-coop-and-competition, system-difficulty-and-dda, system-encounter-design, pattern-pacing-and-tension, genre-narrative-decisions]
+anchors: [anchor-overcooked, anchor-it-takes-two]
+verify-with: docs/FUN.md#8-·-tower-defense
+---
+
+# Coop Chaos
+
+**What it is.** Two-to-four players share one escalating task — a kitchen, a ship, a
+factory — where the work outpaces any single pair of hands. Success needs division
+of labour, hand-offs, and constant talk; the *joyful friction* between players is
+the product. **Extension** beyond FUN.md's 21 genres.
+
+**Player fantasy.** *"We did that — barely."* The shared adrenaline of a near-miss
+pulled off by shouting the right thing at the right second; a story you tell
+afterward, together.
+
+## Pillars
+
+1. **Communication forced by design.** The layout, not the rules, makes players
+   talk — split resources, blind hand-offs, a task no one can finish alone. If
+   silence works, it isn't coop chaos.
+2. **Escalating shared load.** Difficulty is *throughput* the table demands vs the
+   throughput the players can coordinate. The clock and the order queue ramp; the
+   kitchen literally shifts under them.
+3. **Legible chaos.** However frantic, every station, order, and hazard reads at a
+   glance. Chaos you can't parse is noise; chaos you can *just barely* parse is fun.
+
+## The loop stack
+
+| Scale | The beat |
+|---|---|
+| **Moment** | Grab → carry → hand off → place; one micro-task, contested by space and time. |
+| **Encounter** | A level/round: fulfil an order queue before the timer, as a layout fights you. |
+| **Session** | A run of levels; escalating kitchens; star thresholds gating the next. |
+| **Meta** | Unlocked levels/tools/modifiers; co-op star totals; the campaign map. |
+
+## Essential systems
+
+| System | Why it's load-bearing |
+|---|---|
+| [[system-coop-and-competition]] | Interdependence is the core — design tasks no one player can solo. |
+| [[system-difficulty-and-dda]] | The order-rate ramp and the layout-shift are the difficulty; scale to player count. |
+| [[system-encounter-design]] | A level is composed pressure + pockets; the moving hazard IS the encounter. |
+| [[pattern-pacing-and-tension]] | Deliberate breather beats between order surges; the finale is the peak. |
+| [[system-session-structure]] | Short, replayable rounds; the run shape that suits couch play. |
+
+## Content & difficulty model
+
+- **Difficulty = required throughput vs coordinatable throughput.** State it as an
+  inequality (orders/min the queue demands ≤ what N coordinated players can serve)
+  and tune the queue against it (FUN.md law 3).
+- **The layout is the level.** Author kitchens/ships/rooms, not enemy stats. A
+  moving hazard (a splitting kitchen, a rising tide) is a *pacing* device — treat
+  its rhythm like a tower-defense wave curve: surges with breathers, finale peaks.
+- **Scale to player count deterministically.** Task volume and station count key
+  off N; the same seed with 2 vs 4 players must both be winnable and both replay.
+- **Null-coordination loses.** The scripted "everyone works solo, no hand-offs" run
+  must fail the level — that's the proof the design actually forces coop.
+
+## Signature-mechanic seeds
+
+- **Overcooked *but* the recipe is hidden and only one player can read it** — the
+  forced channel is *information*, not just hands (constraint; composes
+  [[genre-narrative-decisions]] for the reader's dilemma).
+- **Overcooked *but* on a train you build ahead of yourselves** — the workspace is
+  also a shared build task (mechanic-swap; the Unrailed bend).
+- **It Takes Two *but* the two mechanics can jam each other** — interdependence
+  sharpened to interference (mechanic-swap; composes [[system-counter-systems]]).
+- **Overcooked *but* asymmetric roles: one cooks, one defends the kitchen** —
+  a coop-chaos/tower-defense blend (structure; composes [[genre-tower-defense]]).
+- **Coop chaos *but* the tasks are secretly competitive — shared kitchen, private
+  scores** (tonal; composes [[system-coop-and-competition]]'s rivalry hooks).
+
+## Common pitfalls
+
+- **Silence wins.** If a good solo player can carry, the coop is decorative. Force
+  hand-offs and split resources so talking is mandatory.
+- **Illegible frenzy.** Too many simultaneous hazards and the chaos stops reading;
+  players fail without understanding why. Cap concurrent threats; keep salience.
+- **Punishing the weaker player.** Chaos that scapegoats one player kills the couch.
+  Design shared blame — failure should feel like *our* miss.
+- **Wall-clock timing.** Order timers and layout shifts must run on sim time, not
+  `Date.now`, or replays and goldens lie (FUN.md law 6).
+
+## Anchors
+
+- [[anchor-overcooked]] — communication-forced-by-design; escalating kitchens; the
+  canonical coop-chaos loop.
+- [[anchor-it-takes-two]] — asymmetric coop set-pieces; a new interdependent
+  mechanic per chapter.
+
+## Verify — extension note
+
+Coop chaos is an **extension**; it has no dedicated FUN.md section, so it *composes
+the verify patterns of its parents*:
+
+- **Wave/pressure pacing** → [FUN.md §8 — Tower defense](../../docs/FUN.md#8-·-tower-defense):
+  gate the order-queue/hazard curve on "each surge breathes, finale peaks," not
+  monotonicity. **This is the primary proof.**
+- **Encounter containment** → [FUN.md §4 — Action-adventure](../../docs/FUN.md#4-·-top-down-action-adventure-zelda-like):
+  keep hand-off lanes / exit rows clear; assert no station softlocks.
+- **Skill-delta** → [FUN.md law 2](../../docs/FUN.md#part-1--universal-laws):
+  a coordinated bot script clears; the null-coordination script fails. Determinism
+  and cosmetic-view rules apply unchanged (laws 6–7).
+
+## Composes with
+
+- [[system-coop-and-competition]] — the interdependence toolkit; this genre is its
+  loudest expression.
+- [[system-difficulty-and-dda]] — scale pressure to player count and skill.
+- [[pattern-pacing-and-tension]] — the surge/breather rhythm that keeps chaos joyful.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §8 — the wave-curve pattern to borrow for order
+  surges.
+- [[genre-tower-defense]] — the parent whose pressure-curve verify this genre reuses.

package/design/20-genres/deckbuilder.md

@@ -0,0 +1,122 @@
+---
+id: genre-deckbuilder
+title: Roguelike Deckbuilder
+kind: genre
+tags: [deckbuilder, cards, draft, synergy, roguelike, build, win-rate]
+summary: Drafts with teeth — a deck that evolves run-to-run, where the draft delta is provable and every spike is blockable in principle.
+use-when: You want a run-based card game where the deck is the strategy and picking cards well is the whole skill.
+composes-with: [system-build-diversity, system-reward-schedules, system-meta-progression, system-procgen-design, system-status-effects, system-telegraphs]
+anchors: [anchor-slay-the-spire, anchor-balatro]
+verify-with: docs/FUN.md#11--roguelike-deckbuilder
+---
+
+# Roguelike Deckbuilder
+
+**What it is.** A run-based game where your **deck is your build**. You start
+with a weak pile, and after each fight you **draft** a card (usually 1 of 3, with
+a skip) — so the deck *becomes* a strategy over the run. Fights are the pressure
+test; the draft is the decision.
+
+**Player fantasy / why it's fun.** *"I built this engine one card at a time and
+watched it come online."* The pull is the draft with teeth: each pick is a
+commitment, synergies compound, and a deck clicking into a combo is the payoff.
+
+## Pillars
+
+1. **Drafts with teeth.** The reward-of-3-with-a-skip is the core decision.
+   Picks must matter — the same pilot drafting *off* must lose far more (the
+   17→9 delta). If any card is fine, drafting isn't a skill.
+2. **Spikes are blockable in principle.** Incoming damage must be answerable —
+   spike dmg ≤ block ceiling + heal — or a fight is a coin flip, not a puzzle.
+   Perfect telegraph honesty: what's shown is exactly what resolves.
+3. **Balance is a win-rate window.** The health instrument is a *range* (e.g.
+   11–19 of 20), not a target. Both edges break: too-easy AND too-hard are bugs.
+
+## The loop stack
+
+| Scale | The beat |
+|---|---|
+| **Moment** | Play a card from hand: read the telegraph, spend energy, resolve — the choreography returns. |
+| **Encounter** | A fight: your deck's engine vs an enemy's telegraphed intents; block/attack/status math. |
+| **Session** | A run: map choice → fights → draft rewards → shape the deck → boss. Thin vs wide is the arc. |
+| **Meta** | Unlock cards/characters, add to the pool; carry archetype knowledge between runs. |
+
+## Essential systems
+
+| System | Why it's load-bearing |
+|---|---|
+| [[system-build-diversity]] | Multiple viable deck archetypes; the reason to re-run. Making many strategies work. |
+| [[system-reward-schedules]] | The card-reward-of-3, relics, shop, rare drops — the draft cadence and its pull. |
+| [[system-status-effects]] | Poison/block/vulnerable/strength — the stacking rules that create combos. |
+| [[system-telegraphs]] | Enemy intents shown ahead; the honesty that makes fights plannable, not luck. |
+| [[system-procgen-design]] | Seeded map, reward, and enemy variance — each run a fresh hand of choices. |
+
+## Content & difficulty model
+
+- **Content is the card pool + relics + enemy intents.** Depth is *interactions*
+  (synergy engines), not raw card count. A small pool with deep combos beats a
+  big pile of vanilla cards.
+- **Tune the goal to the measured win-rate**, not mechanics to a fixed goal — run
+  a greedy pilot, place the window, adjust rewards/enemy math to land inside it.
+- **Draft delta is the proof.** Same pilot, drafting on vs skipping, must show a
+  large gap (17/20 vs 9/20). If null drafting competes, the draft is
+  decorative.
+- **Intent honesty is a one-line audit.** Resolve each telegraph, compare to the
+  shown number — they must match exactly (law 6 / perfect-info honesty).
+- **Meta adds cards, not power.** Unlocks widen the pool; guard against the deck
+  being decided at the menu. See [[system-meta-progression]].
+
+## Signature-mechanic seeds
+
+- **Deckbuilder but hands score like poker** *(mechanic-swap)* — Balatro's
+  bend: the multiplier engine, not the fight, is the number-go-up. Pairs
+  [[anchor-balatro]].
+- **Deckbuilder but the enemy drafts from your discards** *(structure)* — your
+  cast cards arm the boss; deck-thinning becomes a defensive art.
+- **Deckbuilder but one card, played, is gone forever** *(constraint)* — a
+  scarcity deckbuilder; every play is a spend, hoarding stalls you.
+- **Deckbuilder but cards are inked and fade** *(theme + tonal)* — Kentō
+  woodblock cards that wear with use; the deck is a weathering artifact.
+- **Deckbuilder but two players share one deck** *(perspective + coop)* —
+  alternating draws, one strategy; drafting is negotiation. Pairs
+  [[system-coop-and-competition]].
+
+## Common pitfalls
+
+- **Every card is fine.** With no bad picks, drafting has no teeth. Some cards
+  must be traps in the wrong deck.
+- **Unblockable spikes.** Damage past the block ceiling turns fights into coin
+  flips. Keep spikes answerable in principle.
+- **Single dominant archetype.** If one build always wins,
+  [[system-build-diversity]] failed and replay dies.
+- **Dishonest intents.** A telegraph that resolves to a different number breaks
+  the plannability the whole genre rests on.
+- **Balancing to one edge.** Tuning only against "too hard" ships a too-easy
+  game; the window has two walls.
+
+## Anchors
+
+- [[anchor-slay-the-spire]] — the reference: draft-of-3, map choice, deck-as-
+  evolving-strategy. Steal the whole spine.
+- [[anchor-balatro]] — the score-multiplier variant; steal the joker-synergy
+  "number goes up" juice for a scoring-first bend.
+
+## Verify
+
+Prove it in **[FUN.md §11 · Roguelike
+deckbuilder](../../docs/FUN.md#11--roguelike-deckbuilder)**: a greedy pilot lands
+in the win-rate window, a never-draft pilot falls below it, the intent audit
+matches, and a golden climb hash replays.
+
+## Composes with
+
+- [[system-build-diversity]] — the multiple viable archetypes that carry replay.
+- [[system-reward-schedules]] — the draft cadence and its ethical pull.
+- [[system-status-effects]] — the stacking rules that make synergy engines.
+
+## See also
+
+- [`sandboxes/procgen-lab`](../../sandboxes/procgen-lab) — seeded map/reward
+  variance wiring.
+- [`examples/sokoban`](../../examples/sokoban) — pure-state resolution + returned
+  choreography; a card fight is the same pattern (law 6, 7).

package/design/20-genres/exploration.md

@@ -0,0 +1,131 @@
+---
+id: genre-exploration
+title: Exploration
+kind: genre
+tags: [exploration, discovery, immersive-sim, outer-wilds, obra-dinn, curiosity, knowledge, deduction]
+summary: Discovery as the reward — knowledge is the only progression; curiosity gates the world and understanding is the win.
+use-when: The design gates progress on player knowledge/deduction rather than stats or items (Outer Wilds / Obra Dinn-like).
+composes-with: [system-emergent-systems, system-onboarding, pattern-emergence, genre-narrative-decisions, genre-metroidvania]
+anchors: [anchor-outer-wilds, anchor-return-of-the-obra-dinn]
+verify-with: docs/FUN.md#10-·-traditional-roguelike
+---
+
+# Exploration
+
+**What it is.** The world is a knowledge-locked space: nothing bars you but
+*understanding*. You wander, notice, connect clues, and the "unlock" is a
+realisation in your head, not an item in a bag. **Extension** beyond FUN.md's 21
+genres — discovery / immersive-sim-lite, where curiosity is the whole engine.
+
+**Player fantasy.** *"I figured it out."* The rare, clean high of deduction — the
+world trusted you to reason, and you did. Progress you can't buy, only earn by
+paying attention.
+
+## Pillars
+
+1. **Knowledge is the only progression.** No stat gates, no keys — what you *know*
+   is what lets you proceed. The player, not the avatar, levels up. A gate opens
+   the moment you understand it (Outer Wilds); it never opens by grinding.
+2. **Curiosity is the pull.** Every vista, anomaly, and half-answer plants a
+   question. The design's job is a horizon of "what's *that*?" that keeps refilling.
+3. **The world is internally honest.** It rewards reasoning only if it obeys its own
+   rules perfectly. What you observe must always mean what it seems to — deduction
+   dies on a single lie (Obra Dinn's fates are ground truth).
+
+## The loop stack
+
+| Scale | The beat |
+|---|---|
+| **Moment** | Notice → question → probe; a single observation logged. |
+| **Encounter** | A site/puzzle: gather clues, form a hypothesis, test it. |
+| **Session** | A thread pulled to a realisation that reframes the map. |
+| **Meta** | The web of understanding; the endgame that only *knowledge* unlocks. |
+
+## Essential systems
+
+| System | Why it's load-bearing |
+|---|---|
+| [[system-emergent-systems]] | A world that remembers and interlocks turns wandering into a personal investigation. |
+| [[world-narrative-delivery]] | Story lives in the environment/artefacts/systems — embedded, not narrated at you. |
+| [[system-onboarding]] | Teaching *how to notice* without hand-holding is the hardest first-ten-minutes problem. |
+| [[pattern-emergence]] | Interlocking rules let players deduce consequences you didn't script. |
+| [[system-save-and-checkpoint]] | A knowledge journal / clue log is the save state that respects the player's reasoning. |
+
+## Content & difficulty model
+
+- **Gate on understanding, not stats.** For each gate, name the *piece of knowledge*
+  that opens it and prove the world teaches it somewhere reachable. This is a
+  connectivity problem: is every required clue reachable before the gate that needs
+  it? (Borrow the roguelike connectivity sweep — see Verify.)
+- **A clue log is the progression track.** Surface what the player has deduced (Obra
+  Dinn's confirmed-in-threes). The journal is player-critical knowledge, exposed —
+  the same discipline as showing "nights left" in a farming sim.
+- **Difficulty is inference distance**, not enemy stats — how many clues must chain,
+  how obliquely. Ramp by lengthening the chain, never by hiding a required clue.
+- **Non-linearity is the point.** Multiple threads open at once; author a *web*, not
+  a corridor, and prove several valid orders of discovery reach the end.
+
+## Signature-mechanic seeds
+
+- **Outer Wilds *but* the loop is a single tide, not a supernova — the world resets
+  on a rhythm you must learn** (mechanic-swap; composes [[genre-rhythm]] for the
+  clock).
+- **Obra Dinn *but* the deductions are social — who lied, not who died** (theme;
+  composes [[genre-narrative-decisions]] for the trust meters).
+- **Exploration *but* every ability you'd expect to *find* is instead something you
+  *realise you could always do*** — knowledge as the "power-up" (mechanic-swap;
+  composes [[genre-metroidvania]]).
+- **Exploration *but* co-op: two investigators with different senses must share
+  what only they can perceive** (structure; composes [[genre-coop-chaos]]).
+- **Exploration *but* the map is procedural yet its *rules* are fixed — you learn a
+  grammar, not a layout** (structure; composes [[system-procgen-design]]).
+
+## Common pitfalls
+
+- **A single lie.** If one observed thing doesn't mean what it shows, deduction
+  becomes guessing and trust collapses. The world must be honest to the frame
+  (the Obra Dinn / tactics perfect-information discipline).
+- **Fake curiosity (fetch quests).** Markers and checklists replace wonder with
+  chores. Let the *question* pull, not a waypoint.
+- **Unreachable required knowledge.** A gate whose clue spawns behind that same gate
+  is a softlock. Run the connectivity sweep on *knowledge*, not just geometry.
+- **Over-narration.** Cutscenes that hand you the answer steal the deduction. Deliver
+  through the world; let the player assemble it (see [[world-narrative-delivery]]).
+
+## Anchors
+
+- [[anchor-outer-wilds]] — knowledge as the only progression; a curiosity-gated open
+  world that never gates on items.
+- [[anchor-return-of-the-obra-dinn]] — deduction as the core loop; the game trusts
+  your reasoning and confirms it honestly.
+
+## Verify — extension note
+
+Exploration is an **extension**; with no dedicated FUN.md section it *composes its
+parents' verify patterns*:
+
+- **Reachability/connectivity of required knowledge** → [FUN.md §10 — Roguelike](../../docs/FUN.md#10-·-traditional-roguelike):
+  assert every required clue/gate is reachable across seeds/orders BEFORE tuning
+  difficulty. Full-knowledge bots prove a *line exists*, not player experience —
+  exactly the right claim here. **This is the primary proof.**
+- **Content honesty/lint** → [FUN.md §21 — Narrative decisions](../../docs/FUN.md#21-·-narrative-decisions-reigns-like):
+  clues are data — lint for unique ids, every gate's needs-flag settable, no
+  dangling/contradictory clues, no unreachable content.
+- **Perfect-information honesty** → [FUN.md §12 — Tactics](../../docs/FUN.md#12-·-turn-based-tactics):
+  what's shown resolves exactly as shown; deduction demands it.
+- Determinism + pure-data state (laws 6–7) make the clue web replayable and
+  clone-and-score deducible.
+
+## Composes with
+
+- [[system-emergent-systems]] — interlocking, remembering systems are what make a
+  world worth investigating.
+- [[world-narrative-delivery]] — the delivery half; exploration is its most demanding
+  client.
+- [[genre-metroidvania]] — swap its ability-gates for knowledge-gates and you're here.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §10 — the connectivity sweep, repurposed for
+  knowledge reachability.
+- [[genre-narrative-decisions]] — shares the content-lint discipline for clue data.

package/design/20-genres/farming-sim.md

@@ -0,0 +1,122 @@
+---
+id: genre-farming-sim
+title: Farming / Life Sim
+kind: genre
+tags: [farming, life-sim, calendar, crops, seasons, cozy, solvency, routine]
+summary: Calm calendar-driven life sim where the fun is gentle solvency — plans made on a season that can actually come true.
+use-when: Designing a cozy farming/life sim whose pull is a routine of small plans paying off within an honest calendar.
+composes-with: [system-resource-loops, system-session-structure, system-economy, pattern-pacing-and-tension]
+anchors: [anchor-stardew-valley]
+verify-with: docs/FUN.md#15--farminglife-sim
+---
+
+# Farming / Life Sim
+
+**What it is.** A calendar and a plot of land. You plant, water, wait, harvest,
+sell, and reinvest across seasons — a routine of small chores whose payoff arrives
+on a schedule you can read. Optional threads (relationships, foraging, upgrades)
+braid around the core crop loop.
+
+**Player fantasy / why it's fun.** *"I made a plan on Monday and by harvest it came
+true."* The pull is **gentle solvency**: no fail-screen looming, just plans that
+resolve. Calm isn't the absence of goals — it's goals that are *reachable*, a to-do
+list that closes itself one satisfying day at a time.
+
+## Pillars
+
+1. **Plans that can come true.** The calendar is a hard inequality, not a vibe:
+   **season length ≥ longest growDays + harvest slack**. Every crop the game sells
+   must fit the season it's sold in.
+2. **The player knows what the bot knew.** Surface the critical numbers — *nights
+   left in the season*, days to ripen — on screen. Knowledge the diligent bot needs
+   to win is knowledge the player needs to plan.
+3. **One predicate sets the whole mood.** *"Ripe crops survive the season turn"* (or
+   don't) is a single rule that defines the genre's entire emotional register —
+   forgiving vs. punishing. Choose it deliberately.
+
+## The loop stack
+
+| Layer | The beat |
+|---|---|
+| **Moment** | A chore: plant / water / harvest / feed. Small, tactile, done. |
+| **Encounter** | A day: spend energy/time on the plan, watch it advance a step. |
+| **Session** | A season: the plan matures; you reinvest the yield. |
+| **Meta** | The year and beyond: upgrades, relationships, land, mastery. |
+
+## Essential systems
+
+| System | Why this genre needs it |
+|---|---|
+| [[system-resource-loops]] | Gather→convert→spend (seed→crop→cash→seed) is the beating core; bottlenecks (energy, water, space) are the pacing. |
+| [[system-session-structure]] | Day / season / year nesting sets session length and the calendar arithmetic every plan is checked against. |
+| [[system-economy]] | Faucets (harvest) and sinks (seeds, upgrades) must keep reinvestment strictly better than hoarding. |
+| [[pattern-pacing-and-tension]] | Peaks (harvest day, festival) and valleys (the mid-season wait); the calm needs a rhythm, not a flatline. |
+| [[system-collectibles]] | Recipes, shipped items, friendships — the open-ended goals that pull without pressure. |
+| [[system-onboarding]] | The first day must teach plant→water→wait→harvest by doing, on one short crop. |
+
+## Content & difficulty model
+
+- **The calendar is a proof, not a setting.** Assert `seasonLength ≥ max(growDays) +
+  harvestSlack` against the actual crop table. A crop that can't finish its season is
+  a broken promise; a lint should refuse it.
+- **Difficulty is solvency margin.** A "hard" year is a *tighter* budget, not a
+  meaner world. Prove a diligent bot reaches the target by day N; prove no-water →
+  no-growth; prove wither is honest (a crop dies visibly, on a rule).
+- **Reinvest must beat hoard.** Assert the delta — a reinvesting bot out-earns a
+  hoarding one (FUN.md measures 740 vs 236). If hoarding competes, the economy has no
+  loop.
+- **Expose the countdown.** *Nights left in season* is the single most load-bearing
+  number; it turns anxiety into planning.
+- **Content grows sideways.** More crops, animals, tools, and social threads — *width*
+  the player chooses, not a difficulty wall. Solvency stays gentle; ambition scales.
+
+## Signature-mechanic seeds
+
+- **Farming sim but you tend a garden of grief** — each crop is a memory; the season
+  ends when you're ready to release it (tonal + mechanic-swap; the [[process-the-twist]]
+  worked example — calm becomes coming-to-terms).
+- **Farming sim but the plot is one screen, no expansion** — a hard spatial constraint
+  turns every tile into a decision (constraint; solvency gets tight and tactical).
+- **Farming sim but crops are tiles you match** — harvest is a board clear; a bend
+  toward [[genre-match3]] where planting sets up cascades (mechanic-swap).
+- **Farming sim but nights are survival** — day tends, night defends the harvest with a
+  fuel-budgeted lamp (structure + tonal; splices [[genre-survival-horror]]'s dread you
+  can budget onto a cozy day).
+- **Farming sim but the whole game is one exposed rule** — connect farms to yurts, and
+  that single legible predicate is the content (structure; the Tiny Yurts read).
+
+## Common pitfalls
+
+- **Calendar that lies.** Crops that can't ripen in their season, or a season that ends
+  mid-growth without warning — the fastest way to break the "plans come true" promise.
+- **Hidden critical numbers.** If the player can't see nights-left or grow-time, they
+  can't plan, and planning is the fun.
+- **Hoarding beats reinvesting.** Kills the loop; the economy must reward putting the
+  yield back in.
+- **Fake calm.** No peaks, no valleys, just undifferentiated chores → boredom.
+  [[pattern-pacing-and-tension]] gives the calm its rhythm.
+- **Width as busywork.** New crops that don't change a decision are clutter; each
+  should open a plan the player couldn't make before.
+
+## Anchors
+
+- [[anchor-stardew-valley]] — the calm compulsion loop, open-ended goals, and the
+  day/season/year nesting; the definitive DNA for this genre.
+
+## Verify
+
+Diligent bot wins by day N; no-water-no-growth; wither honesty; reinvest-vs-hoard
+delta; golden year → **[docs/FUN.md §15 · Farming/life sim](../../docs/FUN.md#15--farminglife-sim)**.
+Design the calendar and loop here; prove the inequality there.
+
+## Composes with
+
+- [[system-resource-loops]] — the seed→crop→cash→seed cycle at the genre's heart.
+- [[system-session-structure]] — the day/season/year calendar the plans are checked against.
+- [[anchor-stardew-valley]] — the touchstone whose loop you import pre-solved.
+
+## See also
+
+- [docs/FUN.md §15](../../docs/FUN.md#15--farminglife-sim) — mechanical truth + verify recipe.
+- [`sandboxes/`](../../sandboxes/) — the economy/procgen lab to headless-sim a season's
+  solvency before authoring a crop table.