hayao 0.4.1 → 0.4.2

package/design/00-process/refine-and-handoff.md

@@ -0,0 +1,156 @@
+---
+id: process-refine-and-handoff
+title: Refine & Handoff — The Verification Contract
+kind: process
+tags: [handoff, verification-contract, done, spec, proof, seam, checklist, assertions]
+summary: Turn the finished design into a verification contract and hand off to the proof playbook — FUN, JUICE, JUDGE, CONVENTIONS. The seam where the Codex ends.
+use-when: The design is composed and twisted, and you need to declare "designed enough to build" as a set of assertions the proof playbook will run.
+composes-with: [process-composition, process-core-loop, process-pillars, process-the-twist]
+verify-with: docs/VERIFICATION.md
+---
+
+# Refine & Handoff — The Verification Contract
+
+**What it is.** The **last** Codex step and the **seam** to the proof playbook.
+You convert the finished design into a *verification contract*: the concrete
+assertions that must hold for the game to be what the pillars promised. The Codex
+generates; from here on, the game is *proven*, not designed.
+
+**Why it matters.** A design isn't done when it's imagined — it's done when it
+**names its proofs**. The contract is the bridge: FUN.md, JUICE.md, JUDGE.md, and
+CONVENTIONS pick it up and run it. Hand off a design with no contract and the
+proof playbook has nothing to gate against.
+
+## The step
+
+Composed design → a verification contract + a clean handoff. You are not writing
+tests here (that's the build). You are declaring *what would have to be true* — the
+assertions the build must satisfy — and routing each to its channel.
+
+## "Designed enough to build"
+
+The definition of done for the Codex. All must be true:
+
+- [ ] **One "X but Y" hook** survives as a store sentence ([[process-the-twist]]).
+- [ ] **Exactly three pillars**, each with a testable clause ([[process-pillars]]).
+- [ ] **A named moment verb**, prototyped or prototypable in a `sandboxes/*-lab`.
+- [ ] **The loop stack** filled: moment/encounter/session/meta each named
+      ([[process-core-loop]]).
+- [ ] **A system list**, each `[[system-*]]` justified by a pillar
+      ([[process-composition]]).
+- [ ] **Parent genres named** with their FUN.md sections — the verify union.
+- [ ] **The signature mechanic's consequence traced** through ≥ 3 systems.
+- [ ] **A verification contract** (below) — every pillar has a proof, every parent
+      genre its verify pattern, every feel claim a gate.
+
+If any box is empty, refine — don't hand off. A gap here becomes an unverifiable
+mess downstream.
+
+## The verification contract
+
+For each design claim, name the assertion and route it to a channel. Do **not**
+write the assertion's recipe — [docs/VERIFICATION.md](../../docs/VERIFICATION.md)
+owns that. You name *what* and *where*; it owns *how*.
+
+| Design claim (from…) | Becomes the assertion… | Channel / doc |
+|---|---|---|
+| Pillar 1's testable clause | a probe/skill-delta the clause maps to | [FUN.md](../../docs/FUN.md) law 2, Ch. 1a |
+| "The intended strategy beats null play" | `smartScore > nullScore * K` | FUN.md law 2 |
+| A derived envelope (jump gap, season length, fuel budget) | a stated inequality asserted vs. config | FUN.md law 3, Ch. 3 |
+| Each parent genre in the blend | that genre's FUN.md §N verify pattern | FUN.md Part 2 (union — all parents) |
+| Puzzle/turn-based rules | every level solver-provable | [VERIFICATION.md](../../docs/VERIFICATION.md) Ch. 1b |
+| "Same seed → same game" | golden hash + snapshot round-trip | Ch. 1c/1d |
+| Every feel/juice claim ("responsive", "impactful") | a `FeedbackContract` + feel gate | [JUICE.md](../../docs/JUICE.md), Ch. 4 |
+| Pacing ("breathers", "peak finale") | a feel probe over the timeline | Ch. 3 |
+| "Reads at a glance" / the look | the headless SVG judged on palette/legibility | [JUDGE.md](../../docs/JUDGE.md), Ch. 2/5 |
+
+The contract is done when **every pillar traces to at least one row** and **no
+parent genre's verify pattern is missing**.
+
+## How to run it
+
+1. **Walk the pillars.** For each of the three, write the one assertion that
+   proves its testable clause. A pillar with no proof is a pillar you can't keep.
+2. **Union the verify patterns.** From [[process-composition]], list each parent
+   genre and copy in its FUN.md §N verify line. All of them (the blend law).
+3. **Extract the inequalities.** Every derived number (envelope, calendar, fuel,
+   coverage, payback) is a law-3 inequality — state it as a comment-shaped claim.
+4. **Declare the feedback contract.** Every feel adjective from the brief becomes a
+   `FeedbackContract` entry + a Channel 4 gate. Design the *event*; JUICE proves it.
+5. **Name the null strategy.** The do-nothing/never-draft/undefended run that must
+   *lose* — the cheapest and most important scenario (FUN.md law 4).
+6. **Route the look.** State what the headless screenshot must show (bright avatar,
+   palette, legible layout) for JUDGE to pass.
+7. **Hand off.** The contract *is* the spec. Per FUN.md law 1, *the verify suite is
+   the design doc* — you've now written its assertions, first.
+
+## The explicit handoff
+
+Where each concern goes, and the doc that owns it from here:
+
+| Concern | Handed to | Owns |
+|---|---|---|
+| Mechanical truth, skill-delta, inequalities, solver, determinism | **[FUN.md](../../docs/FUN.md)** + [VERIFICATION.md](../../docs/VERIFICATION.md) Ch. 1/3 | Is it correct and beatable? |
+| Feel, feedback contract, shake/hit-stop envelopes | **[JUICE.md](../../docs/JUICE.md)** + Ch. 4 | Does it feel professional? |
+| Looks — palette, layout, legibility | **[JUDGE.md](../../docs/JUDGE.md)** + Ch. 2/5 | Does it look shipped, not debug? |
+| State/view split, `@hayao` imports, cosmetic rule, determinism hygiene | **[CONVENTIONS.md](../../docs/CONVENTIONS.md)** | Is it built the Hayao way? |
+
+After handoff, the build runs `npm run check`, `npm test`, `npm run verify`, and
+`npm run judge` — and the design stands or falls on the contract you wrote. Studio
+([Hayao Studio](../../docs/STUDIO.md); `runStudio`) then closes the human-feel loop.
+
+## Worked example
+
+**Design:** the drafted-tower-defense from [[process-composition]]. Pillars:
+(1) *build decisions matter*, (2) *drafts with teeth*, (3) *the range ring is UI*.
+
+**Contract:**
+
+- **Pillar 1** → mixed drafted build survives 10/10; mono-draft (bigger budget)
+  fails. *(FUN.md §8, Ch. 1a)*
+- **Pillar 2** → same pilot, never-drafting loses by a margin. *(FUN.md §11
+  draft-delta — the grafted parent's pattern)*
+- **Pillar 3** → the range ring renders; headless SVG shows coverage legibly.
+  *(JUDGE, Ch. 2)*
+- **Blend union:** §8 (coverage chord, wave-curve breathes, counter duels both
+  ways) **and** §11 (win-rate window, draft-delta, intent audit). Both, in full.
+- **Inequality:** `range × distanceToLane ≥ minFireChord` per drafted tower, per
+  lane — asserted vs. actual map geometry.
+- **Feedback contract:** `place`, `kill`, `leak` each answer on ≥ 2 senses; shake
+  ≤ envelope. *(JUICE Ch. 4)*
+- **Null:** bare-lane run falls early. *(FUN.md law 4)*
+
+Every pillar has a row; both parents' patterns are present; the seam (drafted
+tower × coverage) has its own proof. **Designed enough to build.**
+
+## Traps
+
+- **Handing off a mood.** "It should feel great" is not a contract. Every claim
+  needs a channel and an assertion, or it can't be gated.
+- **Dropping a parent's verify pattern.** A blend that proves only its dominant
+  genre ships the other half broken. Union, always.
+- **Restating the recipe.** Don't paste FUN/JUICE/VERIFICATION content here — name
+  the claim and *link* the channel. Design here; prove there.
+- **Contract without the null.** If nothing is asserted to *lose*, you haven't
+  proven the game has teeth (FUN.md law 4). Name the null first.
+- **Skipping the look route.** A design that never says what the screenshot must
+  show hands JUDGE nothing to judge. State the salience/palette claim.
+
+## Composes with
+
+- [[process-composition]] — its system list + parent genres become the verify
+  union you owe.
+- [[process-pillars]] — each pillar's testable clause is a contract row.
+- [[process-core-loop]] — the loop's feedback beats become the feedback contract.
+- [[process-the-twist]] — the signature mechanic's traced consequences are extra
+  assertions (the seam proofs).
+
+## See also
+
+- [docs/VERIFICATION.md](../../docs/VERIFICATION.md) — the five channels this
+  contract routes into; the *how* behind every row above.
+- [docs/FUN.md](../../docs/FUN.md) law 1 — *the verify suite IS the design doc*;
+  this step is where you write its assertions first.
+- [docs/JUICE.md](../../docs/JUICE.md) · [docs/JUDGE.md](../../docs/JUDGE.md) ·
+  [docs/CONVENTIONS.md](../../docs/CONVENTIONS.md) — the docs that own the design
+  from here.

package/design/00-process/the-twist.md

@@ -0,0 +1,108 @@
+---
+id: process-the-twist
+title: The Twist — "X but Y"
+kind: process
+tags: [twist, composition, creativity, hook, differentiation, novelty, remix]
+summary: The "X but Y" formula — anchor to a proven game, then bend it along one of six twist vectors so it's yours, not a clone.
+use-when: You have a genre/anchor and need the creative bend that makes the design worth building.
+composes-with: [process-composition, process-pillars, process-intent-to-brief]
+verify-with: none
+---
+
+# The Twist — "X but Y"
+
+**What it is.** Almost every good game is a *known thing, bent*. You don't invent a
+genre from nothing; you take a proven core (the **X** — an [anchor](../10-anchors/)
+or a [genre](../20-genres/)) and apply a **twist vector** (the **Y**) that changes what the game
+*means*. The twist is where your creativity goes. The core is borrowed on purpose —
+it arrives pre-solved, so your invention lands on the *difference*, not on
+re-deriving what a platformer's coyote time should be.
+
+**Why it's fun.** Familiarity is a free tutorial; novelty is the reason to look.
+"X but Y" gives players an instant mental model *and* a surprise. Skip the anchor
+and players are lost. Skip the twist and there's no reason to play yours over X.
+
+> **The pitch test.** If you can't say your game as one "X but Y" sentence, the
+> design isn't focused yet. *Unrailed = Overcooked but on a train you build ahead
+> of yourself. Fertile Crescent = Age of Empires but bronze-age with hunger as the
+> signature pressure. Shadow of War = Assassin's Creed but every orc remembers you.*
+
+## The six twist vectors
+
+Pick **one** primary vector and commit; a second is a bonus, a third is usually
+noise. Each vector answers "*but Y* — bent how?"
+
+| Vector | The bend | Worked "X but Y" |
+|---|---|---|
+| **Theme / setting** | Same mechanics, a new fiction that recolours every system | Doom → *Viking*; AoE → *bronze-age* (Fertile Crescent) |
+| **Mechanic-swap** | Replace or add one load-bearing verb; the rest reorganises around it | Overcooked → *+ track-laying* (Unrailed); Slay the Spire → *+ poker-hand scoring* (Balatro) |
+| **Structure** | Change the container: run-based, roguelite, open-world, endless, campaign | Metroidvania → *roguelite* (Dead Cells); FTL → *no map, one loop* (Loop Hero) |
+| **Perspective / scale** | Zoom in or out; change who the player IS | RTS commander → *one hero in the battle*; city → *one citizen* |
+| **Constraint** | Add a hard limitation that forces new play | One-button; permadeath; no combat; one screen; 60-second runs |
+| **Tonal** | Flip the emotional register | Horror → *cozy*; war → *comedy*; hardcore → *humane* (Celeste's assist mode) |
+
+## The signature mechanic
+
+The strongest twist crystallises into **one signature mechanic** — the thing the
+whole game is *about*, the sentence in the store description, the reason a
+screenshot is legible. Fertile Crescent has **hunger**. Shadow of War has the
+**nemesis system**. Into the Breach has the **telegraphed grid**. Balatro has
+**jokers**. Find yours, then make every other system serve it. A twist that stays
+a coat of paint (theme-only, no mechanical consequence) rarely carries a game;
+push the bend until it changes *how you play*, not just how it looks.
+
+## How to run it
+
+1. **State the X.** Name the anchor(s) from [[process-intent-to-brief]]. Pull their
+   DNA from [`10-anchors/`](../10-anchors/) — the load-bearing structures, not the
+   theme. This is your borrowed, pre-solved core.
+2. **List candidate Ys.** For each vector above, write the one bend that best
+   serves the [[process-pillars]] and the player fantasy. Six candidates.
+3. **Score against the pillars.** Keep the Y that *most sharpens* a pillar. A twist
+   that fights a pillar is a different game — note it and drop it.
+4. **Name the signature mechanic** the twist implies. If none emerges, the bend is
+   cosmetic — pick a stronger vector.
+5. **Trace the consequence.** Walk the twist through every system: what does it
+   change in the economy, combat, progression, level shape? The twist that ripples
+   into 3+ systems is real; one that touches nothing is set-dressing.
+6. **Re-pitch.** Write the final "X but Y" sentence. It must survive as the store
+   hook. If it's boring to say, it'll be boring to play.
+
+## Worked example
+
+**Intent:** *"a chill farming game that's actually about something."*
+
+- **X** = [[anchor-stardew-valley]] (gentle life sim, open-ended goals, calm loop).
+- **Ys considered:** theme (post-apocalyptic garden), mechanic-swap (farming *the
+  dead* — graves grow), structure (roguelite seasons), constraint (one plot, no
+  expansion), tonal (grief instead of cosiness).
+- **Pillar filter:** pillar is *"tending as coming-to-terms."* The **tonal +
+  mechanic-swap** bend wins: you farm a memorial garden; each crop is a memory,
+  and the season ends when you're ready to let go.
+- **Signature mechanic:** *acceptance* — crops you've fully tended can be
+  *released* for the run's only real resource; hoarding them stalls you.
+- **Pitch:** *"Stardew Valley but a garden of grief you're learning to let go of."*
+
+## Traps
+
+- **Twisting the wrong axis.** A theme swap on a genre whose fun is mechanical (a
+  reskinned platformer) adds nothing. Bend where the fun lives.
+- **Three twists at once.** Overloaded pitches read as unfocused. One primary bend.
+- **Novelty with no anchor.** "Totally original" usually means "no mental model" —
+  players bounce. Anchor first, *then* surprise.
+- **Cosmetic signature.** If your "signature mechanic" doesn't change decisions,
+  it's a logo, not a mechanic.
+
+## Composes with
+
+- [[process-composition]] — the twist is chosen *during* composition; this is the
+  creative step inside it.
+- [[process-pillars]] — the pillars are the scoring function for candidate twists.
+- [[pattern-emergence]] — the best signature mechanics are ones that interact with
+  everything else and generate stories.
+
+## See also
+
+- [`10-anchors/`](../10-anchors/) — the X's, distilled to stealable DNA.
+- [AGENTS.md](../../AGENTS.md) "Design from the mechanic, not from the corpus" —
+  the twist is how you *aim above* the corpus.

package/design/10-anchors/README.md

@@ -0,0 +1,99 @@
+# 10-anchors — reference-game DNA
+
+**An anchor is a touchstone game distilled to its stealable structural DNA** —
+the load-bearing structures that make it work, stripped of theme and history.
+It is *not* a review, a retrospective, or a feature list. It answers one
+question: *if I say "my game is X-like," what exactly am I importing for free,
+and where do I bend it?*
+
+## How to use the DNA
+
+Anchors are the **ANCHOR** step of the [pipeline](../README.md): after
+[[process-intent-to-brief]], name the 1–3 games your design *is*, then pull
+their DNA here. Each module gives you four levers:
+
+1. **Design DNA + Load-bearing structures** — the compressed essence and the
+   table of *structure → why it works*. This is the pre-solved core you
+   borrow. Copy the structures; you don't have to re-derive why coyote time or
+   a draft-of-3 works.
+2. **What to steal** — the portable moves, phrased so you can lift them
+   directly.
+3. **What's just theme (drop it)** — the coat of paint. Do **not** import
+   this; it locks you into a clone. Everything here is re-skinnable.
+4. **Twist seams** — 2–3 "X but Y" bends in the [[process-the-twist]]
+   vocabulary (theme / mechanic-swap / structure / perspective / constraint /
+   tonal). This is where your creativity goes: pick a seam, then take it
+   through [[process-the-twist]] and [[process-composition]].
+
+> **Compose, don't clone.** An anchor is the *X* in "X but Y." Import its
+> structure, drop its theme, bend a seam. A design that steals everything —
+> including the theme — is a reskin; a design that steals nothing has no mental
+> model. Aim between. See [AGENTS.md](../../AGENTS.md) "design from the mechanic,
+> not from the corpus."
+
+Anchors feed the deep creative templates in [`20-genres/`](../20-genres/) and
+the modular parts in [`30-systems/`](../30-systems/) — each module's
+**Composes into** section names exactly which. Verification is never here:
+each anchor links the matching `docs/FUN.md` genre section for the proof
+pattern.
+
+## The 24 anchors
+
+### Action, platformer & arcade
+| id | title | one-line DNA |
+|---|---|---|
+| [[anchor-celeste]] | Celeste | Precision platformer where grace is a system and assist mode makes difficulty the player's to own. |
+| [[anchor-tetris]] | Tetris | One perfectly-tuned verb, endless; difficulty rises with your own success. |
+| [[anchor-peggle]] | Peggle | Trivial input (aim + drop) wrapped in variable-ratio payoffs and disproportionate celebration juice. |
+| [[anchor-nuclear-throne]] | Nuclear Throne | Twin-stick arcade roguelite; the over-tuned core minute carries "one more run." |
+
+### Run-based & roguelite
+| id | title | one-line DNA |
+|---|---|---|
+| [[anchor-hades]] | Hades | Death delivers story and power — the meta-loop IS the narrative, so losing is content. |
+| [[anchor-dead-cells]] | Dead Cells | Metroidvania × roguelite; the layout resets but the pool of possibility only ever grows. |
+| [[anchor-vampire-survivors]] | Vampire Survivors | Move-only horde survival; a multiplicative build races a superlinear tide. |
+
+### Deckbuilders & tactics
+| id | title | one-line DNA |
+|---|---|---|
+| [[anchor-slay-the-spire]] | Slay the Spire | Draft-of-3-with-skip; the deck is the build and thinning is a strategy. |
+| [[anchor-balatro]] | Balatro | Score-multiplier engine (`chips × mult`); stacked jokers make the number explode. |
+| [[anchor-into-the-breach]] | Into the Breach | Perfect-information tactics; the game is rewriting a telegraphed future by displacement. |
+
+### Puzzle & fusion
+| id | title | one-line DNA |
+|---|---|---|
+| [[anchor-baba-is-you]] | Baba Is You | The rules are pushable objects; editing the ruleset is the whole game. |
+| [[anchor-loop-hero]] | Loop Hero | Placement + auto-combat + deck fused; you author the world and every tile is a double-edged bet. |
+
+### Strategy & simulation
+| id | title | one-line DNA |
+|---|---|---|
+| [[anchor-age-of-empires]] | Age of Empires | RTS eco/tech ramp; age-up power spikes and rehearsed build orders. |
+| [[anchor-starcraft]] | StarCraft | Faction asymmetry done right — three distinct rosters balanced on one scale. |
+| [[anchor-factorio]] | Factorio | Automation/logistics; the factory itself is the toy, scaling complexity forever. |
+| [[anchor-rimworld]] | RimWorld | Colony sim as story generator; an AI director authoring escalating drama. |
+| [[anchor-stardew-valley]] | Stardew Valley | Gentle life sim; open-ended goals and a calm compulsion loop. |
+| [[anchor-civilization]] | Civilization | 4X "one more turn"; layered systems, snowball tempered by comeback. |
+
+### Co-op, systemic & narrative
+| id | title | one-line DNA |
+|---|---|---|
+| [[anchor-overcooked]] | Overcooked | Couch-coop chaos; communication forced by design, kitchens that escalate. |
+| [[anchor-it-takes-two]] | It Takes Two | Asymmetric coop set-pieces; a new mechanic per chapter, interdependence throughout. |
+| [[anchor-shadow-of-mordor]] | Shadow of Mordor | The nemesis system — emergent, personalised rivals from systemic memory. |
+| [[anchor-reigns]] | Reigns | Swipe-choice stewardship; meters balanced between two ditches. |
+| [[anchor-outer-wilds]] | Outer Wilds | Knowledge is the only progression; a curiosity-gated open world. |
+| [[anchor-return-of-the-obra-dinn]] | Return of the Obra Dinn | Deduction as the core loop; the game trusts your reasoning. |
+
+## See also
+
+- [`../README.md`](../README.md) — the design pipeline (anchors are step 2,
+  ANCHOR).
+- [`../00-process/the-twist.md`](../00-process/the-twist.md) — the "X but Y"
+  formula the twist seams speak.
+- [`../20-genres/`](../20-genres/) · [`../30-systems/`](../30-systems/) —
+  where anchor DNA composes into templates and parts.
+- [`../../docs/FUN.md`](../../docs/FUN.md) — each anchor's verify pattern, by
+  genre.

package/design/10-anchors/age-of-empires.md

@@ -0,0 +1,103 @@
+---
+id: anchor-age-of-empires
+title: Age of Empires
+kind: anchor
+tags: [rts, economy, tech-tree, build-order, power-spike, ramp, macro]
+summary: RTS whose fun is the eco→tech ramp — you bank a peaceful economy into age-up power spikes, and the build order is the real game.
+use-when: The intent is an economy-first RTS/strategy where teching up and timing a power spike is the core decision.
+composes-with: [genre-rts, system-tech-tree, system-economy, system-resource-loops, system-unit-rosters]
+anchors: []
+verify-with: docs/FUN.md#9-rts-lite
+---
+
+# Age of Empires
+
+**What it is.** An RTS where you spend most of your time *not fighting*: you
+harvest four resources, sink them into a **tech ramp**, and cash the whole
+economy in at an **age-up** — a discrete power spike that unlocks a better army
+and a better economy at once. The **build order** — what you build, in what
+sequence, timed to the second — is the skill.
+
+**Player fantasy.** You are a civilisation *becoming*. The dopamine is watching a
+handful of villagers snowball into a stone-age hamlet, a feudal town, an imperial
+war machine — each age a visible, audible level-up you *earned* by planning ahead
+instead of fighting now.
+
+## Design DNA
+
+The engine is a **delayed-gratification loop**: every resource spent on economy or
+tech is an army you *didn't* build. The tension is always "expand now, or convert
+to power now?" Ages are the **commitment gates** that make that tension legible —
+you can *see* the next tier of units greyed out, and you know exactly what banking
+toward it costs. Combat exists to punish players who over-bank (you die with a
+great economy and no army) and reward players who time the spike (you hit Feudal
+with an army while the enemy is still stone-age).
+
+## Load-bearing structures
+
+| Structure | Why it works |
+|---|---|
+| **Multi-resource economy** (food/wood/gold/stone) | Each resource gates a different axis; scarcity of one forces build-order choices. Reduces to faucets/sinks → [[system-economy]]. |
+| **Villager compounding** | Workers make workers; early economy investment pays exponential interest. The core [[pattern-feedback-loops]] runaway. |
+| **Age-up as discrete power spike** | A single expensive gate unlocks a whole tier at once — a legible level-up, not a slow drip. → [[system-tech-tree]]. |
+| **Build order** | A near-optimal opening sequence, timed to seconds; mastery is executing it under pressure. → [[system-mastery-curve]]. |
+| **Tech tree with branch cost** | Upgrades are cheap individually, ruinous in aggregate; you can't have everything, so you specialise. → [[system-tech-tree]]. |
+| **Timing attacks** | The whole game is "hit the enemy in the gap between *my* spike and *their* spike." Skill = reading tempo. |
+| **Counter roster** | Units answer units (spears→cavalry, archers→infantry); army comp is a live rock-paper-scissors. → [[system-counter-systems]]. |
+
+## What to steal
+
+- The **age-up gate**: one expensive, visible, irreversible spike that unlocks a
+  *tier*, not a stat. It converts a grind into a milestone.
+- The **build-order skill floor**: a deterministic opening that rewards knowledge
+  and execution — the thing a null "just make army" player loses to hard (FUN.md
+  law 2 skill-delta).
+- **Idle-worker guilt**: surface the number of idle villagers as UI. The exposed
+  inefficiency *is* the macro game (cf. the city-builder "+N" cursor, FUN.md §17).
+- **Bank-vs-spend tension** at every second: the economy you build is the army you
+  postpone. This is the whole loop; keep it sharp.
+
+## What's just theme (drop it)
+
+- The **historical civilisations** — Britons vs Franks is flavour on a shared
+  spine. Real asymmetry lives in [[system-faction-asymmetry]], not in names.
+- **Four** specific resources — the count is tuning. Two well-differentiated
+  resources can carry the same tension (see [[system-resource-loops]]).
+- **Wonders / relics / one-more-victory-condition** — win-condition garnish, not
+  the loop. Cut them until the ramp is fun alone.
+- **Literal town-building sim** — the base is a means to the ramp, not a SimCity.
+
+## Composes into
+
+- [[genre-rts]] — the parent; AoE is its economy-first exemplar (mass under
+  command, but macro over micro).
+- [[system-tech-tree]] — the age-up spike is a tech-tree gate; this is its home
+  system.
+- [[system-economy]] · [[system-resource-loops]] — faucets/sinks and the
+  gather→convert→spend cycle that funds the ramp.
+- [[system-unit-rosters]] · [[system-counter-systems]] — the army the economy pays
+  for, and why comp matters.
+- [[pattern-feedback-loops]] — villager compounding is the runaway loop that needs
+  a comeback brake.
+
+## Twist seams
+
+- **AoE but the age-up is a roguelite draft** *(structure)* — each age offers a
+  choice-of-3 civ perks instead of a fixed tree; runs diverge. Pairs with
+  [[system-meta-progression]].
+- **AoE but hunger is the fifth clock** *(mechanic-swap)* — food isn't banked, it
+  *drains*; your economy starves if it stalls. (This is Fertile Crescent's
+  signature bend — see [[process-the-twist]].)
+- **AoE but you command one age at a time on a single screen** *(constraint /
+  perspective)* — no map scroll; the ramp happens in one arena, tower-defense
+  tempo. Pairs with [[genre-tower-defense]].
+- **AoE but cozy** *(tonal)* — drop combat entirely; the "spike" is a festival, the
+  pressure is a seasonal deadline. Pairs with [[genre-farming-sim]].
+
+## See also
+
+- [`docs/FUN.md#9-rts-lite`](../../docs/FUN.md) — mass pathing via cached flow
+  fields; the intended line (turtle→counterpush) must beat attack-move.
+- [`sandboxes/pathfinding-demo`](../../sandboxes/pathfinding-demo) — `astarGrid` /
+  flow-field wiring for wall-aware unit movement.
+- [[genre-rts]] · [[system-tech-tree]] · [[system-economy]].

package/design/10-anchors/baba-is-you.md

@@ -0,0 +1,127 @@
+---
+id: anchor-baba-is-you
+title: Baba Is You
+kind: anchor
+tags: [puzzle, rule-manipulation, self-reference, sokoban, systemic, emergence, grid]
+summary: A puzzle where the rules are physical objects on the board — push the word blocks and you rewrite what "you," "win," and "wall" even mean.
+use-when: Designing a puzzle whose depth comes from the player editing the ruleset itself, so the mechanic and the content are the same thing.
+composes-with: [genre-grid-puzzle, pattern-emergence, system-onboarding, system-mastery-curve]
+anchors: [anchor-baba-is-you]
+verify-with: docs/FUN.md#1-·-grid-puzzle-sokoban
+---
+
+# Baba Is You
+
+**What it is.** A Sokoban-like grid puzzle where the *rules are blocks you can
+push*. `BABA IS YOU`, `FLAG IS WIN`, `WALL IS STOP` — break a sentence apart
+and the law it stated stops applying; form a new one and reality reorganises
+around it.
+
+**Player fantasy / why it's fun.** *I am not solving the puzzle — I am
+rewriting it.* The pull is **the mechanic IS the content**: there's no new
+mechanic per level, just deeper implications of one idea. Every "aha" is the
+moment you realise you can make *lava is win*, or *you* the wall, and the
+whole board's meaning inverts.
+
+## Design DNA
+
+Make **the rules first-class objects** in the simulation. Instead of
+hard-coding "walls stop you," the game reads sentences of word-blocks each
+tick and *derives* its rules from the current board. Because the player can
+push those word-blocks, **the ruleset is mutable at runtime** — and the entire
+game is the emergent space of what you can make true. One system, endlessly
+recombined, generates hundreds of puzzles without ever adding a new verb.
+
+The architectural move is the whole trick: **data-drive the laws instead of
+coding them.** A conventional game hard-codes `if (tile.isWall) block()`. Baba
+stores `WALL IS STOP` as three movable objects and, each step, re-parses the
+board into an active ruleset that the sim obeys. The instant the *rule itself*
+is a thing you can push, the design surface explodes — every law becomes
+editable, including the ones a designer would normally hold sacred (what "you"
+are, what "winning" means). The content isn't levels bolted onto a mechanic;
+the content *is* situations that reveal what the one mechanic permits.
+
+This is **emergence as the whole game**: depth comes not from breadth of
+mechanics but from the second-order interactions of a tiny, self-referential
+rule engine. A handful of nouns and properties yields a puzzle space no
+designer could enumerate — which is the efficiency: near-infinite content from
+almost no content.
+
+## Load-bearing structures
+
+| Structure | Why it works |
+|---|---|
+| **Rules are data on the board, re-read each tick** | The sim *derives* its laws from `NOUN IS PROPERTY` sentences rather than hard-coding them — so pushing a word changes physics. This is the entire trick. |
+| **Self-reference (`IS YOU`, `IS WIN`)** | The player can move *win itself*, or become a new object. The win condition and the avatar are editable — nothing is sacred. [[pattern-emergence]]. |
+| **One mechanic, deepening implications** | No new verbs per level; difficulty is *realising what the one system permits*. Content = mastery of the rule engine. [[system-mastery-curve]]. |
+| **Sokoban substrate + undo/restart** | Turn-based grid pushing with full undo — puzzle grace, so wild experimentation is free. FUN.md law 5. [[genre-grid-puzzle]]. |
+| **Every level is solver-provable** | A pure `Puzzle<State, Move>` state (board + active rules) means every level is machine-proven winnable — unwinnable = unshippable. FUN.md truth. |
+| **Teach-by-discovery onboarding** | Early levels *are* the tutorial — you learn the rule engine by breaking one sentence at a time. [[system-onboarding]]. |
+| **Combinatorial state, tiny alphabet** | A handful of nouns × properties yields a vast puzzle space from almost no content. [[system-procgen-design]] (design-space, not runtime). |
+
+## What to steal
+
+- **Promote the rules to editable game objects.** Store laws as data the sim
+  reads each step, not as code. The moment the player can *move a rule*, you
+  have a whole genre. This is the master idea.
+- **Allow self-reference:** let the player edit "you," "win," "the goal." The
+  most memorable puzzles come from nothing being fixed.
+- **Get infinite content from one deep system.** Don't add mechanics; add
+  *situations that reveal implications*. The mechanic is the content — that's
+  the efficiency.
+- **Keep the Sokoban substrate + undo/restart** so experimentation is
+  consequence-free (FUN.md law 5).
+- **Prove every level with a solver** over the pure state (board + active
+  rules) — winnability is CI, not a playtest. Because a self-referential rule
+  engine can trivially author *unwinnable* configurations, a machine proof
+  isn't optional here; unwinnable = unshippable (FUN.md truth).
+- **Front-load the teaching into the levels themselves.** No separate
+  tutorial: the first rooms *are* the onboarding, each isolating one
+  implication of the rule engine (break a sentence, form a new one). Discovery
+  replaces instruction. See [[system-onboarding]].
+
+## What's just theme (drop it)
+
+- **Baba the sheep and the crayon art.** Fully cosmetic.
+- **The specific nouns/properties.** *A small vocabulary of subjects ×
+  predicates* is structural; "ROCK / KEKE / FLAG" is flavour.
+- **The overworld map.** A level-selection wrapper, not the loop —
+  [[system-session-structure]].
+- **English-word framing.** The *sentence-as-rule* structure could be icons,
+  runes, or colours; the readability is what matters —
+  [[pattern-readability]].
+
+## Composes into
+
+- [[genre-grid-puzzle]] — its substrate; Baba is the rule-manipulation
+  variant.
+- [[pattern-emergence]] — the definitive example of second-order, few-pieces
+  depth.
+- [[system-onboarding]] — teach-by-discovery of a single deep system.
+- [[system-mastery-curve]] — difficulty as *understanding*, not execution.
+
+## Twist seams
+
+- **Baba Is You but real-time** *(structure)* — rules re-read every frame
+  while things move; you rewrite physics *during* an action sequence. Bends
+  the turn-based substrate toward reflex.
+- **Baba Is You but two players edit a shared ruleset** *(perspective)* — one
+  can make `WALL IS PUSH` while the other needs it `STOP`; cooperation *and*
+  sabotage live in the sentences. Feeds [[system-coop-and-competition]].
+- **Baba Is You but the theme is bureaucracy — rules are laws you amend**
+  *(theme)* — same self-referential engine, recolored as legislation; every
+  puzzle is "find the loophole." Theme that *reinforces* the mechanic instead
+  of decorating it.
+- **Baba Is You but you write the rules from a limited word-bank you draft**
+  *(mechanic-swap)* — instead of pushing pre-placed words, you *earn and
+  spend* rule-tokens; the puzzle becomes "what's the cheapest sentence that
+  wins." Pulls in [[genre-deckbuilder]] economy over the free-form parser.
+
+## See also
+
+- [[genre-grid-puzzle]] · [[pattern-emergence]] · [[system-onboarding]] ·
+  [[system-mastery-curve]]
+- `docs/FUN.md#1-·-grid-puzzle-sokoban` — `Puzzle<State,Move>` solver + replay
+  determinism.
+- `examples/sokoban/` — the logic/view-split reference this substrate builds
+  on.