hayao 0.4.1 → 0.4.2

package/design/30-systems/session-structure.md

@@ -0,0 +1,113 @@
+---
+id: system-session-structure
+title: Session Structure
+kind: system
+tags: [session, run, campaign, level, world, pacing, length, structure, container]
+summary: The nesting of play — run / campaign / level / world — and how session length and shape set the game's rhythm and stakes.
+use-when: You need to decide how long a sitting is, what a "run" contains, and how sessions nest into a longer arc.
+composes-with: [system-procgen-design, system-meta-progression, system-save-and-checkpoint, pattern-pacing-and-tension]
+anchors: [anchor-hades, anchor-slay-the-spire]
+verify-with: docs/FUN.md#14-incrementalidle
+---
+
+# Session Structure
+
+**What it is.** The **containers** play nests into — a *moment*, a *level* or
+*encounter*, a *run* or *session*, and the *meta* arc across them — and the
+**length and shape** of each. Session structure decides "how long is one sitting,
+what does it contain, and how do sittings add up?" A 3-minute Vampire Survivors
+push and a 40-turn Slay the Spire climb are the same genre-family with wildly
+different session shapes.
+
+**Player fantasy / why it's fun.** *A satisfying unit of time.* A good session has
+a clean arc — start, build, climax, resolution — that fits a real sitting and
+leaves a hook. The pull is closure-plus-appetite: "one more run" works because each
+run *finishes* something and *promises* something.
+
+## When to use / when NOT
+
+This is a **framing** system — every game has a session shape whether or not you
+design it. Reach for it explicitly when:
+
+| Design it deliberately when | It's near-trivial when |
+|---|---|
+| Runs/campaigns/roguelite structure is core | A single continuous level (endless arcade) |
+| You're deciding meta vs. per-run persistence | A one-sitting puzzle box |
+| Session length is a selling point (coffee-break vs. epic) | — |
+
+## The nesting
+
+| Tier | Span | Owns | Ends when |
+|---|---|---|---|
+| **Moment** | seconds | one verb → feedback | the input resolves ([[process-core-loop]]) |
+| **Encounter / level** | 1–5 min | one fight or room | cleared / failed |
+| **Run / session** | 5–60 min | a sequence of encounters + choices | win / death / objective |
+| **Meta / campaign** | many runs | persistent progress, unlocks, story | the long goal ([[system-meta-progression]]) |
+
+The two big shape decisions:
+
+| Decision | Options | Consequence |
+|---|---|---|
+| **Session length** | coffee-break (3–10 min) · sitting (20–60) · epic (hours) | sets stakes per run and save granularity |
+| **Persistence** | fully reset · roguelite carry-over · fully persistent | resets make death cheap; persistence makes it heavy |
+
+## Tuning levers
+
+| Lever | Effect | Watch for |
+|---|---|---|
+| **Run length** | stakes & commitment per session | too long = quitting mid-run loses progress; own it in [[system-save-and-checkpoint]] |
+| **Encounters per run** | the run's internal pacing arc | too few = no arc; too many = a slog |
+| **Meta gain per run** | how much a failed run still *earns* | zero = punishing; too much = trivial |
+| **Hook strength** | the pull into the next session | none = the loop doesn't restart |
+
+## How it wires to Hayao
+
+- **A run is a seed + a snapshot.** Because state is pure JSON in `world.state`
+  with `world.rng`, one run is fully described by `(seed, tuning, inputLog)` and
+  restorable from a snapshot — this is exactly the Studio session artifact
+  ([`docs/STUDIO.md`](../../docs/STUDIO.md), FUN.md law 7). Session structure and
+  the replay artifact are the *same* nesting.
+- **Runs are generated.** A roguelite run is a `generateLevels`/`generateDungeon`
+  sequence over a per-run seed ([[system-procgen-design]],
+  [`src/content/generate.ts`](../../src/content/generate.ts)) — the campaign that
+  ships is a list of seeds.
+- **Campaigns compose.** `composeCampaign(spec)` (grep `docs/API.md`,
+  [`src/content/campaign.ts`](../../src/content/campaign.ts)) assembles proven
+  levels into an ordered arc — the meta tier as data.
+- **Between-run persistence** is meta-progression saved across sessions
+  ([[system-meta-progression]], [[system-save-and-checkpoint]]).
+
+## Fails when…
+
+- **Length ≠ save granularity.** A 45-minute run with no checkpoint punishes anyone
+  who has to stop — respect the player's time ([[system-save-and-checkpoint]]).
+- **No arc per session.** A run with no build-and-climax is texture, not an
+  experience ([[pattern-pacing-and-tension]]).
+- **Failed runs earn nothing.** In roguelites, a death that advances *nothing*
+  feels like theft — grant meta or knowledge ([[anchor-hades]]).
+- **No hook.** A run that finishes and dead-ends stops the "one more" loop.
+- **Deserts in the meta.** Long stretches with no unlock or new goal
+  ([FUN.md §14](../../docs/FUN.md#14-incrementalidle) unlock-desert lint).
+
+## Verify
+
+- **The whole arc paces:** balance-sim the run/campaign; assert pacing windows and
+  **no unlock deserts** across the arc ([FUN.md §14](../../docs/FUN.md#14-incrementalidle)).
+- **A run is reproducible:** golden-hash a full scripted run; snapshot→restore→hash
+  round-trips (FUN.md law 7; [`docs/STUDIO.md`](../../docs/STUDIO.md)).
+- **Every level in the campaign is winnable:** solver proof per level via the
+  generator (FUN.md §10, [`src/content/generate.ts`](../../src/content/generate.ts)).
+
+## Composes with
+
+- [[system-procgen-design]] — a run's content is generated from its seed.
+- [[system-meta-progression]] — the tier that persists across sessions.
+- [[system-save-and-checkpoint]] — session length dictates save granularity.
+- [[pattern-pacing-and-tension]] — each session tier needs its own arc.
+- [[system-difficulty-and-dda]] — the curve spans a run and the campaign both.
+
+## See also
+
+- [`src/content/campaign.ts`](../../src/content/campaign.ts) — `composeCampaign` (the meta tier as data).
+- [`docs/STUDIO.md`](../../docs/STUDIO.md) — a session as a replayable artifact.
+- [[anchor-hades]] · [[anchor-slay-the-spire]] — the run as the fundamental unit.

package/design/30-systems/skill-trees.md

@@ -0,0 +1,111 @@
+---
+id: system-skill-trees
+title: Skill Trees — Branching Unlocks & Builds
+kind: system
+tags: [skill-tree, builds, unlocks, branching, exclusivity, respec, specialization]
+summary: Branching unlock graphs that turn flat power into a build; meaningful exclusivity is what makes the choice a choice, and respec is its grace.
+use-when: Progression should let the player CHOOSE a shape — a build, a specialization — not just accumulate the same power everyone gets.
+composes-with: [system-progression, system-build-diversity, system-tech-tree, system-economy, system-collectibles]
+anchors: [anchor-dead-cells, anchor-slay-the-spire]
+verify-with: docs/FUN.md#2-skill-delta-proofs
+---
+
+# Skill Trees — Branching Unlocks & Builds
+
+**What it is.** A **graph of unlocks** the player buys with a progression
+currency (points, cells, essence). The graph's *branches* — and the fact that you
+can't afford all of them — turn "get stronger" into "become a *kind* of strong."
+
+**Player fantasy / why it's fun.** "This build is *mine*." The tree is a canvas;
+the player paints a strategy and then gets to test it. The pull is the road not
+taken — every point spent is a small identity claim.
+
+## When to use / when NOT
+
+| Use it when | Skip it when |
+|---|---|
+| You want players to express strategy through pre-commitment | There's no meaningful choice — every node is strictly good |
+| Replay value comes from "try a different build" | One optimal path exists; the tree is a formality |
+| Power is horizontal ([[system-progression]]) and needs structure | A flat list of upgrades reads clearer (small games) |
+
+A tree with no **exclusivity** is just a shopping list. If the player will
+eventually own every node, the branches are decoration — either add scarcity
+(can't afford all) or opposition (this node locks that one).
+
+## Variants
+
+| Variant | Structure | The choice is | Example |
+|---|---|---|---|
+| **Prerequisite web** | Nodes gate deeper nodes | *Order & reach* | Path of Exile's lattice |
+| **Point-buy, no gates** | Flat pool, scarce points | *What to skip* | Classic RPG stat spend |
+| **Mutually-exclusive forks** | Pick A xor B at each fork | *Identity* | "Fire OR frost, never both" |
+| **Class/archetype trees** | Separate trees per role | *Which fantasy* | Diablo class trees |
+| **Draft-as-tree** | The run's picks form an implicit build | *Emergent shape* | Hades boons; StS deck |
+
+The **fork** variant carries the most meaning per node and the most respec
+pressure — see levers.
+
+## Tuning levers
+
+| Lever | What it controls | Healthy range / rule |
+|---|---|---|
+| **Point scarcity** | How much you must skip | You should afford ~40–70% of a tree per playthrough — enough to specialise, not complete |
+| **Branch exclusivity** | Whether a choice costs another | At least the *capstones* should be exclusive, or builds converge |
+| **Node granularity** | Fewer big nodes vs many small | Big nodes = legible builds; tiny nodes = fiddly filler |
+| **Capstones** | The payoff that defines a build | Each branch needs a "this is why you went here" node |
+| **Respec cost** | Reversibility | Free in experimental games; costed where commitment is the point |
+| **Gating depth** | Prereqs before the good stuff | Shallow — burying power behind 8 filler nodes reads as grind |
+
+**Respec is grace** (**[[FUN.md law 5]]**, the anti-frustration mindset). A tree
+the player is afraid to touch is a tree they don't engage with. Default to
+generous respec unless *permanent commitment* is an explicit pillar.
+
+## How it wires to Hayao
+
+- **The tree is data.** A node graph (id, cost, prereqs, effect) in `world.state`;
+  unlocking is an **input action** that spends a currency and flips a flag. The
+  effect is applied by pure logic reading owned-node flags — so a build is a
+  reproducible input sequence, and clone-and-score bots can *pilot* builds to
+  measure them (**[[FUN.md law 7]]**).
+- **Exclusivity is a solver constraint.** "Can't own A and B" is a rule the pure
+  logic enforces and a test asserts. Prove *every* branch is viable by piloting
+  each and asserting it beats a null build — the skill-delta proof
+  (**[[FUN.md law 2]]**), applied per branch, is your balance instrument for
+  [[system-build-diversity]].
+- **The tree UI is chrome.** Draw it with `showScreen()` (DOM menu) — it's not
+  sim, so it doesn't belong in `world.hash()`. Grep `docs/API.md`; per CLAUDE.md
+  invariant 4, menus are DOM.
+- **Persist unlocks** via `SaveManager` when the tree is meta
+  ([[system-meta-progression]]).
+
+## Fails when…
+
+- **A trap node.** A branch that's strictly worse wastes the player's one
+  irreversible choice — punishing, not deep. Prove each branch viable.
+- **A God node.** One branch dominates; everyone funnels to it and the tree
+  collapses to a line. The win-rate *window* per build catches this.
+- **No exclusivity.** Own-everything trees have no decisions. Add scarcity or forks.
+- **Filler gating.** Prereq chains of dead nodes to reach the good one — grind
+  wearing a tree costume.
+- **Respec you fear.** No respec + a trap node = a bricked character. Give an out.
+
+## Verify
+
+- Per-branch skill delta — each build beats a null build: **[[FUN.md law 2]]**.
+- Build viability as a win-rate *window*, both edges break CI:
+  **[[FUN.md §11]]** (deckbuilder's balance instrument).
+- Build as a reproducible pilot (clone-and-score): **[[FUN.md law 7]]**.
+
+## Composes with
+
+- [[system-progression]] — the tree spends what progression earns.
+- [[system-build-diversity]] — the tree is the machinery that makes many builds real.
+- [[system-tech-tree]] — the same graph shape at the *strategy* scale (a whole faction).
+- [[system-meta-progression]] — persistent trees between runs.
+- [[system-economy]] — skill points are a currency; the tree is a sink.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §11, law 2 — build deltas and win-rate windows.
+- `examples/slay-the-spire`-style drafting (**[[anchor-slay-the-spire]]**) — the
+  deck IS the tree, built one card at a time.

package/design/30-systems/status-effects.md

@@ -0,0 +1,111 @@
+---
+id: system-status-effects
+title: Status Effects — damage and change over time
+kind: system
+tags: [status, dot, buff, debuff, stacking, poison, burn, legibility]
+summary: DoT, buffs, and debuffs as first-class state — with stacking rules that are legible, bounded, and interact with builds instead of just piling up.
+use-when: You want conditions (poison, burn, slow, shield, rage) that persist across turns/seconds and interact with the rest of combat.
+composes-with: [system-combat-model, system-counter-systems, system-build-diversity, system-telegraphs]
+anchors: [anchor-slay-the-spire, anchor-hades]
+verify-with: docs/FUN.md#11-roguelike-deckbuilder
+---
+
+# Status Effects — damage and change over time
+
+**What it is.** **Conditions** that persist: poison ticking each turn, a burn, a
+shield, a slow, a rage buff. Status turns a hit from a one-frame event into a
+*state you carry* — the layer that lets [[system-build-diversity]] and
+[[system-counter-systems]] interact instead of just stacking flat numbers.
+
+**Player fantasy / why it's fun.** Setting up. The poison you stacked three turns
+ago finally kills; the shield you pre-cast eats the boss's big hit. Status rewards
+*plans*, not just reactions — it's the memory of combat.
+
+## When to use / when NOT
+
+| Use status when… | Skip when… |
+|---|---|
+| You want set-up-then-payoff play | Combat is pure twitch reaction |
+| Builds should interact (a synergy engine) | You have < ~4 effects (just make them direct) |
+| Counters need a vocabulary (cleanse, resist) | Legibility budget is already spent |
+
+Every status is a rule the player must hold in their head. Ship the fewest that
+carry the most interaction — a bloated status list is unreadable, not deep.
+
+## Variants
+
+| Kind | Shape | Stacking | Example |
+|---|---|---|---|
+| **DoT** (poison, burn) | damage per tick, N ticks | intensity or duration | Slay the Spire poison (−1/turn, decays) |
+| **Debuff** (slow, weak, vuln) | multiplier on the target | usually duration | weak = −25% dmg dealt |
+| **Buff** (rage, haste, shield) | multiplier / absorb on self | intensity or refresh | block that expires next turn |
+| **CC** (stun, freeze, root) | skips/limits actions | rarely stacks; diminishing | one turn skipped |
+| **Trigger** (mark, curse) | fires on a condition | count-based | "next hit crits" |
+
+## Stacking rules — pick one per effect, state it
+
+| Rule | Behaviour | Good for |
+|---|---|---|
+| **Intensity** | more applications = bigger effect | poison, bleed |
+| **Duration** | more applications = longer, same size | slow, weak |
+| **Refresh** | re-apply resets the timer, no stack | most buffs |
+| **Independent** | each application is its own timer | rare; hard to read |
+| **Cap** | stacks up to N, then no-op | keep any of the above bounded |
+
+Ambiguous stacking is the #1 status bug. Decide intensity-vs-duration *per effect*
+and cap it — an uncapped intensity DoT trivializes the game (FUN.md law 3).
+
+## Tuning levers
+
+| Lever | Does | Healthy range |
+|---|---|---|
+| **Tick timing** | when DoT resolves | fixed point in the turn/second; deterministic |
+| **Decay** | how stacks fall off | poison −1/turn keeps it self-limiting |
+| **Cap** | max stacks/intensity | always set one |
+| **Cleanse cost** | price to remove a status | real, so statuses are a threat not a nuisance |
+| **Duration** | turns/seconds it lasts | long enough to matter, short enough to plan around |
+
+## How it wires to Hayao
+
+- **Status is pure state** on the entity in `world.state` — a `{ id, stacks, turns }`
+  list, resolved by a pure tick function; all rolls via `world.rng`. That makes
+  clone-and-score bots free (FUN.md law 7): pilot the intended build, assert it beats
+  the null build (FUN.md law 2, §11 draft-delta).
+- **Legibility is intent honesty.** A shown "poison 6" must deal exactly 6 over its
+  ticks (FUN.md §11 — resolve the telegraph, compare to the number). Audit it.
+- **The tick returns choreography** — the number pop and tint are cosmetic
+  (`FloatingText`, `FLOAT_PRESETS`; JUICE Part 1), out of `world.hash()`.
+- No special engine primitive is needed — status is *your* data. Grep [`docs/API.md`](../../docs/API.md)
+  before citing; there is no `applyStatus` in the surface, and there shouldn't be.
+
+## Fails when…
+
+- **Uncapped intensity.** One infinite-scaling DoT becomes the only strategy
+  (dominant, [[system-build-diversity]] collapses).
+- **Illegible stacking.** The player can't predict the tick, so they stop planning —
+  status becomes noise, not depth.
+- **No counter-play.** A status with no cleanse/resist and a long duration is just
+  unfair; give the vocabulary a full loop ([[system-counter-systems]]).
+- **Silent resolution.** Ticks with no pop/tint read as HP randomly draining. Answer
+  on ≥ 2 senses (JUICE).
+
+## Verify
+
+- **[FUN.md §11](../../docs/FUN.md)** — draft/build delta (the status build beats the
+  null build); intent honesty (shown status == resolved damage).
+- **[FUN.md law 3](../../docs/FUN.md)** — the cap inequality asserted against config.
+- Determinism: golden hash of a scripted fight with statuses; view-on == view-off.
+- Feel: number pops answer on ≥ 2 senses → **[JUICE.md Part 3](../../docs/JUICE.md)**.
+
+## Composes with
+
+- [[system-combat-model]] — status is damage/change that resolves over the model's clock.
+- [[system-counter-systems]] — cleanse/resist/immunity are the counter vocabulary.
+- [[system-build-diversity]] — status synergies are a primary source of viable builds.
+- [[system-telegraphs]] — a big incoming debuff should itself telegraph.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §11 — deckbuilder draft-delta and intent honesty.
+- [`docs/JUICE.md`](../../docs/JUICE.md) Part 1 — `FloatingText` / `FLOAT_PRESETS` for pops.
+- [[anchor-slay-the-spire]] — the reference for legible, capped, build-defining status.

package/design/30-systems/tech-tree.md

@@ -0,0 +1,112 @@
+---
+id: system-tech-tree
+title: Tech Tree — Research Gating & the Ramp of Options
+kind: system
+tags: [tech-tree, research, gating, branch-exclusivity, strategy, unlocks, ramp]
+summary: Research-gated unlocks at the strategy scale; branch exclusivity and a widening ramp of options that shape a whole playthrough's arc.
+use-when: The game unlocks strategic capabilities (units, buildings, abilities) over a session and you need the order and exclusivity of those unlocks to matter.
+composes-with: [system-skill-trees, system-resource-loops, system-economy, system-faction-asymmetry, system-progression]
+anchors: [anchor-age-of-empires, anchor-civilization, anchor-factorio]
+verify-with: docs/FUN.md#9-rts-lite
+---
+
+# Tech Tree — Research Gating & the Ramp of Options
+
+**What it is.** A **tech tree** is a **[[system-skill-trees]]** at the *strategy*
+scale: a graph of researchable capabilities — units, buildings, upgrades, ages —
+where each unlock widens what the player can *do*, and prerequisites impose an
+order. Where a skill tree shapes a *character*, a tech tree shapes a *civilization's
+whole arc*.
+
+**Player fantasy / why it's fun.** "My tech path is my strategy." The order you
+research is a plan; a well-timed unlock is a power spike (**[[anchor-age-of-empires]]**
+age-ups). The pull is the branch just out of reach — the tech that would answer
+what's beating you.
+
+## When to use / when NOT
+
+| Use it when | Skip it when |
+|---|---|
+| Strategy is expressed through *what you unlock, when* (RTS, 4X) | The game has a fixed toolset from the start |
+| Build orders and tech timing are a skill | Research would just be a passive timer |
+| You want power spikes to punctuate a long session | Sessions are too short to ramp options |
+
+The tech tree is the RTS/4X engine of **[[pattern-pacing-and-tension]]**: each age
+or era is a plateau, each unlock a spike. If unlocks don't create *timing decisions*
+(rush this or bank for that?), you have a checklist, not a tree.
+
+## Variants
+
+| Variant | Structure | The decision is | Example |
+|---|---|---|---|
+| **Age/era gates** | Discrete tiers; advance to unlock a bracket | *When* to age up (spike vs eco) | AoE ages; Civ eras |
+| **Prerequisite web** | Deep dependency graph | *Route* through the tree | Civ tech web; Factorio science |
+| **Exclusive branches** | Pick a path, lock the other | *Identity/commitment* | Civ policy trees; StarCraft tech choices |
+| **Cost-gated flat** | No prereqs, priced by power | *Priority* | Simple upgrade shops |
+| **Faction trees** | Different tree per faction | *Asymmetric strategy* | See [[system-faction-asymmetry]] |
+
+## Tuning levers
+
+| Lever | What it controls | Healthy range / rule |
+|---|---|---|
+| **Tier/age spacing** | Time between power spikes | Long enough to *feel* the plateau, short enough to keep momentum |
+| **Branch exclusivity** | Whether a path costs another | Some branches exclusive, or every game converges to the same tech |
+| **Research cost curve** | The ramp of options | Rising cost per tier; but each tier's *value* must rise with it |
+| **Gate depth** | Prereqs before a payoff tech | Shallow — burying the fun behind filler tech is grind |
+| **Counter-availability** | Can you tech *into* an answer? | Yes — a tech tree is where RTS counters live; every threat needs a reachable response |
+| **Snowball vs comeback** | Does a tech lead compound? | Add catch-up / comeback techs, or leaders run away ([[pattern-feedback-loops]]) |
+
+## How it wires to Hayao
+
+- **The tree is a data graph + pure logic.** Nodes (`id, cost, prereqs, unlocks`)
+  in `world.state`; researching is an **input action** that spends resources and
+  flips availability flags; unit/ability availability is pure logic reading those
+  flags. So a *build order* is a reproducible input script a bot can pilot
+  (**[[FUN.md law 7]]**).
+- **Strategy is the balance test.** The RTS truth (**[[FUN.md §9]]**): the intended
+  line (e.g. turtle → tech → counterpush) must *beat* a naive line (attack-move /
+  one-tech rush). Pilot both, assert the delta — that's your proof the tech
+  choices matter (law 2).
+- **Counters must be reachable.** Every enemy threat needs a tech-reachable answer;
+  assert it the way tower-defense proves counter duels from both sides
+  (**[[FUN.md §8]]**) and RTS proves every counter edge wins its NvN
+  (**[[FUN.md §9]]**).
+- **The tech panel is chrome** — `showScreen()` DOM; the research *state* is sim
+  (CLAUDE.md invariant 4). Generate/ramp the option-unlock curve as content
+  (`src/content/`, `assertRamp`).
+
+## Fails when…
+
+- **A dominant path.** One tech order is always best; the tree collapses to a line.
+  Skill-delta between *paths* should be small; each viable path should beat null.
+- **Unreachable counters.** A threat with no tech answer is unfair — the RTS/TD
+  counter proof fails from one side.
+- **Filler gating.** Dead prereq techs padding the route to the good one — grind.
+- **Runaway snowball.** A tech lead that compounds into an unbeatable lead with no
+  comeback tech ([[pattern-feedback-loops]]).
+- **Spikes with no plateau.** Constant unlocks = no pacing; the age-up thrill needs
+  the plateau before it.
+
+## Verify
+
+- Intended tech line beats naive line (strategy is the test): **[[FUN.md §9]]**,
+  law 2.
+- Every counter edge wins its duel, both sides: **[[FUN.md §9]]** (RTS) /
+  **[[FUN.md §8]]** (TD).
+- Build order as a reproducible pilot: **[[FUN.md law 7]]**.
+- Option ramp shape as a test: `assertRamp`/`rampIssues` over the unlock curve.
+
+## Composes with
+
+- [[system-skill-trees]] — the same graph shape at the character scale.
+- [[system-resource-loops]] — research consumes the production chain's output.
+- [[system-economy]] — research points/cost are a currency and a sink.
+- [[system-faction-asymmetry]] — different trees are a core asymmetry lever.
+- [[system-counter-systems]] — the tree is where reachable counters live.
+- [[pattern-pacing-and-tension]] — ages/eras are the plateau-and-spike engine.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §9 (RTS strategy-as-test) · §8 (counter duels)
+  — the tech-tree proofs.
+- **[[anchor-age-of-empires]]** (age spikes) · **[[anchor-civilization]]** (deep web).

package/design/30-systems/telegraphs.md

@@ -0,0 +1,106 @@
+---
+id: system-telegraphs
+title: Telegraphs — readable threat
+kind: system
+tags: [telegraph, tells, windup, readability, reaction, threat, combat]
+summary: 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.
+use-when: Any threat can hurt the player in real time or resolve on a turn; you need the danger to be reactable, not a surprise.
+composes-with: [system-combat-model, system-boss-design, system-enemy-ai, system-grace, pattern-readability]
+anchors: [anchor-into-the-breach, anchor-shadow-of-mordor]
+verify-with: docs/FUN.md#4-top-down-action-adventure-zelda-like
+---
+
+# Telegraphs — readable threat
+
+**What it is.** The **tell**: the flash, wind-up, or warning tile that fires *before*
+a threat can hurt you, giving a window to react. A telegraph is the contract that
+makes reactive play possible — without it, damage is a dice roll disguised as a
+fight. It is the readable half of every [[system-combat-model]].
+
+**Player fantasy / why it's fun.** "I saw it coming and I moved." Every dodged blow
+is the player's skill, not the game's mercy. A death after a telegraph is *fair* —
+you read it or you didn't; a death with no telegraph is the designer's fault.
+
+## When to use / when NOT
+
+| Telegraph when… | Skip when… |
+|---|---|
+| A threat can kill/hurt in real time | Damage is player-initiated only (you hit them) |
+| Perfect information is the promise (tactics) | The threat is a slow, always-visible hazard (lava) |
+| A boss/elite has committal, punishable moves | The genre's fun is *not* reacting (idle, puzzle) |
+
+Turn-based games still telegraph — they just do it as **shown intent on the board**
+(the arrow, the highlighted tiles), not a timed flash.
+
+## Variants
+
+| Telegraph | Channel | Window | Anchor | Note |
+|---|---|---|---|---|
+| **Flash / color wind-up** | visual | ~0.45s (§4) | Zelda-likes | the default reactive tell |
+| **Wind-up animation** | visual | scales to move weight | brawlers, [[anchor-shadow-of-mordor]] | big moves telegraph longer |
+| **Audio cue** | audio | leads the visual | rhythm, horror | a growl before the lunge |
+| **Ground marker / AoE** | visual | fills over the window | ARPGs, bosses | the red circle grows, then fires |
+| **Shown intent (turn)** | visual, static | until next turn | [[anchor-into-the-breach]] | the arrow you rewrite |
+| **Charge / meter** | visual | fills to threshold | bosses | commit-punish window |
+
+## Tuning levers
+
+| Lever | Does | Healthy range |
+|---|---|---|
+| **Reaction window** | telegraph frames before the hitbox | **~0.45s** flash floor (FUN.md §4); scale up for heavier moves |
+| **Salience** | how loud the tell reads | brightest thing after the avatar (JUICE salience gate) |
+| **Recovery** | punish window after the move whiffs | long enough to answer; short enough to stay dangerous |
+| **Overlap budget** | simultaneous telegraphs | few enough that each still reads (bullet-hell coherence, §7) |
+| **Channels** | senses the tell fires on | ≥ 2 for the big ones (sfx + flash) |
+
+The window is a **derived inequality** (FUN.md law 3): reaction window ≥ human
+reaction floor + the frames the dodge costs. Don't vibe it — compute it.
+
+## How it wires to Hayao
+
+- **The gate is real.** `telegraphIssues(timeline, minFrames)` (in `@hayao`) walks a
+  per-frame `TelegraphFrame[]` (`{ telegraphing, active }`) and flags any hitbox that
+  goes live after fewer than `minFrames` of contiguous wind-up. This is the direct
+  proof that reactive play is possible.
+- **Store tells as DIRECTIONS, not target tiles.** FUN.md §12: a tactics telegraph is
+  a *direction on the unit*, so a shove/redirect rewrites the outcome for free — the
+  future is editable, which is the whole fun of the genre. Encode the intent, resolve
+  it late.
+- **The tell is cosmetic; the timing is sim time.** The flash/marker are view; the
+  *window* is `world.time` and fixed `dt` (FUN.md law 6). Wire the flash to the sim
+  event, never to wall-clock — a replay reproduces the exact tell.
+- Reference: the top-down §4 pattern (kiting bot reads flashes); [[anchor-into-the-breach]]
+  DNA for shown-intent telegraphs.
+
+## Fails when…
+
+- **No wind-up.** A hitbox that goes live cold is an unfair death — `telegraphIssues`
+  fails and it *should*.
+- **The tell is illegible.** Too dim, too brief, or buried under five other flashes.
+  If the salience gate can't find it, neither can the player ([[pattern-readability]]).
+- **The telegraph lies.** The flash points left, the hit lands right. Perfect
+  information demands perfect honesty (FUN.md §12) — shown must equal resolved.
+- **Uniform windows.** Every move telegraphs 0.45s regardless of weight, so nothing
+  reads as *scary*. Scale the tell to the threat.
+
+## Verify
+
+- **[FUN.md §4](../../docs/FUN.md)** — ~0.45s flash makes reactive play possible;
+  kiting-bot telemetry with an hp floor.
+- **[FUN.md §12](../../docs/FUN.md)** — telegraphs as directions; intent honesty
+  (resolve each telegraph, compare to the shown number/arrow).
+- `telegraphIssues(timeline, minFrames)` → **[VERIFICATION Channel 4](../../docs/VERIFICATION.md)**.
+- Salience: `salienceIssues` proves the tell out-contrasts scenery (JUICE Part 2/3).
+
+## Composes with
+
+- [[system-combat-model]] — the telegraph is the reactive half of the resolution rule.
+- [[system-boss-design]] — bosses live or die on legible, escalating tells across phases.
+- [[system-enemy-ai]] — the AI must *commit* to a telegraphed move, not cancel it.
+- [[pattern-readability]] — signposting and salience are how a tell gets read.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §4 (flash window), §7 (pattern coherence), §12 (directions).
+- [`docs/JUICE.md`](../../docs/JUICE.md) — salience gate; the avatar/threat contrast floor.
+- [`src/verify/gates.ts`](../../src/verify/gates.ts) — `telegraphIssues`, `TelegraphFrame`.