@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/game-storytelling/evals/cases.yaml

@@ -0,0 +1,51 @@
+skill: game-storytelling
+
+should_trigger:
+  - prompt: "I'm making a narrative RPG and I want the whole story to branch based on player choices, but I'm terrified it'll balloon into thousands of scenes I can't write. How should I structure it?"
+    why: "Branching narrative + the combinatorial-explosion fear — the skill's core containment guidance (foldback, gates, reconvergence, state-over-structure). Structure of the narrative graph, not engine code."
+  - prompt: "Help me write the premise, theme, and pillars for my game before I start on any of the actual story content."
+    why: "Premise/theme/narrative-pillars foundation — the skill's 'do this first' section. Explicitly narrative-design groundwork, not mechanics or balance."
+  - prompt: "My dialogue in Ink feels like it has a hundred fake choices that all lead to the same line. How do I make the choices actually matter?"
+    why: "Meaningful choice vs. illusion of choice, in a portable dialogue format (Ink). The skill owns choice design and state; it is not Ink-engine wiring."
+  - prompt: "Players say my game's story doesn't match the gameplay — the character is supposed to be a pacifist healer but the whole loop is shooting enemies. What do I do?"
+    why: "Ludonarrative dissonance — the verb/reward audit and reconciliation is a flagship section. Non-obvious phrasing but squarely narrative-vs-mechanics harmony."
+  - prompt: "I need to design the quest structure for my game — how objectives are tracked, what happens on failure, and how side quests unlock. Can you help lay that out?"
+    why: "Quests & objectives: states, tracking, fail states, dependencies. The skill owns the quest state machine as a design artifact."
+  - prompt: "How can I tell the backstory of this abandoned station through the environment instead of dumping it all in audio logs?"
+    why: "Environmental / show-don't-tell storytelling — the skill's environmental section, preferring diegetic delivery over text-dumps."
+  - prompt: "Which tool should I use to author a branching dialogue tree — Yarn Spinner, Twine, or articy? And how do I keep it localization-ready?"
+    why: "Dialogue-tool selection (tools as pointers) plus localization-readiness — both explicit skill sections. Choosing/authoring the narrative, not wiring the runner into an engine."
+
+should_not_trigger:
+  - prompt: "Design the combat system for my game — how melee combos, stamina, and damage scaling should work and feel balanced."
+    route_to: "game-design"
+    why: "Core mechanics, systems, and balance — what the player DOES. The skill explicitly defers verbs/systems/economy/balance to game-design."
+  - prompt: "Lay out the blockout for this level — where the cover, sightlines, enemy spawns, and the sniper perch go."
+    route_to: "level-design"
+    why: "Spatial layout and encounter placement. The skill defers the geometry of a space (even story-bearing space) to level-design."
+  - prompt: "Wire my Ink story file into Unity — set up the InkRunner, bind the choices to UI buttons, and serialize the story state into my save system."
+    route_to: "unity"
+    why: "Engine integration: dialogue runner, UI binding, save/serialize. The skill authors portable narrative and hands wiring to the engine skill (here, unity)."
+  - prompt: "Write me a short story / novella set in my game's universe — just prose fiction, no choices or branching."
+    route_to: "none"
+    why: "Linear prose fiction with no interactive/branching structure is general creative writing, not interactive narrative design; the skill scopes to story-as-system."
+  - prompt: "Write the Steam store description and the launch trailer voiceover script to market my game."
+    route_to: "marketing"
+    why: "External-facing marketing copy, not in-game narrative. The skill defers store/trailer copy to marketing."
+
+capability:
+  - scenario: "A dev says: 'My branching RPG has about 12 major player choices and I want them all to matter, but I can't author 4000 scenes. And several of my choices feel fake — they lead to the same outcome.' Design the narrative structure."
+    must_include:
+      - "Names the combinatorial-explosion problem explicitly (roughly 2^N futures for N independent binary choices) as why 12 free choices is unauthorable"
+      - "Recommends a foldback / string-of-pearls topology with reconvergence (bottlenecks) so branches rejoin on load-bearing beats"
+      - "Uses gates and state-over-structure: model choices as named flags/variables and have one scene read the flag and swap lines, instead of duplicating scenes"
+      - "Distinguishes meaningful choice (a flag some later node reads back to the player) from illusion of choice, and says you may fake the outcome but never sell fake stakes as consequential"
+      - "Keeps a small budget of global/persistent choices (collapsed into summary variables for endings) while most choices stay local/weave"
+      - "Stays engine-agnostic: produces the narrative graph and a state/flag model, and hands runner/save wiring to the engine skill rather than writing engine code"
+  - scenario: "A dev says: 'Reviewers complain the story doesn't fit the game. My protagonist is written as a compassionate doctor, but the core loop is mowing down hundreds of soldiers.' Diagnose and fix."
+    must_include:
+      - "Identifies this as ludonarrative dissonance: the mechanics/verbs contradict the story the game tells"
+      - "Runs a verb audit (the dominant verb is 'kill', which contradicts 'compassionate doctor') and a reward audit (what the game rewards is the loudest narrative voice)"
+      - "Prefers fixing the cheaper piece — usually re-framing the narrative to match the mechanic — while flagging to game-design when only a mechanic change can resolve it"
+      - "Addresses reconciling failure/death fiction (respawns/checkpoints) with the story rather than leaving it unexplained"
+      - "Frames story as a system in service of play, not a layer of words bolted on to excuse the mechanics"

package/skills/shared/game-storytelling/references/branching-and-state.md

@@ -0,0 +1,134 @@
+# Branching & state — topologies, choice, and containment
+
+Deep dive for the SKILL's "Narrative structures" and "Branching & choice" sections. This is engine-agnostic: model the graph and the state here; the engine skill (`godot`/`unity`/`unreal`) serializes and runs it.
+
+## The narrative topologies (ASCII)
+
+**Linear** — one path; agency is over pace, not direction.
+
+```
+A -> B -> C -> D -> E
+```
+
+**Branching tree** — choices split and (in the pure case) never rejoin. Author cost doubles at each fork.
+
+```
+        /-- B --< D
+A --<             \-- E
+        \-- C --< F
+                  \-- G
+```
+
+**Hub-and-spoke** — a central hub; the player picks self-contained spokes and returns. Agency is over *order* and *selection*.
+
+```
+        B
+        |
+  C --- HUB --- D      (return to HUB after each spoke)
+        |
+        E
+```
+
+**Foldback / string-of-pearls** — branches diverge, then **reconverge** at load-bearing beats ("pearls"). The between-pearl space stays small, so total scenes stay authorable while choices feel consequential. This is the workhorse for long branching stories.
+
+```
+        /-- b1 --\        /-- b3 --\
+BEAT1 --           -- BEAT2         -- BEAT3 -> ...
+        \-- b2 --/        \-- b4 --/
+```
+
+**Gauntlet / branch-and-bottleneck** — like foldback but branches can *drop out* (fail forward) into the main line rather than each reaching the bottleneck.
+
+Most shipped games are a **mix**: a foldback main line, hub-and-spoke for side content, environmental/systemic layered on top.
+
+## Meaningful choice vs. the illusion of choice
+
+A choice is **meaningful** only when all three legs hold:
+
+1. **Intent** — the player understands the options well enough to *want* one (not a blind coin-flip, unless blindness is the point).
+2. **Foreseeable consequence** — a plausible mental model of what each option does (even if the outcome surprises).
+3. **Consequence that lands** — the game later *reads the choice back*: a changed line, a locked door, a dead character, a different ending. If nothing ever reads the flag, the choice was noise.
+
+**Illusion of choice** — options that reconverge to the same outcome — is a legitimate, even essential tool, but only for the right job:
+
+| Illusion is fine for… | Illusion is a betrayal when… |
+| --- | --- |
+| **Expression / roleplay** — *how* your character says a thing (tone, personality) with the same result | it's dressed up as a **stakes** decision ("save her or let her die" → she dies either way, unacknowledged) |
+| **Pacing / tone** — letting the player set register without forking the plot | the player is told/led to believe it's consequential and later discovers it wasn't |
+| **Onboarding** — safe practice choices before real ones | you fake many in a row; players learn choices don't matter and disengage from *all* of them |
+
+Rule of thumb: **you may fake the outcome, never the stakes.** The moment a player catches a stakes-choice that didn't matter, they retroactively distrust every prior choice. Budget your few real, global choices and make them unmistakably land; let the many small choices be honest expression.
+
+### Kinds of consequence (make at least some visible)
+
+- **Immediate** — the next line/scene changes now (satisfying, cheap, local).
+- **Delayed** — pays off hours later (powerful, needs a flag and a reminder so the player *connects* it).
+- **Ambient** — world/NPC reactions, reputation, barks (cheap breadth; makes the world feel to be watching).
+- **Ending-level** — the choice(s) route the finale. Track with a small set of summary flags, not the full history.
+
+Delayed consequences only feel meaningful if the player can **attribute** them to the choice. Plant a callback ("because you spared him at the bridge…") or the payoff reads as random.
+
+## State: model it as named variables
+
+Story state is the spine of everything above. Model it explicitly; never encode meaning in duplicated scene copies.
+
+| State type | Example | Use for |
+| --- | --- | --- |
+| **Boolean flag** | `met_the_witch`, `betrayed_ally` | one-shot facts / gates |
+| **Counter** | `civilians_saved`, `times_lied` | thresholds, tallies, tone tracking |
+| **Enum / stage** | `witch_relationship = ally\|neutral\|enemy` | relationship / quest stages |
+| **Scalar / reputation** | `town_rep = -3..+3` | gradient reactions, gated content |
+| **Set / inventory** | `keys = {east, crypt}` | possession checks |
+
+Guidelines:
+
+- **Name for meaning, not mechanism** (`saved_the_child`, not `flag_37`). Future you and translators read these.
+- **Write once, read many.** A single scene that reads flags and swaps lines beats N near-duplicate scenes.
+- **Keep a state dictionary** — one table listing every variable, type, who sets it, who reads it. This is your single source of truth and your test plan.
+- **Derive, don't duplicate.** Compute "is the player a villain" from counters at read time rather than maintaining a parallel flag that can desync.
+- **Decide persistence with the engine skill.** *What* is saved (which variables survive a reload, a chapter, a new game+) is a design call you make; *how* it serializes is the engine skill's job.
+
+### A portable state-gated scene (Ink-flavored, illustrative)
+
+```ink
+VAR spared_bandit = false
+VAR town_rep = 0
+
+=== gate_market ===
+{ town_rep >= 2:
+    The guard nods you through. -> market
+- else:
+    "Your kind isn't welcome." -> turned_away
+}
+
+=== bandit_reappears ===
+{ spared_bandit:
+    The bandit you spared steps from the shadows — and returns the favor.
+- else:
+    A stranger eyes you coldly and says nothing.
+}
+-> continue
+```
+
+One scene, two behaviors, driven by state — not two authored scenes.
+
+## The combinatorial-explosion trap and how to contain it
+
+**The math:** N *independent* binary choices imply 2^N reachable states; 10 such choices is 1024 futures — unauthorable, untestable. Left unchecked, branching narrative collapses under its own content cost. Contain it deliberately:
+
+1. **Reconvergence (bottlenecks / foldback).** Funnel branches back to shared beats. Between two bottlenecks you only author the small local fan-out, not the global product. This is the single highest-leverage fix.
+2. **Gates.** Require a flag/level/item/reputation to open content. Gating *prunes the live branch set* — most branches aren't reachable in a given playthrough, so you don't pay to author their full downstream.
+3. **State over structure.** Replace divergent *scenes* with one scene that reads *variables*. You trade authored copies for conditional lines — linear content growth instead of exponential.
+4. **Locality (weave).** Keep most choices' effects inside the current scene; let them evaporate at the next bottleneck. Reserve a *small, named budget* of choices for global, persistent state (the ones that reach the ending).
+5. **Summary variables for endings.** Don't branch the finale on the full choice history; collapse it into a few axes (e.g. `mercy_score`, `faction`) and branch on those. Dozens of choices, a handful of endings.
+6. **Orthogonal, not multiplied.** Prefer choices that affect *different* subsystems (one changes a relationship, one changes the map) over choices that all modify the same outcome and must be cross-authored.
+
+### Testing a branching graph (design-side)
+
+- **Reachability** — every node reachable from start under *some* valid state; flag orphans.
+- **No dead ends / soft-locks** — every non-ending node has an exit; no state combination strands the player.
+- **Gate satisfiability** — every gated node is reachable by *some* path that can satisfy its condition (a locked door with no obtainable key is a bug).
+- **Flag hygiene** — every variable read is written somewhere first; no read-before-write.
+- **Ending coverage** — enumerate the summary-variable combinations and confirm each maps to an intended ending.
+
+Keep this list as the acceptance criteria you hand to the engine skill's implementation and QA.

package/skills/shared/game-storytelling/references/dialogue-tools.md

@@ -0,0 +1,117 @@
+# Dialogue tools — the four primitives, a pick-one guide, and one conversation in three formats
+
+Deep dive for the SKILL's "Dialogue systems" section. **Engine-agnostic:** author dialogue in a portable format here; the engine skill (`godot`/`unity`/`unreal`) wires the runner, presenter, save/serialize, and any plugin. Do not write engine binding code in this skill.
+
+## Every tool reduces to four primitives
+
+Design against these, then map them onto whichever tool the project uses:
+
+| Primitive | What it is | Ink | Yarn Spinner | Twine (Twee) | articy:draft X |
+| --- | --- | --- | --- | --- | --- |
+| **Node** | addressable unit of content | knot `=== name ===` / stitch `= name` | node with `title:` + `===` end | passage `:: Name` | flow / dialogue fragment |
+| **Condition** | boolean over state gating content | `{ cond: ... }`, `{ cond: a \| b }` | `<<if $x>> ... <<endif>>` | `(if: $x)[...]` (Harlowe) / `<<if $x>>` (SugarCube) | condition node / expression on a pin |
+| **Variable** | the story state read/written | `VAR x = 0`, `~ x = 1` | `<<set $x to 1>>` | `(set: $x to 1)` / `<<set $x = 1>>` | global variable in the variable set |
+| **Effect** | side effect a node fires | `~ func()`, tags `#`, external funcs | `<<command>>`, functions, `<<set>>` | macros, `<<run>>` (SugarCube) | instruction node / script pin |
+
+If you can express a conversation in these four primitives, it ports to any of the tools below.
+
+## The tools (pointers, current as of 2026)
+
+### Ink — inkle's narrative scripting language
+- **Shape:** a writer-first *language* (not a visual editor). Text is the default; logic is woven in. Prose-heavy, highly expressive.
+- **Core syntax:** knots `=== name ===`, stitches `= name`, diverts `-> name`, once-only choices `*`, sticky choices `+`, gathers `-`, weave (nested choices/gathers), `VAR`, `CONST`, `LIST` (state machines / multi-value), conditionals `{ }`, tunnels `-> x ->`, threads `<- x`, functions, tags `#`, glue `<>`.
+- **Runtime:** compiles to JSON; run with **inkjs** (web/JS) or engine integrations (Unity's `ink-unity-integration`; community Godot integrations). **Inky** is the authoring editor with live preview.
+- **Best for:** branching prose, interactive fiction, dialogue with lots of state and reincorporation. Weakest as a visual overview for non-writers.
+
+### Yarn Spinner — the friendly dialogue tool (v3.x current)
+- **Shape:** node-based, screenplay-ish; friendlier to designers and non-programmers than raw Ink. Nodes edit well in a graph or plain text.
+- **Core syntax:** node = header (`title: Name`) + `---` + body + `===`; options with `->`; `<<set $x to 1>>`, `<<if>>/<<elseif>>/<<else>>/<<endif>>`, `<<jump Node>>`, `<<declare>>`, custom `<<commands>>`, functions, and inline markup `[b]...[/b]`.
+- **Runtime & engines:** first-class **Unity** support; **Godot** via official C# (beta) and GDScript (alpha) integrations; **Unreal** integration in progress for 2026. String tables export for localization are built in.
+- **Best for:** game dialogue with a designer-writer split, VO line management, and Unity projects.
+
+### Twine — visual hypertext editor
+- **Shape:** a **visual node editor** that publishes a self-contained HTML file. Lowest barrier to entry; excellent for prototyping and interactive fiction shipped as a web page.
+- **Story formats matter:** scripting depends on the chosen format — **Harlowe** (default, macro-based `(set:)/(if:)`), **SugarCube** (`<<set>>/<<if>>`, save system, richer for games), **Snowman** (JS-forward), **Chapbook** (prose-forward). Pick the format for the job.
+- **Twee** is Twine's plain-text form (`:: Passage` headers) — version-controllable and a good neutral interchange for design even if the game engine isn't Twine.
+- **Best for:** prototyping branches fast, web-delivered IF, and design-time storyboarding. Not a drop-in engine dialogue runtime for a AAA build.
+
+### articy:draft X — visual narrative database (commercial)
+- **Shape:** a heavyweight **narrative DB + flow editor**. Models flow fragments, dialogue fragments, hubs, conditions, instructions, plus a full entity/location/variable database and templates. Built for large teams and large scripts.
+- **Pipeline:** free **Unity** and **Unreal** importers pull dialogues, entities, variables, and localization in cleanly; a **Generic Engine Export** produces JSON (+ optional assets) for any custom engine. Runs on Windows and macOS.
+- **Best for:** big branching RPGs, teams that need a shared narrative database, template-driven content, and translation at scale. Overkill for a small project.
+
+## Pick one — a fast decision guide
+
+| If… | Reach for |
+| --- | --- |
+| Prose-heavy IF, lots of state, writer-driven | **Ink** |
+| Game dialogue, designer/writer split, Unity, VO + loc built in | **Yarn Spinner** |
+| Rapid prototype, web-delivered, or teaching branching visually | **Twine** (SugarCube for game-like saves) |
+| Large team, huge script, shared entity/variable DB, Unity/Unreal | **articy:draft X** |
+| You just need a portable design artifact, engine undecided | **Twee** or an Ink file (both are plain text, diff-able) |
+
+When the engine is fixed, let the **engine skill** confirm the best-supported integration; when it isn't, author in plain-text (Ink/Twee) so nothing locks you in.
+
+## The same conversation, three formats
+
+A guard who lets you pass only if `has_pass` is true; otherwise you can bribe (needs `gold >= 10`) or leave.
+
+**Ink**
+```ink
+VAR has_pass = false
+VAR gold = 0
+
+=== gate ===
+The guard blocks the door.
+{ has_pass:
+    "Pass, citizen." -> town
+}
+* [Offer a bribe] { gold >= 10:
+        ~ gold = gold - 10
+        The guard pockets it. -> town
+    - else:
+        "You're ten short." -> gate
+    }
+* [Leave] -> street
+```
+
+**Yarn Spinner**
+```yarn
+title: Gate
+---
+The guard blocks the door.
+<<if $has_pass>>
+    Guard: Pass, citizen.
+    <<jump Town>>
+<<endif>>
+-> Offer a bribe <<if $gold >= 10>>
+    <<set $gold = $gold - 10>>
+    The guard pockets it.
+    <<jump Town>>
+-> Leave
+    <<jump Street>>
+===
+```
+
+**Twee (SugarCube)**
+```twee
+:: Gate
+The guard blocks the door.
+<<if $has_pass>>Guard: "Pass, citizen." [[Town]]<<else>>\
+[[Offer a bribe->Bribe]]
+[[Leave->Street]]
+<</if>>
+
+:: Bribe
+<<if $gold gte 10>><<set $gold to $gold - 10>>The guard pockets it. [[Town]]\
+<<else>>"You're ten short." [[Gate]]<</if>>
+```
+
+Same four primitives (node / condition / variable / effect), three syntaxes. Design once; the engine skill binds it.
+
+## Delivery notes (design-side)
+
+- **Barks vs. conversations** — short, interruptible one-liners (barks) need a priority + cooldown model so they don't stack or repeat; full conversations need focus/turn-taking. Design them as different node types.
+- **Line IDs & loc** — every player-facing line carries a stable id and lives in a string table (see the SKILL's localization notes). Ink tags, Yarn's string-table export, and articy's loc columns all support this; use them.
+- **Never concatenate** sentence fragments across variables for grammar (gender/plural/word order) — author full templated lines with named placeholders.
+- **Presentation is the engine's job** — typewriter effect, portraits, camera, choice-timer UI, skip/auto — hand these to the engine skill; keep the dialogue content pure.

package/skills/shared/game-storytelling/references/environmental-storytelling.md

@@ -0,0 +1,71 @@
+# Environmental & systemic storytelling — show, don't tell
+
+Deep dive for the SKILL's "Environmental & systemic storytelling" section. The goal: deliver story *through the world and its rules* so the player assembles meaning and owns it, instead of being narrated at. Engine-agnostic; coordinate the *space* with `level-design` and the *rules* with `game-design`.
+
+## Why show over tell
+
+Told information is received; discovered information is *earned*. A player who infers "someone died here defending this door" from a skeleton, a spent revolver, and claw marks believes it more, and remembers it longer, than the same fact in a text box. Reserve telling (codex, narrator, log dumps) for what the world genuinely cannot carry — precise numbers, distant history, abstract rules.
+
+**Show-don't-tell ladder** (prefer the top; fall back only when needed):
+
+1. **Enacted** — it happens in front of the player through play (an ally sacrifices themselves in a scripted-but-interactive beat).
+2. **Environmental** — the world's state implies the event (aftermath, traces, arrangement).
+3. **Overheard / ambient** — barks, one-sided radio, NPCs talking to each other.
+4. **Readable in-world** — item descriptions, signage, graffiti, terminals that *belong* to the world.
+5. **Collectible logs** — audio logs, diaries, notes. Useful but the most "tell"-like; easy to overuse.
+6. **Non-diegetic** — narrator, codex, cutscene exposition, HUD text. Last resort.
+
+## Environmental storytelling — the technique catalog
+
+- **Set dressing with intent.** Every prop can carry meaning: a single toy in a barracks, wedding photos in a looted home. Composition points the eye (leading lines, light, framing a key object) — coordinate with `level-design` and lighting.
+- **Aftermath / the frozen moment.** Show the scene *after* the event and let the player reconstruct it: overturned table, blood trail, a meal half-eaten. The gap between "what I see" and "what happened" is the story.
+- **Traces & evidence.** Bullet holes, scorch marks, footprints in dust, a barricade built from the wrong side. Physical cause-and-effect the player reads like a detective.
+- **Spatial sequencing.** The *order* the player encounters space tells a story: descend from opulence into rot; a triumphant mural, then the mass grave behind it. The space is a sentence; its layout is the grammar (a `level-design` collaboration).
+- **Object placement & juxtaposition.** Meaning from adjacency — a child's drawing pinned above a weapons cache; a prayer shrine facing a bricked-up window.
+- **Readable descriptions.** Item and examine text that implies a life ("Dented canteen. Someone scratched three tally marks and stopped."). Small, optional, high-flavor; rewards curiosity without gating.
+- **World-state change.** The strongest environmental beat: the space *changes* in response to the player or the plot (a hub burns, a garden regrows, a faction's banners replace another's). The player sees consequence written on the world.
+- **Absence.** What's missing tells a story too — an empty crib, a cleared-out desk, a name scratched off a roster.
+
+Guardrails:
+
+- **Legibility vs. mystery.** Give enough signal that most players read the intended gist, with deeper layers for the attentive. If *no one* gets it, it's decoration, not storytelling; if it's spelled out, it's a text box.
+- **Consistency = trust.** Once the world's props reliably mean things, players *read* every scene. One arbitrary/contradictory arrangement teaches them to stop looking.
+- **Optional, not load-bearing.** Environmental story enriches; don't hide *required* plot solely in a missable detail. Critical beats need a guaranteed channel.
+
+## Diegetic vs. non-diegetic delivery
+
+| | Diegetic (in-world) | Non-diegetic (outside the fiction) |
+| --- | --- | --- |
+| **Examples** | signage, barks, radio, environmental change, in-world terminals | narrator VO, codex/lore menu, HUD text, tutorial popups, cutscene title cards |
+| **Feel** | immersive, earned, "the world tells me" | efficient, precise, "the game tells me" |
+| **Use for** | mood, place, character, consequence, most story | exact numbers, dense history, rules the world can't show, accessibility |
+| **Cost of overuse** | can be missed/ambiguous | breaks immersion; reads as a lecture |
+
+**Diegetic first.** Push information into the world; drop to non-diegetic only for what the world can't carry. Note the honest exceptions: **accessibility** (subtitles, clear objective text, difficulty-scaled hints) and **usability** (a control prompt) are worth a non-diegetic cost — never sacrifice comprehension for purity.
+
+## Systemic & emergent storytelling — the anecdote factory
+
+Scripted story is *authored*; systemic story is *generated* by rules + player + world state producing events no writer placed. The famous colonist who starved defending the fridge, the rival who keeps hunting you across a sandbox — nobody wrote those; the systems did.
+
+You don't write these stories. You design the **conditions and vocabulary** that let them happen and be legible — an "anecdote factory." This is primarily a `game-design` collaboration; your narrative-design job is to make the output *readable as story*.
+
+Design levers:
+
+- **Legible actors** — entities with names, traits, memory, and relationships (a guard who remembers you spared him). Persistent identity turns a system event into a *character* moment.
+- **Consequence that persists** — the world remembers and reflects actions (reputation, scars, changed factions), so events chain into arcs instead of resetting.
+- **Readable causality** — the player can *see why* something happened (a needs/mood readout, a reaction bark, a kill-cam). An unexplained emergent event is just noise; a readable one is an anecdote.
+- **Framing & capture** — surfacing tools (event log, photo mode, relationship screen, killfeed, end-of-run summary) that let the player *notice and retell* the story the systems produced. The retelling is the payoff.
+- **Meaningful randomness** — variety within authored bounds (curated event pools, weighted tables) so runs differ without becoming incoherent.
+- **Interacting systems** — emergence needs ≥2 systems that touch (fire + wind + wood; hunger + weather + AI). One system alone produces events, not stories.
+
+Guardrails:
+
+- **Coherence budget.** Pure emergence drifts into nonsense; pure authorship can't surprise. Set authored guardrails (tone, bounds, curated pools) inside which systems play.
+- **Framing is half the work.** An emergent event the player never notices or can't interpret isn't a story. Invest in the surfacing/retelling tools as much as the simulation.
+- **Name things.** Named actors, places, and factions convert anonymous system state into story the player cares about and repeats.
+
+## Where this hands off
+
+- **`level-design`** — owns the physical space, blockout, sightlines, and encounter flow that environmental beats live inside. Co-own set-dressing that carries narrative.
+- **`game-design`** — owns the systems whose interaction produces emergent story; you specify what must be *legible* and *persistent* for those events to read as narrative.
+- **the engine skill** (`godot`/`unity`/`unreal`) — implements world-state changes, triggers, bark systems, event logs, and the persistence that makes consequence stick.

package/skills/shared/gamedev-multiplayer/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: gamedev-multiplayer
+description: "Use when adding multiplayer or netcode to a game — client-server vs P2P, server authority and anti-cheat, state replication vs RPCs, prediction and reconciliation, lag compensation, plus Godot 4 / Unity NGO / Unreal wiring. NOT single-player gameplay (that is `godot`, `unity`, `unreal`), NOT matchmaking or server hosting (that is `deployment`)."
+tags: [multiplayer, netcode, replication, networking, prediction, authority]
+recommends: [godot, unity, unreal, gamedev-physics]
+profiles: [full]
+origin: ai-hub
+---
+
+# Game multiplayer & netcode
+
+Design and wire the network layer of a game across Godot 4.x, Unity, and Unreal: choose a
+topology, put authority in the right place, replicate the right state, and hide latency without
+opening the door to cheaters. This skill owns the *networking* decisions; the engine skills own
+the local gameplay those decisions sit on top of.
+
+Route elsewhere when the ask is not netcode:
+
+| The ask | Route to | Why not here |
+| --- | --- | --- |
+| Single-player movement, AI, input, animation, save files | [`godot`](../godot/SKILL.md) / [`unity`](../unity/SKILL.md) / [`unreal`](../unreal/SKILL.md) | The engine skill owns local gameplay; no network dimension. |
+| Physics determinism, collision, character controllers | [`gamedev-physics`](../gamedev-physics/SKILL.md) | Netcode *consumes* determinism; it does not own the physics fix. |
+| Matchmaking, lobby backend, dedicated-server hosting, relays, DB, game-server CI | [`deployment`](../deployment/SKILL.md) | Running the fleet, not designing the in-game net layer. |
+| Web realtime — chat, presence, a generic WebSocket app | [`webhooks`](../webhooks/SKILL.md) | Not a game world/simulation. |
+| General threat modeling, authz review | [`secure-coding`](../secure-coding/SKILL.md) | This skill keeps only the game-specific anti-cheat controls. |
+
+## Version contract — read first
+
+Target the current APIs. **Never emit these deprecated / removed APIs:**
+
+| Engine | Target | Banned (removed/legacy) | Emit instead |
+|---|---|---|---|
+| **Godot** | 4.x | `master`/`puppet`/`remote`/`sync` keywords, `rpc_config()` as a func, `rset`, `NetworkedMultiplayerENet` | `@rpc(...)` annotation, `set_multiplayer_authority()`, `ENetMultiplayerPeer`, `MultiplayerSynchronizer` |
+| **Unity** | Netcode for GameObjects (NGO) 1.x/2.x | UNet / HLAPI: `NetworkIdentity`, `[Command]`, `[SyncVar]`, `NetworkServer`, `UnityEngine.Networking` | NGO `NetworkObject`, `NetworkBehaviour`, `NetworkVariable<T>`, `[Rpc(SendTo.X)]` |
+| **Unreal** | 5.x | replicating by polling in `Tick`, skipping `WithValidation` on gameplay RPCs | `UPROPERTY(Replicated / ReplicatedUsing=...)` + `GetLifetimeReplicatedProps`, `Server`/`Client`/`NetMulticast` `UFUNCTION`s |
+
+UNet is **removed** from modern Unity — do not scaffold it. If a repo genuinely uses Mirror (a
+community UNet-like fork), say so; this skill targets first-party NGO. In NGO 2.x the unified
+`[Rpc(SendTo.Server)]` / `[Rpc(SendTo.ClientsAndHost)]` attribute is preferred; the older
+`[ServerRpc]` / `[ClientRpc]` still compile (and enforce `…ServerRpc` / `…ClientRpc` method-name
+suffixes) — cover them but prefer the unified form on new code.
+
+## Topologies & authority
+
+Pick the topology first; everything else follows from it.
+
+- **Client-server, dedicated server** — a headless authoritative process no player controls. The gold
+  standard for competitive/persistent games: one source of truth, hardest to cheat, costs money to run.
+- **Client-server, listen server** — one player's machine is also the server (host). Cheap, zero infra,
+  but the host has a latency advantage and can tamper; fine for co-op and casual PvP. **Design so the
+  same code runs on both** (a listen server is a dedicated server that also has a local client).
+- **Peer-to-peer** — no central authority; peers exchange state directly. Low infra cost and low latency
+  between peers, but NAT traversal is painful, it is the easiest to cheat, and it needs lockstep or a
+  rollback model to stay consistent. Reasonable for small trusted lobbies or deterministic fighting games.
+
+**Server-authoritative is the default.** The server owns the truth; clients send *intent* (inputs,
+requests), never results. **Never trust the client:** the client cannot set its own health, position,
+score, currency, or hit results — it *asks*, the server *decides*, everyone else *observes*. A client
+that says "I moved to X / I did 40 damage / I have 999 gold" is either lagging or cheating; treat both
+the same. The one thing a client legitimately owns is its own input and, by convention, cosmetic-only
+state. See **[references/prediction-and-latency.md](references/prediction-and-latency.md)** for how to
+keep this responsive.
+
+## State replication vs RPCs
+
+Two complementary tools — use the right one:
+
+- **State replication** = *continuous* synchronized values (health, position, ammo, team). The framework
+  watches a variable and pushes changes to relevant peers; late-joiners get the current value automatically.
+  Use for anything a client needs the *latest* of. It is idempotent and self-healing on packet loss.
+- **RPCs (remote procedure calls)** = *one-shot events* ("fire weapon", "play explosion at P", "open door").
+  Fire-and-forget; a dropped unreliable RPC is simply lost. Use for events, **never** for state you need to
+  stay consistent — a missed "you died" RPC leaves a client desynced forever; a replicated `isDead` bool
+  self-corrects.
+
+**Rule of thumb:** replicate *nouns* (state), RPC *verbs* (events). What to replicate: only what other
+peers must see, at the coarsest rate that still looks right — position/rotation of visible actors,
+gameplay stats, animation state flags. Do **not** replicate values a peer can derive locally, purely
+cosmetic particles, or high-frequency data no one observes.
+
+**Ownership / authority** decides *who may write*. Every networked object has an owner (a peer id) and an
+authority (usually the server). Writes to replicated state must come from the authority; ownership lets a
+client drive *its own* pawn's input while the server still validates the outcome. Getting ownership wrong
+is the #1 cause of "it works for the host but not the client" bugs.
+
+## The hard problems
+
+Latency (round-trip time, RTT) is the enemy; jitter and packet loss make it worse. Four techniques,
+covered in depth in **[references/prediction-and-latency.md](references/prediction-and-latency.md)**:
+
+1. **Client-side prediction** — the owning client applies its own input *immediately* instead of waiting a
+   full RTT for the server, so local movement feels instant.
+2. **Server reconciliation** — the server is still authoritative; the client tags each input with a sequence
+   number, and when the authoritative state arrives it *replays* any inputs the server hadn't processed yet.
+   Mismatch → a correction (the visible "rubber-band"); minimize it, don't hide it.
+3. **Snapshot interpolation** — *remote* entities are rendered ~100 ms in the past, interpolating between the
+   last two received snapshots, so other players move smoothly instead of teleporting between updates.
+4. **Lag compensation** — for hitscan/instant hits, the server rewinds other entities to where the shooter
+   *saw* them (at the shooter's render time) before testing the hit. Fairer for the shooter; occasionally
+   "shot behind a wall" for the victim. A deliberate tradeoff, not a bug.
+
+**Tick rate / netrate:** the server simulates at a fixed tick (e.g. 20–64 Hz) and sends state at a *send
+rate* that may be lower than its sim rate and decoupled from client render FPS. Never tie gameplay to frame
+rate on a networked game — simulate on a fixed timestep, interpolate for rendering.
+
+## Per-engine mapping
+
+Short form here; full patterns in the references. All snippets are current-API.
+
+### Godot 4.x — high-level multiplayer
+
+`ENetMultiplayerPeer` for transport, `@rpc` for events, `MultiplayerSynchronizer` for state, and
+`MultiplayerSpawner` to replicate object spawns. Authority via `set_multiplayer_authority(peer_id)`.
+
+```gdscript
+# Host / join
+func host(port := 9999) -> void:
+    var peer := ENetMultiplayerPeer.new()
+    peer.create_server(port, 8)
+    multiplayer.multiplayer_peer = peer
+
+func join(ip: String, port := 9999) -> void:
+    var peer := ENetMultiplayerPeer.new()
+    peer.create_client(ip, port)
+    multiplayer.multiplayer_peer = peer
+
+# RPC: params are optional and order-free. any_peer lets clients call it;
+# authority (default) means only the multiplayer authority may call it.
+@rpc("any_peer", "call_local", "reliable")
+func request_fire(target: Vector3) -> void:
+    if not multiplayer.is_server(): return          # server validates
+    var shooter := multiplayer.get_remote_sender_id()
+    _resolve_shot(shooter, target)                  # server decides the result
+```
+
+- `set_multiplayer_authority(id)` on a node; check with `is_multiplayer_authority()`. A player scene
+  usually gives its input node authority to the owning peer while the server keeps authority over health.
+- `MultiplayerSynchronizer` streams a chosen property list (position, etc.) from the authority to peers;
+  set its replication interval and visibility (`set_visibility_for(peer, bool)`) to scope bandwidth.
+- `MultiplayerSpawner` replicates instancing of scenes under a path so late peers get existing objects.
+- Details, prediction wiring, and the full player-scene pattern:
+  **[references/godot-high-level-multiplayer.md](references/godot-high-level-multiplayer.md)**.
+
+### Unity — Netcode for GameObjects
+
+`NetworkObject` (the identity, spawned via `Spawn()`), `NetworkBehaviour` (networked scripts),
+`NetworkVariable<T>` (replicated state), and RPCs. `NetworkManager.Singleton.StartHost/StartServer/StartClient`.
+
+```csharp
+public class Player : NetworkBehaviour {
+    // Default perms: everyone reads, only the SERVER writes → authoritative health.
+    public NetworkVariable<int> Health = new(100);
+
+    [Rpc(SendTo.Server)]                       // client → server: an intent
+    void FireRpc(Vector3 target) {
+        // runs on the server; validate, then apply and let NetworkVariables replicate the result
+        ResolveShot(OwnerClientId, target);
+    }
+
+    [Rpc(SendTo.ClientsAndHost)]               // server → everyone: an event
+    void PlayMuzzleFxRpc(Vector3 at) { /* cosmetic only */ }
+}
+```
+
+- Ownership/role: `IsOwner`, `IsServer`, `IsClient`, `IsHost`, `OwnerClientId`. Only owners should send
+  owner-intent RPCs; the server validates regardless.
+- `NetworkVariable<T>(value, readPerm, writePerm)` — `NetworkVariableWritePermission.Server` (default) vs
+  `.Owner`; subscribe via `OnValueChanged`. Use `NetworkTransform` for pos/rot sync.
+- Prefer the unified `[Rpc(SendTo.X)]`; legacy `[ServerRpc]`/`[ClientRpc]` still work but need the
+  method-name suffixes. Full patterns:
+  **[references/unity-and-unreal-netcode.md](references/unity-and-unreal-netcode.md)**.
+
+### Unreal — Actor replication
+
+Set `AActor::bReplicates = true` (or `SetReplicates(true)`). Replicate properties with `UPROPERTY` and
+register them in `GetLifetimeReplicatedProps`; use RPC `UFUNCTION` specifiers for events.
+
+```cpp
+UPROPERTY(ReplicatedUsing = OnRep_Health)   // RepNotify fires on clients when it changes
+float Health = 100.f;
+
+UFUNCTION(Server, Reliable, WithValidation)  // client → server intent (+ validation)
+void ServerFire(FVector Target);
+
+UFUNCTION(NetMulticast, Unreliable)          // server → all: cosmetic event
+void MulticastMuzzleFx(FVector At);
+
+void AMyPawn::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& Out) const {
+    Super::GetLifetimeReplicatedProps(Out);
+    DOREPLIFETIME(AMyPawn, Health);          // or DOREPLIFETIME_CONDITION for push/owner-only
+}
+```
+
+- Authority check: `HasAuthority()` (server or standalone); roles `ROLE_Authority`, `ROLE_AutonomousProxy`
+  (the owning client), `ROLE_SimulatedProxy` (observed elsewhere).
+- **Relevancy** keeps bandwidth sane: `NetCullDistanceSquared`, `bAlwaysRelevant`, `IsNetRelevantFor`, and
+  dormancy (`SetNetDormancy`) stop replicating actors a client can't perceive. Movement replicates via
+  `CharacterMovementComponent`, which already does prediction+reconciliation for you.
+- RepNotify vs Multicast, GAS/Network Prediction notes:
+  **[references/unity-and-unreal-netcode.md](references/unity-and-unreal-netcode.md)**.
+
+## Security / anti-cheat basics
+
+- **Validate every client input on the server** — bounds-check movement deltas, cooldowns, line-of-sight,
+  and resource costs. Reject the impossible; never assume a well-behaved client.
+- **Send a client only what it may know.** Don't replicate enemy positions through walls (wallhack fuel),
+  full inventories of others, or hidden RNG seeds — scope with relevancy/visibility.
+- Rate-limit and sanity-check RPCs; a client spamming `ServerFire` faster than the weapon allows is caught
+  by server-side cooldowns, not client-side ones.
+- Encryption/DTLS stops packet tampering on the wire but does **not** stop a modified client — only server
+  authority does. Treat anti-cheat as defense in depth, not a product this skill ships.
+
+## Testing multiplayer locally
+
+- **Godot:** enable *Debug → Run Multiple Instances* (2–4 windows) to host+join on one machine.
+- **Unity:** *Multiplayer Play Mode* (or ParrelSync) runs several virtual players from one project;
+  Network Simulator injects latency/loss.
+- **Unreal:** PIE *Number of Players* + *Net Mode* (Play As Listen Server / Client), and *Net PktLag* /
+  packet-emulation console vars to fake latency.
+- Always test **with simulated latency and packet loss**, not just on localhost — localhost hides every
+  prediction/reconciliation bug. Test the client path, not only the host's.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Writing net code before the topology is chosen | Authority and cost model change everything downstream | Pick dedicated / listen / P2P first, and make the *same code* run on server and listen host |
+| Trusting a client-reported result (health, position, score, hit) | That is the cheat surface, and lag looks identical to cheating | Clients send intent only; the server validates and owns all gameplay state |
+| RPCing state that must stay consistent | A dropped unreliable event desyncs that client permanently | Replicate nouns (state), RPC verbs (events) — replicated values self-correct |
+| Ownership/authority left implicit | The #1 cause of "works for the host, breaks for the client" | Set authority/ownership explicitly on spawn |
+| Forgetting the listen-server host is also a client | Authority-only logic double-executes on the host | Guard it behind `is_server()` / `HasAuthority()` |
+| Making the owning client wait a full RTT for its own input | Movement feels sluggish and unresponsive | Predict locally + reconcile; snapshot-interpolate remote entities |
+| Client-side hit detection for hitscan | Trivially spoofed, and unfair to the higher-ping shooter | Server-side lag compensation: rewind to the shooter's render time |
+| Tying simulation to render FPS | Sim diverges between machines at different frame rates | Fixed timestep on the sim, interpolate on the render |
+| Replicating everything, every tick, to everyone | Melts bandwidth and leaks wallhack fuel | Scope by relevancy/visibility and send rate; rate-limit RPCs |
+| Testing only on localhost | 0 ms RTT masks the exact desync/rubber-band bugs players will hit | Inject latency + packet loss across instances, exercising the client path |
+| Emitting UNet/HLAPI, Godot 3.x `master`/`puppet`/`rset`, or `Tick`-polled Unreal replication | Removed or legacy — it will not compile or will silently underperform | The current APIs in the version contract above |

package/skills/shared/gamedev-multiplayer/evals/README.md

@@ -0,0 +1,12 @@
+# Eval harness — `gamedev-multiplayer` skill
+
+`cases.yaml` is a human/CI-readable trigger-and-capability spec, not an automated runner. Load the full
+skill-catalog descriptions into a routing agent and, for each `should_trigger` prompt, confirm this skill
+fires (including the near-miss phrasings that never say "netcode"); for each `should_not_trigger` prompt,
+confirm it stays silent and that whatever does fire matches the stated `route_to` sibling (godot, deployment,
+gamedev-physics, webhooks, secure-coding). Because LLM routing is non-deterministic, run several trials and
+take the majority. For the `capability` scenario, run it once with the skill body unavailable and once with
+`SKILL.md` + references loaded, then check each output against `must_include` — the with-skill answer must
+use current APIs (ENetMultiplayerPeer, `@rpc("any_peer", …)`, `is_server()` authority gate, no Godot 3.x
+`master`/`puppet`/`rset`) and clearly beat the baseline. Keep `cases.yaml` in sync with SKILL.md's
+"Fires on / When NOT" whenever scope changes.