hayao 0.4.1 → 0.4.2

package/design/40-worldbuilding/narrative-delivery.md

@@ -0,0 +1,129 @@
+---
+id: world-narrative-delivery
+title: Narrative Delivery — story with little text
+kind: worldbuilding
+tags: [narrative, environmental, systemic, embedded, show-dont-tell, story, diegetic]
+summary: Environmental / systemic / embedded storytelling with LITTLE text — show don't tell; let the systems author the story in a small deterministic game.
+use-when: You want the world to tell its story through play and place, not cutscenes — a fit for a small, text-light deterministic game.
+composes-with: [world-worldbuilding-scaffold, world-naming-and-tone, world-aesthetic-direction]
+anchors: [anchor-shadow-of-mordor, anchor-outer-wilds, anchor-return-of-the-obra-dinn]
+verify-with: none
+---
+
+# Narrative Delivery — story with little text
+
+**What it is.** How the world reaches the player *without a wall of text*. A small
+deterministic game can't (and shouldn't) lean on cutscenes and codex dumps. Its
+story lives in **place** (what the level shows), in **systems** (what the rules
+generate), and in **objects** (what a single item implies). The best delivery is
+the one the player *finds*, not the one they're *told*.
+
+**Player fantasy / why it's fun.** Discovered story is *yours*. A player who
+pieces the world together from a broken lantern and a drowned path owns that
+understanding in a way no narrator can give them. Show-don't-tell isn't a style
+choice — it's how you make the player a participant instead of an audience.
+
+## The three delivery channels
+
+| Channel | The story is in… | Costs | Best for |
+|---|---|---|---|
+| **Environmental** | the *place* — layout, ruins, what's worn or broken | art & level design | premise, history, mood |
+| **Systemic** | the *rules interacting* — what the systems generate | mechanical depth | emergent, personal, replayable story |
+| **Embedded** | *objects & fragments* — one item, one line, one name | a little authored text | specific lore, character, the twist |
+
+The house lean is **environmental + systemic first, embedded in tiny doses.** Text
+is a DOM overlay ([[world-naming-and-tone]]); spend it sparingly. A game that
+*shows* its drowning coast and lets its light-mechanic *enact* the loss needs
+almost no words.
+
+## Vectors / options — how much story, and where
+
+Match delivery to the game's shape ([[system-session-structure]]):
+
+| Game shape | Primary channel | What it looks like |
+|---|---|---|
+| Puzzle / arcade | environmental | the level *is* the premise; one title line |
+| Roguelite | systemic | each run's events author a small story ([[system-emergent-systems]]) |
+| Metroidvania / campaign | environmental + embedded | place tells history; fragments gate the twist |
+| Systemic / emergent | systemic | the *nemesis* pattern — the game remembers and narrates back |
+| Deduction | embedded | the player *reconstructs* the story (Obra Dinn) |
+
+## Method
+
+1. **Decide what the player must understand** vs what they may *infer*. Only the
+   first needs delivery; the rest is theirs to imagine
+   ([[world-worldbuilding-scaffold]] kept it minimal — hold that line).
+2. **Assign each beat a channel.** Premise → environmental (show it in the first
+   screen). Stakes → systemic (let a loss *happen*, don't narrate it). A specific
+   reveal → embedded (one fragment).
+3. **Make the environment tell the premise.** The [[world-aesthetic-direction]]
+   brief is your first narrator: a drowned path, a snuffed lantern, a mended crack
+   say more than a paragraph. Compose the frame to be *read*.
+4. **Let systems generate the personal story.** Where you have memory or
+   relationships ([[system-emergent-systems]]), the game authors specifics you
+   didn't write — the guard who caught you twice, the lantern you always lose.
+   That's the Shadow of War trick at small scale.
+5. **Spend embedded text like a miser.** One line on a gravestone, one name on a
+   crest. Diegetic, in-world, in the register ([[world-naming-and-tone]]). Never
+   a scrolling codex.
+6. **Show the change, not the state.** Story is *difference* — the path that was
+   lit and now isn't; the crack that's now gold. Deliver transformations the
+   player caused, so the narrative and the mechanic are the same event.
+
+## Worked example
+
+**World:** the drowned-coast keeper (from [[world-worldbuilding-scaffold]]).
+
+- **Environmental:** the opening frame — a graded dusk, one lit lantern, a path
+  of dark ones trailing into rising water. No text needed; the premise is *seen*.
+- **Systemic:** when the tide claims a lantern, the hamlet behind it goes dark on
+  the map and its light never returns this run. The *rule* tells the loss; the
+  player feels it because they routed there or didn't.
+- **Embedded:** one line at the far lamp — *"the last one lit."* Four words,
+  diegetic, in register. That's the entire authored narrative.
+- **Result:** a complete emotional arc — hope, attrition, a small held light —
+  delivered by place, rule, and four words. No cutscene, no codex.
+
+## Aesthetic hook
+
+Environmental storytelling *is* [[world-aesthetic-direction]] doing double duty:
+the **Kentō** frame that passes the JUDGE's depth axis (a real fore/mid/back,
+a focal point) is also the frame that *narrates* — a snuffed lantern reads as
+loss only if the scene has the depth and contrast to show it. Because text is a
+DOM overlay and the palette carries the mood, you can tell a whole story in ink,
+washi, and one *ko* glow going out. Keep embedded text set in the serif the JUDGE
+renders true (`docs/JUDGE.md`), and let restraint here reinforce the house voice
+([[world-naming-and-tone]]): the systems and the light say it; the words just
+confirm it.
+
+## Traps
+
+- **The lore dump.** A text wall at the start players skip. If it's not
+  discoverable and short, cut it — deliver through play.
+- **Narrating what the system already shows.** A popup "You lost a lantern!" over
+  a lantern the player watched go dark. Trust the mechanic; drop the caption.
+- **Story that ignores the mechanics.** Fiction that contradicts what the rules
+  do ([[world-worldbuilding-scaffold]]'s "rule without echo"). The played story
+  is the real one — align the told one to it.
+- **Embedded everywhere.** Fragments on every rock dilute the ones that matter.
+  Miser's budget.
+- **Cutscene reflex.** Reaching for a scripted scene when a composed frame or a
+  system event would land harder *and* stay deterministic and cosmetic-free.
+
+## Composes with
+
+- [[world-worldbuilding-scaffold]] — decides what little must be understood; this
+  delivers it without text walls.
+- [[system-emergent-systems]] — the systemic channel; the game authors personal,
+  replayable story the designer didn't write.
+- [[world-aesthetic-direction]] — the composed frame is the primary narrator.
+- [[world-naming-and-tone]] — governs the spare, diegetic voice of any embedded
+  text.
+
+## See also
+
+- [`docs/JUDGE.md`](../../docs/JUDGE.md) — depth & composition: a frame with real
+  layers is also a frame that can *tell* something.
+- [[anchor-shadow-of-mordor]] (systemic memory as narrative),
+  [[anchor-outer-wilds]] (knowledge as the only progression),
+  [[anchor-return-of-the-obra-dinn]] (the player reconstructs the story).

package/design/40-worldbuilding/theme-vectors.md

@@ -0,0 +1,134 @@
+---
+id: world-theme-vectors
+title: Theme Vectors — choosing a setting that recolours the mechanics
+kind: worldbuilding
+tags: [theme, setting, fiction, twist, recolour, fantasy, resonance]
+summary: Choosing a setting/theme space; theme as a twist vector that recolours every system, not a skin — pick where the fiction and the mechanic rhyme.
+use-when: You have a core loop and need the world it lives in — a setting that sharpens the mechanics instead of just decorating them.
+composes-with: [world-worldbuilding-scaffold, world-aesthetic-direction, world-narrative-delivery]
+verify-with: none
+---
+
+# Theme Vectors — choosing a setting that recolours the mechanics
+
+**What it is.** The **theme** is the fiction the mechanics wear — the where, when,
+and who. It is one of the six twist vectors in [[process-the-twist]], and the
+cheapest to reach for, which is exactly why it's the easiest to waste. A theme
+earns its place when it *recolours the systems* — makes the same rule mean
+something new — not when it merely repaints the sprites.
+
+**Player fantasy / why it's fun.** A setting is a promise about what the numbers
+*mean*. "Fuel" and "faith" can be the identical resource loop; one is a survival
+horror, one is a pilgrimage. The theme is where the player decides to care.
+
+## The test: does the fiction rhyme with the mechanic?
+
+A theme is load-bearing when you can trace a **rhyme** — a place where the rule
+and the fiction say the same thing. Skip the theme and the loop still works but
+means nothing; skip the loop and the theme is a wallpaper. Aim for both saying it.
+
+| Mechanic | A theme that rhymes | A theme that's just a skin |
+|---|---|---|
+| Resource that decays if unused | *Grief* you must spend before a season ends | "Energy" that ticks down |
+| Territory you can't hold everywhere | A **failing** lighthouse network on a drowning coast | Generic "zones" on a map |
+| Permadeath with persistent memory | Orcs who *remember* every duel (Shadow of War) | Enemies with random names |
+| One-screen constraint | A single tide-pool you tend as the sea rises | "A small arena" |
+
+## Vectors / options
+
+Theme is a *space* to choose within, not a single lever. Move along these axes:
+
+| Axis | Poles | The mechanical consequence to hunt for |
+|---|---|---|
+| **Register** | mythic ↔ mundane | Mythic licenses spectacle & absolutes; mundane licenses stakes you feel |
+| **Scale** | a room ↔ a cosmos | Sets what a "unit" is: a citizen, a hero, an empire, a season |
+| **Agency** | steward ↔ conqueror | Do you *tend* the system or *bend* it? Recolours win conditions |
+| **Time** | one night ↔ generations | Frames the session container; a run vs a campaign vs a lineage |
+| **Tone** | dread ↔ cosy ↔ elegiac | The tonal twist rides here; recolours feedback (menace vs warmth) |
+| **Material** | ink/wood/stone ↔ neon/chrome | Ties directly to [[world-aesthetic-direction]] and the Kentō set |
+
+The Hayao example corpus lives near one corner of this space on purpose:
+*lanternway*, *rootward*, *tarnholm*, *kintsugi* are **mundane-register,
+small-scale, steward-agency, elegiac** worlds rendered in wood and ink. That's a
+house lean, not a law — see the aesthetic hook below.
+
+## Method
+
+1. **Start from the signature mechanic**, not the setting. Name the one rule the
+   game is *about* (from [[process-the-twist]]). The theme has to serve it.
+2. **List 4–6 candidate fictions** the mechanic could wear. Force range: one
+   mythic, one mundane, one cosy, one dreadful. Don't stop at the first.
+3. **Find the rhyme for each.** For every candidate, write the single sentence
+   where the fiction and the rule say the same thing. No rhyme → cut it.
+4. **Trace the recolour** across three systems (economy, threat, progression):
+   does the theme *change what a choice feels like*? A theme that touches only
+   the art layer is a skin — send it to [[world-aesthetic-direction]] and pick a
+   deeper one.
+5. **Check it against the pillars** ([[process-pillars]]). The theme that most
+   sharpens a pillar wins; a theme that fights one is a different game.
+6. **Name the world in one line.** "A drowning coast where the last keeper
+   rations light." If it's boring to say, it'll be boring to inhabit — hand the
+   line to [[world-worldbuilding-scaffold]].
+
+## Worked example
+
+**Loop:** a push-your-luck resource run — bank early for safety, press on for
+more, lose it all if you overreach ([[pattern-risk-reward]]).
+
+- **Candidates:** deep-sea salvage; a tea ceremony under time pressure; a
+  wildfire-line dig; *a lantern-lighter walking a mountain path at dusk*.
+- **Rhyme found:** the lantern-lighter. Each lit lantern is banked progress; the
+  dark ahead is the press. Oil is the run's only currency; the summit shrine is
+  the bank. The fiction *is* the risk-reward curve.
+- **Recolour:** threat becomes *the encroaching dark* (a timer with a face);
+  the "bank" becomes *turning back*, which the fiction makes a real cost, not a
+  menu button. Progression is the path itself.
+- **World line:** *"A lantern-keeper climbing into the dusk, deciding how far
+  the light will reach before the dark takes the path."* (This is *lanternway*'s
+  neighbourhood — arrived at from the mechanic, not copied from it.)
+
+## Aesthetic hook
+
+The house look is **Kentō woodblock / Miyazaki-16** (`KENTO`, `MEADOW`, `DUSK`
+in [`docs/API.md`](../../docs/API.md); see [[world-aesthetic-direction]]). Its
+eight named hues — vermilion *shu*, persimmon *kaki*, ochre *ko*, pine *matsu*,
+teal *asagi*, indigo *ai*, wisteria *fuji*, dusty-rose *saku* — read as *elegant
+Japanese craft*, so themes in that register (folk myth, seasonal ritual, quiet
+stewardship, weathered wood and ink) come pre-harmonised. A **neon-cyberpunk**
+or **candy-arcade** theme fights the palette; if your mechanic truly wants it,
+say so early and swap the palette deliberately — Kentō is a starting point, not a
+cage (`docs/CONVENTIONS.md`). But a theme chosen *near* the house register gets
+its art direction and its AA guarantee (`npm run palette`) close to free.
+
+## Traps
+
+- **Skin, not recolour.** If the theme could be swapped for another with zero
+  mechanical change, it's set-dressing. Bend deeper or pick a vector other than
+  theme.
+- **Theme-first tourism.** Choosing "steampunk" because it's cool, then bolting a
+  loop on. The mechanic picks the theme, not the reverse.
+- **Register mismatch.** Cosy art on a punishing loop (or dread art on a gentle
+  one) confuses the promise. Let tone, mechanic, and palette agree.
+- **Over-lore.** A rich setting with no mechanical rhyme is a wiki, not a game.
+  Minimum viable lore only — [[world-worldbuilding-scaffold]].
+- **Fighting the palette by accident.** Reskinning to a clashing world without
+  swapping `MEADOW`/`DUSK` yields muddy, off-brand frames the JUDGE flags.
+
+## Composes with
+
+- [[process-the-twist]] — theme *is* one of the six vectors; this module is its
+  deep dive.
+- [[world-worldbuilding-scaffold]] — the chosen setting becomes a coherent world
+  with rules and stakes here.
+- [[world-aesthetic-direction]] — theme sets the register; this turns it into a
+  concrete, JUDGE-passing look.
+- [[process-pillars]] — the pillars are the scoring function for candidate themes.
+
+## See also
+
+- [`docs/JUDGE.md`](../../docs/JUDGE.md) — palette harmony (axis 3): does the
+  world's colour belong to *one* set?
+- `docs/CONVENTIONS.md` "Default palette is Kentō" — the house register and the
+  AA gate.
+- Example worlds *lanternway*, *rootward*, *tarnholm*, *kintsugi* — as
+  *convention references* for register, never a menu to copy (AGENTS.md).

package/design/40-worldbuilding/worldbuilding-scaffold.md

@@ -0,0 +1,132 @@
+---
+id: world-worldbuilding-scaffold
+title: Worldbuilding Scaffold — the minimum viable world
+kind: worldbuilding
+tags: [lore, world, setting, stakes, fantasy, rules, coherence, scaffold]
+summary: From a setting to a coherent world with rules, stakes, and a fantasy — the minimum viable lore a small deterministic game actually needs.
+use-when: You picked a theme and need to turn it into a world that holds together — enough lore to justify the mechanics, no more.
+composes-with: [world-theme-vectors, world-faction-identity, world-narrative-delivery, world-naming-and-tone]
+verify-with: none
+---
+
+# Worldbuilding Scaffold — the minimum viable world
+
+**What it is.** A world is not a wiki. For a small deterministic game it's a
+tight bundle: a **premise**, the rules that premise implies, the stakes that make
+a loss sting, and the fantasy the player is buying. Build the load-bearing
+minimum, then stop. Every sentence of lore should either justify a mechanic or
+raise the stakes; if it does neither, it's decoration.
+
+**Player fantasy / why it's fun.** A coherent world makes the player *fill in the
+rest*. Give them a rule and a stake and they'll imagine the history for free.
+Your job is the skeleton, not the encyclopedia.
+
+## The five load-bearing pieces
+
+A world holds together when these five agree. Write one line each — that's the
+whole doc for a small game.
+
+| Piece | The question it answers | Kept small by |
+|---|---|---|
+| **Premise** | What is the world and what just went wrong? | One sentence. "The tide is rising and the lantern network is failing." |
+| **Rules of the world** | What's true here that isn't true elsewhere? | 2–3 rules max, each mapping to a mechanic |
+| **Stakes** | What's lost if you fail? | Something concrete and small enough to feel |
+| **The player's role** | Who are you, and why is it *your* problem? | A verb: keeper, mender, surveyor, forager |
+| **The fantasy** | What does the player get to *feel*? | One clause; this is the sales pitch |
+
+The discipline: **every rule of the world is a mechanic in disguise.** If a
+lore rule has no mechanical echo, it's flavour — fine in small doses, but it
+isn't scaffolding. If a mechanic has no lore rule, the player will invent one;
+make sure it's the one you want.
+
+## Vectors / options — how much world does the scope need?
+
+Match lore weight to session shape ([[system-session-structure]]):
+
+| Game shape | World weight | What you actually write |
+|---|---|---|
+| Single-screen puzzle / arcade | **A premise line** | One evocative sentence; the mechanic is the story |
+| Run-based (roguelite) | **Premise + 2 rules + a role** | Enough for the loop to *mean* something across runs |
+| Campaign / metroidvania | **Full five + a place-geography** | Regions with identity; a why-here for each gate |
+| Systemic / emergent | **Premise + rules that interact** | Lean lore; the *systems* author the stories ([[system-emergent-systems]]) |
+
+More world is not better world. *tarnholm* and *rootward* say almost nothing
+explicitly — the premise is in the name and the mechanics carry the rest.
+
+## Method
+
+1. **Write the premise line.** The world plus the disturbance — the thing that
+   makes it a *game* and not a diorama. Inherit the register from
+   [[world-theme-vectors]].
+2. **Derive 2–3 rules of the world** *from your mechanics*, phrased as fiction.
+   Mechanic "resources decay" → rule "nothing keeps in the salt air." Mechanic
+   "you can't be everywhere" → rule "one keeper, many lamps." Each rule is a
+   promise the systems must keep.
+3. **Set the stake.** Name what failure costs in the fiction — and make it
+   concrete and *scaled to the loop*, not "the world ends." A drowned village
+   reads; a fallen empire is abstract in a 5-minute run.
+4. **Name the role with a verb.** Keeper, mender, surveyor. The verb is the
+   player's fantasy and often the core mechanic's name.
+5. **State the fantasy in one clause.** "The quiet competence of keeping the
+   light on." This is what the [[world-aesthetic-direction]] and
+   [[pattern-juice-choreography]] must deliver on.
+6. **Cut everything else.** If a fact doesn't back a rule, a stake, or the
+   fantasy, it's out of the scaffold. Let players imagine the rest.
+
+## Worked example
+
+**Premise:** *"A coastal shrine-network is drowning; the last keeper walks the
+path relighting lanterns before the dark and the tide close it."*
+
+- **Rules of the world:** (1) *Light holds the dark back only while it burns* →
+  timed lantern mechanic. (2) *One keeper, many lamps* → you can't cover
+  everything; routing is the game. (3) *Oil is scarce and doesn't keep* →
+  a resource loop that punishes hoarding.
+- **Stake:** each lantern that goes dark strands the hamlet behind it — a small,
+  legible loss, not an abstract apocalypse.
+- **Role:** the **keeper** — the verb is the mechanic.
+- **Fantasy:** *the quiet, dwindling competence of holding a line of light against
+  a rising night.*
+
+Three sentences of lore; three mechanics justified; one feeling to deliver.
+Anything more is a wiki.
+
+## Aesthetic hook
+
+The **Kentō woodblock** register (`MEADOW`/`DUSK`; see
+[[world-aesthetic-direction]]) is quiet, weathered, and elegiac by construction —
+it rewards *small, human* stakes over cosmic ones. A world of one keeper and a
+drowning coast reads instantly in ink and washi; a galactic-empire premise fights
+the intimacy the palette wants. Let the scaffold's *scale* match the look: the
+house lean is small worlds with big feelings. The premise line doubles as the
+title/first-screen invitation the JUDGE scores for "invites" (chrome & finish).
+
+## Traps
+
+- **The encyclopedia.** Pages of history no mechanic touches. Cut to the
+  load-bearing five.
+- **Rule without echo.** Lore that promises something the systems never deliver
+  ("the gods are watching" but nothing watches). Every rule needs a mechanic.
+- **Stakes too big to feel.** "Save the universe" is abstract; "don't let this
+  village go dark" lands. Scale the stake to the session.
+- **Role without a verb.** "You are the chosen one" is a title, not a fantasy.
+  Name what you *do*.
+- **Front-loaded lore dump.** Text walls at the start. Deliver the world through
+  play — [[world-narrative-delivery]].
+
+## Composes with
+
+- [[world-theme-vectors]] — supplies the register and the rhyme this scaffold
+  builds on.
+- [[world-faction-identity]] — when the world has sides, each faction is a
+  sub-scaffold with its own premise and values.
+- [[world-narrative-delivery]] — how the scaffold reaches the player without
+  text walls.
+- [[world-naming-and-tone]] — the premise line and role verb are named here.
+
+## See also
+
+- [`docs/JUDGE.md`](../../docs/JUDGE.md) — chrome & finish: does the first screen
+  *invite*? The premise line is your invitation.
+- Example worlds *lanternway*, *rootward*, *tarnholm*, *kintsugi* — each is a
+  three-sentence world, not a wiki (reference the *restraint*, not the content).

package/design/50-patterns/README.md

@@ -0,0 +1,54 @@
+# 50-patterns/ — the cross-cutting fun & polish laws
+
+The other sections are staged — you reach for an [[anchor]] at ANCHOR, a
+[[genre]] at COMPOSE, a [[world]] at SHAPE. **Patterns are always on.** They're the
+laws that apply at *every* stage and across *every* genre: a feedback loop can
+snowball a puzzle or an RTS; risk/reward gives teeth to a card draw or a corner
+line; readability decides whether any mechanic underneath is even visible. Don't run
+these in order — hold them in the back of your mind the whole way through, and check
+each design choice against the ones it touches.
+
+They are written as **laws with teeth**: each ties to a proof or a feel-gate rather
+than a vibe. Where the pattern becomes checkable, the module *routes* to it — the
+skill-delta ([`docs/FUN.md`](../../docs/FUN.md) law 2) for flow and feedback runaway,
+the Channel-4 feel gates ([`docs/JUICE.md`](../../docs/JUICE.md)) for juice and
+forgiveness, the vision judge ([`docs/JUDGE.md`](../../docs/JUDGE.md)) for
+readability — never restating the recipe. Design the pattern here; prove it there.
+
+Several pattern modules pair 1:1 with a concrete `[[system-*]]`: **anti-frustration**
+is the mindset, [[system-grace]] the machinery; **mastery-and-flow** the why,
+[[system-mastery-curve]] the how; **emergence** the principle,
+[[system-emergent-systems]] the parts. Read the pair together.
+
+## The eight pattern modules
+
+| id | title | summary |
+|---|---|---|
+| [[pattern-feedback-loops]] | Feedback Loops | Positive loops snowball, negative loops correct — design which dominates so leads stay tense, not decided. |
+| [[pattern-risk-reward]] | Risk / Reward | A choice with teeth — every reward priced in real risk, every option double-edged, so decisions cost something. |
+| [[pattern-mastery-and-flow]] | Mastery & Flow | Keep challenge riding just above skill — the flow channel — and prove it with the skill-delta gap. |
+| [[pattern-emergence]] | Emergence | Depth from few pieces — rules that interact, not content that stacks; the game generates situations you never authored. |
+| [[pattern-anti-frustration]] | Anti-Frustration | Punish the mistake, not the player — grace, instant retry, undo, and respecting time keep hard fair. |
+| [[pattern-juice-choreography]] | Juice as Choreography | The sim resolves and returns a choreography script; the view replays it — every event answers on ≥2 senses. |
+| [[pattern-readability]] | Readability | The player must instantly find the avatar, read the threat, and see the way — salience, signposting, affordances. |
+| [[pattern-pacing-and-tension]] | Pacing & Tension | Tension is a curve, not a constant — alternate peaks and breathers so the finale reads as a peak. |
+
+## How they interlock
+
+```
+              feedback-loops ──build──▶ pacing-and-tension ◀──build── risk-reward
+                    │                          │                          │
+                    └──────▶ mastery-and-flow ◀┘                          │
+                                    │                                     │
+   emergence ──depth──▶ (the ceiling flow climbs) ◀──variance────────────┘
+
+   readability ──gates the read──▶ juice-choreography  (juice serves the read; read wins ties)
+   anti-frustration ──bounds the anxious side of──▶ mastery-and-flow
+```
+
+The **fun triangle** — feedback loops, risk/reward, and pacing — shapes tension over
+time; **mastery-and-flow** is the channel that tension should stay inside;
+**emergence** is how deep that channel goes on a small content budget. The **feel
+pair** — readability and juice-choreography — governs whether any of it reaches the
+player's eye, and **anti-frustration** keeps the whole thing humane. Every module
+names the siblings it composes with and the exact proof or gate that keeps it honest.

package/design/50-patterns/anti-frustration.md

@@ -0,0 +1,121 @@
+---
+id: pattern-anti-frustration
+title: Anti-Frustration
+kind: pattern
+tags: [forgiveness, grace, anti-frustration, respect, retry, mercy, difficulty, humane]
+summary: Punish mistakes without punishing the player — grace, instant retry, undo, and respecting time keep hard fair.
+use-when: A game is hard or long and you must separate "difficult" from "tedious/unfair"; anywhere a failure costs the player time.
+composes-with: [pattern-mastery-and-flow, pattern-juice-choreography, system-grace, system-save-and-checkpoint]
+verify-with: docs/FUN.md#part-1-—-universal-laws
+---
+
+# Anti-Frustration
+
+**What it is.** A game can be brutally hard and still respect you, or trivially easy
+and still waste your life. **Anti-frustration** is the discipline of punishing the
+*mistake* without punishing the *player* — grace windows, instant retry, undo,
+generous checkpoints, no re-doing solved work. FUN.md law 5 states the core: **grace
+is a system, not polish.**
+
+**Player fantasy.** *"That death was fair, and I'm already trying again."* The
+absence of dread about *losing progress*, so all the tension goes where it belongs —
+the challenge itself. The game is on your side even as it kicks you.
+
+## Why it works
+
+- **Frustration and difficulty are different axes.** Difficulty is the challenge you
+  signed up for; frustration is friction you didn't — reloads, re-treading, input
+  windows so tight the game feels like it's lying. Killing the second lets you crank
+  the first.
+- **The grace mindset keeps players in [[pattern-mastery-and-flow]].** A death that
+  costs three seconds keeps you on the ridge; a death that costs three minutes drops
+  you into anxiety and quitting.
+- **Respecting time is respecting the player.** Re-doing solved work, unskippable
+  intros, punitive save-scumming — these read as contempt. Grace reads as craft.
+
+## Levers
+
+| Lever | Softens | Example |
+|---|---|---|
+| **Coyote time / jump buffer** | Input timing strictness | ~6-frame window past the ledge ([[system-grace]]) |
+| **I-frames / hit-stop buffering** | Cascading damage | Invuln after a hit; buffer intent through the freeze (FUN.md §4) |
+| **Instant retry** | The cost of failure | Respawn in < 1s, momentum preserved (CLAWSTRIKE) |
+| **Undo / restart** | The cost of a wrong move | First-class undo key (Dying Dreams; FUN.md §1) |
+| **Wound-before-death** | One-shot deaths | One grab is a story, two is a death (FUN.md §16) |
+| **Checkpoint density** | Re-tread distance | Save at every room; never re-solve ([[system-save-and-checkpoint]]) |
+| **Mercy clears** | Death spirals | Clear the screen on death/phase change (FUN.md §7) |
+| **Assist modes** | The floor itself | Slow-mo, invuln, skip (Celeste; [[system-accessibility]]) |
+
+## Applied across genres
+
+| Genre | The grace |
+|---|---|
+| **Precision platformer** ([[anchor-celeste]]) | Coyote, buffer, corner-correct, instant retry, assist mode |
+| **Grid puzzle** ([[genre-grid-puzzle]]) | Undo + restart; a wrong push is never a lost level (FUN.md §1) |
+| **Bullet hell** ([[genre-bullet-hell]]) | Mercy clears on death and phase transitions — structural, not optional (FUN.md §7) |
+| **Survival horror** ([[genre-survival-horror]]) | Wound + grace beats instadeath; the fuel budget is winnable *with discipline* (FUN.md §16) |
+| **Roguelike** ([[genre-roguelike]]) | Meta-progression turns a lost run into progress ([[system-meta-progression]]) |
+| **Tactics** ([[genre-tactics]]) | Undo a move within a turn before commit; perfect info means no gotchas |
+| **Racing** ([[genre-racing]]) | Rewind/retry a corner; no re-driving three clean laps for one mistake |
+
+## Overdone when…
+
+- **Grace erases the challenge.** Infinite retries with no stakes flatten the
+  [[pattern-mastery-and-flow]] channel — tension needs *some* cost. Make retry cheap,
+  not free-of-meaning.
+- **Save-scumming replaces skill.** If reloading is the optimal strategy, the design
+  leaks; either commit choices or make grace explicit (undo), not exploitable.
+- **Hand-holding as forgiveness.** Removing failure entirely isn't grace, it's a
+  toy. Anti-frustration removes *tedium*, not *challenge*.
+- **Inconsistent grace.** A coyote window that works on some ledges and not others
+  is worse than none — the player learns not to trust it ([[pattern-readability]]).
+
+## Verify / feel-gate link
+
+Grace is the most *directly testable* fun law — it's law 5 precisely because every
+piece of it is a frame window:
+
+- **Frame-pump the grace window (FUN.md law 5).** Assert accepted-inside /
+  refused-outside to the exact frame: coyote, jump buffer, i-frames, hit-stop input
+  buffering. `forgivenessIssues(CONFIG)` (JUICE.md Part 3, `npm run feel`) gates that
+  coyote/buffer/corner are specced at all.
+- **Buffer through injected pauses (law 5).** Any pause the sim injects (hit-stop,
+  level-up pick) must buffer intent across it — assert a press during the freeze
+  still fires.
+- **Instant retry preserves state (law 7).** Snapshot→restore→hash round-trip proves
+  retry doesn't corrupt or drift the sim.
+- **Respect-time proofs are the checkpoint/save gates** ([[system-save-and-checkpoint]])
+  — no lost solved work across a save/load cycle.
+
+## Worked micro-example
+
+*"A brutally hard platformer players still call fair."* Keep difficulty maxed; strip
+the *frustration* around it. (1) **Instant retry** — respawn in < 1s at the room
+start, momentum intact, so a death costs seconds not minutes (CLAWSTRIKE). (2)
+**Consistent grace** — coyote and jump-buffer windows that work on *every* ledge, so
+the player learns to trust them ([[system-grace]], [[pattern-readability]]). (3)
+**No re-tread** — checkpoint at each screen; never re-solve solved ground
+([[system-save-and-checkpoint]]). The challenge is untouched; the tedium is gone.
+Prove it: frame-pump the grace window (accepted-inside / refused-outside to the exact
+frame, FUN.md law 5) and round-trip snapshot→restore→hash so retry never drifts state.
+
+## Composes with
+
+- [[system-grace]] — this pattern is the *mindset*; that system is the concrete
+  coyote/buffer/i-frame/mercy machinery with the frame values. Read them together.
+- [[pattern-mastery-and-flow]] — grace bounds the anxious side of the flow channel so
+  hard stays humane.
+- [[system-save-and-checkpoint]] — respecting time is mostly a checkpoint-density and
+  no-re-tread problem.
+- [[system-accessibility]] — assist modes are anti-frustration extended to *who* can
+  reach flow at all.
+- [[pattern-juice-choreography]] — a death that *feels* clean (readable cause,
+  quick reset) is half feel, half forgiveness.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) law 5 — grace is a system, not polish; the same
+  shape at every timescale, each unit-testable.
+- [`docs/JUICE.md`](../../docs/JUICE.md) Part 3 — `forgivenessIssues`, the feel gate
+  that fails a build with unspecced grace.
+- [[anchor-celeste]] — assist-mode humaneness as a whole-game thesis.