hayao 0.4.0 → 0.4.2

package/design/50-patterns/readability.md

@@ -0,0 +1,121 @@
+---
+id: pattern-readability
+title: Readability
+kind: pattern
+tags: [readability, salience, signposting, affordance, contrast, clarity, legibility, ui]
+summary: The player must instantly find the avatar, read the threat, and see the way — salience, signposting, and affordances.
+use-when: Anywhere the player might lose the avatar, misread a threat, or miss a path/interaction; setting the visual hierarchy.
+composes-with: [pattern-juice-choreography, pattern-emergence, system-telegraphs, system-onboarding]
+verify-with: docs/JUDGE.md#the-rubric
+---
+
+# Readability
+
+**What it is.** Before a game can be fun it must be **legible**: the player
+instantly finds their avatar, reads what's dangerous, sees where to go, and knows
+what's interactive. Three tools — **salience** (the important thing out-contrasts
+everything), **signposting** (the world points the way), **affordances** (a thing
+*looks* like what it does). If the player can't read it, no mechanic underneath
+matters.
+
+**Player fantasy.** *"I always know what's going on."* The frame parses at a glance;
+attention lands where it should; nothing important hides. Confidence, not confusion.
+
+## Why it works
+
+- **The avatar must be the brightest, highest-contrast thing on screen.** It's the
+  one object the player tracks every frame; lose it and every input becomes a guess
+  (JUICE.md Part 2: updrift's ochre lantern on a twilight cliff). This is the
+  **salience gate**.
+- **Perception is a hierarchy.** The eye goes to contrast, motion, and saturation
+  first. Spend that budget on what matters (avatar > threat > pickup > scenery); a
+  flat, evenly-toned frame gives the eye nowhere to land (JUDGE.md rubric 1 & 2).
+- **Affordances are a free tutorial.** A ledge that *looks* grabbable, a door that
+  *looks* openable, a red spike that *reads* as death — the world teaches without
+  text ([[system-onboarding]]).
+- **Emergence needs legibility to be fair.** Interacting systems ([[pattern-emergence]])
+  are only fun when the player can *foresee* the interaction — Into the Breach shows
+  exactly what resolves. Unreadable emergence is just chaos.
+
+## Levers
+
+| Lever | Tool | Example |
+|---|---|---|
+| **Value contrast** | Salience | Bright avatar over a low-key ground (updrift) |
+| **Colour role** | Palette convention | Red = threat, gold = reward, blue = safe (kept consistent) |
+| **Silhouette** | Shape reads before colour | Distinct enemy silhouettes; contour/autotile terrain masses |
+| **Motion** | Draws the eye | The one thing moving is the thing to watch ([[pattern-juice-choreography]]) |
+| **Telegraphs** | Signpost threat *in time* | ~0.45s flash before an attack ([[system-telegraphs]]) |
+| **Composition** | Foreground/mid/background | Depth so objects don't float in a void (JUDGE.md rubric 2) |
+| **Chrome restraint** | HUD out of the way | Framed, unobtrusive, nothing clipped (JUDGE.md rubric 6) |
+
+## Applied across genres
+
+| Genre | The read that must hold |
+|---|---|
+| **Bullet hell** ([[genre-bullet-hell]]) | Dense patterns that still *read* as coherent — density ≠ illegibility (FUN.md §7) |
+| **Action-adventure** ([[genre-action-adventure]]) | The attack telegraph (~0.45s) makes reactive play possible (FUN.md §4) |
+| **Tactics** ([[genre-tactics]]) | Perfect information *shown* honestly — telegraphed grid you can read (FUN.md §12) |
+| **Tower defense** ([[genre-tower-defense]]) | The range ring is the genre's most important UI (FUN.md §8) |
+| **City builder** ([[genre-city-builder]]) | The live "+N" under the cursor IS the UI (FUN.md §17) |
+| **Precision platformer** ([[genre-precision-platformer]]) | Avatar out-contrasts scenery; a gap reads as jumpable |
+| **Horde survival** ([[genre-horde-survival]]) | The avatar findable inside a screen-filling swarm |
+
+## Overdone when…
+
+- **Juice buries the read.** Particles and shake so heavy the avatar is lost — feel
+  fighting readability, and readability must win ([[pattern-juice-choreography]]).
+- **The flat gray frame.** No value range, no focal point — the eye has nowhere to
+  go (the judge's most common failure: "empty / evenly-gray", JUDGE.md rubric 2).
+- **Convention drift.** Red means threat here and reward there — the player's learned
+  colour language now lies. Keep roles consistent.
+- **Over-signposting.** Arrows, glows, and tooltips on everything — nothing stands
+  out because everything shouts. Salience is a *budget*; spend it on the one thing.
+- **Decorative clutter over the play space.** Foreground detail that occludes the
+  avatar or reads as interactive when it isn't (false affordance).
+
+## Verify / feel-gate link
+
+Readability has a **mechanical floor and a taste ceiling** — both are gated:
+
+- **Salience gate (floor).** `salienceIssues(world.render(), avatarFill, background)
+  .length === 0` (JUICE.md Part 3, `npm run feel`) proves the avatar out-contrasts
+  the scenery *pre-lighting*. Note the Kentō AA contrast guarantee holds pre-lighting
+  only — judge lit contrast from the rendered PNG, never the hexes (JUDGE.md rubric 2).
+- **The vision judge (ceiling).** `npm run judge` — a multimodal model looks at the
+  actual pixels and scores **Readability** (rubric 1) and **Depth & composition**
+  (rubric 2). The gates can pass while the image still reads empty (updrift's
+  invisible parallax mountains passed both gates; only the judge caught it).
+- **Telegraph honesty** ([[system-telegraphs]], FUN.md §4/§12) — the read must arrive
+  *in time*: assert the tell precedes the hit by the reaction window.
+
+## Worked micro-example
+
+*"A twilight-cliff platformer where the player never loses themselves."* The ground is
+low-key by design (mood), which is exactly the trap — the avatar can vanish into it.
+Fix it with a salience budget: (1) the avatar is the single **brightest, highest-
+contrast** token (updrift's ochre lantern), so the eye locks to it every frame; (2)
+threats own **red**, pickups own **gold**, kept consistent so the colour language
+never lies; (3) a real **background layer** (a graded night sky, a moon, layered
+ridges) gives depth so nothing floats in a void. Prove it two ways:
+`salienceIssues(...)` passes *pre-lighting* (the mechanical floor), then `npm run
+judge` looks at the pixels and scores Readability and Depth ≥ 4 — the gate that caught
+updrift's invisible mountains the salience check couldn't.
+
+## Composes with
+
+- [[pattern-juice-choreography]] — the constant tension partner; juice must serve
+  the read, never bury it.
+- [[system-telegraphs]] — signposting threat *in time* is the combat face of
+  readability.
+- [[pattern-emergence]] — interacting systems are only fair when their interactions
+  are foreseeable (legible).
+- [[system-onboarding]] — affordances are the wordless tutorial; readability is how
+  a game teaches itself.
+
+## See also
+
+- [`docs/JUDGE.md`](../../docs/JUDGE.md) — the vision judge; rubric axes 1, 2 & 6 are
+  this pattern scored from pixels. **The** reference here.
+- [`docs/JUICE.md`](../../docs/JUICE.md) Part 2 & 3 — the salience rule and the
+  `salienceIssues` gate.

package/design/50-patterns/risk-reward.md

@@ -0,0 +1,120 @@
+---
+id: pattern-risk-reward
+title: Risk / Reward
+kind: pattern
+tags: [risk, reward, push-your-luck, tradeoff, double-edged, gambling, tension, choice]
+summary: A choice with teeth — every reward priced in real risk, every option double-edged, so decisions cost something.
+use-when: You're designing a decision, upgrade, or resource spend and it feels like a no-brainer (strictly-better = no choice).
+composes-with: [pattern-feedback-loops, pattern-pacing-and-tension, system-reward-schedules, system-build-diversity]
+verify-with: docs/FUN.md#21-·-narrative-decisions-reigns-like
+---
+
+# Risk / Reward
+
+**What it is.** A decision has **teeth** when its upside is priced in a real,
+legible downside — push deeper for more loot at rising odds of losing it all;
+take the strong card that also feeds your discard pile; heal now or bank the mana.
+The pattern is the enemy of the *no-brainer*: if one option is strictly better,
+there was never a choice.
+
+**Player fantasy.** *"Do I dare?"* The pull of the greedy line and the dread of
+the cost, held in the same breath. Owning the outcome — the win you earned by
+holding your nerve, the loss you earned by one more push.
+
+## Why it works
+
+- **A choice is only a choice if both sides cost something.** Strictly-better
+  options are content the player clicks past; double-edged options are content the
+  player *thinks about*. Depth is measured in agonised pauses.
+- **Push-your-luck manufactures tension for free.** Each "one more" raises the
+  stake and the dread on its own — you don't script the peak, the player's greed
+  builds it (see [[pattern-pacing-and-tension]]).
+- **Variance is fun *when the player chose it*.** A gamble you opted into reads as
+  drama; the same swing forced on you reads as unfair. Risk must be *elected*.
+- **The bank point is the whole tension.** The moment you *can* lock in gains is
+  where push-your-luck lives — one-more-push against cash-out-now. Remove the bank
+  point and it's not a gamble, it's an outcome; the choice of *when to stop* is the game.
+
+## Levers
+
+| Lever | Effect | Example |
+|---|---|---|
+| **Bust probability** | How fast the greedy line collapses | Each extra room: +15% ambush |
+| **Reward slope** | How steep the payoff for pushing | Pot doubles each step; last multiplier is the sweetener |
+| **Bank point** | When you can lock in gains | Cash out at any chest; commit at the door |
+| **Double edge** | The cost baked into the *good* option | The power card also damages you (Reigns' |Δ| ≤ 20) |
+| **Information** | How much you know before committing | Telegraphed odds vs blind draw ([[pattern-readability]]) |
+| **Loss size** | What a bust actually costs | Lose the run's haul vs lose one heal |
+
+## Applied across genres
+
+| Genre | The teeth |
+|---|---|
+| **Narrative decisions** ([[genre-narrative-decisions]]) | Every swipe double-edged; meters between two ditches; |Δ| ≤ 20 keeps any single choice from deciding the reign (FUN.md §21) |
+| **Roguelike** ([[genre-roguelike]]) | The cursed item, the risky shortcut, the elite room for elite loot |
+| **Deckbuilder** ([[genre-deckbuilder]]) | Powerful cards with a downside; the skip-the-reward-for-tempo choice |
+| **Physics arcade** ([[genre-physics-arcade]]) | The guarded multiplier peg; last-ball-for-the-jackpot pressure |
+| **Blackjack / push-your-luck** ([[anchor-balatro]]) | Hit or stand; the score you have vs the score you could |
+| **Farming sim** ([[genre-farming-sim]]) | Plant the long crop that might not ripen before the season turn (FUN.md §15) |
+| **Tactics** ([[genre-tactics]]) | Overextend for the kill vs hold the defensible tile |
+
+## Overdone when…
+
+- **The no-brainer.** One option dominates in every state — it's not a decision,
+  it's a speed bump. Cut it or add a cost.
+- **Fake risk.** The "gamble" always pays (odds too kind, loss too small) — players
+  learn to always push and the tension evaporates. The bust must *bite*.
+- **Swing with no agency.** Variance the player didn't choose (a coin-flip boss, an
+  unblockable spike) reads as unfair, not thrilling. FUN.md §11: an incoming spike
+  must be *blockable in principle*, or it's a coin flip, not a decision.
+- **One choice ends the game.** A single decision with an unbounded downside is a
+  trap, not a risk. Reigns caps single-choice effects (|Δ| ≤ 20) so stewardship,
+  not one swipe, is the game.
+- **Risk with no signposting.** A gamble whose odds and stakes the player can't read
+  isn't a decision, it's a blind draw — the tension needs the number *shown*
+  ([[pattern-readability]]). Elected risk requires *informed* consent.
+
+## Verify / feel-gate link
+
+Risk/reward is provable as a **skill-delta with bounded stakes**:
+
+- **Judgement beats recklessness.** The Reigns proof (FUN.md §21): a balanced
+  policy survives, always-push loses — assert `judgementScore ≫ recklessScore`
+  (19/20 vs 0/20). If reckless play competes, the risk has no teeth.
+- **Bounded double-edge.** The content lint for two-sided choices — every effect
+  `|Δ| ≤ 20`, no no-op choices, every needs-flag settable (FUN.md §21). A choice
+  that's all upside is a lint failure.
+- **Blockable-in-principle.** For combat variance, assert the worst incoming ≤ the
+  player's answer ceiling (FUN.md §11) — the difference between a hard choice and a
+  coin flip.
+
+## Worked micro-example
+
+*"A deckbuilder reward screen where the choice actually hurts."* The naive screen
+offers three cards, pick one — but the strong card is *strictly* strong, so it's a
+no-brainer, not a choice. Add teeth three ways: (1) the strong card carries a
+**double edge** (it bloats your draw or damages you); (2) a **skip-for-tempo**
+option (take nothing, keep the deck lean); (3) **information** — telegraph the next
+elite so the player weighs power-now against consistency-later
+([[pattern-readability]]). Now every reward is a *decision*. Prove it: the greedy
+pilot lands in the win-rate window, and a never-skip / always-grab pilot drops out
+of it — the cost was real (FUN.md §11).
+
+## Composes with
+
+- [[pattern-feedback-loops]] — whether to *bank* a lead or *compound* it is a
+  push-your-luck decision riding on the loop's gain.
+- [[system-reward-schedules]] — variable-ratio payoffs are risk/reward with the
+  odds set by the drop table; keep them ethical, not exploitative.
+- [[system-build-diversity]] — double-edged upgrades are what make many builds
+  viable; a strictly-best upgrade collapses the build space.
+- [[pattern-pacing-and-tension]] — push-your-luck is a self-building tension curve.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §21 (Reigns) & §11 (deckbuilder blockability) —
+  the two proofs that risk has teeth *and* is fair.
+- [[anchor-reigns]] · [[anchor-balatro]] — the double-edged-choice and
+  push-your-luck fantasies as whole games.
+- [[anchor-slay-the-spire]] — the draft-of-3-with-a-skip is risk/reward as a whole
+  reward economy; the skip is the double edge made a first-class option.

package/design/CONTRIBUTING.md

@@ -0,0 +1,183 @@
+# Authoring the Codex
+
+How to write and extend Codex modules so 100+ files by many authors read as one
+library. Read this + [`_TEMPLATE.md`](_TEMPLATE.md) before writing a module.
+
+## The contract (non-negotiable)
+
+1. **Voice** = [`docs/FUN.md`](../docs/FUN.md): terse, imperative, second-person,
+   proof-aware. No throat-clearing. Bold the load-bearing noun, not sentences.
+2. **Length** 120–260 lines. Tables and tight bullets over paragraphs.
+3. **Frontmatter** exactly per `_TEMPLATE.md`. `id`, `title`, `kind`, `tags`,
+   `summary`, `use-when` are **required**. IDs are STABLE and match the inventory
+   below.
+4. **Never invent a Hayao API.** Cite only names that exist in
+   [`docs/API.md`](../docs/API.md) (grep first). Prefer pointing to the
+   `sandboxes/<x>-lab` or `examples/<slug>` that already wires it over pasting code.
+5. **Design here, prove there.** Do not restate FUN.md's mechanical truths or
+   verify recipes — set `verify-with` and link them inline. The Codex is the
+   *generative* half; FUN/JUICE/JUDGE are the *verification* half.
+6. **Cross-link** with `[[module-id]]` (from the inventory) and `composes-with`.
+   Link forward freely — a `[[id]]` for a not-yet-written module is a valid TODO.
+7. **One file per Write.** Small modules, written as drafted.
+
+## Body skeletons by kind
+
+- **process** → *The step* · *Inputs → outputs* · *How to run it* (numbered) ·
+  *Worked example* (a real intent taken through it) · *Traps*.
+- **anchor** → *Design DNA* (the compressed essence) · *Load-bearing structures*
+  (what actually makes it work — table) · *What to steal* · *What's just theme*
+  (drop it) · *Composes into* (which genres/systems it feeds).
+- **genre** → *Pillars* (exactly 3) · *The loop stack* (moment/encounter/session/
+  meta) · *Essential systems* (link `system-*`) · *Content & difficulty model* ·
+  *Signature-mechanic seeds* (3–5 twist ideas) · *Common pitfalls* · *Anchors* ·
+  *Verify* (link the matching FUN.md genre section).
+- **system** → *What it is* · *When to use / when NOT* · *Variants* (table) ·
+  *Tuning levers* · *How it wires to Hayao* (real primitives / sandbox pointer) ·
+  *Fails when…* · *Verify*.
+- **worldbuilding** → *The kit* · *Vectors/options* · *Method* (numbered) ·
+  *Aesthetic hook* (Kentō palette / JUDGE) · *Traps*.
+- **pattern** → *The principle* · *Why it works* · *Levers* · *Applied across
+  genres* (table) · *Overdone when…* · *Verify/feel-gate link*.
+
+## Every anchor & genre must name a twist seam
+
+The whole point is composition + a bend. Anchor and genre modules must include at
+least 2–3 concrete *signature-mechanic seeds* or *twist* ideas in the
+[[process-the-twist]] vocabulary (theme / mechanic-swap / structure / perspective
+/ constraint / tonal), each phrased as "X but Y". Show the reader where to bend.
+
+---
+
+## Master inventory
+
+Filenames are relative to the section dir. IDs are final — link to them freely.
+
+### 00-process/ — `process-*`
+| id | file | scope |
+|---|---|---|
+| process-intent-to-brief | intent-to-brief.md | Parse a high-level request into a design brief: fantasy, one-line hook, scope, hard constraints |
+| process-pillars | pillars.md | Derive exactly 3 design pillars; use them as the decision filter for every later choice |
+| process-core-loop | core-loop.md | The loop stack — moment / encounter / session / meta; the verb→challenge→feedback→reward→growth cycle |
+| process-the-twist | the-twist.md | The "X but Y" composition formula; the six twist vectors; worked examples (Unrailed, Fertile Crescent, Shadow of War) |
+| process-composition | composition.md | Combining anchors + genre + systems into one coherent whole; genre-blend rules (satisfy every parent) |
+| process-refine-and-handoff | refine-and-handoff.md | Turn the design into a verification contract; the definition of "designed enough to build"; handoff to FUN/JUICE/JUDGE |
+
+### 10-anchors/ — `anchor-*` (also write README.md)
+| id | file | scope |
+|---|---|---|
+| anchor-celeste | celeste.md | Precision platformer + assist-mode humaneness; grace as system |
+| anchor-hades | hades.md | Action roguelite whose meta-progression IS the narrative; death as content |
+| anchor-vampire-survivors | vampire-survivors.md | Minimal-input horde survival; build-growth vs rising tide; the auto-attack fantasy |
+| anchor-dead-cells | dead-cells.md | Metroidvania × roguelite; permanent unlocks over impermanent runs |
+| anchor-slay-the-spire | slay-the-spire.md | Roguelike deckbuilder; draft-of-3, map choice, deck as evolving strategy |
+| anchor-into-the-breach | into-the-breach.md | Perfect-information tactics; rewriting a telegraphed future |
+| anchor-balatro | balatro.md | Score-multiplier deckbuilder; the joker-synergy "number goes up" juice |
+| anchor-tetris | tetris.md | Pure endless mastery; the perfectly-tuned single verb |
+| anchor-peggle | peggle.md | Physics arcade + variable-ratio reward + maximal juice on trivial input |
+| anchor-baba-is-you | baba-is-you.md | Rule-manipulation puzzle; the mechanic IS the content |
+| anchor-nuclear-throne | nuclear-throne.md | Arcade twin-stick roguelite; run-based tight-loop mastery |
+| anchor-loop-hero | loop-hero.md | Placement + auto-combat + deck; composing three genres into one novel loop |
+| anchor-age-of-empires | age-of-empires.md | RTS eco/tech ramp; age-up power spikes; build orders |
+| anchor-starcraft | starcraft.md | RTS faction asymmetry done right; three rosters, one balance |
+| anchor-factorio | factorio.md | Automation/logistics; the factory as the toy; scaling complexity |
+| anchor-rimworld | rimworld.md | Colony sim as a story generator; an AI director authoring drama |
+| anchor-stardew-valley | stardew-valley.md | Gentle life sim; open-ended goals; the calm compulsion loop |
+| anchor-civilization | civilization.md | 4X "one more turn"; layered systems; snowball vs comeback |
+| anchor-overcooked | overcooked.md | Couch-coop chaos; communication-forced-by-design; escalating kitchens |
+| anchor-it-takes-two | it-takes-two.md | Asymmetric coop set-pieces; a new mechanic per chapter; interdependence |
+| anchor-shadow-of-mordor | shadow-of-mordor.md | The nemesis system; emergent personalized rivals; systemic memory |
+| anchor-reigns | reigns.md | Swipe-choice narrative; meters between two ditches; stewardship |
+| anchor-outer-wilds | outer-wilds.md | Knowledge as the only progression; a curiosity-gated open world |
+| anchor-return-of-the-obra-dinn | return-of-the-obra-dinn.md | Deduction as the core loop; the game trusts your reasoning |
+
+### 20-genres/ — `genre-*` (also write README.md)
+| id | file | scope (deep CREATIVE template; verify links to FUN.md) |
+|---|---|---|
+| genre-grid-puzzle | grid-puzzle.md | Sokoban-like; the solvable knot (FUN.md §1) |
+| genre-precision-platformer | precision-platformer.md | Celeste-like; trust in inputs (FUN.md §2) |
+| genre-metroidvania | metroidvania.md | The locked-door promise (FUN.md §3) |
+| genre-action-adventure | action-adventure.md | Top-down Zelda-like; readable combat (FUN.md §4) |
+| genre-stealth | stealth.md | Plannable danger (FUN.md §5) |
+| genre-horde-survival | horde-survival.md | Twin-stick survivors; rising tide vs build (FUN.md §6) |
+| genre-bullet-hell | bullet-hell.md | Density that reads (FUN.md §7) |
+| genre-tower-defense | tower-defense.md | Build decisions that matter (FUN.md §8) |
+| genre-rts | rts.md | Mass under command; asymmetry (FUN.md §9) |
+| genre-roguelike | roguelike.md | Fair discovery; procgen connectivity (FUN.md §10) |
+| genre-deckbuilder | deckbuilder.md | Drafts with teeth (FUN.md §11) |
+| genre-tactics | tactics.md | Rewriting the telegraphed future (FUN.md §12) |
+| genre-match3 | match3.md | Cascades you triggered (FUN.md §13) |
+| genre-incremental | incremental.md | Pacing curve with no deserts (FUN.md §14) |
+| genre-farming-sim | farming-sim.md | Gentle solvency (FUN.md §15) |
+| genre-survival-horror | survival-horror.md | Dread you can budget (FUN.md §16) |
+| genre-city-builder | city-builder.md | The exposed score; negative synergies (FUN.md §17) |
+| genre-rhythm | rhythm.md | Tight but fair; beat is sim time (FUN.md §18) |
+| genre-physics-arcade | physics-arcade.md | Trustworthy flight (FUN.md §19) |
+| genre-racing | racing.md | Speed/line tradeoff (FUN.md §20) |
+| genre-narrative-decisions | narrative-decisions.md | Impossible stewardship (FUN.md §21) |
+| genre-coop-chaos | coop-chaos.md | EXTENSION beyond FUN.md's 21: couch-coop/party; communication under time pressure |
+| genre-auto-battler | auto-battler.md | EXTENSION: prep-then-watch; economy + positioning + synergy |
+| genre-exploration | exploration.md | EXTENSION: discovery/immersive-sim-lite; curiosity & knowledge as reward |
+
+### 30-systems/ — `system-*` (also write README.md)
+| id | file | scope |
+|---|---|---|
+| system-progression | progression.md | XP / levels / the power curve; pacing power gain |
+| system-skill-trees | skill-trees.md | Branching unlocks; builds; meaningful exclusivity |
+| system-meta-progression | meta-progression.md | Roguelite persistent unlocks between runs; power vs. options |
+| system-mastery-curve | mastery-curve.md | Learnable depth; skill ceiling; the "easy to learn, hard to master" mechanism |
+| system-economy | economy.md | Faucets & sinks; currencies; inflation control |
+| system-resource-loops | resource-loops.md | Gather→convert→spend cycles; bottlenecks as pacing |
+| system-crafting | crafting.md | Recipes; combinatorial depth; discovery vs. lookup |
+| system-tech-tree | tech-tree.md | Research gating; branch exclusivity; the ramp of options |
+| system-reward-schedules | reward-schedules.md | Variable-ratio drops, chests, loot; ethical compulsion |
+| system-collectibles | collectibles.md | Sets, completion, cosmetics; optional goals with pull |
+| system-combat-model | combat-model.md | Damage, resolution, timing; the shape of a hit |
+| system-telegraphs | telegraphs.md | Tells, windups, readable threat; reaction windows |
+| system-status-effects | status-effects.md | DoT/buffs/debuffs; stacking rules; build interaction |
+| system-counter-systems | counter-systems.md | Rock-paper-scissors; near-hard counters; the duel matrix |
+| system-faction-asymmetry | faction-asymmetry.md | Asymmetric identities that balance; the design of "different but fair" |
+| system-unit-rosters | unit-rosters.md | Unit roles, tiers, and diversity; a legible roster |
+| system-boss-design | boss-design.md | Phases, telegraphs, spectacle; the set-piece fight |
+| system-build-diversity | build-diversity.md | Weapons/loadouts/synergies; making many viable strategies |
+| system-grace | grace.md | Coyote/i-frames/buffer/mercy as a SYSTEM (concrete; FUN.md law 5) |
+| system-enemy-ai | enemy-ai.md | Behavior, aggro/threat, steering; readable, beatable minds |
+| system-enemy-archetypes | enemy-archetypes.md | Roles: tank/skirmisher/artillery/swarm/support; the enemy alphabet |
+| system-encounter-design | encounter-design.md | Composing archetypes into fights; pressure & pockets |
+| system-difficulty-and-dda | difficulty-and-dda.md | Difficulty curves, spikes/breathers, dynamic difficulty, assist |
+| system-onboarding | onboarding.md | Tutorialization; teach-by-doing; the first ten minutes |
+| system-accessibility | accessibility.md | Assist modes, remap, colour/contrast, readability floors |
+| system-procgen-design | procgen-design.md | Runs, seeds, variance as content; controlled randomness |
+| system-session-structure | session-structure.md | Run / campaign / level / world; session length & shape |
+| system-save-and-checkpoint | save-and-checkpoint.md | Save, checkpoint, retry; respecting the player's time |
+| system-emergent-systems | emergent-systems.md | Nemesis-style memory, relationships, reputation; systemic story |
+| system-coop-and-competition | coop-and-competition.md | Coop/PvP hooks; asymmetric coop; interdependence & rivalry |
+
+### 40-worldbuilding/ — `world-*` (also write README.md)
+| id | file | scope |
+|---|---|---|
+| world-theme-vectors | theme-vectors.md | Choosing a setting/theme space; theme as a twist vector |
+| world-worldbuilding-scaffold | worldbuilding-scaffold.md | From a setting to a coherent world with rules & stakes |
+| world-faction-identity | faction-identity.md | Making factions feel distinct in fiction (pairs with system-faction-asymmetry) |
+| world-naming-and-tone | naming-and-tone.md | Names, voice, register; the Kentō house restraint |
+| world-aesthetic-direction | aesthetic-direction.md | Art direction; the Kentō woodblock palette; JUDGE hook |
+| world-narrative-delivery | narrative-delivery.md | Environmental / systemic / embedded storytelling with little text |
+
+### 50-patterns/ — `pattern-*` (also write README.md)
+| id | file | scope |
+|---|---|---|
+| pattern-feedback-loops | feedback-loops.md | Positive/negative loops; runaway control; snowball vs. comeback |
+| pattern-risk-reward | risk-reward.md | Push-your-luck; decisions with teeth; double-edged choices |
+| pattern-mastery-and-flow | mastery-and-flow.md | The flow channel; matching challenge to skill |
+| pattern-emergence | emergence.md | Second-order design; interacting rules; depth from few pieces |
+| pattern-anti-frustration | anti-frustration.md | Forgiveness, respecting time; the grace mindset (pairs with system-grace) |
+| pattern-juice-choreography | juice-choreography.md | Feel as choreography; the 2-senses contract (pairs with JUICE.md) |
+| pattern-readability | readability.md | Signposting, salience, affordances (pairs with JUDGE.md) |
+| pattern-pacing-and-tension | pacing-and-tension.md | Peaks & valleys; session rhythm; the tension curve |
+
+---
+
+## The index is generated
+
+Do **not** hand-edit `INDEX.md` or `index.json` — they are built from module
+frontmatter by `scripts/build-design-index.mjs`. Just write correct frontmatter.

package/design/INDEX.md

@@ -0,0 +1,133 @@
+# Codex Index
+
+Generated by `scripts/build-design-index.mjs` from module frontmatter — do not hand-edit.
+98 modules. Search by keyword here, or `grep -ri <term> design/`.
+
+## process — `00-process/` (6)
+
+| id | title | tags | summary |
+|---|---|---|---|
+| [process-composition](00-process/composition.md) | Composition — Assembling the Design | composition, genre-blend, systems, assembly, coherence, parent-genres, checklist | Assemble a design from anchor + genre template + the systems it implies; blend genres by satisfying every parent's verify pattern. |
+| [process-core-loop](00-process/core-loop.md) | The Core Loop Stack | core-loop, gameplay-loop, verb, feedback, reward, progression, pacing, engagement | Design the nested loop stack — moment / encounter / session / meta — and the verb→challenge→feedback→reward→growth cycle inside each layer. |
+| [process-intent-to-brief](00-process/intent-to-brief.md) | Intent → Brief | intent, brief, scope, fantasy, hook, constraints, requirements, parse | Parse a vague request into a one-page brief — player fantasy, one-line hook, scope, hard constraints, target session length. |
+| [process-pillars](00-process/pillars.md) | The Three Pillars | pillars, vision, decision-filter, scope-guard, priorities, focus, scoring | Derive exactly three design pillars — evocative but testable — and use them as the scoring function for every later choice, including the twist. |
+| [process-refine-and-handoff](00-process/refine-and-handoff.md) | Refine & Handoff — The Verification Contract | handoff, verification-contract, done, spec, proof, seam, checklist, assertions | 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. |
+| [process-the-twist](00-process/the-twist.md) | The Twist — "X but Y" | twist, composition, creativity, hook, differentiation, novelty, remix | 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. |
+
+## anchor — `10-anchors/` (24)
+
+| id | title | tags | summary |
+|---|---|---|---|
+| [anchor-age-of-empires](10-anchors/age-of-empires.md) | Age of Empires | rts, economy, tech-tree, build-order, power-spike, ramp, macro | 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. |
+| [anchor-baba-is-you](10-anchors/baba-is-you.md) | Baba Is You | puzzle, rule-manipulation, self-reference, sokoban, systemic, emergence, grid | 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. |
+| [anchor-balatro](10-anchors/balatro.md) | Balatro | deckbuilder, score-multiplier, joker, synergy, poker, escalation, juice | A score-multiplier deckbuilder where poker hands feed a chips×mult engine and stacked jokers make the number explode — the fantasy is watching it go up. |
+| [anchor-celeste](10-anchors/celeste.md) | Celeste | platformer, precision, grace, assist-mode, mastery, humane, momentum | Precision platformer where brutal difficulty and total forgiveness coexist — grace is a system, assist mode makes the mountain optional not easy. |
+| [anchor-civilization](10-anchors/civilization.md) | Civilization | 4x, turn-based, strategy, snowball, comeback, tech-tree, one-more-turn | The 4X "one more turn" engine — many shallow-per-turn systems layered into a deep whole, with victory paths and a snowball you must brake for comebacks. |
+| [anchor-dead-cells](10-anchors/dead-cells.md) | Dead Cells | metroidvania, roguelite, permanence, run-based, combat, unlock-pool, biome-branch | Metroidvania fused with roguelite — runs are impermanent, but permanent unlocks fold discoveries into the pool, so the world persists even when the run doesn't. |
+| [anchor-factorio](10-anchors/factorio.md) | Factorio | automation, logistics, factory, throughput, optimization, scaling, engineering | Automation/logistics sim where the factory itself is the toy — you build the machine that builds, and the fun is untangling throughput bottlenecks that scale forever. |
+| [anchor-hades](10-anchors/hades.md) | Hades | roguelite, meta-progression, narrative, death, build-diversity, boons, run-based | Action roguelite where dying is the delivery mechanism for story and power — meta-progression is narrative, so losing is content, not punishment. |
+| [anchor-into-the-breach](10-anchors/into-the-breach.md) | Into the Breach | tactics, perfect-information, telegraph, turn-based, puzzle, positioning, grid | Perfect-information tactics — every enemy move is shown before it happens, and the game is the puzzle of rewriting that telegraphed future in one turn. |
+| [anchor-it-takes-two](10-anchors/it-takes-two.md) | It Takes Two | coop, asymmetric, set-piece, interdependence, mechanic-per-chapter, two-player | Asymmetric two-player coop as a parade of set-pieces — a fresh interlocking mechanic every chapter, each requiring both players' different verbs at once. |
+| [anchor-loop-hero](10-anchors/loop-hero.md) | Loop Hero | genre-fusion, placement, auto-combat, deckbuilder, roguelite, novel-loop, indirect-control | Three genres fused into one loop — you place tiles from a deck around a fixed track, an auto-battling hero walks it, and the terrain you build both feeds and threatens you. |
+| [anchor-nuclear-throne](10-anchors/nuclear-throne.md) | Nuclear Throne | twin-stick, roguelite, arcade, tight-loop, permadeath, mutation, execution | Twin-stick arcade roguelite built for the tight loop — fast lethal runs, mutation drafts on level-up, and a skill ceiling that lives in your hands. |
+| [anchor-outer-wilds](10-anchors/outer-wilds.md) | Outer Wilds | exploration, knowledge, curiosity, open-world, time-loop, discovery, non-linear | Knowledge is the only progression — no upgrades gate the world, only what *you* understand; a curiosity-driven open world you unlock in your own head. |
+| [anchor-overcooked](10-anchors/overcooked.md) | Overcooked | coop, chaos, party, communication, time-pressure, kitchen, escalation | Couch-coop chaos where the design *forces* communication — a shared task under a clock, split across players so no one can solo it, escalating each level. |
+| [anchor-peggle](10-anchors/peggle.md) | Peggle | physics-arcade, variable-ratio, juice, reward-schedule, aim, one-input, spectacle | Aim, drop a ball, watch physics scatter it through pegs — trivial input wrapped in variable-ratio payoffs and maximal celebration juice. |
+| [anchor-reigns](10-anchors/reigns.md) | Reigns | narrative, choice, swipe, meters, stewardship, cards, decisions | Swipe-choice narrative — binary decisions nudge four meters you must keep between two ditches, so ruling is an act of doomed balance, not victory. |
+| [anchor-return-of-the-obra-dinn](10-anchors/return-of-the-obra-dinn.md) | Return of the Obra Dinn | deduction, mystery, logic, reasoning, verification, non-linear, knowledge | Deduction as the core loop — the game gives you evidence and *trusts your reasoning*, confirming answers only when you've triangulated a solvable set. |
+| [anchor-rimworld](10-anchors/rimworld.md) | RimWorld | colony-sim, story-generator, ai-director, emergent, drama, pacing, simulation | A colony sim built as a story generator — an AI director paces crises against your state so the *narrative*, not a win screen, is the product. |
+| [anchor-shadow-of-mordor](10-anchors/shadow-of-mordor.md) | Shadow of Mordor | nemesis, emergent, systemic-memory, rivalry, procedural-narrative, personalization | The nemesis system — a systemic hierarchy of enemies that remember you, rise from your failures, and become personalized rivals no writer scripted. |
+| [anchor-slay-the-spire](10-anchors/slay-the-spire.md) | Slay the Spire | deckbuilder, roguelike, draft, map-choice, synergy, deck-thinning, run-based | The roguelike deckbuilder — every card is a draft-of-3-or-skip, every fight thins or thickens your deck, and the map is a route of risk you choose in advance. |
+| [anchor-starcraft](10-anchors/starcraft.md) | StarCraft | rts, asymmetry, faction, balance, macro, micro, matchup | The gold standard of RTS faction asymmetry — three rosters that share almost no units yet balance across every matchup because each expresses one clear identity. |
+| [anchor-stardew-valley](10-anchors/stardew-valley.md) | Stardew Valley | life-sim, farming, cozy, open-ended, compulsion-loop, calendar, progression | Gentle life sim whose pull is a calm compulsion loop — open-ended goals, a daily rhythm, and "one more day" pacing that never punishes. |
+| [anchor-tetris](10-anchors/tetris.md) | Tetris | endless, mastery, single-verb, falling-block, tuning, flow, difficulty-ramp | The perfectly-tuned single verb — place falling tetrominoes to clear lines, forever, with a difficulty that rises with your own success. |
+| [anchor-vampire-survivors](10-anchors/vampire-survivors.md) | Vampire Survivors | horde-survival, auto-attack, build-growth, rising-tide, minimal-input, power-fantasy | One-stick horde survival where you only move — weapons fire themselves — and the whole game is your multiplying build racing an escalating swarm. |
+
+## genre — `20-genres/` (24)
+
+| id | title | tags | summary |
+|---|---|---|---|
+| [genre-action-adventure](20-genres/action-adventure.md) | Top-down Action-Adventure (Zelda-like) | action-adventure, zelda, top-down, combat, telegraph, dungeon, readable | Readable combat and gated dungeons — enemies that tell you what they'll do, a hit that feels like it landed, and keys that turn the map into a lock. |
+| [genre-auto-battler](20-genres/auto-battler.md) | Auto-Battler | auto-battler, autochess, prep-then-watch, economy, synergy, positioning, rounds, shared-pool | Prep-then-watch — spend an economy on units, position and synergise them, then watch the round resolve itself. |
+| [genre-bullet-hell](20-genres/bullet-hell.md) | Bullet Hell | bullet-hell, shmup, danmaku, patterns, dodging, boss, density | Screen-filling patterns that read as motion, not noise — dodging is trivial, holding fire lanes under a boss is the skill. |
+| [genre-city-builder](20-genres/city-builder.md) | City / Colony Builder | city-builder, colony, placement, adjacency, synergy, score, zoning, optimization | Placement-optimization builder where the exposed live score under the cursor IS the UI, and negative synergies make the only real decisions. |
+| [genre-coop-chaos](20-genres/coop-chaos.md) | Coop Chaos | coop, couch-coop, party, overcooked, communication, chaos, shared-task, local-multiplayer | Couch-coop chaos — escalating shared tasks that force communication under time pressure; the friction between players IS the fun. |
+| [genre-deckbuilder](20-genres/deckbuilder.md) | Roguelike Deckbuilder | deckbuilder, cards, draft, synergy, roguelike, build, win-rate | Drafts with teeth — a deck that evolves run-to-run, where the draft delta is provable and every spike is blockable in principle. |
+| [genre-exploration](20-genres/exploration.md) | Exploration | exploration, discovery, immersive-sim, outer-wilds, obra-dinn, curiosity, knowledge, deduction | Discovery as the reward — knowledge is the only progression; curiosity gates the world and understanding is the win. |
+| [genre-farming-sim](20-genres/farming-sim.md) | Farming / Life Sim | farming, life-sim, calendar, crops, seasons, cozy, solvency, routine | Calm calendar-driven life sim where the fun is gentle solvency — plans made on a season that can actually come true. |
+| [genre-grid-puzzle](20-genres/grid-puzzle.md) | Grid Puzzle (Sokoban-like) | puzzle, sokoban, grid, solver, deterministic, turn-based, knot | The solvable knot — a grid of pieces where the obvious move is a trap and the real line is a small proof you feel yourself find. |
+| [genre-horde-survival](20-genres/horde-survival.md) | Twin-stick Horde Survival (Vampire Survivors-like) | horde, survivors, twin-stick, auto-attack, build, wave, roguelite, orbit | The rising tide vs your rising build — minimal input, auto-attacks, and a level-up draft that races a superlinear swarm you must out-scale. |
+| [genre-incremental](20-genres/incremental.md) | Incremental / Idle | incremental, idle, clicker, prestige, economy, pacing, payback, ramp | Number-goes-up economy where the design IS the pacing curve — first-buy times and era gaps tuned so there are no deserts. |
+| [genre-match3](20-genres/match3.md) | Match-3 | match3, cascade, tile-swap, puzzle, board, combo, casual, choreography | Swap-adjacent tile matcher where the fun is the cascade you triggered — one swap, a chain reaction the board runs for you. |
+| [genre-metroidvania](20-genres/metroidvania.md) | Metroidvania | metroidvania, exploration, gating, ability, map, backtrack, locked-door | The locked-door promise kept — a single connected world where every ability you earn retroactively unlocks a place you already saw and couldn't reach. |
+| [genre-narrative-decisions](20-genres/narrative-decisions.md) | Narrative Decisions | narrative, decisions, reigns, swipe, meters, stewardship, choice, cards | Impossible stewardship — every choice double-edged, meters balanced between two ditches; judgement beats any fixed policy. |
+| [genre-physics-arcade](20-genres/physics-arcade.md) | Physics Arcade | physics, arcade, breakout, peggle, pinball, bounce, aim, swept-collision | Trustworthy flight — aim, launch, watch a ball obey clean physics; maximal juice on one trivial input. |
+| [genre-precision-platformer](20-genres/precision-platformer.md) | Precision Platformer (Celeste-like) | platformer, precision, celeste, movement, grace, dash, coyote, feel | Trust in inputs — a movement envelope so honest that every death is the player's own, and the retry is instant enough to make failure fuel. |
+| [genre-racing](20-genres/racing.md) | Racing | racing, driving, top-down, understeer, braking, line, checkpoint, laps | The speed/line tradeoff made physical — brake to hold the line or floor it and drift wide; the racing line is the skill. |
+| [genre-rhythm](20-genres/rhythm.md) | Rhythm | rhythm, beat, timing, window, bpm, frame-exact, music, tempo | Beat-locked timing game where the beat IS sim time and fairness is three frame-exact assertions — tight but fair. |
+| [genre-roguelike](20-genres/roguelike.md) | Roguelike | roguelike, procgen, permadeath, runs, connectivity, discovery, turn-based | Fair discovery through procedural dungeons that always connect and turns that always replay — variance as content, not chaos. |
+| [genre-rts](20-genres/rts.md) | Real-Time Strategy | rts, strategy, factions, asymmetry, macro, micro, pathfinding, spectacle | Mass under command — hundreds of wall-aware units, three asymmetric-but-fair factions, and battles that read as spectacle. |
+| [genre-stealth](20-genres/stealth.md) | Stealth | stealth, vision-cone, patrol, noise, plan, heist, guard, route | Plannable danger — vision cones and noise you can read, so the tension is the gap between a route you can see and a route you can execute. |
+| [genre-survival-horror](20-genres/survival-horror.md) | Survival Horror | survival-horror, dread, resource, fuel, light, darkness, tension, scarcity | Scarcity-driven dread where difficulty lives in resource arithmetic — dread you can budget, not monster stats you can't. |
+| [genre-tactics](20-genres/tactics.md) | Turn-Based Tactics | tactics, turn-based, grid, telegraphs, perfect-information, puzzle, positioning | Rewriting a telegraphed future — perfect information, honest tells stored as directions, and every fight a solvable positioning puzzle. |
+| [genre-tower-defense](20-genres/tower-defense.md) | Tower Defense | tower-defense, td, waves, towers, counters, lanes, build-order | Build decisions that matter — near-hard counters, range-ring geometry, and wave curves that breathe. |
+
+## system — `30-systems/` (30)
+
+| id | title | tags | summary |
+|---|---|---|---|
+| [system-accessibility](30-systems/accessibility.md) | Accessibility | accessibility, assist, remap, colorblind, contrast, readability, a11y, salience | Assist modes, input remap, and colour/contrast that clear a readability floor — more players reach the game, none are shamed for it. |
+| [system-boss-design](30-systems/boss-design.md) | Boss Design — the set-piece fight | boss, phases, telegraph, spectacle, set-piece, mercy, encounter | The multi-phase set-piece — a fight that teaches, escalates, and telegraphs, with mercy on every phase transition so a death is fair, not cheap. |
+| [system-build-diversity](30-systems/build-diversity.md) | Build Diversity — many viable strategies | builds, loadouts, synergy, diversity, dominant-strategy, viability, balance | Many strategies that all win — weapons, loadouts, and synergies tuned so the fun is choosing a build, not solving for the one correct build. |
+| [system-collectibles](30-systems/collectibles.md) | Collectibles — Sets, Completion & Optional Pull | collectibles, sets, completion, cosmetics, optional-goals, 100-percent, checklist | Optional goals that pull without shoving — sets to complete, cosmetics to earn; the compulsion of the almost-full grid, kept honest. |
+| [system-combat-model](30-systems/combat-model.md) | Combat Model — the shape of a hit | combat, damage, resolution, timing, real-time, turn-based, hit | The spine every fight sits on — how damage is computed, when it resolves, and whether the clock is frames or turns. |
+| [system-coop-and-competition](30-systems/coop-and-competition.md) | Co-op & Competition | coop, pvp, competition, asymmetric, interdependence, rivalry, multiplayer, communication | Co-op and PvP hooks — asymmetric co-op, interdependence, and rivalry that make other players the most interesting system in the game. |
+| [system-counter-systems](30-systems/counter-systems.md) | Counter Systems — the duel matrix | counters, rock-paper-scissors, matchup, duel, near-hard, balance | Rock-paper-scissors with teeth — NEAR-HARD counters that stay decisive under scaling, so the answer to a threat is a choice, not a bigger number. |
+| [system-crafting](30-systems/crafting.md) | Crafting — Recipes & Combinatorial Depth | crafting, recipes, combination, discovery, lookup, depth, materials | Combining inputs into outputs by recipe; combinatorial depth as content, and the discovery-vs-lookup axis that decides how the player learns it. |
+| [system-difficulty-and-dda](30-systems/difficulty-and-dda.md) | Difficulty & Dynamic Difficulty | difficulty, dda, curve, spikes, breathers, ai-director, assist, ramp, pacing | Difficulty curves that breathe — spikes and breathers, an AI director that authors pressure, and assist modes that never shame. |
+| [system-economy](30-systems/economy.md) | Economy — Faucets, Sinks & the Pacing Window | economy, currency, faucets, sinks, inflation, balance, pacing, incremental | Currencies flowing in through faucets and out through sinks; keeping the two in tension so the player is always almost-able-to-afford the next thing. |
+| [system-emergent-systems](30-systems/emergent-systems.md) | Emergent Systems | emergence, nemesis, memory, relationships, reputation, systemic-story, story-generator, second-order | Nemesis-style memory, relationships, and reputation — systemic story generators where the game remembers you and interactions author drama. |
+| [system-encounter-design](30-systems/encounter-design.md) | Encounter Design | encounter, combat, pacing, pressure, safe-pocket, exit-lane, waves, composition | Composing archetypes into a fight — pressure and safe pockets, exit lanes, and a wave curve that breathes. |
+| [system-enemy-ai](30-systems/enemy-ai.md) | Enemy AI | ai, behavior, aggro, threat, steering, flow-field, pathfinding, kiting, telegraph | Readable, beatable enemy minds — aggro/threat, steering, and pathing that the player can predict, route around, and outplay. |
+| [system-enemy-archetypes](30-systems/enemy-archetypes.md) | Enemy Archetypes | enemy, archetypes, roles, tank, skirmisher, artillery, swarm, support, roster | The enemy alphabet — tank/skirmisher/artillery/swarm/support — a small set of roles that combine into fights bigger than their parts. |
+| [system-faction-asymmetry](30-systems/faction-asymmetry.md) | Faction Asymmetry — different but fair | factions, asymmetry, balance, rts, matchup, identity, starcraft | Asymmetric factions that play nothing alike yet balance — distinct rosters, economies, and win conditions held fair by cross-matchup duels, not mirrors. |
+| [system-grace](30-systems/grace.md) | Grace — forgiveness as a system | grace, coyote, iframes, input-buffer, mercy, undo, forgiveness, retry | Coyote time, i-frames, input buffering, mercy clears, and undo as one concrete system — the same shape at every timescale, each unit-testable. |
+| [system-mastery-curve](30-systems/mastery-curve.md) | Mastery Curve — Easy to Learn, Hard to Master | mastery, skill-ceiling, depth, learnability, flow, execution, expression | Learnable depth as a mechanism — a low skill floor and a high skill ceiling, with the gap between them full of discoverable technique. |
+| [system-meta-progression](30-systems/meta-progression.md) | Meta-Progression — Persistent Unlocks Between Runs | meta-progression, roguelite, unlocks, persistence, power-creep, always-earn, runs | The campaign under the runs — persistent unlocks that make a lost run still pay; the "always earn something" contract, and power-creep vs new options. |
+| [system-onboarding](30-systems/onboarding.md) | Onboarding | onboarding, tutorial, teach-by-doing, first-ten-minutes, hesitation, teaching, ramp | Tutorialization by doing — teach one verb at a time in a safe space, and read hesitation data to find where players actually stall. |
+| [system-procgen-design](30-systems/procgen-design.md) | Procedural Generation Design | procgen, seeds, runs, variance, connectivity, controlled-randomness, generation, replayability | Runs, seeds, and variance as content — controlled randomness that always connects, proven before you tune a single number. |
+| [system-progression](30-systems/progression.md) | Progression — XP, Levels, the Power Curve | progression, xp, levels, power-curve, pacing, growth, vertical, horizontal | Turning play into steadily-earned power; pacing the curve so growth never stalls and never trivialises the challenge it feeds. |
+| [system-resource-loops](30-systems/resource-loops.md) | Resource Loops — Gather → Convert → Spend | resource-loops, gather, convert, spend, bottleneck, production, pacing, chains | The gather→convert→spend cycle that structures effort; bottlenecks placed on purpose are the pacing, not a bug. |
+| [system-reward-schedules](30-systems/reward-schedules.md) | Reward Schedules — Drops, Chests & Ethical Compulsion | rewards, variable-ratio, loot, drops, chests, compulsion, dark-patterns, ethics | How often and how surprisingly the game pays out; variable-ratio's grip, and the honest line between compelling and exploitative. |
+| [system-save-and-checkpoint](30-systems/save-and-checkpoint.md) | Save & Checkpoint | save, checkpoint, retry, respect-time, snapshot, hash, round-trip, resume | Save, checkpoint, and retry that respect the player's time — built free on Hayao's pure-state snapshot/hash round-trip. |
+| [system-session-structure](30-systems/session-structure.md) | Session Structure | session, run, campaign, level, world, pacing, length, structure, container | The nesting of play — run / campaign / level / world — and how session length and shape set the game's rhythm and stakes. |
+| [system-skill-trees](30-systems/skill-trees.md) | Skill Trees — Branching Unlocks & Builds | skill-tree, builds, unlocks, branching, exclusivity, respec, specialization | Branching unlock graphs that turn flat power into a build; meaningful exclusivity is what makes the choice a choice, and respec is its grace. |
+| [system-status-effects](30-systems/status-effects.md) | Status Effects — damage and change over time | status, dot, buff, debuff, stacking, poison, burn, legibility | DoT, buffs, and debuffs as first-class state — with stacking rules that are legible, bounded, and interact with builds instead of just piling up. |
+| [system-tech-tree](30-systems/tech-tree.md) | Tech Tree — Research Gating & the Ramp of Options | tech-tree, research, gating, branch-exclusivity, strategy, unlocks, ramp | Research-gated unlocks at the strategy scale; branch exclusivity and a widening ramp of options that shape a whole playthrough's arc. |
+| [system-telegraphs](30-systems/telegraphs.md) | Telegraphs — readable threat | telegraph, tells, windup, readability, reaction, threat, combat | The wind-up that makes a threat readable — every hitbox announces itself long enough to react, and the tell is stored as a direction, not a guess. |
+| [system-unit-rosters](30-systems/unit-rosters.md) | Unit Rosters — a legible roster | units, roster, roles, tiers, diversity, rts, redundancy | A roster of units whose roles are legible and distinct — every unit earns its slot, overlap is intentional, and redundancy is culled. |
+
+## worldbuilding — `40-worldbuilding/` (6)
+
+| id | title | tags | summary |
+|---|---|---|---|
+| [world-aesthetic-direction](40-worldbuilding/aesthetic-direction.md) | Aesthetic Direction — briefing the Kentō woodblock look | art-direction, palette, kento, woodblock, readability, contrast, look, judge | Art direction — the Kentō woodblock palette and how to brief a look that passes the readability + JUDGE bars (findable avatar, depth, one-world colour). |
+| [world-faction-identity](40-worldbuilding/faction-identity.md) | Faction Identity — making sides feel distinct in fiction | faction, identity, silhouette, motif, colour, values, fiction, asymmetry | Making factions feel distinct in FICTION — silhouette, values, colour, motif; the fiction companion to system-faction-asymmetry's mechanical difference. |
+| [world-naming-and-tone](40-worldbuilding/naming-and-tone.md) | Naming & Tone — the Kentō house restraint | naming, tone, voice, register, restraint, copy, evocative, ux-text | Names, voice, and register — the Kentō house restraint of one-word evocative titles (lanternway, rootward, tarnholm, kintsugi) and text that trusts the player. |
+| [world-narrative-delivery](40-worldbuilding/narrative-delivery.md) | Narrative Delivery — story with little text | narrative, environmental, systemic, embedded, show-dont-tell, story, diegetic | Environmental / systemic / embedded storytelling with LITTLE text — show don't tell; let the systems author the story in a small deterministic game. |
+| [world-theme-vectors](40-worldbuilding/theme-vectors.md) | Theme Vectors — choosing a setting that recolours the mechanics | theme, setting, fiction, twist, recolour, fantasy, resonance | 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. |
+| [world-worldbuilding-scaffold](40-worldbuilding/worldbuilding-scaffold.md) | Worldbuilding Scaffold — the minimum viable world | lore, world, setting, stakes, fantasy, rules, coherence, scaffold | From a setting to a coherent world with rules, stakes, and a fantasy — the minimum viable lore a small deterministic game actually needs. |
+
+## pattern — `50-patterns/` (8)
+
+| id | title | tags | summary |
+|---|---|---|---|
+| [pattern-anti-frustration](50-patterns/anti-frustration.md) | Anti-Frustration | forgiveness, grace, anti-frustration, respect, retry, mercy, difficulty, humane | Punish mistakes without punishing the player — grace, instant retry, undo, and respecting time keep hard fair. |
+| [pattern-emergence](50-patterns/emergence.md) | Emergence | emergence, second-order, systemic, interaction, depth, combinatorics, rules, synergy | Depth from few pieces — design rules that interact, not content that stacks, so the game generates situations you never authored. |
+| [pattern-feedback-loops](50-patterns/feedback-loops.md) | Feedback Loops | feedback, snowball, comeback, runaway, balance, positive-loop, negative-loop, catch-up | Positive loops snowball, negative loops correct — design which one dominates so leads stay tense, not decided. |
+| [pattern-juice-choreography](50-patterns/juice-choreography.md) | Juice as Choreography | juice, feel, feedback, choreography, particles, shake, cosmetic, two-senses, game-feel | The sim resolves instantly and returns a choreography script; the view replays it — every event answers on ≥2 senses. |
+| [pattern-mastery-and-flow](50-patterns/mastery-and-flow.md) | Mastery & Flow | flow, mastery, challenge, skill, difficulty, engagement, learning-curve, skill-delta | Keep challenge riding just above current skill — the flow channel — and prove it with the skill-delta gap. |
+| [pattern-pacing-and-tension](50-patterns/pacing-and-tension.md) | Pacing & Tension | pacing, tension, rhythm, peaks, valleys, breather, session, curve, escalation | Tension is a curve, not a constant — alternate peaks and breathers so the finale reads as a peak, not another wave. |
+| [pattern-readability](50-patterns/readability.md) | Readability | readability, salience, signposting, affordance, contrast, clarity, legibility, ui | The player must instantly find the avatar, read the threat, and see the way — salience, signposting, and affordances. |
+| [pattern-risk-reward](50-patterns/risk-reward.md) | Risk / Reward | risk, reward, push-your-luck, tradeoff, double-edged, gambling, tension, choice | A choice with teeth — every reward priced in real risk, every option double-edged, so decisions cost something. |
+