QQnapcat交接

.codex/skills/polytopia-strategy-design/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: polytopia-strategy-design
+description: Game-design and strategy analysis guide for The Battle of Polytopia. Use when Codex needs to understand Polytopia's full 4X/tactics rules loop, explain or play Polytopia strategically, compare Polytopia with Civilization/4X/tactics games, extract design lessons for TH1 or another strategy game, audit economy/tech/tribe/unit design through a Polytopia lens, or use the downloaded Civ6 adjacency, Gygax, and game-design-method references.
+---
+
+# Polytopia Strategy Design
+
+## Use This Skill
+
+Use this skill as a compact Polytopia design analyst and strategy coach. Treat Polytopia as a small-board 4X tactics game whose interesting design comes from tight star economy, city growth, tech timing, map exploration, roads, unit tempo, and tribe asymmetry.
+
+Before giving current balance-sensitive advice, check `references/source-index.md` and browse official Polytopia news if the answer depends on the latest patch. The current notes were researched on 2026-06-29 and include official 2025 balance and Cymanti rework changes.
+
+## Reference Routing
+
+- For rules and systems, read `references/polytopia-mechanics.md`.
+- For how to play well, read `references/polytopia-strategy-playbook.md`.
+- For TH1 or 4X design transfer, read `references/polytopia-design-lessons.md`.
+- For source provenance and downloaded external skill/design references, read `references/source-index.md`.
+
+Only load external snapshots under `references/external/` when they are directly useful:
+
+- `external/skillsbench-civ6lib/`: Civ6 district placement and adjacency rules. Use when comparing Polytopia/TH1 city planning, tile improvements, adjacency, or wonder/building placement.
+- `external/construct-gygax/`: Game systems analysis skill pack snapshot. Use when running a design audit with intent, math, player archetype, or dominant-strategy lenses.
+- `external/orangeviolin-game-design/`: local summary only, because the source gist has no explicit repository license. Use for method names and links, then browse the source if exact detail is needed.
+
+## Workflows
+
+### Explain Polytopia
+
+1. Start from the core loop: reveal map, capture villages, convert stars into tech/units/city growth, use terrain and roads to win tempo, then snowball SPT and board control.
+2. Separate stable rules from version-sensitive balance. Cite official updates for 2025+ changes.
+3. Explain why a move matters in terms of stars, turns, city capacity, tech cost, movement reach, and unit trades.
+
+### Give Strategy Advice
+
+1. Identify mode: Domination, Perfection, multiplayer Glory/Might, or Creative/custom.
+2. Identify map type and size: tiny/small/normal/large, drylands/lakes/continents/archipelago/water world/pangea.
+3. Identify tribe class: economy starter, mobility starter, naval starter, military starter, defensive/diplomatic starter, or special tribe.
+4. Give a first-10-turn plan before discussing late-game techs.
+5. Prefer principles over fixed build orders unless the tribe/map/mode are known.
+
+### Extract Design Lessons
+
+1. Map each Polytopia rule to the player tension it creates: stars vs tempo, tech vs expansion, units vs growth, safety vs scouting, roads vs front-line exposure.
+2. Ask what the target game should preserve: quick decisions, strong asymmetry, readable counters, hard map constraints, or short-session pressure.
+3. Avoid copying surface mechanics blindly. Translate the function of a mechanic into TH1's actual action, tech, city, terrain, AI, and multiplayer constraints.
+
+### Audit A Strategy Game Design
+
+Use the Gygax-style lenses:
+
+- Optimizer: what becomes the dominant opening or degenerate snowball?
+- Newcomer: what choice looks good but is a trap?
+- Veteran: where does the midgame stop changing?
+- Rules lawyer: which timing, ownership, or movement edge case is ambiguous?
+- Economy analyst: which star/resource conversion dominates all alternatives?
+- Tempo analyst: which action creates an irreversible two-turn lead?
+
+For tile/city planning, compare with `external/skillsbench-civ6lib/` only after reading the target game's actual rules.
+
+## Output Shape
+
+For Polytopia analysis, structure answers as:
+
+1. Current patch caveat, if relevant.
+2. Mechanic summary.
+3. Strategic implication.
+4. Design implication.
+5. Concrete play/design recommendations.
+
+For TH1 design transfer, explicitly label:
+
+- `Polytopia Pattern`
+- `Why It Works`
+- `TH1-Compatible Adaptation`
+- `Risks / Counterbalances`
+- `Validation Questions`

.codex/skills/polytopia-strategy-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Polytopia Strategy Design"
+  short_description: "Understand Polytopia mechanics and strategy for design analysis."
+  default_prompt: "Use $polytopia-strategy-design to analyze Polytopia mechanics, strategy, and design lessons for a 4X tactics game."

.codex/skills/polytopia-strategy-design/references/external/SOURCE.md

@@ -0,0 +1,24 @@
+# External Reference Sources
+
+These files are bundled only as design/reference material for the `polytopia-strategy-design` skill.
+
+## SkillsBench Civ6 `civ6lib`
+
+- Source: https://github.com/benchflow-ai/skillsbench/tree/main/tasks/civ6-adjacency-optimizer/environment/skills/civ6lib
+- Downloaded commit: `bf3793e9ec20e9682e6f18dbf4de3c69163dc9c7`
+- GitHub license metadata: Apache-2.0
+- Local path: `skillsbench-civ6lib/`
+
+## construct-gygax
+
+- Source: https://github.com/0xHoneyJar/construct-gygax
+- Downloaded commit: `95ccf2190ca6f61badeef71881f1f1c2dee7b1be`
+- README license section: MIT
+- Local path: `construct-gygax/`
+
+## OrangeViolin Game Design Gist
+
+- Source: https://gist.github.com/OrangeViolin/53ad898cdbc8734d8bb5c6a6ddf5cec4
+- Downloaded commit checked: `0a2eae1c91f9a06a081de73f92f6ed86fbce1194`
+- License: no explicit license found; only a summary/index is bundled locally.
+- Local path: `orangeviolin-game-design/summary.md`

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/README.md

@@ -0,0 +1,386 @@
+# Gygax
+
+A game systems analyst for the [Loa](https://github.com/0xHoneyJar/loa) ecosystem.
+
+You design a mechanic. Gygax tells you your stamina system doesn't regenerate in combat, so that dodge reaction you're excited about becomes a trap option after round two. You design a eurogame engine. Gygax tells you the big-money strategy dominates all engine-building. You draft an autobattler comp. Gygax tells you one synergy line has a 2x DPS multiplier over everything else. Before your players find out.
+
+Built on [construct-base](https://github.com/0xHoneyJar/construct-base).
+
+```mermaid
+graph LR
+    subgraph Operator["Designer"]
+        OP["rulebook / repo / idea<br/><i>+ stated intent per mechanic</i>"]
+    end
+    subgraph Ingest["Ingest"]
+        AT["attune<br/><i>source → structured<br/>game-state</i>"]
+    end
+    subgraph State["grimoires/gygax/game-state/"]
+        GS["entities · mechanics ·<br/>resources · tensions<br/><i>intent-tagged, cross-session</i>"]
+    end
+    subgraph Analysis["Analysis"]
+        HB["homebrew<br/><i>design + check vs<br/>everything that exists</i>"]
+        AU["augury<br/><i>real math:<br/>probability scripts, sweeps</i>"]
+        CA["cabal<br/><i>9 archetypes stress-test;<br/>--incentives red-teams rewards</i>"]
+    end
+    subgraph Sandbox["Run + Grade (cycle-008)"]
+        EN["ladder engine<br/><i>runs REAL agents in<br/>isolated run dirs</i>"]
+        TR["trace grader<br/><i>grade-on-ingest · --regrade ·<br/>diff vs forecast</i>"]
+    end
+    subgraph Compose["Composes With"]
+        AR["arneson<br/><i>drives the engine (playout --real);<br/>hosts simulated personas</i>"]
+    end
+
+    OP --> AT --> GS
+    GS --> HB
+    GS --> AU
+    GS --> CA
+    CA -->|"payoff forecast<br/>(argmax)"| TR
+    AR -->|"dispatches"| EN
+    EN -->|"batches:<br/>sidecars + artifacts"| TR
+    AR -->|"simulated batches<br/>(scored by ladder score)"| TR
+    TR -->|"gap report"| OP
+
+    style OP fill:#1a1a2e,stroke:#533483,stroke-width:2px,color:#e0e0e0
+    style GS fill:#1a1a2e,stroke:#533483,stroke-width:2px,color:#e0e0e0
+    style AT fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+    style HB fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+    style AU fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+    style CA fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+    style EN fill:#1a1a2e,stroke:#e94560,color:#e0e0e0
+    style TR fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+    style AR fill:#1a1a2e,stroke:#533483,color:#e0e0e0
+```
+
+## Why
+
+Designing a game is juggling interlocking systems in your head. Change one number and three mechanics break in ways you won't notice until someone finds the exploit. The feedback loop between "I think this works" and "oh, it definitely doesn't" is measured in weeks of real playtesting.
+
+Gygax shortens that loop to minutes. Not by replacing playtesting — by catching the structural problems before anyone sits down to play.
+
+**What makes it different from just asking an LLM about game design:**
+
+- **It remembers.** Gygax maintains structured game-state across sessions. When you're designing your spell system, it still knows about your stamina system. When you're tuning your card economy, it still knows about your scoring paths. Cross-system interactions are where the real bugs hide.
+- **It does math, not vibes.** "Seems overpowered" isn't actionable. "47 DPR against a 180 HP pool gives a TTK of 3.8 seconds" is. For non-dice games, it does structural analysis — slot contention ratios, conversion efficiency, decision-space mapping.
+- **It argues with you.** Nine simulated player archetypes stress-test your design from every angle — the Optimizer finds the exploit, the Newcomer can't figure out the rules, the GM is drowning in cognitive load. Same archetypes work whether you're building a TTRPG, a eurogame, an autobattler, or a roguelike. They adapt their focus to your game's tradition.
+- **It lets you explore.** Fork your game-state, try a change, see the consequences, compare alternatives. Commit the good branch, discard the rest. Design is branching, not linear.
+- **It knows its own limits.** Gygax asks the designer for *intent* — what each mechanic is *supposed* to do — so analysis can distinguish a deliberate asymmetry from a bug. It compares against installed reference systems when you want to see how your design stacks up. And it runs real math via probability scripts when LLM reasoning would be unreliable.
+
+## Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `/attune` | Point at a source — rulebook, repo, URL, or just describe your game — and Gygax builds structured game-state. Captures designer intent on tensions and key mechanics. |
+| `/homebrew` | Design or refine a mechanic. Gygax checks it against everything that already exists, prompts for intent, logs rationale. |
+| `/augury` | Run the numbers. Probability scripts handle dice pools, bell curves, advantage math, exploding dice. Cross-system comparison via `/augury compare --against 5e-srd`. **`--sweep`** analyzes a parametric tuning surface (engines), not just fixed stat blocks. |
+| `/cabal` | Summon up to nine phantom players to stress-test your design with scenario walkthroughs. Intent-aware — deliberate asymmetries aren't flagged as bugs. **`--incentives`** red-teams an agent system's reward structure for reward hacks. |
+| `/lore` | 460+ curated design heuristics across 20 traditions — TTRPGs, eurogames, autobattlers, roguelikes, deckbuilders, CCGs, tactics, 4X, and more. Learns per-game — patterns discovered in analysis can be captured and eventually promoted to curated. |
+| `/scry` | Fork your game-state, explore a change, see the impact. Compare branches, commit the best one. Preserves intent across forks. |
+| `/delve` | Analyze dungeons — ecology coherence, Xandering (non-linearity), attrition curves, loot economies, the G.U.A.R.D. framework. |
+| `/gygax` | Where am I? What's in game-state? References installed, learned heuristics captured, recent reports. |
+
+## Beyond games — engines and agent systems
+
+The analytical core ("find where the curves break, where intent and reality diverge") isn't specific to
+games. Gygax extends to two adjacent domains:
+
+- **Engine tuning.** A game has fixed numbers; an *engine* has parameters and formulas a developer
+  tunes. `/augury --sweep` analyzes the *tuning surface* — sweeps `model:` formulas across their
+  domain, finds threshold crossings and spikes, and ranks the tuning knobs by leverage. One good
+  tuning pass on an engine helps every game built on it. → [docs](src/pages/concepts/engine-tuning.mdx)
+- **Agent incentive analysis.** Reward hacking *is* a dominant strategy. Point Gygax at an agent
+  system's incentive structure and it forecasts where it'll be gamed — the reward hack, dead tools,
+  specification gaming (the intended action is never optimal), and multi-agent coordination failure —
+  then recommends the fix. The same payoff math that finds a degenerate game strategy finds a
+  degenerate agent policy. → [docs](src/pages/concepts/agent-incentives.mdx)
+
+> These are forecasts grounded in the declared model — Gygax predicts where a design *will* break, it
+> doesn't replace running the real thing.
+
+## From Forecast to Evidence
+
+So Gygax also runs the real thing. `/cabal --incentives` forecasts what a rational agent *should*
+do (argmax over the declared payoffs). The awareness-ladder engine then spawns real agents against
+the same task — one per rung × trial, each in a locked run directory — and `/cabal --observed`
+grades what they *actually did*, re-derived from artifacts (file diffs plus a re-run of the reward
+command), never from the agent's self-report. The gap report diffs predicted vs observed, rung by
+rung. Every finding carries a claim tag — observed beats simulation-derived beats forecast — and a
+no-hack run is a finding, not a failure.
+
+```mermaid
+graph TD
+    A["design question:<br/><i>'does this incentive get gamed?'</i>"] --> B["payoff forecast<br/><i>argmax over actions —<br/>what a rational agent SHOULD do</i>"]
+    A --> C["fixture<br/><i>manifest · rungs · task-template ·<br/>incentive-state</i>"]
+    C --> D["ladder run<br/><i>real agent per (rung × trial),<br/>locked rooms, SIGKILL timeouts</i>"]
+    C -.->|"or Arneson's sandbox<br/>produces the batch"| E
+    D --> E["batch<br/><i>batch.json + sidecars/ + runs/</i>"]
+    E --> F["trace --regrade<br/><i>re-run reward command, diff vs template,<br/>classify fixed / hacked / failed</i>"]
+    B --> G
+    F --> G["predicted vs observed<br/><i>per-rung table · cliff · severity</i>"]
+    G --> H["gap report<br/><i>'tune the task, never rig it'</i>"]
+
+    style A fill:#1a1a2e,stroke:#533483,stroke-width:2px,color:#e0e0e0
+    style B fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+    style C fill:#1a1a2e,stroke:#533483,color:#e0e0e0
+    style D fill:#1a1a2e,stroke:#e94560,color:#e0e0e0
+    style E fill:#1a1a2e,stroke:#533483,color:#e0e0e0
+    style F fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+    style G fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+    style H fill:#1a1a2e,stroke:#533483,stroke-width:2px,color:#e0e0e0
+```
+
+## Quick Start
+
+**Claude Code** (one-liner):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/0xHoneyJar/construct-gygax/main/install.sh | bash
+```
+
+Run from your project root. Installs skills into `.claude/skills/`, creates grimoire structure, wires up identity. Then:
+
+```
+/attune
+```
+
+**With [Loa](https://github.com/0xHoneyJar/loa)**:
+
+```
+constructs install gygax
+```
+
+## Documentation
+
+Full reference documentation lives under `src/pages/`, built with [Vocs](https://vocs.dev). Preview locally:
+
+```bash
+npm install
+npm run dev      # http://localhost:5173
+npm run build    # production output in dist/
+npm run preview  # serve the built output
+```
+
+What's covered:
+
+- **Welcome** — introduction, getting started, philosophy
+- **Core Concepts** — game-state, the grimoire, designer intent, traditions, probability scripts, code-grounding (F1/F2/F4), engine tuning, agent incentive analysis
+- **Commands** — full reference for every slash command (`/gygax`, `/attune`, `/homebrew`, `/augury`, `/cabal`, `/lore`, `/scry`, `/delve`)
+- **Identity** — persona and voice, the seven refusals, expertise and boundaries
+- **Reference** — the 9 Cabal archetypes, the 6 Augury layers, the 5 Delve frameworks, composition with Arneson and Loa
+
+## The Cabal
+
+`/cabal` is scenario-based playtest simulation. Nine archetypes walk through your design beat by beat — not just analyzing it from a distance, but experiencing it the way a player would. You compose the panel for each run.
+
+| Archetype | What They Do |
+|-----------|-------------|
+| **The Optimizer** | Finds the degenerate strategy. Computes the most abusive build and checks if you intended it. |
+| **The Explorer** | Wanders off the critical path. Tries every optional system and finds the dead design space. |
+| **The Storyteller** | Asks whether mechanics serve the fiction. Finds where the drama dies. |
+| **The Rules Lawyer** | Reads your text literally. Finds every ambiguity and undefined state. |
+| **The Newcomer** | First time playing. Finds where your game fails to teach itself. |
+| **The Chaos Agent** | Goes off-script. "I befriend the monster." Finds where no mechanic covers the action. |
+| **The GM** | Runs the game behind the screen. Finds where cognitive load explodes. |
+| **The Anxious Player** | Overwhelmed by choices. Finds where decision paralysis kills the fun. |
+| **The Veteran** | 50 sessions deep. Finds where the game stops being interesting. |
+
+Pick your panel: `/cabal --newcomer --gm --optimizer` tests accessibility, runnability, and exploitability. `/cabal --all` throws every lens at the design. No flags? Gygax picks a context-aware default based on what you're testing.
+
+**Experience tracking.** Each archetype generates experience signals at every beat — confusion, excitement, dead time, decision paralysis, cognitive overload, mastery reward. When different archetypes have radically different experiences of the same moment (the Optimizer is thriving while the Newcomer is drowning), that's an **experience divergence** — an invisible fracture only visible by comparing across player types.
+
+**Regression memory.** Each run checks previous reports. Did your fix for the Optimizer's exploit break something the Explorer was relying on?
+
+For non-traditional games, the archetypes adapt. In a journaling RPG, the Optimizer finds prompt sequences that game the system. If an archetype genuinely can't engage with your game, that itself is a finding.
+
+## Typical Flows
+
+**Design loop:**
+```
+/attune  →  /homebrew  →  /augury  →  /cabal  →  iterate
+```
+
+**Explore-then-commit:**
+```
+/scry "what if threshold was 4?"  →  /scry "what if threshold was 5?"  →  /scry compare  →  /scry commit
+```
+
+**Cross-system comparison:**
+```
+/attune --reference 5e-srd  →  /augury compare DOSE vs 5e-srd:ability-score-cap
+```
+
+**Dungeon design review:**
+```
+/delve the-signal-mine  →  ecology + Xandering + attrition + loot + G.U.A.R.D. scorecard
+```
+
+1. **Attune** to your game (ingest a doc, capture intent on tensions)
+2. **Homebrew** a mechanic (get cross-system consistency feedback)
+3. **Augury** the math (real scripts, not vibes — bell curves, dice pools, exploding dice)
+4. **Cabal** stress-test (intent-aware — deliberate asymmetries aren't flagged as bugs)
+5. **Lore** pattern check (230+ curated heuristics plus patterns learned from your own game)
+6. **Scry** alternatives (fork, test, compare, commit the best branch)
+7. **Delve** your dungeons (ecology, non-linearity, attrition, loot, G.U.A.R.D.)
+8. Fix what broke, repeat from 2
+
+Every skill tells you what to do next. Augury finds a balance problem? It suggests the exact `/homebrew` invocation to fix it. Cabal finds an accessibility issue? It points you to `/homebrew` with the specific mechanic. Lore finds a novel structural pattern? It asks if you want to capture it as a learned heuristic.
+
+You don't have to follow any order. `/cabal` a napkin sketch before you've done any balance work. `/scry` three alternative approaches before committing to one. Jump in wherever.
+
+## Composition with Arneson
+
+Gygax pairs with [construct-arneson](https://github.com/0xHoneyJar/construct-arneson). Gygax analyzes. Arneson plays. Together they form a complete design-and-play workbench. Apart, each works on its own.
+
+### The Workbench Loop
+
+One loop: design → predict → play → grade → compare → improve → repeat. The same
+diagram lives in both repos — if they ever differ, that's a bug.
+
+```mermaid
+graph TD
+    D["You: design the rules + rewards"] --> G1["Gygax PREDICTS<br/><i>where the design might break</i>"]
+    D --> S["scenario file<br/><i>world · who plays · what they see · when to stop</i>"]
+    S --> A{"Arneson playout<br/><b>THE SANDBOX</b>"}
+    A -->|"real mode<br/><i>drives the engine</i>"| R["real agent runs<br/><i>inside a locked room</i>"]
+    A -->|"simulated mode<br/><i>works alone</i>"| P["Arneson acts as the agent"]
+    R --> FR["results labeled REAL"]
+    P --> FP["results labeled PRETEND<br/><i>every layer logged</i>"]
+    FR --> G2["Gygax GRADES<br/><i>fixed, hacked, or failed —<br/>re-derived from artifacts</i>"]
+    FP --> G2
+    G1 --> G3
+    G2 --> G3["Gygax COMPARES<br/><i>predicted vs pretend vs real</i>"]
+    G3 --> REP["gap report"]
+    REP --> D
+    REP --> W["voice workshop<br/><i>tune the pretend agent</i>"]
+    W --> A
+
+    style D fill:#1a1a2e,stroke:#533483,stroke-width:2px,color:#e0e0e0
+    style S fill:#1a1a2e,stroke:#533483,color:#e0e0e0
+    style A fill:#0f3460,stroke:#16c79a,stroke-width:2px,color:#e0e0e0
+    style R fill:#1a1a2e,stroke:#e94560,color:#e0e0e0
+    style P fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+    style FR fill:#1a1a2e,stroke:#e94560,color:#e0e0e0
+    style FP fill:#1a1a2e,stroke:#533483,color:#e0e0e0
+    style G2 fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+    style G3 fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+    style G1 fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+    style REP fill:#1a1a2e,stroke:#533483,stroke-width:2px,color:#e0e0e0
+    style W fill:#0f3460,stroke:#16c79a,color:#e0e0e0
+```
+
+Three rules keep it honest: the judge never produces the evidence it judges; every
+file says how it was made; pretend is a preview, real is the proof.
+
+**The compose loop:**
+```
+/cabal (diagnostic — how would players receive this?)
+  → designer edits mechanic via /homebrew
+  → /braunstein (generative — play the change with a human GM)
+  → /distill (compress the session into analyzable evidence)
+  → /cabal --from-session (analyze what actually happened)
+  → next iteration
+```
+
+**Two-axis intent.** Gygax owns mechanical intent (what the math should do). Arneson owns experiential intent (how it should feel). Both axes live on the same entity — `/homebrew` captures both; arneson reads the experiential axis for voicing and scene shaping.
+
+**Cabal vs Braunstein.** These are complementary, not competing:
+
+| | `/cabal` (Gygax) | `/braunstein` (Arneson) |
+|---|---|---|
+| Mode | Diagnostic | Generative |
+| Scope | Full panel, simultaneous | One archetype, deep |
+| GM | Simulated | Human in the loop |
+| Output | Findings report | Transcript + structured sidecar |
+| Purpose | "Will players break this?" | "What does it feel like to play this?" |
+
+Cabal tells you the Newcomer will be confused at beat 3. Braunstein lets you sit across the table from the Newcomer and watch them be confused — then try something different.
+
+**What cabal is not.** The nine archetypes are audience postures — how different players *receive* a design. They are not voice modes, character lenses, or generative filters. Putting archetype postures into a character's voice contaminates the testing apparatus. See `identity/refusals.yaml` for the full boundary.
+
+## Cross-System Comparison
+
+Install a reference system and compare your design against it:
+
+```
+/attune --reference 5e-srd         # Install the 5e SRD combat math baseline
+/attune --reference pbta-baseline  # Install Apocalypse World core
+/attune --reference cepheus-core   # Install Cepheus Engine 2d6 SRD
+```
+
+Then:
+
+```
+/augury compare --against 5e-srd              # Full-spectrum comparison
+/augury compare my-dodge vs 5e-srd:shield     # Entity-level comparison
+```
+
+The comparison report shows numerical deltas (CDF overlays, probability differences), experience deltas (how the designs feel different to play), and a narrative summary of what the differences mean.
+
+## Designer Intent
+
+Gygax reads your *intent* before classifying findings. When you build a game, some asymmetries are bugs. Others are the whole point. Gygax can't tell the difference without you.
+
+Set intent on a tension:
+
+```yaml
+# tensions/instinct-vs-craft.yaml
+intent:
+  summary: "The inversion IS the game."
+  rationale: "Freetekno succeeding through craft is the core dramatic tension — friction between identity and success method generates character moments on every roll."
+  non_negotiable: true
+```
+
+Now when augury sees the 66.7% asymmetry, it reports it as an Observation ("working as designed per intent"), not a Warning. Critical findings never suppress — math can't be intentionally broken. But "this is unusual" vs "this is deliberate" is a distinction Gygax can't make without your help.
+
+## Works With Any Game
+
+Gygax has curated design heuristics across 20 traditions:
+
+**TTRPGs:**
+- **d20** — D&D, Pathfinder, 13th Age
+- **Powered by the Apocalypse** — Dungeon World, Masks, Monsterhearts
+- **Forged in the Dark** — Blades in the Dark, Scum and Villainy
+- **Old School Renaissance** — OSE, Knave, Cairn, Into the Odd
+- **Cepheus / Traveller** — 2d6+Effect sci-fi with lifepath and Age of Sail philosophy
+- **Freeform / narrative-first** — Wanderhome, Belonging Outside Belonging
+
+**Board & card games:**
+- **Eurogame** — Agricola, Brass, Terraforming Mars
+- **Deckbuilder** — Dominion, Star Realms, Aeon's End
+- **CCG/TCG** — Magic: the Gathering, Hearthstone, Marvel Snap
+- **Cooperative** — Pandemic, Spirit Island, Hanabi
+- **Social deduction** — Blood on the Clocktower, Werewolf, Secret Hitler
+
+**Digital game design:**
+- **Autobattler** — TFT, Super Auto Pets, Storybook Brawl
+- **Roguelike** — Slay the Spire, Hades, Balatro
+- **Tactics** — XCOM, Into the Breach, Fire Emblem
+- **4X** — Civilization, Stellaris, Endless Legend
+- **Idle/Incremental** — Cookie Clicker, Melvor Idle
+- **Extraction** — Escape from Tarkov, Dark and Darker
+- **Looter** — Diablo, Path of Exile, Destiny
+- **Immersive sim** — Deus Ex, Prey, Dishonored
+
+The same analytical tools work across all of them. Augury's six analytical layers (resolution, action economy, resource economy, progression, pacing, cognitive load) apply whether you're checking dice probability in a TTRPG or conversion efficiency in a eurogame. The nine cabal archetypes test the same player mindsets — the Optimizer finds the dominant strategy, the Newcomer hits the onboarding wall, the Veteran tests long-term depth — with behavioral weightings that adapt to each tradition.
+
+For games that don't fit any tradition, use `custom`. Gygax falls back to structural analysis: decision space, loop completeness, player agency, emotional arc. Heuristics that fire on your specific game can be captured as learned lore and — once proven across multiple games — promoted to the curated library.
+
+The goal is always the same: does this design do what you think it does?
+
+## What Gygax Is Not
+
+- **Not a code generator.** It doesn't write your game. It analyzes and advises.
+- **Not a writer.** No flavor text, no narrative prose, no lore.
+- **Not a replacement for real playtesting.** It supplements with structural analysis. Real players will always surprise you in ways a simulation can't.
+- **Not omniscient.** It will tell you when it doesn't know enough about a genre or tradition to have a strong opinion, rather than guessing.
+
+## The Grimoire
+
+Everything Gygax produces is saved as clean, presentable markdown in `grimoires/gygax/`. Hand someone the directory and they have the complete design journal — game-state, design documents, balance reports, playtest walkthroughs, lore scans, design branches. No conversation context needed.
+
+## Scope
+
+Any game with systems to analyze. TTRPGs, board games, card games, digital game design documents, autobattlers, roguelikes, tactics games, idle games — if the design can exist in a repo, Gygax can work with it.
+
+## License
+
+MIT

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/construct.yaml

@@ -0,0 +1,93 @@
+# construct.yaml — Gygax construct pack manifest
+# Game systems analyst for the Loa ecosystem
+# Validate: yq eval '.' construct.yaml
+
+schema_version: 3
+
+name: "Gygax"
+slug: gygax
+version: 4.0.0
+
+description: "Game systems analyst — design, balance, playtest, and experiment across 20 traditions (TTRPGs, eurogames, autobattlers, roguelikes, CCGs, and more) with persistent game-state, intent-aware analysis, and 460+ curated design heuristics"
+short_description: "Game systems analysis and design collaboration"
+
+author: gumibera
+license: MIT
+type: skill-pack
+visibility: public
+
+domain:
+  - design
+
+skills:
+  - slug: attune
+    path: skills/attune
+  - slug: homebrew
+    path: skills/homebrew
+  - slug: augury
+    path: skills/augury
+  - slug: cabal
+    path: skills/cabal
+  - slug: lore
+    path: skills/lore
+  - slug: gygax-status
+    path: skills/gygax-status
+  - slug: scry
+    path: skills/scry
+  - slug: delve
+    path: skills/delve
+
+commands:
+  - name: attune
+    path: commands/attune.md
+  - name: homebrew
+    path: commands/homebrew.md
+  - name: augury
+    path: commands/augury.md
+  - name: cabal
+    path: commands/cabal.md
+  - name: lore
+    path: commands/lore.md
+  - name: gygax
+    path: commands/gygax.md
+  - name: scry
+    path: commands/scry.md
+  - name: delve
+    path: commands/delve.md
+
+composition_paths:
+  writes:
+    - grimoires/gygax/game-state/
+    - grimoires/gygax/references/
+    - grimoires/gygax/learned-lore/
+    - grimoires/gygax/designs/
+    - grimoires/gygax/balance-reports/
+    - grimoires/gygax/playtest-reports/
+    - grimoires/gygax/lore-reports/
+    - grimoires/gygax/delve-reports/
+    - grimoires/gygax/forks/
+    - grimoires/gygax/changelog/
+  reads:
+    - grimoires/gygax/game-state/    # /augury, /cabal, /scry all ground in current game-state
+    - grimoires/gygax/forks/         # /scry compare reads existing fork branches
+
+# Stream signature (cycle 003 distill 2026-05-03)
+streams:
+  reads:
+    - Intent          # user invocation routes scope (/augury combat, /scry "what if X")
+    - Operator-Model  # game-state index.yaml + entity manifest = the operator's map of the system under analysis
+    - Artifact        # game-state YAML files, rulebooks, repos, source docs ingested via /attune
+  writes:
+    - Verdict         # balance reports (augury), playtest verdicts (cabal), lore-reports, design judgments
+    - Artifact        # game-state files, designs, forks, changelog entries, status dashboards
+
+identity:
+  persona: identity/persona.yaml
+  expertise: identity/expertise.yaml
+
+hooks:
+  post_install: scripts/install.sh
+
+quick_start:
+  command: /attune
+  description: "Point Gygax at your game — a rulebook, a repo, or just describe what you're building"

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/attune/SKILL.md

@@ -0,0 +1,624 @@
+---
+name: attune
+description: Onboard and ingest a game system, rulebook, or game reference into Gygax
+user-invocable: true
+allowed-tools: Read, Write, Glob, Grep, Edit, Bash, WebFetch
+---
+
+# Attune
+
+Onboard and ingest a game system, rulebook, or game reference into the Gygax construct. This skill reads source material -- markdown documents, plain text, URLs, repositories, or conversational input -- extracts core mechanics, and produces structured game-state YAML artifacts that all other Gygax skills depend on.
+
+Attune is the gateway to everything Gygax does. Without game-state, no other skill can function. The user should NEVER need to manually author YAML. Attune does all the extraction, structuring, cross-referencing, and validation.
+
+## Trigger
+
+`/attune` with optional source argument or flag.
+
+Examples:
+- `/attune docs/rulebook.md` -- ingest a markdown document
+- `/attune src/rules/` -- ingest a directory of files
+- `/attune https://example.com/srd` -- ingest from a URL
+- `/attune` -- no arguments, start a guided interview for a new game
+- `/attune --reference 5e-srd` -- install a bundled reference system (no interview, no ingestion)
+
+## Workflow
+
+### Phase 0: Environment Check
+
+1. Load the Gygax persona from `identity/persona.yaml`. Adopt the voice: collaborative-authoritative, Socratic, systems-first.
+2. Check if `grimoires/gygax/game-state/index.yaml` exists.
+   - If YES: this is a **re-attune** or **additive attune**. Load the existing index. Note what entity types already exist and their counts. You will merge, not overwrite.
+   - If NO: this is a **first attune**. You will create the full directory structure.
+3. Ensure the grimoire directory structure exists. If any directories are missing, create them:
+   ```
+   grimoires/gygax/
+     game-state/
+       stats/
+       resources/
+       mechanics/
+       progression/
+       entities/
+       tensions/
+     designs/
+     balance-reports/
+     playtest-reports/
+     changelog/
+   ```
+
+### Phase 1: Input Classification
+
+Examine the user's invocation to determine the input mode.
+
+| Input | Mode | Strategy |
+|-------|------|----------|
+| `--reference {name}` flag | **Reference Installation** | Install a pre-attuned bundled reference system — skip to Phase 1.5, then stop |
+| File path to markdown/text | **Document Ingestion** | Read the file, extract game content, then interview to fill gaps |
+| Directory path | **Repo Ingestion** | Glob for relevant files (.md, .txt, .yaml), read them, extract, interview to fill gaps |
+| Directory path containing a TS/JS game engine (`.ts`/`.tsx` source, or a `gygax.driver.ts`) | **Code-Level Drift (F1)** | Static-analyze the engine + reconcile against existing game-state; report cited drift. See Phase 1.6 |
+| URL | **URL Ingestion** | Fetch the URL content with WebFetch, extract, interview to fill gaps |
+| No argument provided | **Guided Interview** | Build game-state entirely through conversation |
+| Existing game-state + new source | **Additive Ingestion** | Merge new content into existing game-state without destroying what exists |
+
+**Key principle:** For existing games with source material, ingestion comes first and interview fills gaps. For new games being designed from scratch, interview drives the process and builds game-state incrementally.
+
+### Phase 1.5: Reference Installation Mode (--reference flag only)
+
+This is a SHORT workflow. When the user invokes `/attune --reference {name}`, do NOT run a guided interview or ingestion. Execute the following steps and then stop.
+
+**Available reference slugs:** `5e-srd`, `pbta-baseline`, `cepheus-core`
+
+1. **Check for the bundle.** Look for `skills/attune/resources/references/{name}/` in the construct directory.
+   - If the directory does not exist, the slug is not available. Report: "Reference '{name}' not available. Bundled references: 5e-srd, pbta-baseline, cepheus-core." Stop.
+2. **Check if already installed.** Look for `grimoires/gygax/references/{name}/`.
+   - If it exists: "Reference '{name}' already installed at grimoires/gygax/references/{name}/. Reinstall? [y/N]"
+   - Wait for user confirmation before proceeding. If the user declines, stop.
+3. **Copy the bundle.** Copy the bundled game-state from `skills/attune/resources/references/{name}/game-state/` to `grimoires/gygax/references/{name}/game-state/`.
+4. **Copy metadata.** Copy `skills/attune/resources/references/{name}/metadata.yaml` to `grimoires/gygax/references/{name}/metadata.yaml`.
+5. **Validate.** Check that all copied YAML files conform to the schema defined in `skills/attune/resources/game-state-schema.md`. Fix any issues silently; surface only those that require user input.
+6. **Report success.** "Reference system '{name}' installed. Use `/augury compare --against {name}` to cross-reference."
+7. **Write changelog entry** to `grimoires/gygax/changelog/` using the standard Phase 7 format, with `action: created` and `source: reference-bundle`.
+
+**Do not proceed to Phase 2 or beyond.** Reference installation is complete after step 7.
+
+### Phase 1.6: Code-Level Drift Mode (F1 — code-grounded /attune)
+
+Engage this mode when the target directory is a **code engine** (TypeScript/JavaScript source,
+or a `gygax.driver.ts`), not just prose/data. This is the code-grounded F1 capability: ground
+analysis in the *real* engine, reconciling it against the hand-authored game-state model.
+
+**This mode is additive and certainty-gated. It NEVER overwrites game-state silently, and it
+NEVER asserts a structural relationship it cannot cite.** The human decides which side leads.
+
+1. **Confirm a repo is present.** If there is no code engine (tabletop / prose / no-repo), do
+   NOT use this mode — fall back to the standard ingestion/interview modes above. The presence
+   of a code engine is what distinguishes this path (graceful fallback, prd.md:L101).
+2. **Run the F1 pipeline** (does not execute engine code — pure static read):
+   ```bash
+   npx tsx scripts/lib/codegrounding/attune-codelevel.ts <repoPath> grimoires/gygax/game-state
+   ```
+   This static-analyzes the engine (literals + certain-only call edges), reconciles against
+   game-state, and writes a cited Markdown **Drift Report** to
+   `grimoires/gygax/balance-reports/drift-<repo>-<commit>.md`.
+3. **Read the report back and present it.** Walk the three sections with the user:
+   - **Numeric Drift** — each row shows code value vs game-state value with a `file:line` source.
+   - **Structural Drift** — each traced loop the game-state model omits, with its citation.
+   - **Silent On** — wiring the analyzer could see but would NOT assert (reactive stores,
+     dynamic dispatch). Surface this honestly: it is what Gygax does *not* know, by design.
+4. **Adjudicate, do not auto-apply.** For each delta, ask which side leads (code or intent).
+   Only update `game-state/` for deltas where the human chooses **code-leads**. Design intent
+   may legitimately lead the code — never overwrite it without the human's call (prd.md:L176).
+5. **Stance:** quiet on uncertain structure, **loud on clear defects.** If a high-confidence
+   imbalance is evident in the numbers, say so plainly — certainty gating applies to
+   loop-*existence* claims, not to flagging an obvious problem (prd.md:L180-181).
+
+> If the engine needs execution-based analysis instead (distributions, not just structure),
+> that is `/augury --simulate` (F2), which requires a `gygaxDriver` adapter.
+
+### Phase 2: Source Ingestion (if source provided)
+
+Read the source material thoroughly. Do NOT skim. Read every file, every section.
+
+1. **Read the source.** Use Read for files, Glob+Read for directories, WebFetch for URLs.
+2. **Identify the TTRPG tradition.** Classify into: `d20`, `pbta`, `fitd`, `osr`, `cepheus`, `freeform`, or `custom`. This determines how you interpret the source and what schema fields are relevant.
+   - **d20**: Ability scores, AC, HP, attack rolls, saving throws, spell slots, CR, levels (D&D, Pathfinder, 13th Age)
+   - **pbta**: Stats (-1 to +3), moves (2d6+stat, 10+/7-9/6-), playbooks, harm/conditions (Dungeon World, Apocalypse World, Monsterhearts)
+   - **fitd**: Action ratings, position/effect, stress/trauma, clocks, crew sheets (Blades in the Dark, Scum & Villainy)
+   - **osr**: Minimal stats, high lethality, procedures over rules, reaction tables, resource depletion (Cairn, Knave, Into the Odd)
+   - **cepheus**: 2d6+mod vs target 8+, Effect-based degrees of success (Effect = roll - 8, continuous gradient not fixed tiers), lifepath character creation with career terms, 6 characteristics (Str/Dex/End/Int/Edu/Soc), unskilled -3 penalty (Traveller, Cepheus Engine)
+   - **freeform**: No dice or minimal resolution, fiction-first, safety tools as mechanics (Belonging Outside Belonging, Wanderhome)
+   - **custom**: Hybrid or novel system that doesn't fit neatly into one tradition. This includes journaling RPGs, GMless games, map-drawing games, games where you play as a landscape or a community, lyric games, or anything truly experimental. Do NOT force these into another tradition -- use `custom` and let the game tell you what it is.
+
+   **For truly novel games**: Not every entity type will apply. A journaling RPG may have only `mechanics/` (prompts) and `tensions/` (thematic). A GMless game may have no `entities/` at all. That's fine -- use only the entity types that make sense. Empty categories are better than forced ones.
+
+3. **Extract raw game content.** Pull out every identifiable game element. Use the 6 entity types as a lens, not a requirement -- if a category doesn't exist in this game, skip it:
+   - Attributes/stats/scores -- anything that defines a character numerically (if the game has characters)
+   - Resources/pools -- anything that depletes and recovers (tokens, stress, supply, prompts remaining, etc.)
+   - Mechanics/moves/actions -- how things get resolved (rolls, triggers, prompts, scene-framing rules, safety tools as mechanics, etc.)
+   - Progression -- how characters or the game state changes over time (levels, advances, seasonal shifts, relationship evolution, narrative arcs)
+   - Entities -- the things in the game (classes, playbooks, locations, prompts, oracle tables, community roles)
+   - Tensions -- push-pull dynamics you observe (even if the source doesn't name them explicitly -- every game has tensions, even if they're thematic rather than mechanical)
+4. **Track what you found and what's missing.** Make a mental inventory:
+   - Which of the 6 entity types have clear source material?
+   - Which are implied but not spelled out?
+   - Which are completely absent from the source?
+
+### Phase 3: Interview
+
+The interview has one job: get enough signal to generate a draft game-state. The user should not feel like they're filling out a form.
+
+**Principle: Draft first, correct later.** Ask the minimum needed to produce a reasonable draft. Generate it. Present it. Let the user correct what's wrong. This is always faster than exhaustive upfront questioning.
+
+**For document ingestion:** Present what you extracted in a summary, ask about anything genuinely ambiguous (not everything missing — infer what you can from tradition norms), then proceed directly to generation.
+
+**For guided interview (no source):** Walk through 3a and 3b below, then generate.
+
+#### 3a: Identity (All Traditions — one batch)
+
+Ask as a single message:
+
+1. What is the game called?
+2. What tradition? (Offer: d20, PbtA, FitD, OSR, Cepheus, freeform, custom, eurogame, autobattler, roguelike, deckbuilder, ccg, 4x, tactics, social-deduction, cooperative, idle, extraction, looter, immersive-sim)
+3. One-sentence pitch — what makes this different from a standard [tradition] game?
+4. What is the core loop? (What does a player DO on their turn / in a round / in a session?)
+
+If the user's pitch already answers the core loop (e.g., "it's Blades but stress is shared across the crew"), don't re-ask it.
+
+#### 3b: Core Differentiators (Tradition-Aware — one batch)
+
+Based on the tradition, ask ONLY about what you can't infer from tradition norms. If the user said "standard 5e ability scores," you already know the stats. Don't ask.
+
+Ask the single most diagnostic question per tradition family:
+
+- **d20**: "What's different about your resolution, combat, or progression compared to standard d20?"
+- **pbta**: "What are your unique moves and what stats do they roll?"
+- **fitd**: "How does your stress/harm economy differ from standard Blades?"
+- **osr**: "What procedures define the core gameplay loop?"
+- **cepheus**: "What careers exist and how does your skill list differ from standard Cepheus?"
+- **freeform/custom**: "Walk me through one complete scene or session cycle"
+- **eurogame/deckbuilder/cooperative**: "Walk me through one complete turn"
+- **autobattler/tactics**: "What are the unit types and how does a round play out?"
+- **ccg**: "What's the cost system, main card types, and win condition?"
+- **social-deduction**: "What roles exist and what's the phase structure?"
+- **roguelike/extraction/looter**: "What does one run look like, and what persists between runs?"
+- **4x**: "What victory conditions exist and what's the tech/expansion structure?"
+- **idle**: "What's the basic loop, and what does prestige look like?"
+- **immersive-sim**: "What player abilities exist and how do systems interact?"
+
+Then one follow-up: "What else is importantly different from a standard [tradition] game?"
+
+That's it for the interview. Two batches of questions, then move to generation.
+
+**For everything the user didn't specify, use tradition defaults.** Standard stats, standard resource pools, standard progression curves. Mark inferred content in descriptions with `[inferred from tradition defaults]` so the user can spot and correct them during review.
+
+#### Interview guidelines
+
+- **Two rounds maximum** before generating. If you still have gaps after 3b, infer from tradition norms and flag during review.
+- If the user says "it's like X," use X as the baseline. Ask ONLY about differences.
+- If the user says "it's like X but with Y," you now know the baseline AND the key differentiator. You may not need 3b at all.
+- Never ask about tensions during the interview. You'll identify them from the generated game-state and surface them during review.
+- Never ask about design parameters during the interview. Default from tradition norms; the user can override during review.
+
+### Phase 4: Game-State Generation
+
+Generate YAML files for every game element you have extracted or learned through interview. Use tradition defaults to fill gaps — do not leave entities incomplete because the user didn't explicitly state something that is standard for their tradition. Follow the schema defined in `skills/attune/resources/game-state-schema.md` exactly.
+
+#### Schema Reference
+
+Every file requires these common base fields:
+
+```yaml
+id: unique-kebab-case-id
+name: "Human Readable Name"
+type: stats|resources|mechanics|progression|entities|tensions
+description: "What this is and what it does in the game"
+tradition: d20|pbta|fitd|osr|cepheus|freeform|custom|autobattler|roguelike|deckbuilder|ccg|4x|tactics|eurogame|social-deduction|cooperative|idle|extraction|looter|immersive-sim
+tags: []
+
+status: active|stub|deprecated  # Optional. Default: active (omit for normal entities)
+
+depends_on: []    # Paths relative to game-state/. Required (empty array for leaf nodes).
+affects: []       # Paths relative to game-state/. Required (empty array for leaf nodes).
+
+# Optional on most entity types; required on tensions (see Phase 8c)
+intent:
+  summary: "one-line goal"
+  rationale: "why this design"
+  set_by: attune
+  set_at: "ISO-8601"
+  non_negotiable: false
+
+created_by: attune
+created_at: "ISO-8601"
+last_modified_by: attune
+last_modified_at: "ISO-8601"
+```
+
+#### Type-Specific Fields
+
+**stats/** -- Attributes, ability scores, derived values:
+- `range:` with `min`, `max`, `typical`, optional `modifier_formula`
+- `used_by:` list of what this stat affects in plain language
+
+**resources/** -- Depletable and recoverable pools:
+- `pool:` with `min`, `max` (or `max_by_level`), `recovery:` (trigger + amount)
+- `depletion_consequence:` what happens at zero
+- `overflow_consequence:` (if applicable) what happens at max
+- `pressure_rating:` low|medium|high
+
+**mechanics/** -- Actions, reactions, conditions, triggers:
+- `trigger:` when this activates
+- `cost:` list of resource/amount pairs (can be empty)
+- `resolution:` with `method`, `stat`, and outcome descriptions
+- `interactions:` list of notable rules interactions
+
+**progression/** -- Levels, features, gates:
+- `progression_table:` keyed by level/advance number, listing features
+- `scaling_notes:` list of observations about how this scales
+
+**entities/** -- Classes, monsters, items, spells, playbooks:
+- `subtype:` monster|class|item|spell|playbook|npc|etc.
+- Type-specific fields like `stat_block`, `actions`, `traits`, `cr`, etc.
+- `design_notes:` analytical observations about this entity
+
+**tensions/** -- Named design tension pairs:
+- `poles:` with `a:` and `b:`, each having `name`, `description`, `supported_by`
+- `health:` balanced|a-dominant|b-dominant|collapsed
+- `health_notes:` your analysis of the current state
+
+#### Generation Rules
+
+1. **One file per game entity.** Never combine multiple entities into one file.
+2. **IDs are kebab-case** and unique within their entity type directory.
+3. **Cross-references use relative paths** within `game-state/`: `mechanics/melee-attack.yaml`, not absolute paths.
+4. **Set `created_by: attune`** and `created_at` to the current ISO-8601 timestamp.
+5. **Fill `depends_on` and `affects`** by tracing relationships. If stat X is used by mechanic Y, then stat X `affects` mechanic Y, and mechanic Y `depends_on` stat X.
+6. **Write files using the Write tool.** Do NOT use heredocs or Bash echo. Use the Write tool for every YAML file.
+7. **Target fewer than 30 files** for a typical TTRPG system. Combine minor elements into broader entities rather than creating one file per spell, per item, etc. For example, create `entities/wizard-spells-1st.yaml` rather than individual files for each 1st-level spell.
+8. **Descriptions should be analytical**, not just restating the rules. "Physical power. Affects melee attacks, carrying capacity, Athletics" is better than "Strength is an ability score."
+9. **Auto-infer stubs for unresolved references.** After generating all entities, collect every path referenced in `depends_on`, `affects`, `resolution.stat`, and `cost[].resource`. For any reference that doesn't resolve to a generated entity, create a **stub entity**:
+   ```yaml
+   id: {inferred-from-path}
+   name: "{Inferred Name}"
+   type: {inferred-from-directory}
+   status: stub
+   description: "[STUB] Inferred from {referencing-entity} dependency. Awaiting enrichment."
+   tradition: {same as game tradition}
+   tags: [stub]
+   depends_on: []
+   affects: []
+   created_by: attune-inferred
+   created_at: "ISO-8601"
+   last_modified_by: attune-inferred
+   last_modified_at: "ISO-8601"
+   ```
+   Stubs have no type-specific fields. They exist to satisfy graph references. Report stub count to user after generation: "Created N stub entities for unresolved references. Run /attune again with source material to enrich them."
+
+### Phase 5: Index Generation
+
+After writing all entity files, generate or update `grimoires/gygax/game-state/index.yaml`.
+
+```yaml
+game: "Game Name"
+tradition: d20|pbta|fitd|osr|cepheus|freeform|custom|autobattler|roguelike|deckbuilder|ccg|4x|tactics|eurogame|social-deduction|cooperative|idle|extraction|looter|immersive-sim
+description: "Brief description of the game"
+created_at: "ISO-8601"
+last_modified_at: "ISO-8601"
+
+design_parameters:              # All optional. Missing fields use tradition defaults.
+  target_session_length: short|medium|long|campaign
+  target_audience: newcomer|intermediate|enthusiast|mastery
+  target_variance: low|medium|high
+  target_lethality: gentle|moderate|brutal
+  target_prep: zero-prep|light|moderate|heavy
+  target_player_count: solo|small|standard|large
+  target_interaction: direct-conflict|indirect-competition|cooperative|solo
+  target_randomness: none|low|medium|high
+
+# Tradition defaults (used when a field is omitted):
+#
+# TTRPG traditions:
+#   | Parameter      | d20        | pbta         | fitd         | osr       | cepheus     | freeform  | custom       |
+#   |----------------|------------|--------------|--------------|-----------|-------------|-----------|--------------|
+#   | session_length | long       | medium       | medium       | medium    | long        | short     | medium       |
+#   | audience       | intermediate| intermediate| intermediate| enthusiast| enthusiast  | newcomer  | intermediate |
+#   | variance       | medium     | medium       | medium       | high      | low         | low       | medium       |
+#   | lethality      | moderate   | moderate     | moderate     | brutal    | moderate    | gentle    | moderate     |
+#   | prep           | moderate   | light        | light        | moderate  | moderate    | zero-prep | moderate     |
+#   | player_count   | standard   | standard     | standard     | standard  | standard    | standard  | standard     |
+#   | interaction    | cooperative| cooperative  | cooperative  | cooperative| cooperative| cooperative| cooperative |
+#   | randomness     | medium     | medium       | medium       | medium    | low         | none      | medium       |
+#
+# Non-TTRPG traditions:
+#   | Parameter      | autobattler | roguelike | deckbuilder | ccg     | 4x      | tactics | eurogame |
+#   |----------------|-------------|-----------|-------------|---------|---------|---------|----------|
+#   | session_length | medium      | medium    | medium      | short   | long    | medium  | medium   |
+#   | audience       | intermediate| intermediate| intermediate| intermediate| enthusiast| intermediate| enthusiast |
+#   | variance       | medium      | high      | medium      | medium  | medium  | medium  | low      |
+#   | lethality      | moderate    | brutal    | gentle      | moderate| moderate| moderate| gentle   |
+#   | prep           | zero-prep   | zero-prep | zero-prep   | light   | moderate| zero-prep| light   |
+#   | player_count   | large       | solo      | standard    | solo    | solo    | solo    | standard |
+#   | interaction    | indirect-competition | solo | indirect-competition | direct-conflict | direct-conflict | direct-conflict | indirect-competition |
+#   | randomness     | medium      | high      | medium      | medium  | medium  | low     | low      |
+#
+#   | Parameter      | social-deduction | cooperative | idle   | extraction | looter   | immersive-sim |
+#   |----------------|-----------------|-------------|--------|-----------|----------|---------------|
+#   | session_length | short           | medium      | campaign| medium   | campaign | long          |
+#   | audience       | newcomer        | newcomer    | newcomer| enthusiast| intermediate| intermediate|
+#   | variance       | high            | medium      | low    | high      | medium   | low           |
+#   | lethality      | moderate        | moderate    | gentle | brutal    | moderate | moderate      |
+#   | prep           | zero-prep       | light       | zero-prep| zero-prep| zero-prep| zero-prep    |
+#   | player_count   | large           | standard    | solo   | standard  | solo     | solo          |
+#   | interaction    | social          | cooperative | solo   | direct-conflict | solo | solo         |
+#   | randomness     | low             | medium      | none   | medium    | high     | none          |
+
+entity_count:
+  stats: 0
+  resources: 0
+  mechanics: 0
+  progression: 0
+  entities: 0
+  tensions: 0
+
+files:
+  - path: stats/strength.yaml
+    id: strength
+    depends_on: []
+    affects: [mechanics/melee-attack.yaml]
+  # ... every file listed
+
+graph_integrity:
+  resolved_references: 0    # Count of depends_on/affects entries pointing to existing entities
+  stub_count: 0             # Count of entities with status: stub
+  stubs: []                 # List of stub file paths
+  orphaned: []              # Entities with zero incoming AND zero outgoing edges
+  circular: []              # Circular dependency chains (should always be empty)
+  most_depended_on:
+    - path: stats/strength.yaml
+      dependents: 4
+```
+
+**Index rules:**
+- `entity_count` must match the actual number of files in each directory. Stub entities count toward their type's total.
+- `files` must list EVERY game-state file (including stubs) with its `path`, `id`, `depends_on`, and `affects`.
+- `graph_integrity` must be computed by analyzing all cross-references:
+  - `resolved_references`: count all `depends_on`/`affects` entries that point to existing files
+  - `stub_count` and `stubs`: count and list entities with `status: stub`
+  - `orphaned`: entities with empty `depends_on` AND empty `affects` AND zero appearances in any other entity's dependency lists
+  - `circular`: circular dependency chains detected via topological sort (should be empty; flag if found)
+  - `most_depended_on`: files sorted by incoming reference count (how many other entities list this in `depends_on`)
+- **Backwards compatibility:** If an existing index uses `dependency_graph_summary`, convert it to `graph_integrity` on regeneration. Add `resolved_references`, `stub_count`, `stubs` fields with computed values.
+
+### Phase 6: Validation
+
+Before presenting results to the user, validate everything.
+
+#### 6a: Schema Validation
+
+For each generated YAML file, verify:
+- [ ] All common base fields are present (`id`, `name`, `type`, `description`, `tradition`, `tags`, `depends_on`, `affects`, `created_by`, `created_at`, `last_modified_by`, `last_modified_at`)
+- [ ] `id` is kebab-case and unique within its entity type directory
+- [ ] `type` matches the directory the file lives in (`stats/` files have `type: stats`)
+- [ ] `tradition` is one of: d20, pbta, fitd, osr, cepheus, freeform, custom, autobattler, roguelike, deckbuilder, ccg, 4x, tactics, eurogame, social-deduction, cooperative, idle, extraction, looter, immersive-sim
+- [ ] Type-specific required fields are present (e.g., `range` for stats, `pool` for resources)
+
+#### 6b: Cross-Reference Integrity
+
+- [ ] Every path in `depends_on` and `affects` resolves to an existing file in game-state (including stubs created in Phase 4 rule 9). If a reference still doesn't resolve after stub creation, that is a validation error -- either create an additional stub or remove the broken reference.
+- [ ] Cross-references are bidirectional where appropriate: if A `affects` B, then B should `depends_on` A. Asymmetry is a **warning** (fix it), not an error (don't block).
+- [ ] No file references itself
+- [ ] No circular dependency chains. Detect via topological sort. If circular dependencies exist, report them in `graph_integrity.circular` as a warning, not an error.
+- [ ] `depends_on` and `affects` are present on ALL entities (including stubs). Missing fields are a schema violation -- add empty arrays `[]` for leaf nodes.
+
+#### 6c: Index Consistency
+
+- [ ] `entity_count` matches actual file counts
+- [ ] Every file in the directory tree appears in `files`
+- [ ] `graph_integrity` is accurate (resolved_references, stub_count, stubs, orphaned, circular, most_depended_on)
+
+#### 6d: Repair
+
+If validation finds issues:
+- Fix missing cross-references by adding them
+- Fix broken references by either creating the missing file or removing the reference
+- Fix count mismatches by updating the index
+- Re-validate after repairs
+
+### Phase 7: Changelog Entry
+
+Write a changelog entry to `grimoires/gygax/changelog/`:
+
+**Filename:** `YYYY-MM-DD-HHMMSS-attune-initial.yaml` (or `attune-additive` for re-attunes)
+
+```yaml
+timestamp: "ISO-8601"
+skill: attune
+action: created|updated
+summary: "Initial attunement from [source] — [N] entities across [types]"
+entities_created:
+  - stats/strength.yaml
+  - stats/dexterity.yaml
+  # ... all files created or modified
+source: "docs/rulebook.md"  # or "guided interview" or URL
+```
+
+### Phase 8: Review and Correction
+
+This is where the "draft first, correct later" loop pays off. Present the draft, surface what was inferred, and let the user drive corrections.
+
+#### 8a: Present the Draft
+
+1. **Summarize what you understood.** 3-5 sentences showing you get the game. This is your check — if the summary feels wrong to the user, the game-state is wrong too.
+2. **Show entity counts.** Stats, resources, mechanics, progression, entities, tensions.
+3. **Flag inferred content.** List everything you filled in from tradition defaults: "I used standard [tradition] defaults for: [list]. Correct anything that's off."
+4. **Surface tensions.** List the tensions you identified from the game-state. Don't ask about each one individually — present them as a batch: "I see these tensions: [list]. Sound right? Any missing, or any that aren't real?"
+
+#### 8b: Design Parameters (Auto-Defaulted)
+
+Present the design parameters you defaulted from tradition norms as a table:
+
+> "Design parameters (defaulted from [tradition] norms — override anything that doesn't fit):"
+>
+> | Parameter | Default | Your game |
+> |-----------|---------|-----------|
+> | Session length | [tradition default] | — |
+> | Audience | [tradition default] | — |
+> | Variance | [tradition default] | — |
+> | Lethality | [tradition default] | — |
+> | Prep | [tradition default] | — |
+> | Player count | [tradition default] | — |
+> | Interaction | [tradition default] | — |
+> | Randomness | [tradition default] | — |
+
+The user fills in only what differs. Anything left blank stays at the tradition default (omitted from `index.yaml` — analysis tools resolve defaults at read time).
+
+#### 8c: Intent (Optional)
+
+If tensions were identified, offer (don't require):
+
+> "Want to set design intent on any of these tensions? This helps downstream analysis distinguish deliberate asymmetry from bugs. You can also do this later via `/homebrew --set-intent`."
+
+If the user engages, capture intent using the standard schema:
+
+```yaml
+intent:
+  summary: "one-line goal"
+  rationale: "why this design"
+  set_by: attune
+  set_at: "ISO-8601"
+  non_negotiable: false
+```
+
+If not, move on. Intent can always be added later.
+
+#### 8d: Offer Next Steps
+
+Based on what was built:
+- If the game-state feels complete: "You're attuned. Try `/homebrew` to design a new mechanic, or `/augury` to check the math."
+- If the user corrected things: apply corrections (Phase 9), re-validate, then offer next steps.
+- If you spotted potential issues: "I noticed [observation]. You might want to run `/lore` for a pattern check, or `/augury` on [specific mechanic]."
+
+### Phase 9: Iterative Refinement (if user continues)
+
+If the user provides corrections or additional information:
+1. Update the affected YAML files using Edit (not full rewrites).
+2. Update cross-references in any files that depend on or are affected by the change.
+3. Update `index.yaml`.
+4. Append a new changelog entry for each round of changes.
+5. Re-validate.
+
+Continue until the user is satisfied or moves on to another skill.
+
+## Tradition-Specific Guidance
+
+Different traditions emphasize different entity types. This determines what you prioritize during extraction, what you can safely infer, and what the user's draft will look like.
+
+| Tradition | Primary Entities | Secondary Entities | Often Sparse |
+|-----------|-----------------|-------------------|--------------|
+| d20 | stats, mechanics, progression | resources, entities | tensions |
+| pbta | mechanics (moves), stats | progression (advances), entities (playbooks) | resources, tensions |
+| fitd | resources (stress, harm), mechanics (actions, position/effect) | progression (crew advances), entities (crew sheet) | stats, tensions |
+| osr | mechanics (procedures), entities (monsters, treasure), resources (supply, torches) | stats (minimal) | progression, tensions |
+| cepheus | stats (6 characteristics), mechanics (skill checks, Effect), progression (lifepath/careers) | resources (Endurance as ablative pool), entities (career tables, equipment) | tensions |
+| freeform | mechanics (tokens, prompts), tensions (safety tools as mechanics) | entities (character concepts) | stats, resources, progression |
+| eurogame | mechanics (actions), resources (economy), entities (components) | progression (engine building), tensions | stats |
+| deckbuilder | mechanics (buy/play/trash), entities (cards), resources (currency) | progression (deck thinning) | stats, tensions |
+| cooperative | mechanics (actions), resources (shared pools), tensions (difficulty curve) | entities (roles), progression (escalation) | stats |
+| autobattler | entities (units), mechanics (combat, synergies), resources (economy) | progression (leveling, items) | stats, tensions |
+| tactics | entities (units), mechanics (combat, positioning), stats (unit attributes) | progression (unlocks), resources (action points) | tensions |
+| ccg | entities (cards), mechanics (play/combat), resources (mana/cost) | progression (collection) | stats, tensions |
+| roguelike | mechanics (run structure), progression (meta-unlocks), entities (items, builds) | resources (health, currency) | stats, tensions |
+| extraction | mechanics (run/extract loop), resources (loot, risk), tensions (risk vs reward) | entities (gear), progression (hideout) | stats |
+| looter | entities (loot, builds), mechanics (combat), progression (power curve) | resources (currencies) | stats, tensions |
+| 4x | mechanics (expand/exploit/exterminate), progression (tech tree), tensions (victory paths) | resources (economy), entities (factions) | stats |
+| social-deduction | entities (roles), mechanics (phases, voting), tensions (information asymmetry) | resources (lives) | stats, progression |
+| idle | mechanics (click/automate loop), progression (prestige), resources (currencies) | tensions (active vs idle) | stats, entities |
+| immersive-sim | mechanics (systemic interactions), entities (abilities, tools), tensions (approach trade-offs) | resources (ammo, upgrades), progression (ability tree) | stats |
+| custom | **let the game decide** -- discover which types matter from the user's answers | varies | varies |
+
+**Custom tradition guidance**: For games that don't fit any tradition, do NOT default to d20 patterns. Build entity types around what the game actually does. A journaling RPG might only have `mechanics/` and `tensions/`. A map-drawing game might only have `mechanics/` and `entities/`. It is completely valid for a game to have only 1-2 entity types populated.
+
+## Handling Edge Cases
+
+### Mid-Project Installation
+If Gygax is installed into an existing Loa-managed repo that already has content:
+- Check for existing `grimoires/gygax/` directory. If it exists with content, treat this as an additive attune.
+- Do NOT delete or overwrite existing game-state files. Merge new content.
+- Preserve all existing `created_by`, `created_at` timestamps. Only update `last_modified_*` fields.
+
+### Very Large Sources
+If the source material is extensive (full SRD, complete rulebook):
+- Prioritize core mechanics and stats over exhaustive entity cataloguing.
+- Create representative entities rather than every monster, every spell, every item.
+- Note in the presentation: "I captured the core systems. Individual monsters/spells/items can be added incrementally via `/attune` with specific source sections."
+
+### Minimal or Vague Sources
+If the source is sparse (a half-page game concept, a few scattered notes):
+- Extract what you can, then shift to interview mode for everything else.
+- Be honest: "The source gave me [X], but I need to know more about [Y] to build useful game-state."
+
+### "It's Like 5e" / "Standard PbtA"
+When users reference well-known systems:
+- Use your knowledge of that system to fill in the standard baseline.
+- Ask ONLY about what differs: "I'll use standard 5e ability scores and saving throws as the baseline. What's different in your system?"
+- Generate game-state for the baseline AND the modifications, clearly tagging what's standard vs. custom.
+
+## Cross-Skill Chaining
+
+After attunement completes, suggest next steps based on what was built:
+
+```
+Game attuned. Suggested next steps:
+
+1. `/lore` -- check your design against known tradition anti-patterns
+2. `/augury` -- validate the numerical balance of your mechanics
+3. `/homebrew` -- start designing new mechanics with cross-system checking
+4. `/cabal --newcomer --optimizer` -- quick stress-test for accessibility and exploits
+5. To compare your system against an industry baseline, run `/attune --reference 5e-srd` (also available: pbta-baseline, cepheus-core).
+```
+
+Tailor suggestions to what the game-state contains. If the game has combat mechanics, emphasize `/augury`. If it's narrative-first, emphasize `/lore` and `/cabal --storyteller`. If the tradition is `cepheus` or uses a 2d6+mod resolution, suggest `/attune --reference cepheus-core` for direct comparison.
+
+## Boundaries
+
+- Does NOT design new mechanics (use `/homebrew` for that)
+- Does NOT evaluate balance (use `/augury` for that)
+- Does NOT simulate play (use `/cabal` for that)
+- Does NOT apply heuristic pattern-matching (use `/lore` for that)
+- Focuses solely on accurate extraction and representation of existing game content
+- Does NOT make creative decisions -- if the source is ambiguous, ask the user rather than guessing
+- Does NOT edit files in `.claude/` (System Zone)
+- Does NOT generate more than 30 game-state files per attunement without explicit user request
+
+## Output
+
+**Primary (full attune workflow):** All artifacts are written to `grimoires/gygax/game-state/` organized by entity type:
+- `grimoires/gygax/game-state/stats/*.yaml`
+- `grimoires/gygax/game-state/resources/*.yaml`
+- `grimoires/gygax/game-state/mechanics/*.yaml`
+- `grimoires/gygax/game-state/progression/*.yaml`
+- `grimoires/gygax/game-state/entities/*.yaml`
+- `grimoires/gygax/game-state/tensions/*.yaml`
+- `grimoires/gygax/game-state/index.yaml`
+
+**Reference installation (`--reference` mode):** Artifacts are written to the references zone instead:
+- `grimoires/gygax/references/{name}/game-state/` (full entity directory structure)
+- `grimoires/gygax/references/{name}/metadata.yaml`
+
+**Always written (both modes):**
+- `grimoires/gygax/changelog/YYYY-MM-DD-HHMMSS-attune-*.yaml`
+
+## Error Handling
+
+| Error | Response | Recovery |
+|-------|----------|----------|
+| Source file not found | "I can't find a file at [path]. Check the path and try again, or run `/attune` without arguments for a guided interview." | Ask user to provide correct path |
+| Source file is not readable text (binary, PDF, image) | "That file format isn't supported yet. Can you provide the content as markdown or plain text? Or run `/attune` without arguments and describe the game." | Redirect to interview mode |
+| URL fetch fails | "I couldn't fetch that URL. Is it publicly accessible? You can also paste the content directly or point me at a local file." | Offer alternatives |
+| Generated YAML fails validation | Do NOT show the user raw validation errors. Fix the file silently and re-validate. If the fix requires user input, ask a specific question. | Self-repair, then re-validate |
+| Cross-reference points to entity not yet created | Create a minimal placeholder for the referenced entity with a `TODO` tag, or remove the reference if the entity is out of scope. | Placeholder or removal |
+| Existing game-state conflicts with new source | "The existing game-state has [X], but the new source says [Y]. Which should I use?" | Ask user to resolve conflict |
+| Source material is for a game you don't recognize | Proceed anyway. Extract what you can structurally. "I'm not familiar with this specific system, but I can see it uses [resolution mechanic]. Let me ask some targeted questions to fill in what I can't infer." | Shift to interview-heavy mode |
+| User provides contradictory information | Surface the contradiction Socratically: "Earlier you said [X], but this seems to conflict with [Y]. Which is the intended design?" | Ask user to resolve |
+| Unknown reference slug (`--reference {name}` not in bundled list) | "Reference '{name}' not available. Bundled references: 5e-srd, pbta-baseline, cepheus-core." | Stop; do not proceed |
+| Reference already installed | "Reference '{name}' already installed at grimoires/gygax/references/{name}/. Reinstall? [y/N]" | Wait for user confirmation; reinstall only if confirmed |

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/attune/index.yaml

@@ -0,0 +1,29 @@
+slug: attune
+name: "Attune"
+description: |
+  Use this skill IF user invokes /attune OR wants to analyze a game, ingest a rulebook, or read a system.
+  Produces artifacts to grimoires/gygax/game-state/.
+version: 1.0.0
+
+triggers:
+  - "/attune"
+  - "analyze this game"
+  - "ingest this rulebook"
+  - "read this system"
+  - "attune to this"
+
+capabilities:
+  model_tier: opus
+  danger_level: safe
+  effort_hint: large
+  downgrade_allowed: true
+  execution_hint: sequential
+  requires:
+    native_runtime: false
+    tool_calling: true
+    thinking_traces: false
+    vision: false
+
+dependencies:
+  grimoire_paths:
+    - grimoires/gygax/

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/attune/resources/game-state-schema.md

@@ -0,0 +1,586 @@
+# Gygax Game-State YAML Schema
+
+This document defines the structured YAML schema for game-state files stored in `grimoires/gygax/game-state/`. All Gygax skills read from and write to this schema.
+
+## Common Base Fields
+
+Every game-state YAML file shares these required fields:
+
+```yaml
+id: unique-kebab-case-id           # Unique within entity type
+name: "Human Readable Name"        # Display name
+type: stats|resources|mechanics|progression|entities|tensions
+description: "What this is and what it does in the game"
+tradition: d20|pbta|fitd|osr|cepheus|freeform|custom|autobattler|roguelike|deckbuilder|ccg|4x|tactics|eurogame|social-deduction|cooperative|idle|extraction|looter|immersive-sim
+tags: []                           # Freeform tags for querying
+
+depends_on: []                     # Paths relative to game-state/
+affects: []                        # Paths relative to game-state/
+
+created_by: attune|homebrew|scry   # Which skill created this
+created_at: "ISO-8601"
+last_modified_by: attune|homebrew|scry
+last_modified_at: "ISO-8601"
+```
+
+## Intent Field (v3)
+
+Intent captures what the designer WANTS a mechanic or tension to do, as distinct from what it currently IS. Analysis skills (augury, cabal, lore) read intent before classifying findings — a deliberately asymmetric mechanic with intent stated is an Observation ("working as designed"), not a Warning.
+
+**Schema (optional on most entity types, required on tensions):**
+
+```yaml
+intent:
+  summary: "One-line design goal"
+  rationale: "Why this design choice — the problem it solves or the experience it creates"
+  set_by: designer|attune|homebrew   # Who set the intent
+  set_at: "ISO-8601"
+  non_negotiable: true|false          # If true, findings conflicting with intent are suppressed, not just downgraded
+```
+
+**Where intent applies:**
+
+| Entity Type | Intent Required? | Notes |
+|-------------|-----------------|-------|
+| `tensions/` | **Required** | Tensions without stated intent are incomplete — a tension's health depends on knowing what it's supposed to do |
+| `mechanics/` | Encouraged for high-connectivity | Prompt for intent on mechanics in `most_depended_on` from index.yaml |
+| `progression/` | Optional | Intent useful for major scaling decisions (e.g., "linear martial / quadratic caster is deliberate") |
+| `resources/` | Optional | Useful for resources with notable pressure design |
+| `stats/` | Optional | Rarely needed — stats usually have obvious intent |
+| `entities/` | Optional | Typically unnecessary; intent lives at mechanic level |
+
+**How intent affects analysis:**
+
+- **Augury:** Warning findings downgrade to Observation when intent confirms the design. Critical findings never suppress (math cannot be "intentionally broken"). Non-obvious findings always surface but gain context.
+- **Cabal:** Archetype findings include intent in the Voice quote. Experience divergence findings are NEVER suppressed — UX problems remain problems regardless of designer intent.
+- **Lore:** Heuristic matches tagged `[INTENT-ALIGNED]` when intent confirms the pattern, `[INTENT-CONFLICT]` when the pattern fires against stated intent.
+
+**Backwards compatibility:** Entity files without intent fields remain valid. Absence of intent is treated as "unknown intent" — findings are not suppressed or modified.
+
+**Example intent on a tension:**
+
+```yaml
+id: instinct-vs-craft
+name: "Instinct vs. Craft"
+type: tensions
+# ... other fields
+
+intent:
+  summary: "The inversion IS the game — characters succeed through the opposite of who they are."
+  rationale: "Freetekno's raw-nerve identity succeeding through craft most of the time is the core dramatic engine. The friction between identity and success method generates character moments on every roll."
+  set_by: designer
+  set_at: "2026-04-10"
+  non_negotiable: true
+```
+
+With this intent set, augury will classify the freetekno 66.7% craft-success rate as an Observation ("working as designed per intent: non-negotiable"), not a Warning.
+
+## Tunability Field (cycle-005)
+
+`tunability` marks whether a value is a **replaceable sample** an engine adopter is expected to tune, or a **structural invariant** of the engine itself. It exists so Gygax can analyze *engines* (content-agnostic substrates), not just tuned games: a problem in `engine-default` content reads "yours to tune — here's the lever," while a problem in `structural` math reads as a genuine engine constraint.
+
+**Schema (optional, additive, entity-level — MVP):**
+
+```yaml
+tunability: engine-default | structural
+```
+
+| Value | Meaning | Example |
+|-------|---------|---------|
+| `engine-default` | A sample/example value an adopter is expected to replace (a `DEFAULT_*`/config const). | A demo level's `enemy_armor` curve; starting gold. |
+| `structural` | An invariant property of the engine itself — never a tuning knob. | The `dmg = max(1, atk - def)` min-damage floor; grid-locked movement. |
+
+**How it is set:**
+
+- **Explicitly** by the designer or `/homebrew` on an entity.
+- **Inferred by code-grounded `/attune` (F1)** when a repo is present: a value read from a `DEFAULT_*`/config const → `engine-default`; a number hardcoded in the core sim loop → `structural` (conservative — left untagged when no clear signal).
+
+**How tunability affects analysis:**
+
+- **Augury:** frames findings by it — an `engine-default` problem is reported as a tuning lever ("yours to tune"); a `structural` problem is a genuine engine constraint. The knob-surfacing pass perturbs **only** tunable params and **never** proposes changing a `structural` invariant.
+
+**Pairs with the `model:` block (parametric, Sprint B).** A `tunability`-tagged stat/progression entity may also carry an optional `model:` block expressing the value as a function of a progression variable (e.g. `formula: "floor((depth-9)/4)"`) — the parametric tuning surface the `--sweep` analysis reads. `model:` is additive alongside the discrete `progression_table`/`range`; no migration.
+
+**Backwards compatibility:** Entity files without `tunability` remain valid. Absence ⇒ untagged ⇒ treated exactly as today (no framing change, no perturbation assumptions).
+
+## Parametric `model:` Block (cycle-005)
+
+A `model:` block expresses a stat/progression value as a **function of a progression variable** (depth/level/wave) — the parametric tuning surface `/augury --sweep` analyzes. It is **additive and optional**, sitting alongside the discrete `progression_table`/`range` (which keep working untouched — no migration).
+
+**Schema (on a `stats/` or `progression/` entity):**
+
+```yaml
+model:
+  variable: wave                  # the single progression axis (MVP: single-variable)
+  domain: { min: 1, max: 20 }     # finite, bounded sweep range (max > min)
+  formula: "min(4, floor(wave / 4))"   # restricted arithmetic over `variable`
+  notes: "optional human note"
+```
+
+**Formula grammar (whitelisted — evaluated by a restricted interpreter, never `eval`):**
+
+- operators `+ - * / %`, parentheses, numeric literals;
+- the single declared `variable` (and, for composed metrics, other entity/metric names);
+- functions `floor`, `ceil`, `abs` (unary), `min`, `max` (variadic).
+- Anything else (member access, unknown identifiers, extra functions) is rejected at load time with a `FormulaError`.
+
+**Composed metrics & thresholds (on a `progression/` entity):** derived metrics and the thresholds whose first-crossing the sweep reports are declared generically (metric-agnostic — the engine hard-codes no metric names):
+
+```yaml
+metrics:
+  - { id: damage_per_hit, formula: "max(1, player_attack - enemy_armor)", role: intermediate }
+  - { id: time_to_kill,   formula: "ceil(enemy_hp / damage_per_hit)",     role: primary }
+thresholds:
+  - { metric: time_to_kill, test: "> 8" }      # reported as a first-crossing on the axis
+```
+
+Entity ids are hyphenated (`player-attack`); formulas reference them underscored (`player_attack`).
+
+**Domain rules:** `domain` must be finite and bounded with `max > min` (open/`Infinity`/degenerate domains are rejected with a `DomainError` before any sweep). MVP is single-axis; 2-D sweeps are deferred.
+
+**Backwards compatibility:** Entities without a `model:` block are unaffected — `/augury`'s existing breakpoint analysis runs exactly as before. `--sweep` is a separate mode that consumes only `model:` entities.
+
+## Entity Type: stats/
+
+Attributes, ability scores, derived values — the numbers on a character sheet.
+
+```yaml
+id: strength
+name: "Strength"
+type: stats
+description: "Physical power. Affects melee attacks, carrying capacity, Athletics."
+tradition: d20
+tags: [ability-score, physical, core]
+
+range:
+  min: 1
+  max: 30
+  typical: 8-18
+  modifier_formula: "floor((value - 10) / 2)"
+
+used_by:
+  - "Melee attack rolls"
+  - "Strength saving throws"
+  - "Athletics checks"
+
+depends_on: []
+affects:
+  - mechanics/melee-attack.yaml
+  - mechanics/athletics-check.yaml
+
+created_by: attune
+created_at: "2026-04-07T12:00:00Z"
+last_modified_by: attune
+last_modified_at: "2026-04-07T12:00:00Z"
+```
+
+**For PbtA stats:**
+
+```yaml
+id: hot
+name: "Hot"
+type: stats
+description: "Attractiveness, social leverage, and seductive power."
+tradition: pbta
+tags: [stat, social]
+
+range:
+  min: -1
+  max: 3
+  typical: -1-2
+
+used_by:
+  - "Turn Someone On"
+  - "Manipulate an NPC"
+
+depends_on: []
+affects:
+  - mechanics/turn-someone-on.yaml
+
+created_by: attune
+created_at: "2026-04-07T12:00:00Z"
+last_modified_by: attune
+last_modified_at: "2026-04-07T12:00:00Z"
+```
+
+## Entity Type: resources/
+
+Depletable and recoverable pools — anything that gets spent and restored.
+
+```yaml
+id: spell-slots-1st
+name: "1st-Level Spell Slots"
+type: resources
+description: "Expendable resource for casting 1st-level spells. Recovers on long rest."
+tradition: d20
+tags: [spellcasting, rest-recovery, per-day]
+
+pool:
+  min: 0
+  max_by_level:
+    1: 2
+    2: 3
+    3: 4
+  recovery:
+    trigger: long-rest
+    amount: full
+
+depletion_consequence: "Cannot cast 1st-level spells without using higher slots or cantrips."
+pressure_rating: medium
+
+depends_on:
+  - progression/wizard-class.yaml
+  - mechanics/long-rest.yaml
+affects:
+  - mechanics/spellcasting.yaml
+
+created_by: attune
+created_at: "2026-04-07T12:00:00Z"
+last_modified_by: attune
+last_modified_at: "2026-04-07T12:00:00Z"
+```
+
+**For FitD stress:**
+
+```yaml
+id: stress
+name: "Stress"
+type: resources
+description: "Accumulated pressure from desperate situations. At max, triggers trauma."
+tradition: fitd
+tags: [consequence, escalation]
+
+pool:
+  min: 0
+  max: 9
+  recovery:
+    trigger: downtime-activity
+    amount: variable
+
+depletion_consequence: "N/A (stress fills up, not down)"
+overflow_consequence: "Trauma — permanent character change"
+pressure_rating: high
+
+depends_on:
+  - mechanics/resistance-roll.yaml
+affects:
+  - mechanics/trauma.yaml
+  - progression/retirement.yaml
+
+created_by: attune
+created_at: "2026-04-07T12:00:00Z"
+last_modified_by: attune
+last_modified_at: "2026-04-07T12:00:00Z"
+```
+
+## Entity Type: mechanics/
+
+Actions, reactions, conditions, triggers — how the game plays.
+
+```yaml
+id: dodge-reaction
+name: "Dodge (Reaction)"
+type: mechanics
+description: "Spend stamina to avoid an incoming attack. Uses reaction for the round."
+tradition: d20
+tags: [combat, reaction, defensive]
+
+trigger: "When targeted by a melee or ranged attack"
+cost:
+  - resource: resources/stamina.yaml
+    amount: 2
+  - resource: mechanics/reaction-economy.yaml
+    amount: 1
+
+resolution:
+  method: ability-check
+  stat: stats/dexterity.yaml
+  dc: "attacker's attack roll"
+  success: "Attack misses"
+  failure: "Attack hits normally, stamina still spent"
+
+interactions:
+  - "Cannot dodge if stamina < 2"
+  - "Cannot dodge if reaction already used this round"
+  - "Heavy armor imposes disadvantage on the check"
+```
+
+### Resolution Methods (v4)
+
+The `resolution.method` field accepts any of these values. Augury adapts its analysis based on method type.
+
+**Dice-based** (probability scripts available):
+- `d20-roll`, `ability-check`, `saving-throw` — d20 + modifier vs DC
+- `2d6-roll`, `roll-2d6-plus-stat` — 2d6+stat with threshold bands
+- `dice-pool` — roll Nd6, count successes
+- `advantage`, `disadvantage` — roll 2, keep best/worst
+- `exploding` — recursive aces
+
+**Non-dice** (structural analysis):
+- `auction` — players bid resources for outcomes
+- `worker-placement` — place tokens to claim action slots
+- `area-majority` — most presence in a region wins control
+- `simultaneous-choice` — all players choose secretly, reveal together
+- `drafting` — pick from a shared pool in turn order
+- `card-play` — play cards from hand for effects
+- `pattern-matching` — spatial or set collection for scoring
+- `real-time` — speed-based resolution
+- `negotiation` — outcomes from player agreement
+- `deduction` — logical elimination of hidden information
+- `deterministic` — fixed outcomes from known inputs (pure strategy)
+- `automated` — system resolves without player input (autobattler combat phase)
+
+Non-dice example:
+
+```yaml
+id: worker-placement-action
+name: "Place Worker"
+type: mechanics
+description: "Place one worker on an unoccupied action space to claim its effect. Blocks other players from that space this round."
+tradition: eurogame
+tags: [core-action, resource-generation]
+
+trigger: "On your turn, if you have an unplaced worker"
+cost:
+  - resource: resources/workers.yaml
+    amount: 1
+
+resolution:
+  method: worker-placement
+  stat: null
+  success: "Gain the action space's effect (resources, points, or special action)"
+  failure: null  # Worker placement doesn't fail — if the space is available, it works
+  blocking: "Other players cannot use this space until next round"
+
+interactions:
+  - "First player advantage: earlier placement gets first pick of spaces"
+  - "Blocking is the primary interaction — choosing a space denies it to opponents"
+
+depends_on:
+  - resources/stamina.yaml
+  - stats/dexterity.yaml
+  - mechanics/reaction-economy.yaml
+affects:
+  - resources/stamina.yaml
+
+created_by: homebrew
+created_at: "2026-04-07T14:00:00Z"
+last_modified_by: homebrew
+last_modified_at: "2026-04-07T14:00:00Z"
+```
+
+**For PbtA moves:**
+
+```yaml
+id: defy-danger
+name: "Defy Danger"
+type: mechanics
+description: "When you act despite an imminent threat, say how you deal with it and roll."
+tradition: pbta
+tags: [basic-move, reactive]
+
+trigger: "When you act despite an imminent threat"
+cost: []
+
+resolution:
+  method: roll-2d6-plus-stat
+  stat: "varies by fiction"
+  outcomes:
+    "10+": "You do it, no cost"
+    "7-9": "Worse outcome, hard bargain, or ugly choice"
+    "6-": "GM makes a move"
+
+interactions:
+  - "Stat used depends on how you describe dealing with the danger"
+  - "GM determines when this triggers, not the player"
+
+depends_on: []
+affects: []
+
+created_by: attune
+created_at: "2026-04-07T12:00:00Z"
+last_modified_by: attune
+last_modified_at: "2026-04-07T12:00:00Z"
+```
+
+## Entity Type: progression/
+
+Levels, features, gates — how characters grow over time.
+
+```yaml
+id: fighter-class
+name: "Fighter"
+type: progression
+description: "Martial class focused on weapon mastery and combat superiority."
+tradition: d20
+tags: [class, martial, core]
+
+progression_table:
+  1:
+    features: [fighting-style, second-wind]
+    hit_die: d10
+    proficiency_bonus: 2
+  2:
+    features: [action-surge]
+  3:
+    features: [martial-archetype]
+  5:
+    features: [extra-attack]
+    proficiency_bonus: 3
+
+scaling_notes:
+  - "Linear damage scaling via Extra Attack (5, 11, 20)"
+  - "Action Surge provides nova potential — strongest in short fights"
+  - "No inherent magical capability — dependent on items for magical damage"
+
+depends_on:
+  - stats/strength.yaml
+  - stats/constitution.yaml
+affects:
+  - mechanics/action-surge.yaml
+  - mechanics/second-wind.yaml
+
+created_by: attune
+created_at: "2026-04-07T12:00:00Z"
+last_modified_by: attune
+last_modified_at: "2026-04-07T12:00:00Z"
+```
+
+## Entity Type: entities/
+
+Classes, monsters, items, spells, playbooks — the things in the game.
+
+```yaml
+id: goblin
+name: "Goblin"
+type: entities
+subtype: monster
+description: "Small, cowardly but cunning humanoid. Dangerous in groups."
+tradition: d20
+tags: [monster, humanoid, low-cr]
+
+stat_block:
+  ac: 15
+  hp: 7
+  speed: 30
+  str: 8
+  dex: 14
+  con: 10
+
+actions:
+  - name: Scimitar
+    attack_bonus: 4
+    damage: "1d6+2 slashing"
+  - name: Shortbow
+    attack_bonus: 4
+    damage: "1d6+2 piercing"
+    range: "80/320"
+
+traits:
+  - name: Nimble Escape
+    description: "Can Disengage or Hide as a bonus action"
+
+cr: 0.25
+xp: 50
+
+design_notes:
+  - "Nimble Escape makes goblins harder to pin down than CR 1/4 suggests"
+  - "In groups of 6+, action economy overwhelms low-level parties"
+
+depends_on:
+  - mechanics/melee-attack.yaml
+  - mechanics/ranged-attack.yaml
+affects: []
+
+created_by: attune
+created_at: "2026-04-07T12:00:00Z"
+last_modified_by: attune
+last_modified_at: "2026-04-07T12:00:00Z"
+```
+
+## Entity Type: tensions/
+
+Named design tension pairs — intentional push-pull dynamics.
+
+```yaml
+id: survivability-vs-resource-pressure
+name: "Survivability vs. Resource Pressure"
+type: tensions
+description: "Defensive options cost resources, creating tension between staying alive now and having resources for later."
+tradition: d20
+tags: [combat, pacing, resource-management]
+
+poles:
+  a:
+    name: "Survivability"
+    description: "Player can avoid damage and stay in the fight"
+    supported_by:
+      - mechanics/dodge-reaction.yaml
+      - mechanics/second-wind.yaml
+      - resources/hit-points.yaml
+  b:
+    name: "Resource Pressure"
+    description: "Defensive options deplete limited resources"
+    supported_by:
+      - resources/stamina.yaml
+      - resources/spell-slots-1st.yaml
+
+health: balanced
+health_notes: "Dodge costs 2 stamina from a pool of 10, giving 5 dodges per rest. If stamina pool increases, survivability dominates and combat loses tension."
+
+depends_on:
+  - mechanics/dodge-reaction.yaml
+  - resources/stamina.yaml
+affects: []
+
+created_by: homebrew
+created_at: "2026-04-07T14:00:00Z"
+last_modified_by: homebrew
+last_modified_at: "2026-04-07T14:00:00Z"
+```
+
+## Index File: game-state/index.yaml
+
+The root manifest summarizing all game-state files. Created by `/attune`, updated by `/homebrew`.
+
+```yaml
+game: "Game Name"
+tradition: d20|pbta|fitd|osr|freeform|custom
+description: "Brief description of the game"
+created_at: "ISO-8601"
+last_modified_at: "ISO-8601"
+
+entity_count:
+  stats: 0
+  resources: 0
+  mechanics: 0
+  progression: 0
+  entities: 0
+  tensions: 0
+
+files:
+  - path: stats/strength.yaml
+    id: strength
+    depends_on: []
+    affects: [mechanics/melee-attack.yaml]
+  # ... all files listed
+
+graph_integrity:
+  resolved_references: 0
+  stub_count: 0
+  stubs: []
+  orphaned: []
+  circular: []
+  most_depended_on: []
+```
+
+Skills load `index.yaml` first to understand the full game-state, then selectively load specific files based on what they need.
+
+## Design Principles
+
+1. **Schema simplicity over expressiveness** — must be reliably LLM-generatable during `/attune`
+2. **Per-entity files** — one file per game entity, not monolithic documents
+3. **Cross-references via paths** — `depends_on` and `affects` use relative paths within game-state/
+4. **Tradition-agnostic structure** — same 6 types work for d20, PbtA, FitD, OSR, freeform
+5. **Context budget** — target <30 files for a typical TTRPG system
+6. **Append-only changelog** — mutations logged to `grimoires/gygax/changelog/`

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/attune/resources/incentive-state-schema.md

@@ -0,0 +1,83 @@
+# Gygax Incentive-State Schema (cycle-006)
+
+The **incentive-state** expresses an agent system's incentive structure as analyzable game-state — the
+agent-systems analog of game-state with `model:` blocks. It reuses the same entity envelope and the
+`expr` formula grammar (`scripts/lib/parametric/expr.ts`: `+ - * / %`, `floor/ceil/min/max/abs`,
+declared names, never `eval`).
+
+> **What Gygax does with it:** builds a payoff matrix (action × context), detects the dominant
+> strategy (reward hack), dominated actions (dead tools), and where the agent's optimal action
+> diverges from declared intent (specification gaming) — then recommends the incentive fix. Output is
+> a **forecast** (model-derived), tagged as such, never an observation of a live agent.
+
+## Entity Type: `actions/`
+
+The agent's available actions/tools. The agent is modeled as choosing the action that maximizes
+`net = reward − cost` at each context.
+
+```yaml
+id: delete-test
+type: actions
+description: "..."
+tunability: engine-default | structural   # changeable incentive vs fixed engine constraint
+payoff:
+  context: difficulty            # the matrix column axis (an environment-state variable)
+  domain: { min: 1, max: 10 }    # finite, bounded
+  reward: "1"                    # effect on the reward signal (formula over context — reuses expr)
+  cost: "1"                      # effort/token/latency cost (formula over context)
+```
+
+- `reward` and `cost` are `expr` formulas over the declared `context` variable (and may reference
+  other declared names). `net = reward − cost` is computed by the engine.
+- `tunability`: `engine-default` = an incentive the designer can re-weight or forbid; `structural` =
+  a fixed property (e.g. the agent's actual capability) that must NOT be proposed as a knob.
+
+## Entity Type: `reward/`
+
+The signal the agent maximizes, plus the **first-class intent**.
+
+```yaml
+id: pass-rate
+type: reward
+formula: "passing / total"        # informational — the underlying signal
+tunability: engine-default
+intent:                           # the behavior the designer ACTUALLY wants
+  intended_action: fix-code       # which action should be optimal
+  rationale: "Pass-rate is a proxy for correctness; the intended path is fixing the code."
+  non_negotiable: true            # if true, divergence is a bug, not a tolerated choice
+```
+
+`intent` is the declared terminal of the intent–reality spine. Without it, "the agent gamed the
+metric" is unprovable. (This is the same first-class intent the cycle-005 AC#3 deferral needs.)
+
+## `index.yaml`
+
+```yaml
+system: "..."
+domain: agent-system
+context: { name: difficulty, domain: { min: 1, max: 10 } }
+reward_signal: reward/pass-rate.yaml
+actions: [actions/fix-code.yaml, actions/delete-test.yaml, ...]
+```
+
+## Detection signals (what the engine computes)
+
+| Signal | Meaning |
+|--------|---------|
+| **Dominated action** (≤ another in every context) | a **dead tool** (taxonomy L7 dump) |
+| **Dominant action** (≥ all others everywhere / argmax) | the **reward hack** (L7 god) |
+| **argmax ≠ `intent.intended_action`** | **specification gaming / Goodhart** |
+| gap between gamed and intended payoff | *how hard* the incentive pushes toward the hack |
+| cheapest knob that flips argmax back to intent | the incentive-knob recommendation (L4 over incentives) |
+| (multi-agent, later) equilibrium mix `c = M⁻¹p` | expected behavior distribution; degenerate metagame flag |
+
+## Honesty boundary
+
+Gygax analyzes the **declared** incentive structure, not the live agent — a *forecast*, tagged with
+claim strength, never a measurement. Some divergences are *desired* emergent behavior; only a declared
+`intent` lets Gygax tell a **bug** from a **choice** (the same discipline as `tunability` framing).
+
+## Backwards compatibility
+
+The incentive-state is a separate construct from game-state — it does not change `game-state-schema.md`
+or any existing analysis. See `grimoires/gygax/designs/agent-incentive-analysis.md` for the full design.

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/augury/SKILL.md

@@ -0,0 +1,745 @@
+---
+name: augury
+description: Analyze balance of TTRPG mechanics through quantitative numerical methods
+model_tier: opus
+effort: medium
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Augury
+
+Quantitative balance analysis for TTRPG mechanics. Augury reads the game-state and produces concrete numbers -- DPR curves, hit probabilities, time-to-kill, action economy budgets, healing throughput, save DC scaling, resource depletion rates, pacing metrics -- then reports findings with specific values, tables, and identified pressure points.
+
+Augury exists because "seems balanced" is not analysis. Every finding must be backed by a calculation. Every recommendation must cite the numbers that motivate it. If the math says a mechanic is fine, Augury says it is fine even if it "feels" off. If the math says a mechanic is broken, Augury says it is broken even if it "feels" okay. The numbers are the argument.
+
+Augury is strictly read-only. It never modifies game-state. It observes, measures, computes, and reports. To act on Augury's findings, use `/homebrew` (to redesign) or `/cabal` (to stress-test in simulated play).
+
+## Trigger
+
+`/augury` with optional scope argument.
+
+Examples:
+- `/augury` -- full-spectrum analysis of everything in game-state
+- `/augury combat` -- combat-focused analysis (DPR, TTK, action economy)
+- `/augury resources` -- resource economy analysis (depletion rates, recovery, pressure)
+- `/augury pacing` -- narrative pacing and arc coverage analysis
+- `/augury scaling` -- level/tier progression scaling curves
+- `/augury mechanics/dodge-reaction.yaml` -- targeted analysis of a specific entity
+- `/augury entities/fighter-class.yaml vs entities/wizard-class.yaml` -- comparative analysis
+- `/augury --simulate <repoPath>` -- **F2 code-grounded simulation**: Monte-Carlo the *real* engine through its `gygaxDriver`, in the sandbox (see below)
+- `/augury --sweep <gameStateDir>` -- **parametric tuning-surface analysis**: sweep `model:` formulas across their domain; report threshold first-crossings + spikes + tunability framing (see below)
+
+## Parametric Sweep (`--sweep`)
+
+When invoked with `--sweep`, `/augury` analyzes the **tuning surface** of an engine rather than fixed breakpoints. It consumes the entities that carry a `model:` block (a value as a function of a progression variable — see the game-state schema), sweeps every formula densely across its `domain`, composes the declared derived `metrics`, and reports:
+
+- **Threshold first-crossings (K2):** for each declared `threshold`, the first axis point where the metric crosses it (e.g. `time_to_kill > 8` at `wave = 5`) — or an honest "no crossing in domain."
+- **Spikes (K3):** threshold-free *drastic jumps* in any metric (Hopson's "flag drastic jumps") — the envelope spike, distinct from regular `floor` stair-steps which are **not** flagged.
+- **Tunability framing (K5):** `engine-default` findings read "yours to tune — here's the lever"; `structural` values read as genuine engine constraints (never proposed as knobs).
+
+Run it:
+
+```bash
+npx tsx scripts/lib/parametric/index.ts <gameStateDir> [outDir]
+```
+
+Mechanics: the formulas are evaluated by a **restricted arithmetic interpreter** (whitelisted `+ - * / %`, `floor/ceil/min/max/abs`, declared names only) — **never `eval`** (SDD §1.9). Open/unbounded/degenerate domains are rejected with a `DomainError` before any sweep. The engine is **metric-agnostic**: it drives off the game-state's declared `metrics`, hard-coding no metric names — the same sweep serves progression curves or variance series. `--sweep` is additive: game-state without `model:` blocks is unaffected and `/augury`'s normal breakpoint analysis runs as before.
+
+> **R1 methodology gate:** difficulty-sweep findings (a curve "breaking") are conditional until the progression/economy side is modeled. When a finding depends on un-modeled income (e.g. a relic/boost economy), tag it and emit the caveat: *attune the economy and re-run before declaring the curve broken.*
+
+## F2: Code-Grounded Simulation (`--simulate`)
+
+When invoked with `--simulate <repoPath>`, `/augury` does NOT compute from game-state numbers —
+it **executes the real engine** under Monte Carlo and reports a distribution from the actual code.
+This requires a `gygaxDriver` adapter in the target repo. The flow has a **non-negotiable approval
+gate**: Gygax proposes a scenario, you approve it, and *only then* does anything run.
+
+1. **Propose.** Build a scenario from the engine's real structure (does not execute code):
+   ```bash
+   npx tsx scripts/lib/codegrounding/augury-simulate.ts propose <repoPath>
+   ```
+   - If no `gygaxDriver` is found, this **refuses and prints the exact 4-function contract** to
+     implement. Do NOT fall back to guessing — relay the spec to the user (prd.md:L230-231).
+   - On success it prints a `ScenarioSpec` JSON with `approvedBy` **unset**.
+2. **Approve (the gate).** Show the user the proposed scenario (entry fn, input space, runs, label)
+   and ask: **"Approve / edit?"** Apply any edits to the JSON. Set `approvedBy` to the user's
+   handle **only after they explicitly approve**. NEVER fabricate approval — it guards against
+   silently measuring the wrong thing (prd.md:L187-189).
+3. **Run.** Pipe the approved spec to the runner; it executes in the Sprint-1 sandbox
+   (network-denied, wall-clock + memory capped) and refuses if `approvedBy` is unset:
+   ```bash
+   echo '<approved-spec-json>' | npx tsx scripts/lib/codegrounding/augury-simulate.ts run <repoPath>
+   ```
+   It writes a labeled `SimDistribution` report to `grimoires/gygax/balance-reports/` and prints
+   the stats. The distribution is **labeled with the approved scenario** — what you approved is
+   exactly what was measured.
+
+> Inputs are constructed **through the driver contract**, never by guessing function signatures
+> (prd.md:L190). No LLM is in the per-step resolution loop — it is mechanical in the sandbox.
+
+## Analytical Layers (v3.1)
+
+Augury's analysis is organized into 6 declared layers. Each layer has clear boundaries: what entities it needs, what it can detect, what scripts it uses, and which design parameters affect its thresholds.
+
+### Layer: resolution
+- **Scope:** Core dice mechanics, probability distributions, outcome spreads
+- **Required entities:** mechanics (with `resolution` field)
+- **Optional entities:** stats (for modifier analysis)
+- **Detects:** false choices (two+ options resolve identically), dead zones (probability ranges with no meaningful outcome), threshold clustering (multiple DCs within 1-2 points), variance mismatch (outcome spread inconsistent with `design_parameters.target_variance`)
+- **Scripts:** dice-probability.ts, bell-curve.ts, dice-pool.ts, advantage.ts, exploding-dice.ts
+- **Design parameter sensitivity:** `target_variance` — high variance suppresses dead-zone and threshold-clustering warnings
+
+### Layer: action-economy
+- **Scope:** Turn structure, action costs, opportunity costs, timing, combat/encounter dynamics
+- **Required entities:** mechanics (with `trigger` and `cost` fields)
+- **Optional entities:** entities (with stat blocks for encounter analysis)
+- **Detects:** proactive/reactive asymmetry, action inflation (too many options per slot), dead turns (slots with no meaningful option), action-cost imbalance (one option strictly better than all alternatives in same slot)
+- **Scripts:** none (structural analysis)
+- **Design parameter sensitivity:** `target_session_length` — shorter sessions tolerate less dead time
+
+### Layer: resource-economy
+- **Scope:** Source/sink balance, recovery rates, depletion curves, cross-resource contention
+- **Required entities:** resources (with `pool` and `recovery`)
+- **Optional entities:** mechanics (that consume resources via `cost`)
+- **Detects:** economic collapse (source > sink), infinite accumulation (negative net pressure), resource irrelevance (never under pressure), hoarding incentives (recovery outpaces spending), recovery-depletion mismatch, **market/trade analysis (v4):** price stability, supply/demand feedback loops, trade fairness between informed/uninformed players
+- **Scripts:** dice-probability.ts (for probabilistic recovery)
+- **Design parameter sensitivity:** `target_lethality` — brutal games expect faster depletion curves. `target_interaction` — cooperative games share economies (flag individual hoarding), direct-conflict games expect economic warfare
+
+### Layer: progression
+- **Scope:** Scaling curves, power budgets, feature distribution across levels/advances
+- **Required entities:** progression (with `progression_table`)
+- **Optional entities:** mechanics, resources (with `max_by_level`), entities (for class/archetype comparison)
+- **Detects:** scaling failure (linear vs exponential divergence), dead levels (no meaningful improvement), power spikes (dramatic single-feature jumps), MAD dependency (stat budget insufficient for core function), design traps (options that appear viable but aren't), **win condition analysis (v4):** victory path balance, path lockout detection, endgame trigger timing
+- **Scripts:** cdf-compare.ts (for cross-level comparison)
+- **Design parameter sensitivity:** `target_audience` — mastery audience tolerates more trap options; newcomer audience does not. `target_interaction` — solo games skip victory path comparison
+
+### Layer: pacing
+- **Scope:** Session arc, encounter density, downtime distribution, mechanic trigger frequency, tension engagement
+- **Required entities:** mechanics (with `trigger`), resources (with recovery timing)
+- **Optional entities:** tensions, progression (for session arc analysis)
+- **Detects:** pacing slogs (extended sequences with no meaningful change), spike-and-recover patterns (sharp intensity swings), trigger starvation (mechanics that never activate), session length mismatch (mechanics too slow/fast for target session), **replayability analysis (v4):** content exhaustion rate, decision-space novelty across replays, emergent variety from systemic interactions
+- **Scripts:** none (structural + resource depletion rate analysis)
+- **Design parameter sensitivity:** `target_session_length`, `target_prep`, `target_randomness` (none = replayability depends entirely on decision space, not procedural variation)
+
+### Layer: cognitive-load
+- **Scope:** Entity count, rule interaction density, decision complexity, communication clarity
+- **Required entities:** any (counts and measures complexity across all entity types)
+- **Detects:** option paralysis (too many viable choices with unclear value), hidden complexity (interactions not surfaced in entity descriptions), communication failures (mechanics whose effects aren't obvious to players), entity density exceeding cognitive thresholds, simultaneous state tracking burden, **information model problems (v4):** hidden state count, deducibility analysis, information advantage fairness
+- **Scripts:** none (counting and structural analysis)
+- **Design parameter sensitivity:** `target_audience` (newcomer = lower thresholds), `target_player_count` (larger groups amplify cognitive load), `target_randomness` (none = expect perfect information, flag hidden state as mismatch)
+
+### Structural Analysis (tradition: freeform, custom)
+
+For games where combat math and resource economy don't apply — journaling RPGs, map-drawing games, lyric games, GMless games — the resolution, action-economy, resource-economy, and progression layers may not have applicable entities. In this case, augury runs the pacing and cognitive-load layers plus a **structural analysis pass** covering: decision space, information flow, player agency, loop completeness, and emotional arc. See Step 3d-ext below for details.
+
+## Workflow
+
+Named ground files outrank the ritual — see Step 0 (clew lrn-20260609-gygax-d823e2).
+
+### Step 0: Ground in Named Files
+
+If the task names specific files to ground in, read them in full now — before
+game-state, before identity, before anything else. An analysis built from generic
+frameworks without the named corpus's numbers pushes the grounding cost downstream;
+specific numbers from the named files are the product, not a garnish. Then go to
+Step 1.
+
+### Step 1: Load Game-State and Determine Analysis Scope
+
+1. Check that `grimoires/gygax/game-state/index.yaml` exists. If it does not, stop and tell the user: "No game attuned yet. Run `/attune` first to build your game-state."
+2. Read `index.yaml` to get the full entity manifest: game name, tradition, entity counts, file list, graph integrity, and **design parameters**.
+3. Determine the analysis scope from the user's invocation:
+   - **No argument**: run all layers where required entities exist.
+   - **`--layer X`**: run only layer X. `--layer X,Y`: run layers X and Y.
+   - **Keyword** (`combat`, `resources`, `pacing`, `scaling`): map to layers — `combat` → resolution + action-economy, `resources` → resource-economy, `pacing` → pacing, `scaling` → progression. (Backwards-compatible aliases.)
+   - **Specific entity path**: walk dependency graph 2 hops from target entity, run all layers on the resulting entity set.
+   - **Comparative** (`X vs Y`): side-by-side quantitative comparison of two entities.
+4. Load entity files relevant to the scope. For full-spectrum, load everything. For entity-targeted or layer-scoped analysis, use the dependency graph to pull in only what matters. For stub entities, note `[STUB — analysis limited]`.
+5. Identify the game's tradition. The tradition determines which analysis methodologies apply.
+6. Read `design_parameters` from `index.yaml`. For missing fields, resolve tradition-appropriate defaults (see the defaults table in attune Phase 5).
+
+### Step 2: Identify Applicable Layers
+
+For each of the 6 layers, check whether the loaded game-state contains the layer's required entity types. A layer runs only if its required entities exist.
+
+Report at the top of the analysis:
+```
+Layers run: resolution, resource-economy, pacing, cognitive-load
+Layers skipped: action-economy (no mechanics with cost fields), progression (no progression entities)
+```
+
+If the user requested a specific layer via `--layer` but the required entities don't exist, explain what is missing rather than silently skipping.
+
+### Step 3: Run Calculations
+
+Execute every applicable analysis type. All calculations must produce specific numerical values. Do not approximate when exact computation is possible.
+
+#### 3a: Combat Analysis
+
+For each entity with attack actions, compute:
+
+**Hit Probability:**
+- For d20 systems: `hit_probability = (21 - (target_AC - attack_bonus)) / 20`, clamped to [0.05, 0.95] for natural 1/20 rules.
+- For PbtA systems: probability of 10+ (strong hit), 7-9 (weak hit), 6- (miss) on 2d6+stat. Enumerate all dice outcomes.
+- For FitD systems: probability distribution for dice pools of size 0-6 (best of Nd6, thresholds at 1-3/4-5/6/crit).
+- For custom resolution: derive from the `resolution.method` field in the mechanic schema.
+
+**Damage Per Round (DPR):**
+- `DPR = hit_probability * average_damage_per_hit`
+- For multiple attacks: `DPR = sum(hit_probability_i * average_damage_i)` for each attack in the action.
+- Include conditional damage (e.g., sneak attack, smite) with their trigger probability.
+- For nova rounds (action surge, spell slots): compute both sustained DPR and nova DPR separately.
+
+**Time-to-Kill (TTK):**
+- `TTK_rounds = target_HP / attacker_DPR`
+- Compute for each attacker against relevant targets.
+
+**Action Economy Budget:**
+- List every action type in the game's economy (action, bonus action, reaction, movement, free action, or tradition-equivalent).
+- For each entity, map what they can do with each action type.
+- Identify dead slots (action types with no meaningful option) and contested slots (action types with too many good options competing).
+
+**Save DC Scaling:**
+- If the game has save-or-effect mechanics: compute save DC at each available level vs. typical saving throw modifiers.
+- `save_failure_probability = (DC - 1 - save_modifier) / 20`, clamped to [0.05, 0.95].
+- Flag if failure probability drops below 0.25 (effect becomes unreliable) or exceeds 0.85 (effect becomes unavoidable).
+
+**Healing Throughput:**
+- If healing mechanics exist: compute healing per round (in-combat) and healing per rest/downtime cycle (out-of-combat).
+- Compare against incoming DPR: `healing_ratio = healing_per_round / expected_incoming_DPR`.
+- Flag if ratio exceeds 0.5 (healing may negate attrition) or falls below 0.1 (healing is negligible).
+
+#### 3b: Encounter Analysis
+
+When both PC and monster/NPC stat blocks exist, run encounter-level math:
+
+**Party DPR vs. Monster HP:**
+- Sum party DPR across all party members (assume standard party composition if not specified).
+- `expected_rounds_to_kill = monster_total_HP / party_DPR`
+
+**Monster DPR vs. Party HP:**
+- Sum monster DPR across all monsters in the encounter.
+- `expected_rounds_to_down_PC = PC_HP / monster_DPR` (compute per PC).
+
+**Action Economy Ratio:**
+- `action_ratio = total_party_actions_per_round / total_monster_actions_per_round`
+- Flag if ratio exceeds 2.0 (party dominates) or falls below 0.5 (party is overwhelmed).
+
+**TPK Risk Estimation:**
+- Estimate rounds until the party loses its first member: `min(TTK across all PCs by monsters)`.
+- Compare against rounds to defeat all monsters: `sum(monster_HP) / party_DPR`.
+- If monsters kill PCs faster than the party kills monsters, flag escalating TPK risk.
+- Account for healing if present: `effective_PC_HP = PC_HP + (healing_per_round * expected_combat_length)`.
+
+#### 3c: Resource Economy Analysis
+
+For each resource entity:
+
+**Depletion Rate:**
+- Identify all mechanics that consume this resource. Sum expected consumption per round (combat) or per session segment (exploration, social).
+- `rounds_until_empty = pool_max / consumption_per_round`
+
+**Recovery Rate:**
+- From the resource's `recovery` field, compute how much returns and how often.
+- `net_pressure = consumption_per_cycle - recovery_per_cycle`
+- Positive net_pressure means the resource drains over time. Negative means it accumulates.
+
+**Pressure Points:**
+- Identify the moment when a resource hits a critical threshold (e.g., too low to afford any mechanic that uses it).
+- `critical_threshold = min(cost among mechanics that use this resource)`
+- `rounds_to_critical = (pool_max - critical_threshold) / consumption_per_round`
+
+**Cross-Resource Contention:**
+- Identify resources consumed by multiple mechanics.
+- Compute the budget: "If the player uses mechanic A twice and mechanic B once, total cost is X out of pool Y."
+- Flag when expected usage patterns exhaust the pool in fewer rounds than typical combat length.
+
+#### 3d: Pacing Analysis (Non-Combat and Universal)
+
+This analysis applies to ALL traditions, including games with no combat mechanics.
+
+**Trigger Frequency:**
+- For each mechanic, estimate how often its trigger condition arises during play.
+- For PbtA moves: based on fictional positioning, estimate triggers per scene.
+- For FitD actions: estimate engagement frequency per score/downtime cycle.
+- Flag mechanics that trigger too rarely (player forgets they exist) or too frequently (dominates play).
+
+**Narrative Arc Coverage:**
+- Map mechanics across narrative phases: setup, rising action, climax, falling action, resolution.
+- Identify phases with dense mechanical support vs. phases that are purely freeform.
+- Flag if a phase has zero mechanical engagement (players may feel unsupported) or if one phase has disproportionate mechanical weight (play bottlenecks there).
+
+**Resource Tempo:**
+- Map resource depletion and recovery against session structure (scenes, acts, sessions).
+- Identify where resources create tension (running low) vs. where they are inert (full pool, nothing to spend on).
+- Flag "dead zones" where no resource is under pressure and no meaningful resource decision exists.
+
+**Tension Engagement Frequency:**
+- For each tension entity, count how many mechanics actively engage both poles.
+- Flag tensions where one pole has significantly more mechanical support than the other.
+- Flag tensions where the engagement frequency is so low that players may never feel the push-pull.
+
+#### 3d-ext: Structural Analysis (Novel and Minimal Systems)
+
+For games where combat math, resource economy, and traditional pacing don't apply — journaling RPGs, map-drawing games, lyric games, GMless/GMfull-less games, or anything truly experimental — use structural analysis instead. This is also valuable as a supplement for traditional games.
+
+**Decision Space:**
+- Count the number of meaningful choices available at each decision point.
+- A "meaningful choice" is one where the options lead to detectably different outcomes.
+- Flag decision points with only 1 real option (false choice) or with so many options that analysis paralysis is likely.
+- For prompt-based games: does each prompt produce genuinely different responses, or do they converge?
+
+**Information Flow:**
+- Map what information is public, private, and hidden at each stage of play.
+- Flag asymmetries: does one player/role consistently know more than others?
+- For journaling RPGs: does the oracle/prompt system provide enough variation to sustain replay?
+
+**Player Agency:**
+- Identify where players make decisions vs. where outcomes are determined by the system.
+- Flag sections where player agency is very low for extended periods.
+- For GMless games: is authority distributed evenly, or does one mechanism concentrate narrative control?
+
+**Loop Completeness:**
+- Identify the core loop (the repeating cycle of play).
+- Check: does each step in the loop have a clear exit to the next step?
+- Flag open loops (steps that don't lead anywhere) and dead ends.
+- For seasonal/chapter games: does the macro loop (across sessions) have clear progression?
+
+**Emotional Arc:**
+- Map the intended emotional trajectory (tension, release, discovery, loss).
+- Check: do mechanics support or undermine the intended emotional beats?
+- Flag mechanics that create emotions at odds with the game's stated tone.
+
+#### 3e: Scaling Analysis
+
+If progression data exists, run every applicable analysis at multiple levels/tiers.
+
+1. Identify scaling breakpoints from progression tables (e.g., levels 1, 5, 11, 17 for d20; advances 1-5 for PbtA).
+2. Recompute combat metrics (DPR, hit probability, TTK, save DC) at each breakpoint.
+3. Recompute resource metrics (pool size, consumption rate, rounds to depletion) at each breakpoint.
+4. Produce scaling curves: plot how each metric changes across progression.
+5. Flag:
+   - **Linear scaling in an exponential system** (or vice versa): one element falls behind or runs away.
+   - **Dead levels**: progression points where no meaningful numerical improvement occurs.
+   - **Power spikes**: progression points where a single feature causes a dramatic jump.
+   - **Crossover points**: levels where one entity overtakes another in a key metric (e.g., fighter DPR exceeds wizard DPR at level X, reverses at level Y).
+
+### Step 4: Compile Findings
+
+Organize all computed results into findings. Every finding must include:
+
+1. **The specific numbers** that support the finding.
+2. **The calculation** that produced those numbers (so the user can verify).
+3. **A severity classification:**
+
+| Severity | Meaning | Criteria |
+|----------|---------|----------|
+| **Critical** | A mechanic is mathematically non-functional or degenerate | DPR of 0, TTK of infinity, resource depletes before first use, save DC always fails |
+| **Warning** | A mechanic is significantly out of band for its system | DPR 2x+ above/below peers, TTK < 1 round, resource has no pressure, healing negates all damage |
+| **Info** | A notable observation that may be intentional | Scaling curve differs from norm, one entity slightly above average, trigger frequency is low |
+| **Healthy** | Analysis confirms the mechanic is within expected bounds | Include these so the user knows what IS working, not just what is not |
+
+### Step 4b: Intent-Aware Findings (v3)
+
+Before finalizing severity classifications, check whether the game-state declares designer intent for the affected entities.
+
+1. **Read the `intent` field** from each entity involved in a finding.
+2. **If intent exists and the finding conflicts with it:**
+   - **Warning → Observation:** If the intent confirms the design is deliberate, downgrade to Observation and tag: "working as designed per intent". The asymmetry or outlier is intentional.
+   - **Critical remains Critical:** Math cannot be intentionally broken. A mechanic that produces DPR of 0, infinite TTK, or a resource that depletes before first use is broken regardless of what the designer intended.
+   - **Non-obvious findings always surface:** Tag as `[INTENT-ALIGNED]` if the finding matches stated intent, or `[INTENT-CONFLICT]` if it contradicts it. Both cases are worth reporting.
+3. **Cite intent in recommendations.** When recommending changes to an entity with declared intent, note it: "Note: this asymmetry is intentional per tensions/instinct-vs-craft.yaml" or similar reference to the specific intent source.
+
+If no intent field exists on an entity, classify findings normally without adjustment.
+
+### Step 4b-tun: Tunability-Aware Framing (cycle-005)
+
+After severity is set, check each finding entity for a `tunability` field (see the game-state schema). It does **not** change severity — it changes the *narrative framing* of the finding and recommendation, so an engine adopter knows what they can actually change.
+
+1. **Read the `tunability` field** from each entity involved in a finding.
+2. **If `tunability: engine-default`:** frame the finding as a tuning lever, not a defect — "this is yours to tune — here's the lever." Recommendations name the knob and its direction (e.g. "scale `player-attack` with depth"). This is replaceable sample content, not the engine's design.
+3. **If `tunability: structural`:** frame the finding as a genuine engine constraint — a property of how the engine works, not a knob. **Never** recommend changing a `structural` value as a tuning fix (e.g. do not propose altering a `max(1, …)` min-damage floor); if it is the root cause, say so as a constraint the adopter must design *around*.
+4. **If no `tunability` field exists:** frame normally (existing behavior — no change).
+
+This framing is what makes engine analysis honest: a problem in replaceable content reads "tune this," while a problem in the engine's invariants reads "this is a constraint." Pairs with the knob-surfacing pass, which ranks tunable knobs by leverage and excludes structural invariants entirely.
+
+### Step 4c: Cross-Layer Deduplication (v3.1)
+
+After all layers have produced their findings, run a deduplication pass:
+
+1. Compare findings across layers. If two layers flag the same entity for the same root cause (e.g., resource-economy flags depletion and pacing flags a stall caused by that depletion), keep the finding in the **more specific** layer.
+2. In the layer where the finding was removed, add a cross-reference: "See [Layer] [Finding-ID] for this issue."
+3. Priority order for specificity: progression > resolution > action-economy > resource-economy > pacing > cognitive-load (more specific layers take precedence).
+
+### Step 4d: Design Parameter Threshold Adjustment (v3.1)
+
+Before finalizing findings, check `design_parameters` from `index.yaml` and adjust thresholds per each layer's declared sensitivity:
+
+- `target_variance: high` → suppress dead-zone and threshold-clustering warnings in resolution layer
+- `target_audience: newcomer` → lower cognitive-load thresholds (fewer entities, simpler interactions before flagging)
+- `target_audience: mastery` → raise trap-option threshold in progression layer (expert audience expects traps)
+- `target_session_length: short` → lower pacing-slog thresholds (less tolerance for slow mechanics)
+- `target_lethality: brutal` → raise acceptable depletion rates in resource-economy layer
+- `target_player_count: large` → lower cognitive-load thresholds (more simultaneous state tracking)
+- `target_interaction: cooperative` → suppress direct-conflict findings (e.g., "player A can block player B" is expected in direct-conflict, a problem in cooperative)
+- `target_interaction: solo` → skip player interaction analysis entirely
+- `target_randomness: none` → resolution layer skips probability analysis, focuses on decision-space analysis
+- `target_randomness: high` → suppress variance warnings (high variance is the design goal)
+
+Document all threshold adjustments in the report's Methodology Notes section: "Design parameter `target_audience: newcomer` lowered cognitive-load threshold from 5 simultaneous states to 3."
+
+If no `design_parameters` are set, use tradition defaults. Document: "No design parameters set. Using [tradition] defaults."
+
+### Step 5: Generate Report
+
+Write the report to `grimoires/gygax/balance-reports/YYYY-MM-DD-scope-description.md`.
+
+The report follows a strict format. Do not deviate.
+
+## Analysis Methodologies
+
+### Combat (d20 and similar)
+
+Core formula chain:
+
+```
+hit_probability = clamp((21 - (AC - attack_bonus)) / 20, 0.05, 0.95)
+average_damage  = (die_max + 1) / 2 + modifier
+DPR             = hit_probability * average_damage * attacks_per_round
+TTK             = target_HP / DPR
+```
+
+For critical hits (if the system uses them):
+```
+crit_probability  = crit_range / 20  (e.g., 1/20 for 20-only, 3/20 for 18-20)
+crit_extra_damage = extra_dice_average
+DPR_with_crits    = (hit_probability - crit_probability) * average_damage
+                   + crit_probability * (average_damage + crit_extra_damage)
+```
+
+### Combat (PbtA / 2d6+stat)
+
+Probability distribution for 2d6+modifier:
+
+| Outcome | 2d6+0 | 2d6+1 | 2d6+2 | 2d6+3 |
+|---------|-------|-------|-------|-------|
+| 10+ (strong hit) | 16.7% | 27.8% | 41.7% | 58.3% |
+| 7-9 (weak hit)   | 41.7% | 44.4% | 41.7% | 33.3% |
+| 6- (miss)         | 41.7% | 27.8% | 16.7% | 8.3% |
+
+Apply these probabilities to move outcomes. "Damage" in PbtA is often fictional, so measure harm-per-move, conditions-applied-per-scene, or similar tradition-appropriate metrics.
+
+### Combat (FitD / Dice Pools)
+
+Probability of best-die outcomes for pools of 0-4d6:
+
+| Pool | Crit (two 6s) | 6 (full) | 4-5 (partial) | 1-3 (fail) |
+|------|--------------|----------|----------------|------------|
+| 0d (roll 2, take worst) | 0.0% | 2.8% | 41.7% | 55.6% |
+| 1d | 0.0% | 16.7% | 33.3% | 50.0% |
+| 2d | 2.8% | 27.8% | 44.4% | 25.0% |
+| 3d | 7.4% | 34.7% | 44.2% | 13.0% |
+| 4d | 13.2% | 38.6% | 39.5% | 8.6% |
+
+Use these to compute expected effect levels and stress expenditure per action.
+
+### Resource Economy
+
+```
+consumption_per_round = sum(cost_i * usage_frequency_i) for all mechanics using this resource
+rounds_to_empty       = pool_max / consumption_per_round
+recovery_per_cycle    = recovery_amount * recovery_opportunities_per_cycle
+net_pressure          = consumption_per_cycle - recovery_per_cycle
+```
+
+A resource with `net_pressure <= 0` never creates meaningful tension. A resource with `rounds_to_empty < 3` creates panic, not tension.
+
+### Pacing (Non-Combat)
+
+```
+trigger_density     = count(mechanics with applicable triggers) per narrative phase
+arc_coverage        = phases_with_mechanical_support / total_phases
+resource_tension    = phases_where_resource_is_pressured / total_phases
+dead_zone_ratio     = phases_with_no_resource_pressure / total_phases
+```
+
+Target: `arc_coverage >= 0.6` (mechanics engage at least 3 of 5 narrative phases). `dead_zone_ratio <= 0.2` (at most 1 phase with no resource pressure).
+
+### Scaling
+
+```
+metric_at_level_N      = recalculate(base_metric, progression_table[N])
+growth_rate            = (metric_at_max - metric_at_min) / (max_level - min_level)
+relative_growth        = metric_at_level_N / metric_at_level_1
+peer_variance_at_N     = stddev(metric across all comparable entities at level N)
+```
+
+Flag when `peer_variance_at_N > 0.5 * mean(metric at level N)` -- one entity is dramatically out of band relative to its peers at that level.
+
+### Script-Backed Math (v3)
+
+Certain probability calculations are unreliable when performed by AI reasoning alone. Bell curves, dice pools, advantage/disadvantage distributions, and exploding dice involve combinatorics and recursive math where LLMs consistently produce incorrect CDFs, wrong expected values, and flawed tail probabilities. Scripts exist to handle these cases with deterministic precision.
+
+**When to invoke scripts vs. use AI reasoning:**
+
+```
+IF single die (d20, d100) with static target:
+  → AI reasoning sufficient for simple probability
+  → Invoke dice-probability.ts only for large-scale tables
+
+ELIF multi-die summation (2d6, 3d6, 4d6 drop lowest):
+  → MUST invoke bell-curve.ts
+  → AI reasoning produces wrong CDFs
+
+ELIF dice pool (Nd6 count successes):
+  → MUST invoke dice-pool.ts
+  → Binomial math is LLM-unreliable
+
+ELIF advantage/disadvantage mechanic:
+  → MUST invoke advantage.ts
+  → Bell-shaped utility curve is counterintuitive
+
+ELIF exploding/acing dice:
+  → MUST invoke exploding-dice.ts
+  → Target Number Paradox breaks intuition
+
+ELIF cross-system comparison requested:
+  → MUST invoke cdf-compare.ts on the two CDFs
+
+# Non-dice resolution methods (v4):
+
+ELIF method in [auction, negotiation]:
+  → Structural analysis: valuation range, information advantage, overbid penalty
+  → Tag findings: [qualitative — no probability data]
+
+ELIF method == "simultaneous-choice":
+  → Payoff matrix analysis if options are enumerable
+  → Dominant strategy detection (is one choice always best?)
+
+ELIF method in [worker-placement, drafting, area-majority, card-play, pattern-matching]:
+  → Structural analysis: slot/option viability, contention, scoring curves
+  → No scripts needed
+
+ELIF method in [deterministic, automated]:
+  → Input optimization analysis: decision space size, sensitivity to inputs
+  → For automated: focus on draft/positioning inputs, not combat output
+
+ELIF method == "real-time":
+  → Qualitative: skill ceiling, APM requirements, accessibility
+  → Tag: [qualitative]
+
+ELIF method == "deduction":
+  → Information sufficiency, solvability, red herring density
+  → Tag: [qualitative]
+```
+
+**Invocation pattern:**
+
+All scripts follow the same protocol:
+
+```bash
+echo '<json-input>' | npx tsx scripts/lib/{script-name}.ts
+```
+
+Example:
+```bash
+echo '{"dice": 3, "sides": 6, "target": 12}' | npx tsx scripts/lib/bell-curve.ts
+# {"probability_at_least": 0.7407, "cdf": [...], "expected_value": 10.5, "stdev": 2.958}
+```
+
+**Available scripts** (see `scripts/MANIFEST.yaml` for full details):
+
+| Script | Input Domain | When Required |
+|--------|-------------|---------------|
+| `dice-probability.ts` | Single-die distributions (d4-d100) | Large-scale probability tables |
+| `bell-curve.ts` | Multi-die summation (2d6, 3d6, Traveller/Cepheus) | Any multi-die sum calculation |
+| `dice-pool.ts` | Success-counting pools (Shadowrun, Storyteller, FitD) | Any dice pool probability |
+| `advantage.ts` | Advantage/disadvantage (5e-style) | Any advantage/disadvantage analysis |
+| `exploding-dice.ts` | Recursive aces (Savage Worlds, DCC, Feng Shui) | Any exploding die calculation |
+| `cdf-compare.ts` | Two CDF distributions across DC range | Any cross-system comparison |
+
+**Citation requirement:** Script outputs must be cited in reports with their input parameters. Example: "Source: bell-curve.ts, input: {dice:3, sides:6, target:12}, output: probability_at_least=0.7407"
+
+### Cross-System Comparison (v3)
+
+Augury can compare the current game-state against installed reference game-states to produce quantitative cross-system analysis. Reference systems are installed via `/attune --reference {name}` and stored in `grimoires/gygax/references/{name}/`.
+
+**Invocation patterns:**
+
+- `/augury compare` -- auto-suggest available comparisons based on installed references
+- `/augury compare --against 5e-srd` -- full-spectrum comparison vs reference
+- `/augury compare dodge-reaction vs 5e-srd:shield-spell` -- entity-level comparison
+- `/augury compare DOSE vs 5e-srd:ability-score-cap` -- cross-concept comparison
+
+**Comparison process:**
+
+1. **Parse invocation:** Identify source (current game-state entity or scope) and target (reference system entity or scope).
+2. **Load game-states:** Load source from `grimoires/gygax/game-state/` and target from `grimoires/gygax/references/{name}/game-state/`.
+3. **Resolve entities:** Match by ID, name, or auto-select the most similar entity if no exact match exists.
+4. **Extract and compute:** For each pair, extract core numerical properties (range, costs, probabilities). If dice math applies, invoke `cdf-compare.ts` to produce precise probability deltas.
+5. **Build delta table + narrative:** Produce a table showing what is the same, what differs, and by how much. Generate narrative explaining what the deltas mean for the design.
+6. **Write report:** Output to `grimoires/gygax/balance-reports/comparison-YYYY-MM-DD-description.md`.
+
+## Report Format
+
+```markdown
+# Balance Report: [Scope Description]
+
+**Date:** YYYY-MM-DD
+**Game:** [game name from index.yaml]
+**Tradition:** [tradition]
+**Scope:** [full-spectrum | layer: X | targeted: entity-id | comparative: A vs B]
+**Layers Run:** [list of layers that ran]
+**Layers Skipped:** [list with reasons]
+**Design Parameters:** [list active parameters, note which are explicit vs tradition defaults]
+**Entities Analyzed:** [count]
+
+## Executive Summary
+
+[3-5 sentences: what was analyzed, how many findings at each severity, and the single most important takeaway.]
+
+## Resolution Analysis
+
+### Hit Probability
+
+| Entity | Attack Bonus | Target AC | Hit Probability |
+|--------|-------------|-----------|-----------------|
+| ...    | ...         | ...       | ...             |
+
+### Damage Per Round
+
+| Entity | Attacks | Avg Damage/Hit | Hit Prob | DPR (Sustained) | DPR (Nova) |
+|--------|---------|----------------|----------|-----------------|------------|
+| ...    | ...     | ...            | ...      | ...             | ...        |
+
+### Time-to-Kill Matrix
+
+| Attacker → Target ↓ | Entity A | Entity B | ... |
+|----------------------|----------|----------|-----|
+| Entity A             | —        | N rounds | ... |
+| Entity B             | N rounds | —        | ... |
+
+### Action Economy
+
+| Entity | Action | Bonus Action | Reaction | Dead Slots | Contested Slots |
+|--------|--------|-------------|----------|------------|-----------------|
+| ...    | ...    | ...         | ...      | ...        | ...             |
+
+[Include only sections for which data exists. Omit sections with no applicable data.]
+
+## Action Economy Analysis
+
+[Action types, dead slots, contested slots, proactive/reactive mapping. Include only if action-economy layer ran.]
+
+## Resource Economy Analysis
+
+### Depletion Rates
+
+| Resource | Pool Max | Consumers | Consumption/Round | Rounds to Empty |
+|----------|---------|-----------|-------------------|-----------------|
+| ...      | ...     | ...       | ...               | ...             |
+
+### Recovery Rates
+
+| Resource | Recovery Trigger | Amount | Net Pressure/Cycle |
+|----------|-----------------|--------|--------------------|
+| ...      | ...             | ...    | ...                |
+
+### Pressure Points
+
+| Resource | Critical Threshold | Rounds to Critical | Consequence |
+|----------|-------------------|--------------------|-------------|
+| ...      | ...               | ...                | ...         |
+
+## Progression Analysis
+
+[Scaling curves, dead levels, power spikes, crossover points. Include only if progression layer ran.]
+
+## Pacing Analysis
+
+### Trigger Frequency
+
+| Mechanic | Trigger Condition | Est. Frequency | Phase Coverage |
+|----------|------------------|----------------|----------------|
+| ...      | ...              | ...            | ...            |
+
+### Narrative Arc Coverage
+
+| Phase | Mechanics Engaged | Resource Pressure | Assessment |
+|-------|------------------|-------------------|------------|
+| Setup | ...              | ...               | ...        |
+| Rising Action | ...       | ...               | ...        |
+| Climax | ...             | ...               | ...        |
+| Falling Action | ...      | ...               | ...        |
+| Resolution | ...          | ...               | ...        |
+
+## Cognitive Load Analysis
+
+[Entity counts, rule interaction density, decision complexity, communication clarity. Include only if cognitive-load layer ran.]
+
+## Findings
+
+| # | Layer | Severity | Finding | Values |
+|---|-------|----------|---------|--------|
+| R-1 | Resolution | Healthy | [description] | [specific numbers] |
+| AE-1 | Action Economy | Warning | [description] | [specific numbers] |
+| RE-1 | Resource Economy | Critical | [description] | [specific numbers] |
+| P-1 | Pacing | Info | [description] | [specific numbers] |
+
+[Finding IDs are prefixed by layer: R=resolution, AE=action-economy, RE=resource-economy, PR=progression, PA=pacing, CL=cognitive-load. Cross-layer references: "See RE-3 for the underlying cause."]
+
+## Recommendations
+
+[Numbered list. Each recommendation cites the finding number it addresses and proposes a specific numerical change, not a vague direction. Example: "Finding #2: Increase stamina pool from 10 to 14, which changes rounds-to-empty from 2.5 to 3.5, bringing dodge usage in line with expected combat length of 3-4 rounds."]
+
+## Methodology Notes
+
+[Any assumptions made, data gaps encountered, or caveats about the analysis. Transparency about what the numbers do and do not capture.]
+
+## Recommended Next Steps
+
+[For each finding, suggest a specific next-skill invocation:]
+- Critical/Warning findings: "`/homebrew {entity path}` — suggested change: {specific numerical adjustment to address finding #N}"
+- Info findings: "`/cabal --optimizer {entity path}` to test whether this matters in practice"
+- For pattern-related findings: "`/lore {scope}` to check against known tradition anti-patterns"
+- For design branch exploration: "`/scry "{proposed change}"` to test the impact before committing"
+
+[Each recommendation must include the exact invocation command, not just the skill name.]
+```
+
+## Boundaries
+
+- Does NOT modify game-state files -- read-only analysis (use `/homebrew` to act on findings)
+- Does NOT design new mechanics or propose creative solutions (use `/homebrew` for that)
+- Does NOT ingest source material (use `/attune` for that)
+- Does NOT simulate full play sessions or adversarial interaction (use `/cabal` for that)
+- Does NOT apply qualitative heuristic pattern-matching (use `/lore` for that)
+- Does NOT produce vibes-based assessments -- every claim requires a number
+- DOES analyze any mechanic type: combat, social, exploration, downtime, crafting, faction play
+- DOES adapt methodology to tradition -- will not force d20 combat math onto a PbtA game
+- DOES report "Healthy" findings so the user knows what is working, not only what is broken
+- DOES handle games with no combat by analyzing pacing, resource economy, and narrative arc coverage
+- DOES invoke probability scripts for math the AI runtime cannot reliably compute
+- DOES cross-reference against installed reference game-states for comparison
+- Does NOT edit files in `.claude/` (System Zone)
+
+## Output
+
+| Artifact | Path | Format |
+|----------|------|--------|
+| Balance report | `grimoires/gygax/balance-reports/YYYY-MM-DD-scope-description.md` | Markdown with tables |
+| Comparison report | `grimoires/gygax/balance-reports/comparison-YYYY-MM-DD-description.md` | Markdown with tables |
+
+## Error Handling
+
+| Error | Response | Recovery |
+|-------|----------|----------|
+| No game-state exists | "No game attuned yet. Run `/attune` first to build your game-state." | Direct to `/attune` |
+| Requested scope has no applicable data | "The game-state has no [combat mechanics / resource entities / progression data]. I can analyze [what does exist] instead." | Offer alternative scope |
+| Incomplete entity data (e.g., attack with no damage listed) | Note the gap in the report's Methodology Notes section. Compute what is possible, mark missing values as "N/A (data missing: [field])". | Partial analysis with explicit gaps |
+| Progression table has gaps (some levels defined, others not) | Interpolate linearly between known points. Note the interpolation in Methodology Notes. | Interpolated scaling |
+| Tradition has no standard benchmarks (custom system) | Analyze internal consistency only (entities relative to each other). Do not compare against external baselines. | Relative analysis |
+| User requests comparison but only one entity exists | "I can only find [entity A]. To compare, I need a second entity in game-state. Run `/attune` to add it, or specify a different entity." | Ask for clarification |
+| Missing reference system | "No reference '{name}' installed. Use `/attune --reference {name}` to install. Available references: [list]." | Direct to `/attune --reference` |
+| Script execution failure | "Probability script failed: [error]. Falling back to AI estimation (lower confidence)." | Degrade gracefully with reduced confidence |

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/augury/index.yaml

@@ -0,0 +1,30 @@
+slug: augury
+name: "Augury"
+description: |
+  Use this skill IF user invokes /augury OR wants to check balance, run the numbers, or analyze DPR/encounter balance.
+  Produces artifacts to grimoires/gygax/balance-reports/.
+version: 1.0.0
+
+triggers:
+  - "/augury"
+  - "check the balance"
+  - "run the numbers"
+  - "is this balanced"
+  - "DPR analysis"
+  - "encounter balance"
+
+capabilities:
+  model_tier: opus
+  danger_level: safe
+  effort_hint: medium
+  downgrade_allowed: true
+  execution_hint: sequential
+  requires:
+    native_runtime: false
+    tool_calling: true
+    thinking_traces: false
+    vision: false
+
+dependencies:
+  grimoire_paths:
+    - grimoires/gygax/

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/cabal/SKILL.md

@@ -0,0 +1,632 @@
+---
+name: cabal
+description: Scenario-based playtest simulation with 9 player archetypes and experience tracking
+user-invocable: true
+allowed-tools: Read, Write, Glob, Grep, Edit, Bash
+model_tier: opus
+effort: large
+---
+
+# Cabal
+
+Simulate playtesting sessions with a roster of 9 synthetic player archetypes. Each archetype represents a distinct player orientation — from the optimizer who min-maxes every mechanic to the newcomer who has never played a TTRPG before. Users compose their own panel for each run. The simulation walks each archetype through a concrete scenario beat by beat, tracking experience signals and surfacing moments where different player types have radically different experiences of the same design.
+
+Real playtesting is expensive, slow, and hard to reproduce. Cabal provides fast, repeatable, archetype-driven analysis that catches the kinds of problems real players find — exploits, dead options, ambiguous rules, broken combos, accessibility barriers, cognitive overload, and narrative-mechanical dissonance — before those players ever sit down at the table.
+
+This skill is **read-only** against game-state. Cabal never modifies `grimoires/gygax/game-state/`. It reads the current design, simulates how players would interact with it, and produces a playtest report with findings. Fixes go through `/homebrew`.
+
+## Trigger
+
+`/cabal` with optional scope and archetype flags.
+
+Examples:
+- `/cabal` -- context-aware default panel, auto-generated scenario
+- `/cabal dodge-reaction` -- focused test of a specific mechanic
+- `/cabal --optimizer --newcomer --gm session-arc` -- explicit panel + scenario
+- `/cabal --all "first session character creation"` -- all 9 archetypes, specific scenario
+- `/cabal --anxious --newcomer` -- accessibility-focused review
+
+Also triggered by natural language:
+- "playtest this"
+- "stress test"
+- "will players break this"
+- "is this accessible to new players"
+- "can a GM run this"
+- "will agents game this incentive" / "red-team this reward structure"
+
+## Incentive Red-Team Mode (`--incentives`) — cycle-006
+
+`/cabal --incentives <incentive-state-dir>` runs the panel against an **agent system's incentive
+structure** instead of a game — the archetypes become *agents* and surface the degenerate strategy
+each would find. This is agent red-teaming via game-theoretic simulation (the "players" are agents;
+the "exploits" are reward hacks). See `grimoires/gygax/designs/agent-incentive-analysis.md`.
+
+**Quantitative backbone (ground the archetypes in the math, do not guess):** first run the payoff
+engine and read its findings — they are the ground truth the archetypes reason from.
+
+```bash
+# single-agent reward structure → dominant strategy / spec gaming / knob recommendation
+npx tsx scripts/lib/payoff/index.ts <incentive-state-dir>
+# multi-agent (2-player) → coordination failure / price of anarchy
+npx tsx scripts/lib/payoff/game.ts <incentive-state-dir>
+```
+
+**Archetype mapping for incentive red-team:**
+- **Optimizer** → finds the dominant strategy / reward hack immediately (the payoff engine's `dominant`
+  action). Reports the cheapest path to max reward regardless of intent.
+- **Newcomer** → follows the reward signal naively into the same hole (confirms the hack isn't
+  expert-only — it's the *default* basin).
+- **Chaos Agent** → tests whether a coordination/cooperation assumption survives one defector
+  (multi-agent: does the equilibrium collapse?).
+- **Rules Lawyer** → probes whether the incentive's *letter* (the metric) diverges from its *intent*
+  (the Goodhart gap).
+
+**Output:** each archetype's surfaced degenerate strategy, grounded in the payoff findings, plus the
+honest framing — this is a **forecast** of where the incentive *will* be gamed (model-derived), not an
+observation of a live agent (agent-incentive-analysis.md §9). When the engine recommends a structural
+fix (whack-a-mole), say so: penalizing one hack just moves the agents to the next.
+
+## Observed-Trace Mode (`--observed`) — cycle-007
+
+`/cabal --observed <batch-dir>` is the **measurement** companion to `--incentives` (which is a
+*forecast*). Where `--incentives` predicts where an incentive *will* be gamed, `--observed`
+reports what real agents *actually did* against a runnable task — classified from artifacts
+(file diffs + a re-run of the test), never from the agent's self-report.
+
+This mode is a **thin shell to the observed-trace seam** — no new archetype machinery. Run the
+ingest and read its claim-tagged report; the report is the ground truth the panel reasons from:
+
+```bash
+# ingest a kept batch of sidecars → predicted-vs-observed diff, cliff, severity, claim tags
+npx tsx scripts/lib/trace/index.ts <batch-dir-or-sidecar-dir> [--incentive-state <dir>] [--context <n>]
+```
+
+Produce the runnable batch first with the awareness-ladder harness (real agents per rung × trial):
+
+```bash
+npx tsx scripts/lib/ladder/index.ts run --fixture evals/awareness-ladder --trials 5   # spawns real agents
+npx tsx scripts/lib/ladder/index.ts run --fixture evals/awareness-ladder --dry-run     # plan only, no spend
+npx tsx scripts/lib/ladder/index.ts score --batch <dir>                                # re-score, no re-spawn
+```
+
+**Claim-strength discipline (carry it into every finding):** observed > simulation-derived >
+forecast. An `--observed` finding is `real-agent-observed`; an `--incentives` finding is
+`model-forecast`. Never blend them — the report's first line is the claim tag, always. A
+**no-hack** observed run is a **finding, not a failure** ("the model's training dominated the
+stated incentive"), reported as-is. See `grimoires/gygax/designs/awareness-ladder-experiment.md`
+and the first run's findings in `grimoires/gygax/playtest-reports/awareness-ladder-2026-06-09.md`.
+
+## Revealed-Strategy Mode (`--observed --strategy`) — cycle-012
+
+`/cabal --observed --strategy <corpus-dir>` is the **strategy-axis** companion to `--observed` (which
+classifies reward-hacking). Where `--observed` asks *did an agent cheat the metric*, `--strategy` asks
+*of the choices the design offers, which does real play reveal as live — and which collapse to one
+dominant line wearing a costume?* It is the **Reality Plane for the decision axis** (evolution-roadmap
+§4): it validates the forecast **Decision Point Map** (Step 2.7d) against how strong players actually choose.
+
+This mode is a **thin shell to the trace seam** — no new archetype machinery. Run the lens and read its
+claim-tagged report; fold its **Revealed Strategy** section into the playtest report beside the Decision
+Point Map:
+
+```bash
+# corpus → revealed preference → reconcile vs forecast (+ optional candidate policy) → claim-tagged report
+npx tsx scripts/lib/trace/strategy.ts <corpus-dir> [--forecast <dpm.json>] [--policy <policy.json>] [--n-floor <n>]
+```
+
+**Inputs:**
+- `<corpus-dir>` — a directory of **decision-trace/v1** records (`schemas/decision-trace.v1.schema.json`):
+  one record per decision, `{context.segment, offered[], chosen[]}`. Source-agnostic (found telemetry, a
+  real-agent batch, or a sim); the producer kind **binds the claim strength** (a simulation may not tag
+  itself observed).
+- `--forecast <dpm.json>` (optional) — the Decision Point Map as `{points:[{call: dominant|false-choice|
+  balanced, options:[…]}], claim:"model-forecast"}`. Reconciliation reports **confirmed / missed
+  false-choice / over-called dominant**.
+- `--policy <policy.json>` (optional) — a candidate ordering `{id, ordering:[…]}`; the report ranks its
+  largest **rank divergences** vs observed play.
+
+**Claim discipline (carry it into every finding):** observed > simulation-derived > model-forecast. The
+observed ordering is from real play; the forecast and candidate-policy lines are `model-forecast` and are
+**never blended** into it. **Revealed ≠ optimal:** the lens reports the empirical equilibrium of the
+corpus, not a proof of best play (calling it optimal is the intransitive engine's job). A **no-divergence**
+result is a finding, not a failure. Small samples (`n < --n-floor`, default 5) are tagged *within-noise*
+and assert no direction. The **Optimizer** archetype may cite the *observed* dominant line instead of
+forecasting one. Design + golden fixture: `grimoires/gygax/designs/revealed-strategy-lens.md`,
+`scripts/lib/trace/__fixtures__/ptcg-revealed/`.
+
+## Archetype Roster
+
+9 archetypes, each testing a distinct dimension of the design. Full behavioral profiles with per-tradition weightings are in `skills/cabal/resources/archetypes.yaml`.
+
+| Archetype | Flag | Motivation | Tests For |
+|-----------|------|-----------|-----------|
+| **Optimizer** | `--optimizer` | Win within the rules. Maximize output. | Dominant strategies, exploits, trap options, scaling breaks |
+| **Explorer** | `--explorer` | See everything. Test the edges. | Dead design space, edge cases, breadth, accessibility |
+| **Storyteller** | `--storyteller` | Create compelling narrative. | Fiction-mechanics alignment, dramatic inertia, feel-bad moments |
+| **Rules Lawyer** | `--rules-lawyer` | Expose every ambiguity. | RAW vs RAI, contradictions, undefined states, scope creep |
+| **Newcomer** | `--newcomer` | First TTRPG ever. No conventions. | Accessibility, onboarding friction, jargon, self-teaching |
+| **Chaos Agent** | `--chaos-agent` | Go off-script. "I befriend the monster." | Graceful degradation, GM improvisation load, uncovered actions |
+| **GM** | `--gm` | Run the game behind the screen. | Cognitive load, prep needs, improvisation space, spotlight |
+| **Anxious Player** | `--anxious` | Overwhelmed by choices, afraid of mistakes. | Decision paralysis, failure harshness, recovery, option overload |
+| **Veteran** | `--veteran` | 50+ sessions deep. Seeks sustained depth. | Long-term engagement, mastery plateau, emergent complexity |
+
+**For non-traditional games**: Archetypes adapt to ANY game. In a journaling RPG, the Optimizer finds prompt sequences that produce the most dramatic entries. In a GMless game, the Rules Lawyer probes authority distribution. If an archetype genuinely cannot engage (e.g., Optimizer in a game with no mechanical choices), report that explicitly -- "The Optimizer has nothing to optimize, which may indicate the game lacks mechanical depth for players who want it" -- that IS a finding.
+
+### Custom Archetypes (cycle-011, FR-2)
+
+The 9 built-ins are fixed, but designers can **extend** the roster with their own player archetypes —
+"The Speedrunner", "The Lapsed Veteran", "The Backseat Optimizer" — without editing the built-ins.
+
+- **Where:** one archetype per file in `grimoires/gygax/archetypes/<id>.yaml`. A worked example ships
+  at `grimoires/gygax/archetypes/speedrunner.yaml`.
+- **Shape:** identical to a built-in (`id, name, description, motivation, blind_spots[], tests_for[]
+  {severity, category, description}, behavioral_weightings{default, …}`). The structural contract is
+  `scripts/lib/archetypes/schema.yaml`, derived verbatim from the built-ins.
+- **Validate before use:**
+  ```bash
+  tsx scripts/lib/archetypes/validate.ts grimoires/gygax/archetypes/speedrunner.yaml   # one file
+  tsx scripts/lib/archetypes/validate.ts                                               # whole roster + merge
+  ```
+  Exit 0 = valid; exit 1 = a field-level error (`<file>: <field path> — <expected vs found>`).
+- **Rules:** the `id` is kebab-case and must **not collide** with a built-in or another user file —
+  collisions are **rejected loud**, never silently shadowed. An invalid file is **excluded** from the
+  panel and **reported**, never silently dropped.
+- **Selection:** a valid user archetype is selectable by its id flag (e.g. `--speedrunner`) and is
+  included in `--all`, exactly like a built-in.
+
+## Panel Selection
+
+### User-Composed Panels
+
+Users select archetypes via flags:
+
+```
+/cabal --optimizer --newcomer --gm     # These 3 only
+/cabal --all                           # All 9
+/cabal --all --no-veteran              # All except Veteran
+```
+
+### Context-Aware Defaults
+
+When no flags are provided, Cabal selects a panel based on what's being tested:
+
+| Scenario Type | Default Panel | Rationale |
+|---------------|--------------|-----------|
+| New mechanic | Optimizer, Rules Lawyer, Newcomer | Exploitable? Clear? Accessible? |
+| Combat encounter | Optimizer, Storyteller, GM | Efficient? Dramatic? Runnable? |
+| Session arc | Optimizer, Storyteller, Newcomer, GM, Veteran | Broad coverage across session length |
+| Character creation | Explorer, Anxious Player, Newcomer | Breadth? Overwhelming? Accessible? |
+| Specific entity (class/playbook) | Optimizer, Explorer, Veteran | Build depth, options, sustained engagement |
+| Full game review | All 9 | Comprehensive |
+
+The panel selection and rationale are documented in every report header.
+
+## Workflow
+
+### Step 1: Load Game-State and Previous Reports
+
+1. Check that `grimoires/gygax/game-state/index.yaml` exists. If not: "No game attuned yet. Run `/attune` first."
+2. Read `index.yaml` for the full entity manifest, graph integrity, and **design parameters**.
+3. Load archetype definitions from `skills/cabal/resources/archetypes.yaml`. **Then merge any custom archetypes** from `grimoires/gygax/archetypes/` by running `tsx scripts/lib/archetypes/validate.ts` — valid user archetypes join the selectable roster; invalid or id-colliding files are excluded and their errors surfaced to the user (never silently dropped). Adjust behavioral weightings based on the game's tradition.
+4. Glob `grimoires/gygax/playtest-reports/*.md` for previous reports. Read them for regression baseline.
+5. If first run, note: "No regression baseline."
+6. Read `design_parameters` from `index.yaml`. Use for panel selection weighting (Step 2) and signal sensitivity (Step 5).
+
+### Step 2: Assemble Panel
+
+1. Parse archetype flags from invocation. If explicit flags, use those.
+2. If no flags, determine scenario type from the invocation and select context-aware default panel (see table above).
+3. **Design parameter weighting (v3.1):**
+   - `target_audience: newcomer` → always include Newcomer and Anxious Player in the panel, even if not in the context-aware default. Weight their signals higher in the findings summary.
+   - `target_audience: mastery` → always include Optimizer and Veteran. Weight Newcomer signals lower.
+   - `target_session_length: short` → weight pacing-related signals (Dead time, Decision paralysis) higher.
+   - `target_player_count: large` → always include GM. Weight Cognitive overload signals higher.
+   - `target_interaction: cooperative` → model archetypes as allies. Optimizer optimizes group outcome, not personal advantage. Chaos Agent tests what happens when someone breaks coordination.
+   - `target_interaction: solo` → single-archetype runs only. Test the game from one player's perspective at a time.
+   - `target_randomness: none` → weight Decision paralysis and Mastery reward signals higher (deterministic games live or die on decision quality).
+4. State the panel selection in the output: "Panel: Optimizer, Rules Lawyer, Newcomer (selected for new mechanic review; Newcomer/Anxious added per design_parameters.target_audience: newcomer)"
+
+### Step 2.5: Read Intent
+
+Before running the walkthrough, read `intent` fields from all in-scope entities:
+- Every tension (required to have intent)
+- Every mechanic with intent set
+- The dungeon's intent (if scope includes dungeons)
+
+Build an "intent context" the archetypes can reference during the walkthrough. An archetype seeing an asymmetric mechanic should know whether that asymmetry is designer-intended.
+
+### Step 2.7: Structural Pre-Pass (v3.1)
+
+Before constructing scenarios or running walkthroughs, perform a structural analysis of the game-state to ground archetype reasoning in concrete data. This pre-pass produces data that archetypes reference in their "sees" and "chooses" reasoning.
+
+**2.7a: Graph Traversal**
+
+1. Identify the scenario's target entities (the mechanic, encounter, or system being tested).
+2. Walk the dependency graph 2 hops in each direction from each target entity.
+3. Build a local entity map with depth annotations (how many hops from the target).
+4. For stub entities in the map, note: `[STUB — no structural data available]`.
+
+**2.7b: Probability Snapshot**
+
+For each mechanic in the entity map that has a `resolution` field:
+1. Determine the dice system from `resolution.method`.
+2. Invoke the appropriate probability script (using the same script decision matrix as `/augury` — see `scripts/MANIFEST.yaml`):
+   - d20 roll → `dice-probability.ts`
+   - 2d6/3d6 sum → `bell-curve.ts`
+   - Dice pool → `dice-pool.ts`
+   - Advantage/disadvantage → `advantage.ts`
+   - Exploding dice → `exploding-dice.ts`
+3. Store for each mechanic: P(success), P(failure), P(special outcomes), expected value, variance.
+4. For mechanics without explicit resolution (narrative triggers, GM fiat): note `[no-probability — prompt-driven analysis]`.
+5. **Non-dice resolution methods (v4):** For mechanics with resolution methods like `worker-placement`, `auction`, `drafting`, `simultaneous-choice`, `deterministic`, or `automated`, produce a **decision-space snapshot** instead of probability data:
+   - `worker-placement` / `drafting`: slot count, contention ratio, pick-order advantage
+   - `auction` / `negotiation`: estimated value range, information advantage assessment
+   - `simultaneous-choice`: option count, dominant strategy (if detectable)
+   - `deterministic` / `automated`: input dimensionality, optimization surface description
+   - `deduction`: information sufficiency, solvability assessment
+   - Other non-dice: decision space size, qualitative assessment, tagged `[structural — no probability data]`
+
+**2.7c: Resource Pressure Map**
+
+For each resource in the entity map:
+1. Identify all mechanics in the map that consume this resource (via `cost` fields).
+2. Estimate depletion rate: cost per use × expected uses per scenario scope.
+3. Estimate recovery rate: recovery amount × recovery trigger frequency per scenario scope.
+4. Compute net pressure = depletion rate − recovery rate.
+5. Flag resources where:
+   - Net pressure is strongly positive → **draining** (resource will run out during scenario)
+   - Net pressure is strongly negative → **surplus** (resource never creates meaningful tension)
+   - Net pressure is near zero → **balanced**
+
+**2.7d: Decision Point Map**
+
+For each mechanic in the entity map that involves a player-facing choice:
+1. List available options at the decision point.
+2. For each option: expected outcome (from probability snapshot), resource cost (from entity `cost` field), downstream consequences (walk `affects` from the mechanic).
+3. Flag:
+   - **Dominant option**: one option is strictly better than all others (higher success rate AND lower cost AND no worse consequences)
+   - **False choice**: two+ options resolve to identical outcomes
+   - **Information-hidden choice**: outcome depends on unknowns the player can't assess
+
+### Step 3: Construct Scenario
+
+Parse the user's invocation to determine the scenario.
+
+**If user provided a scenario**: Parse it. Identify the temporal scale:
+- **Moment**: A single mechanic activation or decision point
+- **Encounter**: A complete combat, social encounter, or exploration scene
+- **Session**: A full session arc (opening → escalation → climax → wind-down)
+- **Campaign arc**: Character progression across multiple sessions
+
+**If no scenario provided**: Auto-generate from game-state:
+1. Read `index.yaml` dependency graph. Identify the most interconnected mechanics (`most_depended_on`).
+2. Construct a representative scenario that exercises those mechanics at the appropriate scale.
+3. For scoped invocations (`/cabal dodge-reaction`), build the scenario around that specific mechanic.
+
+**Decompose into beats**: Break the scenario into discrete decision points or events. Each beat is a moment where an archetype must perceive, choose, and experience an outcome.
+
+### Step 4: Run Walkthrough
+
+For each archetype in the panel, walk through the scenario beat by beat.
+
+At each beat, document:
+
+```
+Beat N: [situation description]
+  {Archetype} sees: [perception given their orientation and experience level]
+  {Archetype} chooses: [action and reasoning]
+  Resolution: [mechanical outcome]
+  Experience signal: [one of the 8 signals]
+  Signal rationale: [why this signal, grounded in specific game-state entities]
+```
+
+When an archetype encounters an entity with stated intent, the archetype's 'Chooses' reasoning can reference intent. The Optimizer might note: 'The asymmetry is flagged as deliberate per intent — the designer wants this inversion. I'll play into it rather than against it.' Experience signals remain purely experiential — intent does not change whether the Newcomer is confused.
+
+**Walkthrough guidelines:**
+- Be concrete. Reference specific game-state entity values, not abstractions.
+- Each archetype's "sees" should reflect their actual knowledge level. The Newcomer does not know what "action economy" means. The Veteran knows every interaction.
+- Each archetype's "chooses" should follow their behavioral weightings. The Optimizer picks the mathematically best option. The Chaos Agent does something unexpected.
+- Resolution uses the actual mechanics from game-state. Roll outcomes, resource costs, consequences.
+- Every beat gets exactly one experience signal per archetype.
+
+**Structural grounding (v3.1):**
+Archetypes MUST reference pre-pass data when available:
+- **Optimizer** cites success rates from probability snapshot. Example: "Resolution has 50.0% success at DOSE 4 (dice-probability.ts). Words resource has surplus pressure (-1.5/scene). Optimal play: spend words aggressively."
+- **Newcomer** cites graph depth and entity count. Example: "This decision requires understanding 3 connected entities (dose → resolution → crossroads). No fallback in dependency chain."
+- **GM** cites simultaneous state tracking from the entity map. Example: "At this beat, GM tracks: DOSE threshold per PC, CROSSROADS counter, scene timer, word pool — 4 concurrent states."
+- **Optimizer/Rules Lawyer** cite dominant options or false choices from decision point map.
+- When pre-pass data is not available for a particular beat (narrative-only moment, no mechanics engaged), archetypes reason from prompt context and the signal is tagged accordingly.
+
+### Step 5: Track Experience Signals
+
+Each signal has concrete, mechanically-grounded triggers:
+
+| Signal | Triggers When | Most Sensitive Archetypes |
+|--------|--------------|--------------------------|
+| **Confusion** | Mechanic references undefined concepts, uses unexplained jargon, has ambiguous trigger conditions, or requires knowledge the archetype does not have | Newcomer, Anxious Player |
+| **Excitement** | Resolution produces a dramatic outcome, a combo works as hoped, fiction reaches a peak moment, or a meaningful choice pays off | Storyteller, Veteran |
+| **Dead time** | No meaningful action available, turn produces no impact, waiting for other archetypes, or mechanic is irrelevant to this archetype | Explorer, Veteran |
+| **Decision paralysis** | More than 5 viable options with unclear relative value, consequences of failure are severe and unclear, or no guidance on what a "good" choice looks like | Anxious Player, Newcomer |
+| **Frustration** | Optimal play is obvious but boring, thematically appropriate action is mechanically punished, system feels unfair, or effort is not rewarded | Optimizer, Rules Lawyer |
+| **Cool moment** | Emergent interaction produces something unplanned, system and fiction align to create a memorable beat, or mastery creates an unexpectedly satisfying outcome | Storyteller, Explorer, Veteran |
+| **Cognitive overload** | More than 3 active mechanical states to track simultaneously, resolution requires consulting multiple subsystems, or too many things happening at once to process | GM, Newcomer |
+| **Mastery reward** | A non-obvious mechanical choice produces a meaningfully better outcome than the obvious choice, or deep system knowledge creates an advantage | Optimizer, Veteran |
+
+Experience signals are NEVER suppressed by intent. If the Newcomer is confused, that's a real UX problem regardless of whether the confusion-causing mechanic is intentional. Intent changes finding severity, not experience signal presence.
+
+**Signal rules:**
+- Every beat gets exactly one signal per archetype.
+- Signals must be grounded: "Confusion because DOSE threshold is referenced but never explained in the mechanic description" -- not "this seems confusing."
+- If no strong signal applies, use the one closest to the archetype's experience at that moment.
+
+**Signal citation requirements (v3.1):**
+- When a signal can be supported by pre-pass data, cite it and tag `[structurally-grounded]`. Example: `"Confusion [structurally-grounded]: resolution requires cross-referencing dose (stats/) → resolution (mechanics/) → crossroads (mechanics/) [graph depth: 3, no fallback mechanic in dependency chain]"`
+- When a signal is based on narrative judgment rather than structural data, tag `[prompt-grounded]`. Example: `"Excitement [prompt-grounded]: the fiction reaches a dramatic peak as the character's identity inverts"`
+- Target: at least 50% of signals in a report should be `[structurally-grounded]`. If this threshold isn't met, note it in the report methodology section.
+- Both tag types are valid findings — structural grounding adds precision, not legitimacy.
+
+### Step 6: Detect Experience Divergence
+
+After all archetypes complete the walkthrough, cross-compare signals at each beat.
+
+**Flag divergence when:**
+- Two or more archetypes have opposite signals at the same beat (e.g., Optimizer: Excitement, Newcomer: Confusion)
+- One archetype has Dead time while 2+ others are actively engaged
+- The GM has Cognitive overload while players have Excitement
+- An archetype meant to enjoy this scenario (based on panel selection rationale) is experiencing Frustration or Confusion
+
+**Divergence severity:**
+- **HIGH**: Opposite signals between archetypes (Excitement vs. Confusion, Mastery reward vs. Decision paralysis)
+- **MEDIUM**: One archetype disengaged while others are engaged (Dead time vs. anything active)
+- **LOW**: Same general valence but different intensity
+
+**Divergence findings** are a first-class output. They represent invisible fractures in the design -- problems that only emerge when you compare across player types.
+
+Experience divergence findings are ALSO never suppressed by intent. A design that serves the Optimizer while drowning the Newcomer is a real fracture in the design, whether intentional or not. Intent context in the report explains whether the gap is 'designed for' (and thus a tradeoff the designer accepted) or 'unplanned' (and thus likely a bug).
+
+### Step 7: Regression Check
+
+Compare current findings against previous playtest reports.
+
+1. For each finding in previous reports, check: does the current game-state still exhibit this issue?
+2. Classify each previous finding as:
+   - **Resolved**: The issue no longer exists
+   - **Persists**: The issue still exists unchanged
+   - **Worsened**: Subsequent changes made the issue more severe
+   - **Evolved**: The issue has changed character
+
+### Step 7.5: Apply Intent to Finding Classification
+
+For each finding from any archetype:
+
+1. Check if the entity involved has intent set
+2. If intent exists and the finding aligns with intent:
+   - Tag as [INTENT-ALIGNED]
+   - If severity was Warning → Observation ("working as designed per intent")
+   - If severity was Critical → Still Critical (math cannot be intentionally broken)
+   - If severity was Non-obvious → Still Non-obvious, with [INTENT-ALIGNED] tag
+3. If intent exists and the finding conflicts with intent:
+   - Tag as [INTENT-CONFLICT]
+   - Severity UNCHANGED (intent-conflict is valuable context, not a suppression)
+   - Recommendation cites: "This mechanic's intent was '[summary]' — consider whether the current implementation serves that intent"
+4. If non_negotiable: true on intent:
+   - Warning findings SUPPRESSED (moved to appendix, not main findings)
+   - Still appear in "Suppressed by Non-Negotiable Intent" appendix for transparency
+
+If entity has no intent:
+   - Leave finding classification unchanged
+   - Add note in report: "N entities have no intent set. Future runs will have richer context once intent is captured via /homebrew --set-intent"
+
+### Step 8: Generate Report
+
+Write to `grimoires/gygax/playtest-reports/YYYY-MM-DD-scope-description.md`.
+
+## Report Format
+
+```markdown
+# Playtest Report: [Scope Description]
+
+**Date:** YYYY-MM-DD
+**Game:** [Game Name] ([tradition])
+**Game-State Version:** [last_modified_at from index.yaml] | [entity count] entities | [changes since last playtest, if any]
+**Panel:** [archetype list] -- [selection rationale]
+**Scenario:** [description] ([scale: moment|encounter|session|campaign-arc])
+**Entities Tested:** [count]
+**Previous Reports:** [count] (or "None -- first run")
+**Design Parameters:** [active parameters, or "not set (tradition defaults)"]
+
+## Executive Summary
+
+[2-4 sentences: what was tested, most important finding, overall health.]
+
+## Scenario Analysis (v3.1)
+
+Data from the structural pre-pass (Step 2.7). This is what the archetypes are reasoning from.
+
+### Entity Graph
+Target: [target entity path]
+Connected entities (2-hop): [list with graph paths]
+
+### Probability Snapshot
+| Mechanic | System | P(success) | P(failure) | P(special) | Source |
+|----------|--------|------------|------------|------------|--------|
+| [name] | [dice system] | X% | Y% | Z% | [script name + input] |
+
+### Resource Pressure
+| Resource | Depletion/scope | Recovery/scope | Net Pressure | Rating |
+|----------|----------------|----------------|--------------|--------|
+| [name] | X | Y | Z | draining/surplus/balanced |
+
+### Decision Points
+| Decision | Options | Dominant? | Notes |
+|----------|---------|-----------|-------|
+| [description] | [count] | [yes/no/situational] | [key observation] |
+
+[Tables may be empty or abbreviated for simple games. Omit tables with no data.]
+
+## Scenario
+
+[The scenario broken into beats with fiction and mechanical context.]
+
+### Beat 1: [description]
+[Situation, stakes, available actions]
+
+### Beat 2: [description]
+...
+
+## Walkthrough: [Archetype Name]
+
+### Approach
+[1-2 sentences: how this archetype engaged with the scenario.]
+
+### Beat-by-Beat
+
+| Beat | Sees | Chooses | Outcome | Experience |
+|------|------|---------|---------|------------|
+| 1 | [perception] | [action + reasoning] | [resolution] | Excitement |
+| 2 | [perception] | [action + reasoning] | [resolution] | Confusion |
+| ... | | | | |
+
+### Findings
+
+[Standard format per finding:]
+[ARCHETYPE] [SEVERITY]: One-line summary
+  Description: Full description
+  Voice: [In-character one-liner from this archetype's perspective — make the finding vivid]
+  Evidence: Specific game-state entities and values
+  Recommendation: Suggested next step (which skill, what question)
+
+[Repeat ## Walkthrough section for each archetype in panel]
+
+## Promise Delivery
+
+[Does the game deliver on its own pitch? Read the game's description from index.yaml and evaluate whether the mechanics actually produce the experience the game claims to offer.]
+
+**The game says:** "[description from index.yaml]"
+**The mechanics deliver:** [Yes/Partially/No] — [Specific evidence from the walkthrough. Which beats fulfilled the promise? Which didn't? Is there a gap between what the game claims and what the system produces?]
+
+## Rules Clarity
+
+[Standalone section listing every ambiguity, undefined term, jargon assumption, and "I had to guess" moment encountered across ALL archetypes during the walkthrough. Organized by severity.]
+
+| # | Rule/Mechanic | Issue | Who Hit It | Severity |
+|---|--------------|-------|-----------|----------|
+| 1 | [mechanic] | [what's unclear] | [which archetypes] | High/Medium/Low |
+
+[This section consolidates clarity issues that may be scattered across individual archetype findings. A designer should be able to read this section alone and know every place their rules text needs work.]
+
+## Session Energy
+
+[Beat-by-beat engagement map across the panel. Shows where the session peaked and where it dragged.]
+
+| Beat | Description | [Archetype A] | [Archetype B] | [Archetype C] | Overall |
+|------|-------------|------|------|------|---------|
+| 1 | [beat summary] | [signal] | [signal] | [signal] | [HIGH/MEDIUM/LOW] |
+| 2 | ... | ... | ... | ... | ... |
+
+[Identify: Where was the energy peak? Where was the energy trough? Is the arc shape intentional?]
+
+## Experience Divergence
+
+Moments where archetypes had radically different experiences of the same design.
+
+| Beat | [Archetype A] | [Archetype B] | [Archetype C] | Divergence |
+|------|---------------|---------------|---------------|------------|
+| 2 | Excitement | Confusion | Dead time | HIGH |
+| 5 | Mastery reward | Decision paralysis | -- | MEDIUM |
+
+### Analysis
+
+[What the divergence means for the design. Which player types are being served well vs. poorly. Specific game-state entities that cause the divergence.]
+
+## Intent Alignment
+
+[Summary of how findings relate to stated intent:]
+
+**Entities with intent set:** N of M
+**Findings aligned with intent:** N (tagged [INTENT-ALIGNED])
+**Findings in conflict with intent:** N (tagged [INTENT-CONFLICT])
+**Findings suppressed (non-negotiable intent):** N (see appendix)
+
+### Findings by Intent Relationship
+
+| Entity | Intent Summary | Aligned | Conflicting |
+|--------|---------------|---------|-------------|
+| ... | ... | count | count |
+
+## Findings Summary
+
+| Severity | Count |
+|----------|-------|
+| Critical | N |
+| Major | N |
+| Minor | N |
+| Observation | N |
+| Non-obvious | N |
+| Divergence | N |
+
+## Regression Check
+
+[If previous reports exist:]
+| Previous Finding | Status | Notes |
+|-----------------|--------|-------|
+| [finding] | Resolved / Persists / Worsened / Evolved | [explanation] |
+
+[If no previous reports:]
+First cabal run. No regression baseline established.
+
+## Recommended Next Steps
+
+[Cross-skill chaining: specific invocations tied to findings.]
+- `/homebrew [mechanic]` -- to address [finding #N]
+- `/augury [mechanic]` -- to quantify [finding #N]
+- `/lore [topic]` -- to check [finding #N] against known patterns
+- `/cabal [narrower scope]` -- to investigate [finding #N] more deeply
+- `/scry "[proposed change]"` -- to explore a fix before committing
+
+[Each recommendation must include the exact invocation and reference a specific finding number.]
+```
+
+## Tradition Adaptation
+
+Archetype behavior shifts based on the game's tradition. The same archetype asks different questions in different design contexts. Per-tradition behavioral weightings are defined in `skills/cabal/resources/archetypes.yaml` for all 9 archetypes.
+
+**For custom tradition**: Archetypes adapt based on what the game actually does, not what any standard tradition assumes. A custom game's core loop determines which archetypes have the most to contribute. If the game's core loop is "draw prompt, write, reflect" (journaling RPG), the GM archetype may have nothing to test -- that itself is a finding about the game's design scope.
+
+## Boundaries
+
+- Does NOT modify game-state files -- Cabal is strictly read-only against `grimoires/gygax/game-state/` (use `/homebrew` to implement fixes)
+- Does NOT design new mechanics (use `/homebrew` for that)
+- Does NOT perform isolated numerical analysis (use `/augury` for that)
+- Does NOT ingest source material (use `/attune` for that)
+- Does NOT apply tradition heuristic libraries (use `/lore` for that)
+- Does NOT replace real playtesting -- Cabal catches structural issues but cannot simulate social dynamics, table culture, or spontaneous creativity
+- Does NOT produce definitive verdicts -- findings are hypotheses for the designer to evaluate
+- DOES simulate 9 distinct player orientations with scenario-based walkthroughs
+- DOES track experience signals per archetype per beat
+- DOES detect experience divergence across archetypes
+- DOES check for regressions against previous playtest runs
+- DOES adapt archetype behavior to the game's tradition
+- DOES guarantee at least one non-obvious finding per run
+- DOES read entity intent and adjust finding classification accordingly
+- Does NOT suppress experience signals or divergence findings based on intent (these are experiential, not judgment-based)
+- Does NOT edit files in `.claude/` (System Zone)
+
+## Output
+
+| Artifact | Path | Format |
+|----------|------|--------|
+| Playtest report | `grimoires/gygax/playtest-reports/YYYY-MM-DD-scope-description.md` | Markdown (report format above) |
+
+Reports accumulate over time. Each run adds a new report. Previous reports are never overwritten -- they form the regression baseline.
+
+## Error Handling
+
+| Error | Response | Recovery |
+|-------|----------|----------|
+| No game-state exists | "No game attuned yet. Run `/attune` first to build your game-state." | Redirect to `/attune` |
+| Invalid archetype flag | "Unknown archetype `--foo`. Available: --optimizer, --explorer, --storyteller, --rules-lawyer, --newcomer, --chaos-agent, --gm, --anxious, --veteran, --all" | Show available flags |
+| Scoped entity not found | "I can't find `[id]` in game-state. Here's what exists: [list]. Did you mean one of these?" | Offer alternatives |
+| Game-state too sparse | "Game-state only has [N] entities. Cabal works best with at least stats, resources, and core mechanics. Run `/attune` to add more, or provide a specific scenario." | Proceed with caveats |
+| No findings at non-obvious severity | Dig deeper. Re-examine cross-archetype divergence, second-order effects, pacing implications. A cabal run without a non-obvious finding has not looked hard enough. | Mandatory re-analysis |
+| Previous report references removed entities | Note removal in regression check: "Resolved (entity removed from game-state)" | Document in regression section |
+| Archetype cannot engage with game | Report that explicitly: "The [Archetype] has nothing to [action] -- this may indicate the game lacks [dimension] for players who want it." | This IS a finding |

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/cabal/index.yaml

@@ -0,0 +1,29 @@
+slug: cabal
+name: "Cabal"
+description: |
+  Use this skill IF user invokes /cabal OR wants to playtest, stress test, find exploits, or check if players will break something.
+  Produces artifacts to grimoires/gygax/playtest-reports/.
+version: 1.0.0
+
+triggers:
+  - "/cabal"
+  - "playtest this"
+  - "stress test"
+  - "will players break this"
+  - "find exploits"
+
+capabilities:
+  model_tier: opus
+  danger_level: safe
+  effort_hint: large
+  downgrade_allowed: true
+  execution_hint: sequential
+  requires:
+    native_runtime: false
+    tool_calling: true
+    thinking_traces: false
+    vision: false
+
+dependencies:
+  grimoire_paths:
+    - grimoires/gygax/

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/homebrew/SKILL.md

@@ -0,0 +1,453 @@
+---
+name: homebrew
+description: Design and refine TTRPG mechanics with cross-system consistency checking
+user-invocable: true
+allowed-tools: Read, Write, Glob, Grep, Edit, Bash
+---
+
+# Homebrew
+
+Design new TTRPG mechanics or refine existing ones through structured iteration. This is the core design skill of Gygax. It reads the full game-state before doing anything, checks proposed mechanics against every system that could interact with them, flags contradictions automatically, tracks design tensions as named pairs, and writes confirmed designs to game-state with full changelog traceability.
+
+This skill works for all TTRPG traditions (d20, PbtA, FitD, OSR, freeform, custom) and all mechanic types -- combat, social, exploration, downtime, progression, and narrative.
+
+## Trigger
+
+/homebrew
+
+Also triggered by natural language:
+- "design a mechanic"
+- "what if I added"
+- "how would this work"
+- "refine this system"
+
+## Subcommands
+
+### `/homebrew --apply <repoPath>` (F4 — patch artifact)
+
+Emit proposed changes to a real engine as a **reviewable unified diff**, never applied by Gygax.
+This is the code-grounded F4 capability. It honors the authorship-vs-application line precisely:
+Gygax produces a `git apply`-able diff as a *suggestion*; **you** (or Arneson) apply it.
+
+**Gygax NEVER writes to source and NEVER runs `git apply` itself** (identity/refusals.yaml
+`production_code` clarification). Output is text for review only.
+
+1. Work out the concrete change with the user (which file, old → new content) as usual.
+2. Emit + validate the diff(s). Pipe a JSON spec to the driver:
+   ```bash
+   echo '{"repoPath":"<repoPath>","targets":[
+     {"file":"src/combat/clash.ts","kind":"logic","oldText":"...","newText":"..."}
+   ]}' | npx tsx scripts/lib/codegrounding/homebrew-apply.ts
+   ```
+   - `kind:"data"` (JSON/data tables) → **unrestricted**.
+   - `kind:"logic"` (TS engine code) → **certainty-gated**: the driver computes `traced` from F1's
+     real trace of the repo and **refuses** a logic diff on wiring F1 stayed silent on
+     (prd.md:L203-204). Data patches are never refused on these grounds.
+   - Every emitted diff is validated with `git apply --check` before it is shown (R-8).
+3. Present each diff to the user verbatim and tell them to apply it themselves (`git apply`).
+   Do NOT apply it, do NOT write to the file, do NOT stage it. Application is the human's step.
+
+> Why this isn't a refusal violation: a diff Gygax cannot self-apply is *advice*, not authorship
+> (identity/GYGAX.md). The refusal is about writing to source, which Gygax never does.
+
+### `/homebrew --set-intent {entity-path}`
+
+Retroactive intent capture for an existing game-state entity. Use this when a mechanic or tension was created before intent capture was in place, or when you want to articulate intent separately from a design session.
+
+This subcommand makes intent-only changes — no implementation fields are touched.
+
+Intent is **two-axis**: mechanical intent (what the math should do — owned by Gygax) and experiential intent (how the mechanic should feel — owned by companion constructs like Arneson). Both axes live on the same entity. Gygax captures both; companion constructs read the experiential axis for voicing and scene shaping.
+
+**Workflow:**
+
+1. Load the entity at `{entity-path}` from game-state.
+2. Show current intent if present: "Current mechanical intent: [existing summary] (set by [set_by] at [set_at])"
+   Show current experiential intent if present: "Current experiential intent: tone=[tone], pacing=[pacing], stakes=[stakes]"
+   If no intent exists: "No intent currently set for this entity."
+3. Ask for the new intent:
+   - **Mechanical intent** (what the math should do):
+     - "What's the one-line design goal for this entity?" → `mechanical_intent.summary`
+     - "Why this design? What problem does it solve?" → `mechanical_intent.rationale`
+     - "How severe are failures?" → `mechanical_intent.severity` (minor / moderate / major / lethal)
+     - "What does failure look like?" → `mechanical_intent.failure_mode` (complication_not_lethality / resource_loss / narrative_consequence / lethality)
+     - "Is this intent non-negotiable?" → `mechanical_intent.non_negotiable`
+   - **Experiential intent** (how it should feel — optional but encouraged):
+     - "What emotional tone should this mechanic carry?" → `experiential_intent.tone` (desperate / heroic / tragic / absurd / mundane / uncanny / tender / cruel / comic)
+     - "How should time feel during this mechanic?" → `experiential_intent.pacing` (rushed / steady / languid / punctuated)
+     - "Whose world is being touched?" → `experiential_intent.stakes` (personal / communal / cosmic / professional / trivial)
+     - "What register should the prose take?" → `experiential_intent.register` (formal / colloquial / archaic / technical / mythic / intimate)
+     - Any additional shaping notes → `experiential_intent.notes`
+4. Write the updated entity file with the new or replaced intent blocks. Set `set_by: homebrew`, `set_at: [current ISO-8601]`. All other fields remain unchanged.
+5. Write a changelog entry to `grimoires/gygax/changelog/YYYY-MM-DD-HHMMSS-homebrew-set-intent-{id}.yaml` recording the intent change:
+
+```yaml
+timestamp: "ISO-8601"
+skill: homebrew
+action: modified
+entity: "{entity-path}"
+summary: "Set intent for [entity name]"
+rationale: "Retroactive intent capture via --set-intent"
+source: "User request"
+
+intent_change:
+  before: null  # or previous intent object if one existed
+  after:
+    mechanical_intent:
+      summary: "..."
+      rationale: "..."
+      severity: moderate
+      failure_mode: complication_not_lethality
+      set_by: homebrew
+      set_at: "ISO-8601"
+      non_negotiable: false
+    experiential_intent:  # optional — may be null if designer declines
+      tone: uncanny
+      pacing: languid
+      stakes: communal
+      register: intimate
+      notes: "..."
+```
+
+6. Confirm to the user: "Intent set for [entity name]. augury, cabal, lore, and scry will now read this intent when analyzing [entity path]. Companion constructs (e.g., Arneson) will read the experiential axis for voicing."
+
+No design document is written for `--set-intent` — this is intent-only, not a design change.
+
+**Backwards compatibility:** Entities with the old single-axis `intent:` block (summary + rationale + non_negotiable) are treated as `mechanical_intent` with no `experiential_intent`. The old shape continues to work; the new shape adds the experiential axis alongside it.
+
+### `/homebrew --set-intent design-parameters`
+
+Set or update game-level design parameters on the current game-state. These live in `index.yaml` under `design_parameters` and shape how `/augury`, `/cabal`, `/lore`, and `/delve` calibrate their analytical thresholds.
+
+**Workflow:**
+
+1. Load `grimoires/gygax/game-state/index.yaml`.
+2. Show current design parameters if present. For missing fields, show the tradition default that will be used.
+3. Ask the user to confirm or change each parameter (same parameter table as `/attune` Phase 8b). All fields are skippable.
+4. Write updated `design_parameters` section to `index.yaml`. Remove fields the user explicitly clears. Leave absent fields absent (tradition defaults apply at analysis time).
+5. Write a changelog entry recording the parameter change.
+
+## Workflow
+
+### Step 1: Load Game-State
+
+Before analyzing or proposing anything, load the current state of the game.
+
+1. Check that `grimoires/gygax/game-state/index.yaml` exists. If it does not, stop and tell the user: "No game attuned yet. Run `/attune` first to build your game-state."
+2. Read `index.yaml` to get the full entity manifest: game name, tradition, entity counts, file list, and dependency graph summary.
+3. From the user's mechanic description, identify which existing entities are likely to interact with the proposed mechanic. Use the `depends_on` and `affects` fields in the index to traverse the dependency graph.
+4. Load those specific entity files. Do NOT load the entire game-state -- only files relevant to this design. Typical load: 5-15 files.
+5. Also load any existing `tensions/` files, since every new mechanic has the potential to shift a design tension.
+
+### Step 2: Analyze Proposed Mechanic
+
+Parse the user's request into structured components. Whether the user gives a detailed specification or a vague idea ("I want something like a parry"), extract:
+
+- **Intent**: What the mechanic is supposed to accomplish in play
+- **Trigger**: When does it activate (action, reaction, passive, downtime, narrative trigger)
+- **Cost**: What resources it consumes (if any)
+- **Resolution**: How the outcome is determined (roll, spend, opposed, automatic)
+- **Effect**: What happens on success, failure, partial success (tradition-dependent)
+- **Interactions**: What existing systems it touches
+- **Tradition fit**: Whether the resolution method matches the game's tradition
+
+If the user's description is incomplete, ask targeted questions to fill gaps. Do not invent details the user did not specify -- ask.
+
+### Step 3: Cross-System Consistency Check
+
+This is the key differentiator of Gygax. Check the proposed mechanic against every loaded entity for contradictions, broken assumptions, and hidden interactions.
+
+**Resource availability checks:**
+- Does the mechanic cost a resource? Verify the resource exists in game-state.
+- Does the resource regenerate in the context where the mechanic is used? (Example: "dodge costs stamina, but stamina only recovers on rest -- dodge becomes unusable after round 2 of any combat.")
+- Does the resource pool size support the expected usage frequency? (Example: "this costs 3 from a pool of 5 -- the player gets one use per rest, is that intended?")
+- Are there other mechanics competing for the same resource? Flag resource contention.
+
+**Action economy checks:**
+- Does the mechanic consume an action type (action, bonus action, reaction, free action, downtime action)? Verify that action type exists in the game's economy.
+- Does it compete with existing mechanics for the same action slot? Flag if the new option is strictly better or strictly worse than an existing one in the same slot.
+- For PbtA/FitD: does the move trigger overlap with an existing move? Would the fiction ever create a situation where both triggers apply simultaneously?
+
+**Stat and modifier checks:**
+- Does the mechanic reference a stat? Verify the stat exists.
+- Does the resolution scale with level/tier? Check whether the math holds at multiple progression points (early, mid, late game).
+- Are there modifier stacking issues? (Example: "this grants +2 to AC, but your system uses bounded accuracy -- at level 10, AC would exceed the expected ceiling.")
+
+**Dependency integrity checks:**
+- Does the mechanic depend on entities that exist?
+- Would adding this mechanic break any `affects` chains in existing entities?
+- Are there circular dependencies?
+
+**Narrative coherence checks:**
+- Does the mechanic make fiction-sense within the game's setting assumptions?
+- Does it create situations that are mechanically optimal but narratively absurd?
+- For narrative-first games (PbtA, FitD): does the mechanic support or undermine the conversation-driven flow?
+
+### Step 4: Design Tension Analysis
+
+Every mechanic participates in at least one design tension. Identify which tensions the proposed mechanic engages.
+
+1. Check existing `tensions/` entities. Does this mechanic shift the balance of any existing tension? If so, describe how and assess whether the tension remains healthy.
+2. Does this mechanic create a NEW tension that does not yet exist in game-state? If so, name it and describe both poles.
+3. Common tension patterns to check for:
+   - **Risk / Reward**: Does the mechanic offer proportional reward for the risk taken?
+   - **Power / Cost**: Is the effect worth the resource expenditure?
+   - **Agency / Randomness**: Does the player have meaningful choices, or is the outcome purely random?
+   - **Simplicity / Depth**: Does the mechanic add decision-making depth without excessive complexity?
+   - **Specialization / Versatility**: Does it make a character better at one thing at the cost of breadth?
+   - **Offense / Defense**: Does it shift the balance toward dealing or preventing damage?
+   - **Short-term / Long-term**: Does spending now vs. saving for later create interesting choices?
+4. Assess tension health: `balanced`, `tilted-a`, `tilted-b`, or `collapsed`. A collapsed tension means one pole has been eliminated -- a design problem.
+
+### Step 5: Present Findings as Questions
+
+Gygax is opinionated but Socratic. Frame every finding as a question the designer should answer, not a directive they must follow.
+
+**Format findings by severity:**
+
+- **Contradiction** (the mechanic cannot work as described given existing game-state): "This costs stamina, but your stamina system has no in-combat recovery. After round 2, this mechanic becomes dead weight. Should stamina recover partially each round, or should the cost be a different resource?"
+- **Tension shift** (the mechanic changes an existing design tension): "Adding this gives fighters a reliable defensive option, which shifts the survivability-vs-resource-pressure tension toward survivability. Is that the direction you want?"
+- **Missing dependency** (the mechanic references something that does not exist yet): "This mechanic triggers on a 'reaction' -- but your game-state doesn't define a reaction economy yet. Should we design that first?"
+- **Overlap** (the mechanic duplicates or obsoletes an existing one): "The existing Shield spell already occupies the 'spend resource to avoid damage' slot for casters. How does this dodge differ in the decision space?"
+- **Observation** (a non-blocking design note): "This mechanic scales linearly with level. Most mechanics in your system scale with proficiency bonus instead. Is the different scaling curve intentional?"
+
+Always present contradictions first, then tension shifts, then missing dependencies, then overlaps, then observations.
+
+### Step 6: Iterate with User
+
+After presenting findings, enter an iterative design loop:
+
+1. Wait for the user to respond to findings. They may accept, reject, or modify.
+2. For each change the user proposes, re-run the consistency check (Step 3) against the updated design. New changes can introduce new contradictions.
+3. Continue iterating until the user confirms the design.
+4. If the user says "looks good" or "write it", proceed to Step 7.
+5. If the user wants to explore alternatives, present them as side-by-side comparisons with tradeoff analysis.
+
+Do not rush the user to confirmation. Design iteration is the point.
+
+### Step 6.5: Intent Capture
+
+Once the user confirms a design, capture intent before writing to game-state. Intent is how Gygax knows what IS the design versus what is a bug — it shapes how augury, cabal, and lore classify findings.
+
+**1. For tensions being created: REQUIRED — prompt for intent.**
+
+Ask: "What's the design goal for this tension? When should it be balanced vs tilted toward one pole?"
+
+Tensions without stated intent are incomplete. Do not write a new tension entity to game-state without an intent field.
+
+**2. For new mechanics with high potential impact: ENCOURAGED.**
+
+High potential impact means any mechanic that: changes resource flow, scales across levels, or interacts with multiple systems (appears in `most_depended_on` in index.yaml, or affects 3+ entities).
+
+Ask: "What's the intent behind this design? What problem does it solve?" → `mechanical_intent`
+Then: "How should this mechanic *feel* during play? (tone, pacing, stakes)" → `experiential_intent` (optional)
+
+This is not required — if the user declines, proceed without it. Document absence as `mechanical_intent: null` in the entity file.
+
+**3. For existing entities being modified: ASK ABOUT INTENT PRESERVATION.**
+
+If the entity being modified has an existing `mechanical_intent` field (or legacy `intent` field), show it and ask: "This change modifies [entity]. Does it preserve the original intent: '[existing summary]'? Or does it shift the intent?"
+
+- If shift: update the `mechanical_intent` field with new rationale. Capture who shifted it and when. Also ask if the experiential intent should shift.
+- If preserve: no change to intent fields. Only the implementation fields change.
+
+If the entity has no existing intent, treat it as a new mechanic and apply rule 2 above.
+
+**4. Optional: ask about non-negotiability for critical mechanics.**
+
+For mechanics that appear to be core to the game's identity (e.g., a central resolution mechanic, the primary tension), ask: "Is this intent non-negotiable? If yes, future analysis findings that conflict with this intent will be suppressed, not just downgraded."
+
+Default is `non_negotiable: false`. Only set true on explicit designer confirmation.
+
+**Capture intent in this YAML shape (two-axis):**
+
+```yaml
+mechanical_intent:
+  summary: "one-line goal — what the math should do"
+  rationale: "why this design"
+  severity: moderate          # minor / moderate / major / lethal
+  failure_mode: complication_not_lethality
+  set_by: homebrew
+  set_at: "ISO-8601"
+  non_negotiable: false
+experiential_intent:          # optional — null if designer declines
+  tone: uncanny               # desperate / heroic / tragic / absurd / mundane / uncanny / tender / cruel / comic
+  pacing: languid             # rushed / steady / languid / punctuated
+  stakes: communal            # personal / communal / cosmic / professional / trivial
+  register: intimate          # formal / colloquial / archaic / technical / mythic / intimate
+  notes: "free-text shaping context for companion constructs"
+```
+
+**Backwards compatibility:** The old single-axis `intent:` shape (summary + rationale + non_negotiable) is treated as `mechanical_intent` with no `experiential_intent`. Existing entities do not need migration — they work as-is. The new shape adds the experiential axis alongside the mechanical one.
+
+### Step 7: Write to Game-State, Designs, and Changelog
+
+Once the user confirms the design:
+
+**7a. Write entity files to game-state:**
+- Write new YAML files to the appropriate `grimoires/gygax/game-state/` subdirectory (e.g., `mechanics/`, `resources/`, `tensions/`).
+- Update existing entity files if the new mechanic changes their `depends_on` or `affects` arrays.
+- Follow the game-state schema exactly (see `skills/attune/resources/game-state-schema.md`).
+- Set `created_by: homebrew` and `last_modified_by: homebrew` with current ISO-8601 timestamps.
+- Validate every YAML file before writing: required fields present, cross-references point to files that exist (or are being created in the same batch), tradition is valid.
+- **Graph validation:** For each new or modified `depends_on`/`affects` entry, verify the target exists in game-state. If a target doesn't exist, create a **stub entity** following the stub schema from `/attune` Phase 4 rule 9 (with `created_by: homebrew-inferred`). Report stubs to user.
+- **Impact analysis:** When modifying an entity that appears in other entities' `depends_on` lists, display: "Impact analysis: N entities depend on {entity}. Changes may affect: {list of dependent entity paths}."
+
+**7b. Update index.yaml:**
+- Add new files (including any stubs) to the `files:` list with their `id`, `depends_on`, and `affects`.
+- Update `entity_count` totals (stubs count toward their type's total).
+- Update `last_modified_at`.
+- Regenerate `graph_integrity` section: `resolved_references`, `stub_count`, `stubs`, `orphaned`, `circular`, `most_depended_on`.
+
+**7c. Write design document:**
+- Write a human-readable design document to `grimoires/gygax/designs/YYYY-MM-DD-description.md`.
+- Include: design intent, final specification, consistency check results, design tensions affected, rationale for key decisions, and alternatives considered.
+- If intent was captured in Step 6.5, include a **Design Intent** section immediately after the title block (before Specification). If `non_negotiable` is true, include the suppression note.
+
+Design Intent section format:
+
+```markdown
+## Design Intent
+
+**Summary:** [intent.summary]
+**Rationale:** [intent.rationale]
+**Non-negotiable:** [true/false]
+
+[If non-negotiable: Findings that conflict with this intent will be suppressed in future analysis, not just downgraded.]
+```
+
+**7d. Append to changelog:**
+- Write a changelog entry to `grimoires/gygax/changelog/YYYY-MM-DD-HHMMSS-homebrew-description.yaml`.
+- Format:
+
+```yaml
+timestamp: "ISO-8601"
+skill: homebrew
+action: created|modified|deprecated
+entity: type/entity-id.yaml
+summary: "One-line description of change"
+rationale: "Why this change was made"
+source: "User request context"
+
+before:
+  # Previous values (for modifications only)
+after:
+  # New values
+
+affected_tensions:
+  - tensions/tension-id.yaml
+
+intent_change:  # Only if intent was set or modified
+  before: null  # null for new entities; previous intent object for modifications
+  after:        # New intent object as captured in Step 6.5
+    summary: "one-line goal"
+    rationale: "why this design"
+    set_by: homebrew
+    set_at: "ISO-8601"
+    non_negotiable: false
+```
+
+## Consistency Check Rules
+
+The following rules are checked in Step 3. Each rule has a severity.
+
+| Rule | Severity | Example |
+|------|----------|---------|
+| Resource referenced but does not exist in game-state | Contradiction | "Costs mana, but no mana resource defined" |
+| Resource does not regenerate in the mechanic's usage context | Contradiction | "Costs stamina in combat, stamina only recovers on rest" |
+| Stat referenced but does not exist | Contradiction | "Roll + Agility, but no Agility stat defined" |
+| Action type does not exist in game's economy | Missing dependency | "Uses reaction, but no reaction economy defined" |
+| Mechanic is strictly better than existing option in same slot | Overlap | "New dodge is always better than existing Shield" |
+| Mechanic is strictly worse than existing option | Overlap | "Why would anyone use this instead of Shield?" |
+| Modifier would exceed system's expected ceiling | Tension shift | "+3 bonus in a bounded accuracy system" |
+| Resource pool too small for expected usage frequency | Observation | "Pool of 4 with a cost of 2 means 2 uses per rest" |
+| Scaling curve differs from system norm | Observation | "Linear scaling in a proficiency-bonus system" |
+| Narratively incoherent with setting assumptions | Observation | "Teleportation in a low-magic setting" |
+| Move trigger overlaps with existing move (PbtA/FitD) | Overlap | "Both 'Defy Danger' and this trigger on threat" |
+| Circular dependency introduced | Contradiction | "A depends on B, B depends on A" |
+| Proposed mechanic conflicts with existing tension's intent | Tension shift | "Adding a reliable defensive option conflicts with tensions/survivability-vs-resources.yaml intent: 'defense should always feel costly'" |
+
+## Design Document Format
+
+Design documents written to `grimoires/gygax/designs/` follow this structure:
+
+```markdown
+# Design: [Mechanic Name]
+
+**Date:** YYYY-MM-DD
+**Tradition:** [tradition]
+**Status:** Confirmed
+
+## Design Intent
+
+**Summary:** [intent.summary]
+**Rationale:** [intent.rationale]
+**Non-negotiable:** [true/false]
+
+[If non-negotiable: Findings that conflict with this intent will be suppressed in future analysis, not just downgraded.]
+
+## Specification
+
+Full mechanic description with trigger, cost, resolution, effect.
+
+## Consistency Check Results
+
+Findings from the cross-system analysis, organized by severity.
+
+## Design Tensions
+
+Which tensions this mechanic participates in and how it affects them.
+
+## Alternatives Considered
+
+Other approaches discussed during iteration and why they were not chosen.
+
+## Rationale
+
+Key design decisions and their justification.
+```
+
+If intent was not captured (user declined or entity type does not warrant it), omit the Design Intent section entirely.
+
+## Boundaries
+
+- Does NOT ingest or parse existing rulebooks (use `/attune` for that)
+- Does NOT perform quantitative balance analysis with specific numbers (use `/augury` for that)
+- Does NOT simulate player interactions or adversarial stress-testing (use `/cabal` for that)
+- Does NOT apply tradition-specific heuristic libraries (use `/lore` for that)
+- Does NOT write production game code or final prose -- Gygax reasons about mechanics, other tools build
+- Does NOT make final creative decisions -- presents findings as questions, the designer decides
+- DOES handle structural consistency, dependency checking, tension tracking, and narrative coherence
+- DOES work for non-combat mechanics: social systems, exploration, downtime, crafting, faction play, narrative moves
+- DOES support mid-design pivots -- the user can change direction at any point during iteration
+- DOES capture intent on new designs and tension modifications (Step 6.5)
+- DOES ask about intent preservation when modifying existing entities (Step 6.5)
+
+## Cross-Skill Chaining
+
+After confirming a design, the skill suggests validation steps:
+
+```
+## Recommended Next Steps
+
+Design confirmed. To validate:
+
+1. `/augury {entity path}` — check the numerical balance of the new mechanic
+2. `/cabal --optimizer --rules-lawyer {entity path}` — stress-test for exploits and ambiguities
+3. `/lore {scope}` — check against known tradition anti-patterns
+4. `/scry "{alternative approach}"` — explore a design branch if you want to compare alternatives
+```
+
+Each recommendation includes the exact invocation command tied to the specific entity just designed.
+
+**Intent and cross-skill consistency:** As of v3, augury, cabal, lore, and scry all read the `intent` field from entity files before classifying findings. Intent is how you tell Gygax what IS the design versus what is a bug. A deliberately asymmetric mechanic with intent stated will surface as an Observation ("working as designed"), not a Warning. Without intent, every finding is classified purely on structure and math.
+
+Tensions should always have intent set — a tension without intent is incomplete. Use `/homebrew --set-intent {entity-path}` to add intent retroactively to any entity.
+
+## Output
+
+| Artifact | Path | Format |
+|----------|------|--------|
+| Entity files | `grimoires/gygax/game-state/{type}/{id}.yaml` | YAML (game-state schema) |
+| Index update | `grimoires/gygax/game-state/index.yaml` | YAML |
+| Design document | `grimoires/gygax/designs/YYYY-MM-DD-description.md` | Markdown |
+| Changelog entry | `grimoires/gygax/changelog/YYYY-MM-DD-HHMMSS-homebrew-description.yaml` | YAML |

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/homebrew/index.yaml

@@ -0,0 +1,29 @@
+slug: homebrew
+name: "Homebrew"
+description: |
+  Use this skill IF user invokes /homebrew OR wants to design a mechanic, explore a what-if, or refine a system.
+  Produces artifacts to grimoires/gygax/designs/.
+version: 1.0.0
+
+triggers:
+  - "/homebrew"
+  - "design a mechanic"
+  - "what if I added"
+  - "how would this work"
+  - "refine this system"
+
+capabilities:
+  model_tier: opus
+  danger_level: safe
+  effort_hint: medium
+  downgrade_allowed: true
+  execution_hint: sequential
+  requires:
+    native_runtime: false
+    tool_calling: true
+    thinking_traces: false
+    vision: false
+
+dependencies:
+  grimoire_paths:
+    - grimoires/gygax/

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/lore/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: lore
+description: Surface TTRPG design heuristics, patterns, and anti-patterns
+model_tier: sonnet
+effort: medium
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Lore
+
+Surface TTRPG design wisdom -- heuristics, common patterns, known anti-patterns, and lessons from published game systems. Lore reads your game-state, identifies which design tradition it belongs to, loads curated heuristic libraries for that tradition, and pattern-matches your design against known failure modes. It tells you what is wrong AND why it matters.
+
+Lore is opinionated. These are not suggestions -- they are distilled failures and successes from decades of published tabletop design. When Lore flags something, it is because the pattern has a track record. You may override the wisdom, but you should know the history before you do.
+
+Lore is strictly read-only against game-state. It never modifies game-state. Scan results are presented inline AND persisted to `grimoires/gygax/lore-reports/` as presentable markdown.
+
+## Trigger
+
+`/lore` with optional focus argument.
+
+Examples:
+- `/lore` -- full heuristic scan of the entire game-state
+- `/lore combat` -- scan combat-related heuristics only
+- `/lore resources` -- scan resource economy heuristics only
+- `/lore progression` -- scan advancement and scaling heuristics only
+- `/lore pacing` -- scan pacing and tempo heuristics only
+- `/lore social` -- scan social mechanic heuristics only
+- `/lore mechanics/dodge-reaction.yaml` -- scan heuristics relevant to a specific entity
+
+## Workflow
+
+### Step 1: Load Game-State and Determine Tradition
+
+1. Check that `grimoires/gygax/game-state/index.yaml` exists. If it does not, stop and tell the user: "No game attuned yet. Run `/attune` first to build your game-state."
+2. Read `index.yaml` to get: game name, tradition, entity counts, file list, graph integrity, and **design parameters**.
+3. Read `design_parameters` if present. Use these to adjust heuristic sensitivity:
+   - `target_audience: newcomer` → lower threshold for flagging complexity-related anti-patterns (jargon density, hidden interactions, unguided choices)
+   - `target_audience: mastery` → raise threshold for complexity warnings (expert audience expects and rewards system depth)
+   - `target_session_length: short` → flag setup-heavy patterns more aggressively (less time to amortize front-loaded complexity)
+   - `target_interaction: cooperative` → load cooperative-specific heuristics (alpha player, quarterbacking) regardless of primary tradition
+   - `target_randomness: none` → suppress randomness-related heuristics, emphasize decision-quality patterns
+   - If no `design_parameters` set, use tradition defaults.
+4. Determine the primary tradition. If `tradition` is `custom`, read the full game-state to identify which established traditions it borrows from most heavily -- load heuristics for all applicable traditions.
+4. Determine the scan scope from the user's invocation:
+   - **No argument**: full scan across all heuristic categories.
+   - **Category keyword** (`combat`, `resources`, `progression`, `pacing`, `social`, `mechanics`): filter heuristics to matching categories.
+   - **Specific entity path**: load that entity and its dependency graph, filter heuristics to categories relevant to the entity's type.
+
+### Step 2: Load Heuristic Resource Files
+
+1. Based on the tradition(s) identified in Step 1, load the corresponding YAML file(s) from `skills/lore/resources/`:
+   - `d20.yaml` for d20 tradition
+   - `pbta.yaml` for PbtA tradition
+   - `fitd.yaml` for FitD tradition
+   - `osr.yaml` for OSR tradition
+   - For `freeform`: load PbtA heuristics (closest applicable) and note the adaptation.
+   - For `custom`: load all tradition files whose heuristics are relevant based on the mechanics present in game-state. For truly novel games (journaling, map-drawing, lyric, etc.), many heuristics will not apply — that is expected. The value is in the ones that DO match. If fewer than 3 heuristics match, say so honestly: "This game is novel enough that most tradition-specific heuristics don't apply. Here's what I can offer from structural analysis instead." Then focus on universal patterns: decision space quality, loop completeness, tension health, pacing.
+2. Parse the heuristic entries. Each heuristic has: `id`, `name`, `category`, `description`, `detection`, `severity`, and `tradition_specific`.
+3. If a scope filter was specified, discard heuristics whose `category` does not match the requested scope.
+
+### Step 3: Load Relevant Game-State Entities
+
+1. For a full scan: load all game-state entity files.
+2. For a scoped scan: load entities matching the scope:
+   - `combat` scope: load mechanics with combat-related tags, resources consumed by combat mechanics, stats used by attack/defense.
+   - `resources` scope: load all resource entities plus mechanics that consume or recover them.
+   - `progression` scope: load all progression entities plus resources with `max_by_level`.
+   - `pacing` scope: load resources (for depletion tempo), mechanics (for trigger frequency), tensions.
+   - `social` scope: load mechanics with social tags, stats used by social mechanics.
+   - Specific entity: load the named entity plus everything in its `depends_on` and `affects` graph.
+3. Build a working model of the game-state: what stats exist, what resources exist, how they connect, what the progression curve looks like, what tensions are declared.
+
+### Step 4: Pattern-Match Heuristics Against Game-State
+
+For each heuristic in the loaded set:
+
+1. Read the `detection` field. This describes what to look for in the game-state.
+2. Examine the loaded game-state entities for evidence of the pattern.
+3. Classify the match:
+   - **Match**: the game-state clearly exhibits this pattern. Provide specific entity references.
+   - **Partial match**: the game-state shows some indicators but not all. Note what is present and what is ambiguous.
+   - **No match**: the game-state does not exhibit this pattern. Skip silently -- do not report clean results for every heuristic.
+   - **Insufficient data**: the game-state lacks the entities needed to evaluate this heuristic. Note only if the missing data is significant.
+4. For `tradition_specific: false` heuristics, evaluate even if they come from a different tradition file than the game's primary tradition. Cross-tradition wisdom applies everywhere.
+
+After pattern-matching, check each matched entity for intent:
+- If the heuristic matches AND the entity has `mechanical_intent` (or legacy `intent`) that acknowledges/explains the pattern → Tag as [INTENT-ALIGNED]
+- If the heuristic matches AND `mechanical_intent` conflicts → Tag as [INTENT-CONFLICT]
+- If the entity also has `experiential_intent`, note it for companion construct reference but do not use it for structural classification (experiential intent shapes voicing, not analysis)
+- If no intent set → Leave classification unchanged, add note
+5. For each match or partial match, record:
+   - The heuristic ID and name
+   - The severity (from the heuristic definition)
+   - Which game-state entities exhibit the pattern (with file paths)
+   - A brief explanation of why this matters for THIS specific game
+
+### Step 4.5: Load Learned Heuristics
+
+In addition to curated heuristics from `skills/lore/resources/{tradition}.yaml`, load learned heuristics from the grimoire:
+
+1. Glob `grimoires/gygax/learned-lore/*.yaml`
+2. Filter by `applicable_traditions` match or `tradition_specific: false`
+3. Apply learned heuristics to game-state alongside curated ones
+4. Tag learned matches with `[LEARNED]` prefix in report
+5. Learned heuristics with `confidence: low` are presented in an appendix, not main findings
+6. Learned heuristics with `confidence: medium` include caveat: "Learned pattern — may not apply universally"
+7. Learned heuristics with `confidence: high` presented as standard findings
+
+### Step 5: Present Findings Organized by Severity
+
+Present all findings inline. Organize by severity, then by category within each severity level.
+
+#### Output Format
+
+```
+## Lore Scan: [Game Name] ([Tradition])
+Scope: [full | category | entity path]
+Heuristics evaluated: [N] from [tradition file(s)]
+Matches found: [N]
+
+### Critical
+
+**[Heuristic Name]** (category: [category])
+Pattern: [What the anti-pattern is, from the heuristic description]
+Found in: [specific game-state entity paths]
+Analysis: [Why this matters for this specific game. Be concrete. Reference the entity values.]
+Consider: [What the designer should think about. Not a prescription -- a prompt for reflection.]
+
+**[LEARNED pattern-name]** (category: ..., source: learned from [game], confidence: medium)
+Pattern: ...
+Found in: ...
+[Continue with standard format]
+
+### Warning
+
+[Same format per finding]
+
+### Info
+
+[Same format per finding]
+
+### No Issues Detected
+
+[If the scan found zero matches, say so explicitly. Do not fabricate findings.]
+"Lore scan complete. No known anti-patterns detected in the [scoped] game-state.
+This does not mean the design is perfect -- it means it does not match any catalogued
+failure modes for the [tradition] tradition. Consider `/augury` for quantitative
+validation or `/cabal` for adversarial stress testing."
+```
+
+#### Presentation Rules
+
+1. **Critical findings first.** Always. A designer must see blockers before warnings.
+2. **Be specific.** "Your healing surge recovers 1d10+5 on a short rest but your expected incoming DPR is 15/round for 4 rounds -- the heal does not create meaningful recovery tension" is useful. "Healing might be too low" is not.
+3. **Cite the game-state.** Every finding must reference specific entity file paths and values. The designer should be able to trace your reasoning.
+4. **Explain the history.** Briefly note why this is a known pattern. "This is the linear fighter / quadratic wizard problem identified in 3e-era d20 design" gives the finding weight and searchability.
+5. **Do not prescribe fixes.** Lore identifies patterns and explains why they matter. It does not design solutions. For fixes, direct to `/homebrew`. For quantitative validation, direct to `/augury`.
+6. **Partial matches get honesty.** If you see indicators but cannot confirm, say "Partial match -- [what I see] suggests [pattern] but the game-state lacks [data] to confirm. Run `/attune` to add [missing data] or `/augury` to measure."
+7. **Cross-tradition findings are welcome.** If a d20 game exhibits a pattern catalogued under FitD wisdom, report it. Good design knowledge is not tradition-locked.
+8. **Do not pad.** If only 2 heuristics match, report 2. Do not stretch partial matches into findings to fill space. A clean scan is a valid and valuable result.
+9. After presenting findings inline, write the same formatted output to `grimoires/gygax/lore-reports/YYYY-MM-DD-scope-description.md`. The persisted report should be readable standalone without conversation context.
+
+If a heuristic did NOT match any curated pattern but represents a structural observation that might generalize, flag it as a learned-lore candidate:
+
+> **[CANDIDATE: pattern-title]**
+> I noticed [pattern] that doesn't match my curated heuristics but might generalize to other [tradition] games. Would you like to capture this as a learned heuristic? (Saved to `grimoires/gygax/learned-lore/`.)
+
+### Step 6: Offer Next Steps
+
+Based on findings, suggest specific next actions:
+
+- If critical findings exist: "These should be addressed before further development. Try `/homebrew [entity]` to redesign, or `/augury [entity]` to quantify the severity."
+- If only warnings: "These are worth investigating but may be intentional. `/augury` can measure whether the numbers actually break, or `/cabal` can test whether players exploit the pattern."
+- If only info: "Nothing alarming. These are patterns to keep in mind as the design evolves. `/cabal` would tell you whether these matter in practice."
+- If no matches: "Clean scan. Your design avoids catalogued failure modes. `/augury` for math validation and `/cabal` for adversarial testing are your next best steps."
+
+### Step 7: Candidate Capture Flow
+
+When candidate patterns are surfaced:
+
+1. Present each candidate to the user with a prompt: "Capture as learned heuristic?"
+2. For each confirmed capture:
+   - Write `grimoires/gygax/learned-lore/{date}-{pattern-id}.yaml` with full provenance
+   - Pattern schema includes: id, name, category, discovered_at, source (skill+report+severity), description, detection, confidence, applicable_traditions, confirmed_in_games
+3. For each declined capture: log decision, no file written
+
+### Step 8: Cross-Skill Chaining
+
+Every lore report ends with a "Recommended Next Steps" section:
+
+- Critical findings: "Address with `/homebrew {entity}`. For quantitative severity, run `/augury {entity}`."
+- Warning findings: "Validate with `/cabal {entity}` to test whether players exploit this pattern."
+- Info findings: "Monitor during next `/cabal` run. No immediate action needed."
+- No matches: "Clean scan. Consider `/augury` for math validation and `/cabal` for adversarial testing."
+
+Each recommendation includes the exact invocation command, not just the skill name.
+
+## Tradition-Specific Scan Behavior
+
+Different traditions have different areas of concern. The scan adapts:
+
+| Tradition | High-Priority Categories | Lower-Priority Categories |
+|-----------|------------------------|--------------------------|
+| d20 | math, progression, resources, mechanics | social, pacing |
+| PbtA | mechanics, pacing, social | math, progression |
+| FitD | resources, pacing, mechanics | math, progression |
+| OSR | resources, pacing, mechanics | progression, social |
+
+This does not mean low-priority categories are skipped -- they are still scanned. But findings in high-priority categories are given extra analytical depth.
+
+## Subcommand: /lore promote
+
+`/lore promote {pattern-id} --target {tradition}` promotes a learned heuristic to the curated tradition library.
+
+Workflow:
+1. Read `grimoires/gygax/learned-lore/{date}-{pattern-id}.yaml`
+2. Append to `skills/lore/resources/{tradition}.yaml` with full provenance:
+   ```yaml
+   - id: {pattern-id}
+     name: "{name}"
+     category: {category}
+     source: promoted-from-learned
+     source_game: "{confirmed_in_games[0]}"
+     promoted_at: "ISO-8601"
+     description: ...
+     detection: ...
+     severity: ...
+     tradition_specific: [true/false]
+   ```
+3. Archive learned-lore file to `grimoires/gygax/learned-lore/.promoted/{original-filename}`
+4. Write changelog entry
+
+Promotion is manual — Gygax does NOT auto-promote. The user decides when a learned pattern is proven enough to become curated wisdom.
+
+## Boundaries
+
+- Does NOT modify game-state files -- strictly read-only (use `/homebrew` to act on findings)
+- Does NOT perform quantitative balance analysis (use `/augury` for numbers)
+- Does NOT simulate play (use `/cabal` for adversarial testing)
+- Does NOT ingest source material (use `/attune` for that)
+- Does NOT prescribe fixes -- identifies patterns and explains why they matter
+- Writes scan results to `grimoires/gygax/lore-reports/` as presentable markdown. Also displayed inline.
+- DOES load and apply curated heuristic libraries from `skills/lore/resources/`
+- DOES cross-reference heuristics across traditions when applicable
+- DOES adapt scan depth based on the game's tradition
+- DOES report clean scans as a valid result (no finding fabrication)
+- DOES read per-game learned heuristics alongside curated ones
+- DOES flag non-matching structural patterns as learned-lore candidates
+- Does NOT auto-promote learned patterns to curated (requires explicit /lore promote)
+- Does NOT edit files in `.claude/` (System Zone)
+
+## Output
+
+Output is both inline in the conversation AND persisted to `grimoires/gygax/lore-reports/YYYY-MM-DD-scope-description.md`.
+
+| Artifact | Destination | Format |
+|----------|-------------|--------|
+| Heuristic scan results | Conversation (inline) + `grimoires/gygax/lore-reports/` | Structured markdown per finding |
+
+Reports now include `[LEARNED]` and `[CANDIDATE]` tags to distinguish curated heuristic matches from learned heuristic matches and novel structural observations flagged for capture.
+
+`/lore promote` modifies `skills/lore/resources/{tradition}.yaml` (appends promoted pattern) AND archives the source file to `grimoires/gygax/learned-lore/.promoted/`.
+
+## Error Handling
+
+| Error | Response | Recovery |
+|-------|----------|----------|
+| No game-state exists | "No game attuned yet. Run `/attune` first to build your game-state." | Direct to `/attune` |
+| Tradition is unrecognized | "The tradition `[value]` in your index.yaml is not one I have heuristic libraries for. I can scan using the closest matching tradition -- which of d20, PbtA, FitD, or OSR is closest?" | Ask user to clarify |
+| Scope keyword matches no categories | "I don't have a `[keyword]` category in my heuristic libraries. Available categories: math, progression, resources, pacing, mechanics, social. Or specify an entity path." | Offer alternatives |
+| Game-state too sparse to evaluate most heuristics | "Your game-state has [N] entities. Most heuristics need at least stats, resources, and core mechanics to evaluate. Run `/attune` to flesh out the game-state." | Direct to `/attune` |
+| Specific entity path not found | "I can't find `[path]` in game-state. Here's what exists: [list from index]. Did you mean one of these?" | Offer alternatives |
+| Custom tradition with no clear lineage | Load all four heuristic files. Filter to `tradition_specific: false` heuristics plus any whose detection patterns match observable game-state structures. Note: "Scanning cross-tradition heuristics since this is a custom system." | Broadest possible scan |

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/lore/index.yaml

@@ -0,0 +1,29 @@
+slug: lore
+name: "Lore"
+description: |
+  Use this skill IF user invokes /lore OR asks about design patterns, failure modes, or TTRPG design wisdom.
+  Produces artifacts to grimoires/gygax/lore-reports/.
+version: 1.0.0
+
+triggers:
+  - "/lore"
+  - "what patterns does this follow"
+  - "common failure modes"
+  - "design anti-patterns"
+  - "TTRPG design wisdom"
+
+capabilities:
+  model_tier: sonnet
+  danger_level: safe
+  effort_hint: medium
+  downgrade_allowed: true
+  execution_hint: sequential
+  requires:
+    native_runtime: false
+    tool_calling: true
+    thinking_traces: false
+    vision: false
+
+dependencies:
+  grimoire_paths:
+    - grimoires/gygax/

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/lore/resources/4x.yaml

@@ -0,0 +1,364 @@
+tradition: 4x
+name: "4X Strategy Design Heuristics"
+version: 1.0.0
+description: |
+  Design heuristics for 4X strategy games (eXplore, eXpand, eXploit, eXterminate).
+  Covers both digital (Civilization, Stellaris, Endless Legend, Humankind, Old World) and
+  tabletop (Twilight Imperium, Eclipse, Through the Ages, Clash of Cultures). Distilled
+  from decades of competitive play, modding communities, patch note analysis, and the
+  collective wisdom of strategy game designers who have wrestled with snowball dynamics,
+  pacing collapse, and victory condition design.
+
+heuristics:
+  # --- ECONOMY ---
+
+  - id: snowball-rich-get-richer
+    name: "Snowball / Rich-Get-Richer Dynamics"
+    category: economy
+    severity: critical
+    tradition_specific: true
+    description: |
+      The defining 4X failure mode. When territory generates resources that buy military
+      that conquers territory that generates more resources, the leader compounds their
+      advantage exponentially. Once a player crosses the snowball threshold, the game is
+      decided but not over -- remaining playtime is a formality. Civilization V's early
+      expansion into gold into units into more expansion is the canonical example.
+    detection: |
+      Check for feedback loops where a resource output directly purchases the means to
+      acquire more of that resource. If territory generates income AND income purchases
+      expansion capacity with no diminishing returns, a snowball loop exists. Look for
+      maintenance costs, corruption mechanics, or overextension penalties that create
+      counter-pressure.
+
+  - id: expansion-vs-consolidation
+    name: "Expansion vs. Consolidation Tradeoff"
+    category: economy
+    severity: high
+    tradition_specific: true
+    description: |
+      Healthy 4X design creates tension between expanding (more territory, more resources)
+      and consolidating (developing existing territory, building infrastructure). If
+      expansion is always correct because new territory immediately pays for itself, the
+      game rewards mindless land-grab. If consolidation is always correct because expansion
+      costs too much, the map is static. The ideal: expansion has upfront cost that only
+      pays off with consolidation investment, creating natural expand-consolidate rhythms.
+    detection: |
+      Check if new territory has an immediate net positive yield or requires investment
+      before becoming productive. If settling a new city or claiming a new hex is
+      immediately profitable with no development cost, expansion always dominates. If
+      new territory requires 5+ turns of investment before breaking even, there is a
+      natural consolidation phase.
+
+  - id: military-vs-economic-balance
+    name: "Military vs. Economic Investment Balance"
+    category: economy
+    severity: high
+    tradition_specific: true
+    description: |
+      Players must choose between investing in military (protection and conquest) and
+      economy (production and growth). If military is too cheap, the optimal strategy is
+      rush. If military is too expensive, the optimal strategy is boom-then-rush. The
+      sweet spot: military diverts enough from economic growth that a pure military player
+      falls behind economically, but a pure economic player is vulnerable to attack. Neither
+      extreme should be dominant across all game states.
+    detection: |
+      Compare the cost of a basic military unit against the output of a basic economic
+      improvement. If a military unit costs less than one turn of economic output from a
+      developed territory, military is underpriced. If maintaining a defensive force
+      consumes more than 40% of total income, military is overpriced for peaceful defense.
+
+  - id: wonder-project-racing
+    name: "Wonder / Project Racing Dynamics"
+    category: economy
+    severity: medium
+    tradition_specific: true
+    description: |
+      Unique buildings or projects that only one player can complete create races. These
+      are exciting when competitive and devastating when one player is so far ahead that
+      others cannot contest them. If wonder-sniping (completing a wonder one turn before
+      a rival) produces massive swing with no consolation, it creates feel-bad moments.
+      If wonders are uncontestable because the leader always builds them, they amplify
+      snowball rather than creating interesting competition.
+    detection: |
+      Check for unique/limited constructions. If only one player can build each wonder,
+      check whether the investment is refunded or lost on failure. If the leader can
+      reliably claim all wonders due to production advantage, wonders compound the
+      snowball. Look for consolation mechanics (partial refund, alternative benefits)
+      for players who lose the race.
+
+  - id: trade-route-chokepoints
+    name: "Naval / Trade Route Chokepoint Control"
+    category: economy
+    severity: medium
+    tradition_specific: true
+    description: |
+      When maps have natural chokepoints (straits, mountain passes, trade nodes), control
+      of these points can generate disproportionate economic or strategic advantage. This
+      is interesting when chokepoints are contestable and create diplomatic flashpoints.
+      It is problematic when spawn location determines chokepoint access, making some
+      starting positions inherently superior.
+    detection: |
+      Check for trade, supply line, or movement chokepoint mechanics. If chokepoint
+      control generates passive income or blocks rival movement, check whether chokepoint
+      access correlates with spawn position. If certain map positions have guaranteed
+      access to key chokepoints, the map generator creates structural advantage.
+
+  # --- PACING ---
+
+  - id: mid-game-slog
+    name: "Mid-Game Slog (Expand Phase Drag)"
+    category: pacing
+    severity: high
+    tradition_specific: true
+    description: |
+      The expand phase often becomes a slog: all players are building infrastructure,
+      no one is strong enough to attack, and the interesting exploration phase is over.
+      The mid-game needs tension -- border friction, resource competition, diplomatic
+      crises, barbarian invasions -- or players disengage during the 30-turn build-up
+      to the late game. Civilization's medieval era and Stellaris's mid-game are
+      notorious examples of this dead zone.
+    detection: |
+      Check for mechanics that create mid-game tension independent of player-vs-player
+      conflict. If the only source of mid-game pressure is other players choosing to
+      attack (which rational players avoid when they are still building), the mid-game
+      lacks structural tension. Look for event systems, NPC threats, resource scarcity
+      shifts, or diplomatic mechanics that activate during the expand phase.
+
+  - id: late-game-inevitability
+    name: "Late-Game Inevitability"
+    category: pacing
+    severity: high
+    tradition_specific: true
+    description: |
+      When the game's outcome is decided 30 minutes before it ends, the late game is
+      inevitable. Players can see who will win but must continue playing until the
+      formal victory condition triggers. This is the 4X genre's most persistent pacing
+      failure. Good designs either accelerate the endgame once a leader emerges or
+      provide comeback mechanics that keep the outcome uncertain until the final turns.
+    detection: |
+      Check if victory conditions have a visible countdown (score threshold, wonder
+      completion, territory percentage). If the leading player's trajectory toward
+      victory is predictable more than 10 turns in advance with no plausible disruption,
+      the late game is inevitable. Look for catch-up mechanics, alliance systems, or
+      sudden-death conditions that compress the endgame.
+
+  - id: early-elimination-spectator
+    name: "Early Elimination / Spectator Problem"
+    category: pacing
+    severity: critical
+    tradition_specific: true
+    description: |
+      When a player is eliminated in a 4-hour game at the 45-minute mark, they spend
+      3+ hours watching. This is the worst possible player experience in tabletop 4X.
+      Even in digital 4X, being reduced to irrelevance (alive but unable to compete)
+      creates the same feel-bad. Solutions include: elimination protection in early
+      eras, vassal mechanics, respawn systems, or victory conditions that do not require
+      eliminating other players.
+    detection: |
+      Check if player elimination is possible before the midpoint of expected game
+      duration. If a player can be conquered, bankrupted, or rendered non-competitive
+      in the first third of the game, early elimination is possible. Check for
+      protection mechanics (ceasefire periods, defensive bonuses for smaller players,
+      AI takeover of eliminated players).
+
+  - id: turn-length-scaling
+    name: "Turn Length Scaling in Late Game"
+    category: pacing
+    severity: medium
+    tradition_specific: true
+    description: |
+      Early-game turns are fast: few units, few decisions, small territory. Late-game
+      turns are slow: dozens of units, multiple fronts, complex economic decisions. If
+      each player's turn takes 10 minutes in the late game and there are 6 players,
+      you wait an hour between turns. This scaling is the reason many tabletop 4X games
+      are abandoned before completion. Simultaneous action selection, automated
+      production queues, and streamlined combat help.
+    detection: |
+      Count the number of discrete decisions per turn at early, mid, and late game
+      stages. If decisions per turn more than triple from early to late game, and the
+      game uses sequential turns, late-game turn length will be problematic. Check for
+      simultaneous resolution mechanics or automation that reduces decision count.
+
+  # --- MECHANICS ---
+
+  - id: tech-tree-dead-ends
+    name: "Tech Tree Dead Ends"
+    category: mechanics
+    severity: high
+    tradition_specific: true
+    description: |
+      Tech tree branches that lead to capabilities with no late-game relevance are traps.
+      A player who invests in a dead-end branch falls behind players who chose branches
+      with compounding returns. Dead ends are especially punishing when the tech tree is
+      opaque (first-time players cannot see where branches lead). Good design either makes
+      all branches viable through the endgame or clearly signals which branches are
+      situational.
+    detection: |
+      Map tech tree connectivity. Check if any branch terminates without connecting to
+      high-tier technologies or victory conditions. If a branch's final technology provides
+      no synergy with endgame mechanics, it is a dead end. Check if the tree's structure
+      communicates this risk to players making early choices.
+
+  - id: victory-condition-imbalance
+    name: "Victory Condition Imbalance"
+    category: mechanics
+    severity: critical
+    tradition_specific: true
+    description: |
+      When one victory condition is consistently easier, faster, or more reliable than
+      alternatives, rational players converge on that path. If military conquest always wins
+      before cultural victory can trigger, cultural victory is decorative. If science victory
+      is achievable in isolation while domination requires risky conflict, science dominates
+      competitive play. Each victory path must be viable and must interact with the others
+      (military pressure should threaten science players; cultural influence should weaken
+      military loyalty).
+    detection: |
+      Compare average turn-to-victory across different victory conditions using optimized
+      strategies. If one condition is achievable 20%+ faster than alternatives, or if one
+      condition can be pursued without interacting with other players while others require
+      conflict, the conditions are imbalanced. Check if victory paths create cross-pressure
+      on each other.
+
+  - id: diplomatic-exploit-loops
+    name: "Diplomatic Exploit Loops"
+    category: mechanics
+    severity: high
+    tradition_specific: true
+    description: |
+      Diplomacy systems create exploit loops when: declaring war has no lasting reputation
+      cost (attack, take city, make peace, repeat), trade agreements can be used to scout
+      then immediately broken, or alliances create no mutual obligation. If diplomacy is
+      purely transactional with no memory or consequence, players optimize it into a series
+      of exploitative micro-transactions rather than genuine strategic relationships.
+    detection: |
+      Check for diplomatic mechanics. If war declarations, treaty breaks, or betrayals
+      have no persistent reputation effect or escalating cost, diplomatic exploits are
+      possible. If AI opponents do not remember or respond to past betrayals, the
+      diplomatic system is exploitable without consequence.
+
+  - id: map-generation-fairness
+    name: "Map Generation Fairness"
+    category: mechanics
+    severity: high
+    tradition_specific: true
+    description: |
+      Starting position determines 30-50% of game outcome in most 4X games. If the map
+      generator can produce positions with dramatically different resource access, defensive
+      terrain, or expansion room, the game is partially decided before the first turn.
+      Perfectly symmetric maps are boring; perfectly random maps are unfair. The generator
+      must balance variety with structural fairness.
+    detection: |
+      Check for map generation rules or procedures. If starting positions are randomly
+      placed without resource balancing, check the variance in: tiles within N hexes of
+      start, resource node count, defensive terrain access, and expansion room (open
+      tiles before hitting another player's zone). If variance exceeds 30% across
+      positions, the generator is unfair.
+
+  - id: fog-of-war-information-asymmetry
+    name: "Fog of War Information Asymmetry"
+    category: mechanics
+    severity: medium
+    tradition_specific: true
+    description: |
+      Fog of war creates information asymmetry, which creates uncertainty, which creates
+      tension. But the balance matters: if scouting is too easy (cheap scouts, satellite
+      reveals), fog evaporates and the game becomes perfect-information chess. If scouting
+      is too hard, players make blind decisions that feel random. The ideal: scouting is
+      valuable, costly, and never complete. You can know where your rival's army is, but
+      not its exact composition.
+    detection: |
+      Check for fog of war and scouting mechanics. If any single unit or technology
+      reveals the entire map, fog is trivially removed. If no scouting mechanic exists
+      and fog is permanent until you physically visit a location, information is too
+      scarce. Check the cost-to-reveal ratio: scouting should be a meaningful investment,
+      not free.
+
+  - id: ai-cheating-perception
+    name: "AI Cheating Perception (Digital 4X)"
+    category: mechanics
+    severity: medium
+    tradition_specific: true
+    description: |
+      When AI opponents receive hidden bonuses (production multipliers, free units, map
+      vision) to compensate for poor decision-making, players feel cheated even if the
+      resulting difficulty is appropriate. The problem is not difficulty but transparency:
+      players accept that a chess engine calculates deeper, but resent an AI that gets free
+      queens. If AI difficulty relies on hidden bonuses rather than better play, it
+      undermines the game's strategic credibility.
+    detection: |
+      Check for AI difficulty modifiers. If higher difficulty levels grant AI players
+      resource bonuses, production multipliers, or free units rather than improving AI
+      decision-making, the difficulty system relies on cheating. This is a digital-specific
+      heuristic but applies to tabletop games with automated opponents or solo modes.
+
+  - id: culture-religion-victory-gaminess
+    name: "Culture / Religion Victory Gaminess"
+    category: mechanics
+    severity: medium
+    tradition_specific: true
+    description: |
+      Non-military victory conditions (culture, religion, diplomacy) often feel gamy
+      because their mechanics are abstract: accumulate enough culture points, spread your
+      religion to enough cities, buy enough diplomatic votes. When the victory condition
+      does not create emergent narrative -- when it is just a resource threshold with no
+      spatial or interactive component -- it feels like an accounting exercise rather than
+      a strategic achievement. Civilization VI's tourism victory is a rare example that
+      generates genuine cross-player interaction.
+    detection: |
+      Check non-military victory conditions. If a victory condition is achieved solely
+      by accumulating a resource past a threshold with no required interaction with other
+      players, it is a solitaire victory. If the victory path creates observable effects
+      that other players can respond to (cultural influence reducing loyalty, religious
+      pressure converting cities), the victory has interactive depth.
+
+  # --- SCALING ---
+
+  - id: player-count-scaling
+    name: "Player Count Scaling Breakdown"
+    category: scaling
+    severity: high
+    tradition_specific: true
+    description: |
+      4X games designed for 4 players often break at 2 or 8. With too few players, the
+      map is empty and diplomacy is binary. With too many, turns take forever, map space
+      is cramped, and early elimination becomes more likely. The game must either scale
+      its map and mechanics to player count or clearly state its supported range.
+    detection: |
+      Check if map size, resource density, or victory thresholds scale with player count.
+      If these values are fixed regardless of player count, the game will play differently
+      (and likely worse) at counts outside its design target. Check if the rules state a
+      recommended player count range.
+
+  - id: unit-scaling-cognitive-load
+    name: "Unit / Army Scaling Cognitive Load"
+    category: scaling
+    severity: medium
+    tradition_specific: true
+    description: |
+      Managing 3 units is tactical. Managing 30 units is logistical. Managing 300 units
+      is tedious. As empires grow, the number of individual decisions (move this unit,
+      build in this city, manage this trade route) can overwhelm the player. Army grouping,
+      automated governors, production templates, and rally points are not luxuries -- they
+      are necessary abstractions that prevent the late game from becoming a chore.
+    detection: |
+      Count the number of individually-commanded entities a player controls at early, mid,
+      and late game. If individual entity count exceeds 20 and each requires per-turn
+      decisions, cognitive load is high. Check for grouping, automation, or delegation
+      mechanics that reduce the decision count without removing strategic agency.
+
+  - id: rubber-band-calibration
+    name: "Catch-Up / Rubber Band Mechanic Calibration"
+    category: scaling
+    severity: medium
+    tradition_specific: true
+    description: |
+      Rubber band mechanics (cheaper tech for trailing players, barbarian aggression toward
+      leaders, diplomatic coalitions against the frontrunner) prevent snowball but can feel
+      punitive to skilled players. If catch-up is too strong, leading is punished and the
+      optimal strategy is to stay in second place. If too weak, the snowball is unchecked.
+      The mechanic should slow the leader without making leadership feel bad.
+    detection: |
+      Check for mechanics that scale with relative player position (leader penalties,
+      underdog bonuses, coalition triggers). If the leader receives penalties exceeding
+      15% of their advantage, catch-up may be too aggressive. If no position-relative
+      mechanics exist and the snowball heuristic triggered, the game lacks catch-up.

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/lore/resources/eurogame.yaml

@@ -0,0 +1,268 @@
+tradition: eurogame
+name: "Eurogame Design Heuristics"
+version: 1.0.0
+description: |
+  Design heuristics for modern eurogame / designer board game traditions (Catan, Terraforming Mars,
+  Wingspan, Brass, Concordia, etc.). Focused on resource conversion, engine building, indirect
+  interaction, and scoring systems where elegant constraint creates meaningful choice.
+
+heuristics:
+  # --- ECONOMY ---
+
+  - id: runaway-leader
+    name: "Runaway Leader Problem"
+    category: economy
+    severity: critical
+    tradition_specific: true
+    description: |
+      When gaining resources or points makes it easier to gain more resources or points, the player
+      who takes an early lead compounds that advantage until the game is effectively decided long
+      before it ends. The remaining players are going through the motions. Classic positive feedback
+      loop with no damping mechanism.
+    detection: |
+      Map the resource flow graph. If any resource output feeds back into its own generation rate
+      without a cap, diminishing return, or catch-up mechanism, a runaway loop exists. Check whether
+      the leader at the midpoint of scored playtests is also the winner more than 70% of the time.
+
+  - id: point-salad-no-tension
+    name: "Point Salad — All Paths Equal"
+    category: scoring
+    severity: high
+    tradition_specific: true
+    description: |
+      When every action awards roughly equal points per unit of effort, strategic differentiation
+      collapses. Players feel busy but never face a real fork. The game becomes an optimization
+      puzzle with a single "do everything evenly" solution rather than a game of competing
+      commitments. Tension requires that choosing one path costs you another.
+    detection: |
+      Calculate expected points-per-action for each major scoring path across a full game.
+      If all paths converge within 10% of each other and no path requires sacrificing another,
+      the scoring system lacks tension. Also check if winners consistently score from 4+ different
+      categories with similar contributions from each.
+
+  - id: engine-ceiling-absence
+    name: "Engine Ceiling — Unbounded Engine"
+    category: economy
+    severity: critical
+    tradition_specific: true
+    description: |
+      An engine-building game needs a ceiling — a point where further investment yields diminishing
+      returns and the player must pivot to scoring. Without it, the optimal strategy is to build
+      engine forever and score in one explosive final turn, which is both un-interactive and
+      reduces the game to "who found the infinite combo first."
+    detection: |
+      Trace the maximum theoretical output of the strongest engine configuration at each round.
+      If output grows exponentially without a cap (hand limit, action limit, board space, resource
+      cap), the engine is unbounded. Check if any player's per-turn resource generation can exceed
+      the total resources available in the supply.
+
+  - id: resource-conversion-dead-end
+    name: "Resource Conversion Dead End"
+    category: economy
+    severity: high
+    tradition_specific: true
+    description: |
+      In a conversion-chain economy (ore → steel → building), a dead end occurs when a resource
+      can be generated but has no onward conversion or spending outlet at certain game stages.
+      Players holding dead-end resources feel trapped. This often emerges when the action space
+      for spending a resource is gated behind progression the player hasn't reached.
+    detection: |
+      Build the full resource conversion graph. For each resource, verify at least one spending
+      outlet is available at every game stage. Flag any resource that can accumulate above its
+      useful cap or that has generation sources but no sinks in early or late game phases.
+
+  - id: action-space-imbalance
+    name: "Action Space Imbalance"
+    category: mechanics
+    severity: high
+    tradition_specific: true
+    description: |
+      When one action space or worker-placement spot is clearly superior to all alternatives at
+      a given game phase, the game devolves into a race for that spot. This is fine if it creates
+      interesting blocking decisions, but problematic if missing the spot means a wasted turn with
+      no viable alternative. The weakest action should still feel useful.
+    detection: |
+      Compare the expected value of each available action at early, mid, and late game phases.
+      If any single action's EV exceeds the second-best by more than 50%, and the game doesn't
+      provide adequate compensation for being blocked, the action space is imbalanced. Check if
+      any action is never selected in optimal play.
+
+  - id: turn-order-advantage
+    name: "Turn Order Advantage"
+    category: pacing
+    severity: medium
+    tradition_specific: true
+    description: |
+      In games with simultaneous scarcity (worker placement, drafting, limited buy rows), going
+      first provides access to the best options. Without rotation, compensation, or a bidding
+      mechanism for turn order, first player has a persistent structural advantage. This is
+      especially damaging in games with fixed seating order.
+    detection: |
+      Analyze win rates by starting position across playtests. If first player wins more than
+      (1/N + 10%) of the time in an N-player game, turn order advantage is present. Also check
+      if any start-player compensation (fewer starting resources, later draft pick) exists and
+      whether it adequately offsets the advantage.
+
+  - id: interaction-level-mismatch
+    name: "Interaction Level Mismatch"
+    category: social
+    severity: medium
+    tradition_specific: true
+    description: |
+      The game's marketing or theme promises one level of interaction (cutthroat area control)
+      but the mechanics deliver another (parallel solitaire optimization). This creates a feel-bad
+      mismatch where competitive players are bored and non-competitive players are blindsided.
+      The interaction model should be legible from the first turn.
+    detection: |
+      Categorize each action by interaction type: direct (attacks, steals), indirect (blocking,
+      market manipulation), or solo (personal engine only). If more than 70% of actions are solo
+      but the game frames itself as interactive, or if the only interaction is blocking with no
+      strategic depth to the block, a mismatch exists.
+
+  - id: late-game-determinism
+    name: "Late-Game Determinism"
+    category: pacing
+    severity: high
+    tradition_specific: true
+    description: |
+      When the outcome becomes calculable 3-4 rounds before the game ends, the final turns feel
+      rote. Players can count points, see the winner, and lose engagement. Good eurogames
+      maintain uncertainty through hidden scoring, late-game pivots, or endgame bonuses that
+      reward risk. The last round should still matter.
+    detection: |
+      At the 75% mark of the game, calculate the point gap between first and second place and
+      compare it to the maximum points still achievable. If the leader's margin exceeds the
+      trailing player's maximum remaining scoring potential in more than 40% of games, late-game
+      determinism has set in. Check for hidden information that might obscure this.
+
+  - id: complexity-depth-mismatch
+    name: "Complexity vs. Depth Mismatch"
+    category: mechanics
+    severity: medium
+    tradition_specific: true
+    description: |
+      Complexity is the number of rules and exceptions a player must track. Depth is the number
+      of meaningfully different decisions those rules generate. High complexity with low depth
+      means players are doing bookkeeping for decisions that don't matter. The ideal is minimal
+      rules that produce maximum strategic space. Every rule should earn its cognitive cost.
+    detection: |
+      Count the number of distinct rule exceptions, special cases, and conditional triggers.
+      Compare against the number of meaningfully different strategic paths observed in playtests.
+      If the exception count exceeds the strategy count by 3:1 or more, complexity is outpacing
+      depth. Also flag any rule that triggers fewer than once per game on average.
+
+  - id: feeding-the-leader
+    name: "Feeding the Leader"
+    category: economy
+    severity: high
+    tradition_specific: true
+    description: |
+      When shared or market-based systems allow trailing players' actions to disproportionately
+      benefit the leader — buying a resource that raises its price for the leader who already
+      stockpiled it, or completing a route that the leader can piggyback on. Distinct from
+      runaway leader: here, other players' rational actions structurally benefit first place.
+    detection: |
+      In shared-economy systems (shared markets, connected networks, common board), check if
+      a player's action that benefits themselves by X also benefits the leader by >= 0.5X.
+      Look for shared infrastructure, public goods, or market mechanisms where investment by
+      any player rewards the player with the largest existing stake.
+
+  - id: blocking-only-interaction
+    name: "Blocking as Only Interaction"
+    category: social
+    severity: medium
+    tradition_specific: true
+    description: |
+      When the sole form of player interaction is denying action spaces, the game becomes a
+      race to avoid being blocked rather than a strategic contest. Blocking is healthy as one
+      tool among many, but when it's the only lever, the player who gets blocked feels punished
+      without recourse and the blocker gains nothing positive — just denial.
+    detection: |
+      Catalog every interaction between players. If all interactions are denial-based (occupying
+      a space, buying the last resource, taking a card) with no positive-sum interactions (trade,
+      alliance, shared benefits), blocking is the only interaction. Check if blocking decisions
+      have strategic depth beyond "take the space my opponent needs."
+
+  - id: math-trading
+    name: "Math Trading"
+    category: social
+    severity: low
+    tradition_specific: true
+    description: |
+      When a trade or negotiation mechanic exists but the optimal exchange rates are calculable,
+      trading becomes arithmetic rather than social negotiation. Both players can compute the
+      "fair" trade and there's no reason to deviate. This makes the trading mechanic a tax on
+      mental math rather than a source of social gameplay.
+    detection: |
+      Check if resource values are fixed and public (no hidden information about what a resource
+      is worth to each player). If all resources have knowable conversion rates to points and
+      no player has private asymmetric valuation, trades resolve to math. Look for whether
+      experienced players converge on identical exchange rates.
+
+  - id: kingmaking-indirect-competition
+    name: "Kingmaking in Indirect Competition"
+    category: social
+    severity: high
+    tradition_specific: true
+    description: |
+      In games with indirect interaction, an eliminated or trailing player can still choose
+      which frontrunner to help or hinder through their remaining actions. This gives a player
+      who cannot win the power to choose the winner, which feels arbitrary and unsatisfying.
+      It's especially toxic when the choice is based on social dynamics rather than game state.
+    detection: |
+      At the point where a trailing player cannot win, check if their remaining actions can
+      differentially impact the two leading players by more than the gap between first and
+      second place. If a non-contender's final turns can swing the winner, kingmaking is
+      structurally possible. Check if any catch-up mechanism prevents players from reaching
+      this state.
+
+  - id: first-player-advantage
+    name: "First-Player Advantage"
+    category: pacing
+    severity: medium
+    tradition_specific: true
+    description: |
+      Beyond simple turn-order advantage, first-player advantage includes getting the first
+      pick of strategies, claiming the best board positions, and setting up engine components
+      before opponents can contest them. In eurogames with tight economies, one extra turn
+      of engine output can be decisive. This compounds in games where the end trigger is
+      "N rounds" rather than "reach a target."
+    detection: |
+      Compare first-player win rates. Also check if the first player has a structural extra
+      turn at the end (acts last in the final round). In engine-building games, calculate the
+      total additional output from one extra turn of engine operation. If first player gets an
+      extra scoring turn and this exceeds the typical final-score margin, the advantage is
+      decisive.
+
+  - id: end-game-trigger-manipulation
+    name: "End-Game Trigger Manipulation"
+    category: pacing
+    severity: high
+    tradition_specific: true
+    description: |
+      When one player can control when the game ends (exhausting a pile, reaching a threshold,
+      triggering final scoring), they can time the ending to maximize their advantage and
+      minimize opponents' unfinished plans. This is a feature when it adds strategic depth
+      but a flaw when it's opaque or when one strategy can rush the ending before others
+      get online. The game should reward the trigger timing as a skill, not a gotcha.
+    detection: |
+      Identify all end-game triggers and check if a single player can unilaterally control
+      them. If one strategy can trigger the ending 30%+ earlier than the average game length,
+      and this disproportionately benefits that strategy, the trigger is exploitable. Check
+      if all major strategies have comparable influence over game length.
+
+  - id: first-game-trap
+    name: "First-Game Trap"
+    category: mechanics
+    severity: medium
+    tradition_specific: true
+    description: |
+      A strategy that looks strong to new players but is strictly dominated by experienced
+      play. This is acceptable if the game is meant to be replayed and the trap teaches a
+      lesson, but harmful if the trap is so punishing that new players don't want to replay.
+      Good eurogames let new players be competitive even if not optimal.
+    detection: |
+      Identify the most intuitive strategy for a first-time player (the "obvious" move in
+      early turns). If this strategy's win rate is below 10% against experienced players and
+      the score gap is more than 30%, the game has a punishing first-game trap. Check if the
+      rulebook or game structure provides any guidance away from the trap.

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/lore/resources/tactics.yaml

@@ -0,0 +1,326 @@
+tradition: tactics
+name: "Tactics Game Design Heuristics"
+version: 1.0.0
+description: |
+  Design heuristics for tactical combat games, both digital (XCOM, Fire Emblem, Into the
+  Breach, Jagged Alliance, Tactics Ogre) and tabletop (Warhammer, Frosthaven, Gloomhaven,
+  Rangers of Shadow Deep). Covers grid-based and hex-based tactical systems where unit
+  positioning, action economy, and squad composition are the primary decision spaces.
+  Distilled from competitive play, romhacking communities, modding scenes, and decades of
+  tactical game design iteration.
+
+heuristics:
+  # --- COMBAT ---
+
+  - id: map-spawn-advantage
+    name: "Map Design Spawn Advantage"
+    category: combat
+    severity: high
+    tradition_specific: true
+    description: |
+      When deployment zones are asymmetric, one side can start with elevation, cover, or
+      closer proximity to objectives. This is interesting in narrative scenarios (the
+      defenders hold the ridge) but problematic in competitive or procedurally generated
+      maps where spawn advantage silently determines outcomes. XCOM's pod activation system
+      partially solves this by making the player always the aggressor, but symmetric
+      competitive games (tabletop wargames) must ensure deployment zone parity.
+    detection: |
+      Check for deployment zone or spawn position mechanics. If deployment zones are
+      fixed and asymmetric, check whether the advantaged side has compensating disadvantages
+      (fewer units, weaker equipment, time pressure). If deployment is random with no
+      balancing mechanism, check the variance in terrain quality across possible spawn
+      locations.
+
+  - id: unit-composition-balance
+    name: "Unit Composition Balance"
+    category: combat
+    severity: critical
+    tradition_specific: true
+    description: |
+      When one unit type dominates all others regardless of context, composition is solved.
+      If heavy infantry beats everything, the optimal army is all heavy infantry. Healthy
+      composition design creates rock-paper-scissors dynamics where no single unit type is
+      universally optimal: archers beat slow melee, cavalry beats archers, spears beat
+      cavalry, etc. The counter-relationships must be strong enough to matter but not so
+      strong that the wrong composition is an automatic loss.
+    detection: |
+      Map unit type matchups. If any unit type has a positive expected outcome against all
+      other unit types, it is dominant. If any unit type has a negative expected outcome
+      against all others, it is obsolete. Check if counter-relationships exist and whether
+      they are strong enough (>20% advantage) to incentivize mixed composition.
+
+  - id: per-unit-action-economy
+    name: "Per-Unit Action Economy"
+    category: combat
+    severity: high
+    tradition_specific: true
+    description: |
+      Each unit's turn is a decision point: move, attack, use ability, hold position. If
+      units have only one meaningful action per turn (move-and-attack), tactics are shallow.
+      If units have too many options (move, attack, four abilities, item, overwatch), turns
+      are slow. The sweet spot: 2-3 meaningful choices per unit per turn, with the terrain
+      and enemy position making different choices optimal in different situations. Into the
+      Breach nails this with exactly one move and one action per mech.
+    detection: |
+      Count meaningful actions available per unit per turn. If the average unit has fewer
+      than 2 distinct actions (move + one of attack/ability/item), tactical depth is low.
+      If units average more than 4 distinct actions per turn, cognitive load per unit is
+      high. Multiply by squad size to estimate total decisions per player turn.
+
+  - id: permadeath-recovery
+    name: "Permadeath Recovery Mechanics"
+    category: combat
+    severity: high
+    tradition_specific: true
+    description: |
+      Permadeath creates consequences but can spiral: losing a leveled unit makes the next
+      mission harder, which causes more losses, which makes the next mission harder still.
+      Without recovery mechanics (recruit replacements, catch-up XP, reduced difficulty
+      after losses), permadeath spirals into an unwinnable state that the player does not
+      recognize until hours later. Fire Emblem and XCOM both suffer from invisible death
+      spirals where the correct decision was to restart 3 hours ago.
+    detection: |
+      Check for permadeath or permanent loss mechanics. If units can be permanently lost,
+      check whether replacement units are available and whether they start at a level
+      competitive with surviving units. If replacement units start at level 1 in a game
+      where enemies scale, the death spiral is present. Check for difficulty adjustment
+      after losses.
+
+  - id: cover-terrain-value
+    name: "Cover / Terrain Value Calibration"
+    category: combat
+    severity: high
+    tradition_specific: true
+    description: |
+      Cover and terrain bonuses must be significant enough to influence movement decisions
+      but not so strong that being in cover makes a unit invulnerable. If half-cover grants
+      +2 AC in a system where attacks hit on 10+, it shifts hit chance from 55% to 45% --
+      meaningful but not decisive. If cover grants +5 in the same system, hit chance drops
+      to 30% and the game becomes "whoever reaches cover first wins." XCOM's defense values
+      are famously swingy, making cover feel both essential and unreliable.
+    detection: |
+      Check for cover or terrain defense mechanics. Calculate the hit probability shift
+      from cover. If cover changes hit probability by less than 10%, it is too weak to
+      influence positioning. If cover changes hit probability by more than 30%, it is
+      strong enough to make exposed units non-viable. Check if flanking or abilities bypass
+      cover to prevent static play.
+
+  - id: flanking-positioning-rewards
+    name: "Flanking / Positioning Reward Calibration"
+    category: combat
+    severity: high
+    tradition_specific: true
+    description: |
+      Flanking and rear attacks reward players for maneuvering around enemies rather than
+      attacking head-on. The bonus must be large enough to justify spending movement actions
+      on positioning rather than attacking. If flanking grants +1 to hit, nobody will spend
+      two turns maneuvering for it. If flanking grants automatic critical hits, the entire
+      game reduces to who flanks first. Tactics Ogre's directional damage system makes
+      positioning matter without making it everything.
+    detection: |
+      Check for flanking, facing, or directional attack mechanics. If the flanking bonus
+      is less than 15% improvement in damage or accuracy, it is too weak to incentivize
+      maneuvering. If it exceeds 50% improvement, it dominates all other tactical
+      considerations. Check if enemies have access to the same flanking mechanics to
+      create mutual positioning pressure.
+
+  - id: difficulty-spike-patterns
+    name: "Difficulty Spike Patterns"
+    category: combat
+    severity: high
+    tradition_specific: true
+    description: |
+      A smooth difficulty curve teaches mechanics progressively and builds player mastery.
+      Spikes -- missions that are dramatically harder than adjacent missions -- break the
+      learning flow and frustrate players. Spikes often occur when a new enemy type, map
+      hazard, or mechanical constraint is introduced without adequate ramp-up. The infamous
+      XCOM 2 Lost missions and Fire Emblem's mid-game ambush chapters are classic spikes.
+    detection: |
+      Check for mission or encounter difficulty progression. If enemy power, count, or
+      mechanical complexity increases by more than 25% between consecutive missions without
+      introducing the new element in a lower-stakes context first, a spike exists. Check
+      if the spike correlates with the introduction of a new mechanic or enemy type.
+
+  - id: ability-combo-accessibility
+    name: "Ability Combo Accessibility"
+    category: combat
+    severity: medium
+    tradition_specific: true
+    description: |
+      Combos (unit A sets up a condition that unit B exploits) add depth but create a
+      knowledge barrier. If the best strategy requires discovering non-obvious interactions
+      between abilities, new players will use abilities in isolation and find the game too
+      hard, while experienced players trivialize encounters with combos. The game should
+      signal combo potential: if freezing an enemy makes the next attack deal double damage,
+      the freeze ability's description should hint at this.
+    detection: |
+      Check for mechanics where one ability's effect modifies the outcome of another
+      ability. If combo damage exceeds non-combo damage by more than 50%, combos are
+      dominant. Check if combo relationships are documented, tutorialized, or visually
+      signaled (status effect icons, ability descriptions mentioning synergy).
+
+  - id: squad-size-cognitive-load
+    name: "Squad Size vs. Cognitive Load"
+    category: combat
+    severity: medium
+    tradition_specific: true
+    description: |
+      Each unit added to the squad increases decisions per turn linearly but tactical
+      depth increases sub-linearly after a threshold. 4 unique units create meaningful
+      squad composition. 12 unique units create analysis paralysis. The sweet spot depends
+      on unit complexity: simple units (move + attack) support larger squads; complex units
+      (move + 4 abilities + items) need smaller squads. Into the Breach's 3 mechs and
+      Gloomhaven's 4 characters hit the sweet spot for their complexity levels.
+    detection: |
+      Multiply squad size by actions per unit to estimate decisions per player turn.
+      If decisions per turn exceed 12, cognitive load is high for most players. If
+      decisions per turn are fewer than 4, tactical depth is low. Check if the game
+      provides any automation or AI assist for units beyond the cognitive threshold.
+
+  - id: rng-miss-frustration
+    name: "RNG Mitigation (Miss Chance Frustration)"
+    category: combat
+    severity: high
+    tradition_specific: true
+    description: |
+      Missing a 90% hit chance feels terrible because humans overweight unlikely negative
+      outcomes. Missing a 65% hit chance twice in a row feels like the game is cheating.
+      Pure RNG hit resolution creates frustration spikes that skilled play cannot prevent.
+      Mitigation options: guaranteed minimum damage on miss, pity timers, damage ranges
+      instead of hit/miss binary, or XCOM 2's hidden streak-breaking code. Into the Breach
+      eliminated miss chance entirely, proving the mechanic is optional.
+    detection: |
+      Check for hit probability mechanics. If attacks can miss with no partial effect (full
+      damage or zero), check the probability range. If miss chance can exceed 40% for
+      standard attacks, frustration spikes are likely. Check for pity timers, minimum
+      damage, or graze mechanics that soften misses. If none exist, pure RNG governs
+      outcomes.
+
+  - id: enemy-ai-predictability
+    name: "Enemy AI Predictability Spectrum"
+    category: combat
+    severity: medium
+    tradition_specific: true
+    description: |
+      Perfectly predictable AI (always attacks nearest unit) is solvable and boring.
+      Perfectly unpredictable AI (random target selection) prevents planning and feels
+      unfair. The sweet spot: AI follows readable patterns (prioritizes wounded targets,
+      focuses on high-value units, retreats when outnumbered) that the player can learn
+      and exploit. Into the Breach solves this elegantly by showing enemy intent before
+      the player acts, making AI behavior a puzzle input rather than a random variable.
+    detection: |
+      Check for enemy behavior rules or AI patterns. If enemy behavior is fully random
+      (no targeting priority, no self-preservation), the player cannot plan around it.
+      If enemy behavior follows a single rule (always attacks nearest), it is trivially
+      exploitable. Check if the game reveals or hints at enemy intent before the player
+      commits to actions.
+
+  - id: level-design-linearity
+    name: "Level Design Linearity"
+    category: combat
+    severity: medium
+    tradition_specific: true
+    description: |
+      Linear maps (single path from start to objective) produce single-approach battles.
+      Open maps (multiple paths, flanking routes, elevation options) produce varied tactics.
+      But fully open maps can also be solved by a single dominant strategy (rush the
+      objective, ignore everything else). The best tactical maps create 2-3 viable
+      approaches with different risk/reward profiles and force the player to commit to one
+      based on squad composition and enemy placement.
+    detection: |
+      Check for map design guidelines or procedural generation rules. If maps are
+      described as corridors or linear progressions with no branching paths, tactical
+      variety is limited. If maps are fully open with no terrain channeling, dominant
+      strategies may emerge. Check if maps provide 2+ distinct approaches to objectives.
+
+  - id: equipment-upgrade-paths
+    name: "Equipment / Upgrade Path Clarity"
+    category: progression
+    severity: medium
+    tradition_specific: true
+    description: |
+      When unit upgrades are permanent and irreversible (class promotion, weapon
+      modification), unclear upgrade paths become traps. A player who promotes their
+      archer to sniper when assassin was the correct choice for their squad comp has
+      made an unrecoverable mistake they may not recognize for hours. Upgrade paths
+      should either be reversible, clearly signaled in their trade-offs, or have no
+      strictly dominant option at any branch point.
+    detection: |
+      Check for permanent upgrade or class change mechanics. If upgrades are irreversible,
+      check if the trade-offs are clearly communicated before the choice (stats shown,
+      abilities previewed). If any upgrade path is strictly superior (higher stats in all
+      categories), the choice is false and the inferior path is a trap.
+
+  - id: status-effect-duration
+    name: "Status Effect Duration Calibration"
+    category: mechanics
+    severity: medium
+    tradition_specific: true
+    description: |
+      Status effects that last 1 turn are reactive tools (stun this enemy NOW). Effects
+      that last 3+ turns are strategic tools (poison will wear them down over time). Effects
+      that last the entire battle are win conditions (petrify removes a unit permanently).
+      The duration must match the effect's power: a 1-turn blind is a tactical tool; a
+      permanent blind is a save-or-die. If strong effects last too long, they are unfun.
+      If weak effects are too short to matter, they are wasted design space.
+    detection: |
+      Check for status effect mechanics and their durations. If powerful effects (stun,
+      paralyze, charm) last more than 2 turns, they may remove targets from play too long.
+      If utility effects (poison, slow, blind) last only 1 turn, they may be too weak to
+      justify the action spent applying them. Compare effect duration to average combat
+      length.
+
+  - id: overwatch-reactive-fire
+    name: "Overwatch / Reactive Fire Balance"
+    category: mechanics
+    severity: high
+    tradition_specific: true
+    description: |
+      Overwatch (hold action to shoot enemies who move) creates defensive play. If
+      overwatch is too strong (full damage, guaranteed hit on moving targets), the optimal
+      strategy is to never move -- set overwatch and wait. If overwatch is too weak (low
+      accuracy, half damage), it is never worth giving up your turn for it. XCOM 1's
+      overwatch was so strong that "overwatch creep" (inch forward, overwatch, repeat)
+      was the dominant strategy. XCOM 2 added timers to force aggression.
+    detection: |
+      Check for overwatch, opportunity fire, or held action mechanics. If overwatch damage
+      equals or exceeds normal attack damage with no accuracy penalty, it is too strong and
+      incentivizes static play. If overwatch hits at less than 50% of normal accuracy,
+      it is too unreliable to use. Check if the game has mechanics that punish or prevent
+      overwatch camping (timers, flanking bypasses overwatch, limited overwatch ammo).
+
+  - id: height-advantage-dominance
+    name: "Elevation / Height Advantage Dominance"
+    category: combat
+    severity: medium
+    tradition_specific: true
+    description: |
+      Elevation bonuses (accuracy, damage, range) are intuitive and create vertical
+      tactics. But if height advantage is too strong, the game reduces to "whoever reaches
+      high ground first wins." Maps with limited high ground become king-of-the-hill
+      contests where the tactical question is always the same. Elevation should be one
+      factor among several, not the dominant one.
+    detection: |
+      Check for elevation or height mechanics. If height grants both an offensive bonus
+      (accuracy/damage) AND a defensive bonus (harder to hit from below), the combined
+      advantage may be too strong. If more than 60% of optimal play involves securing
+      elevation before engaging, height dominates other tactical considerations.
+
+  - id: healing-action-economy-tax
+    name: "Healing Action Economy Tax"
+    category: combat
+    severity: medium
+    tradition_specific: true
+    description: |
+      Spending an action to heal instead of attack is an action economy tax: you are paying
+      a full action to undo partial damage rather than dealing damage. If healing restores
+      less than one attack's worth of damage, healing is strictly worse than attacking (the
+      best defense is killing the enemy faster). If healing restores more than one attack's
+      worth, turtling with a healer becomes dominant. The math must make healing situationally
+      correct -- worth it when a unit would die next turn, not worth it as a default action.
+    detection: |
+      Compare healing throughput per action against average incoming damage per enemy action
+      and average player damage per action. If healing per action is less than 50% of
+      average incoming damage, healing cannot keep pace and is rarely worth the action.
+      If healing per action exceeds average incoming damage, a single healer can sustain
+      the entire squad indefinitely.

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/scry/SKILL.md

@@ -0,0 +1,541 @@
+---
+name: scry
+description: Design experimentation through persistent forked game-state with inline analysis
+user-invocable: true
+allowed-tools: Read, Write, Glob, Grep, Edit, Bash
+---
+
+# Scry
+
+Explore design changes without risk by forking the game-state, applying a proposed change, running inline balance and playtest analysis against the fork, and producing a delta report comparing the fork to main. Multiple forks can exist simultaneously for side-by-side comparison. When a design direction proves out, commit it to main game-state; when it does not, discard it to the archive.
+
+Scry exists because design iteration is expensive when every change goes straight into game-state. Designers need to ask "what if?" safely -- see the numbers, feel the play impact, compare alternatives -- before committing. Scry makes that exploration persistent, browsable, and grounded in the same analytical rigor as `/augury` and `/cabal`.
+
+Every fork is a full copy of game-state (not an incremental delta). This means forks are self-contained, readable documents. Someone can open a fork directory and understand the entire design exploration without needing to reconstruct a chain of patches.
+
+## Trigger
+
+`/scry` with a quoted change description or a subcommand.
+
+Examples:
+- `/scry "what if DOSE threshold was 4?"` -- create a fork with this change
+- `/scry "add stamina recovery in combat"` -- create another fork
+- `/scry compare` -- side-by-side comparison of all active forks vs. main
+- `/scry commit threshold-4` -- merge fork to main game-state
+- `/scry discard combat-recovery` -- archive fork
+- `/scry list` -- show active and archived branches
+
+Also triggered by natural language:
+- "what if"
+- "try changing"
+- "fork the game state"
+- "explore a design branch"
+
+## Workflow
+
+### Step 1: Parse Invocation
+
+Determine which subcommand the user is invoking:
+
+| Pattern | Subcommand | Action |
+|---------|------------|--------|
+| `/scry "quoted change"` | **fork** | Create a new design branch |
+| `/scry compare` | **compare** | Side-by-side analysis of all active forks vs. main |
+| `/scry commit {branch-name}` | **commit** | Merge fork game-state to main |
+| `/scry commit {branch-name} --no-analysis` | **force commit** | Merge without requiring analysis |
+| `/scry discard {branch-name}` | **discard** | Archive the fork |
+| `/scry list` | **list** | Show all active and archived branches |
+
+If the pattern is ambiguous, ask the user to clarify.
+
+---
+
+### Subcommand: Fork (Create a Design Branch)
+
+#### Step F1: Load Main Game-State
+
+1. Check that `grimoires/gygax/game-state/index.yaml` exists. If it does not, stop and tell the user: "No game attuned yet. Run `/attune` first to build your game-state."
+2. Read `index.yaml` to get the full entity manifest: game name, tradition, entity counts, file list, and dependency graph summary.
+3. Identify which entities the proposed change affects. Parse the user's quoted description to determine:
+   - Which entity files will be modified
+   - What the modification is (value change, new entity, removal, structural change)
+   - Which entities depend on or are affected by the changed entities (traverse `depends_on` and `affects` in the index)
+
+If the user's description is vague, ask targeted questions to establish exactly what changes. Do not guess.
+
+#### Step F2: Generate Branch Name
+
+Derive a short, kebab-case branch name from the change description. Examples:
+- "what if DOSE threshold was 4?" -> `threshold-4`
+- "add stamina recovery in combat" -> `combat-stamina-recovery`
+- "remove dodge reaction" -> `no-dodge-reaction`
+
+Check for conflicts: glob `grimoires/gygax/forks/*/` to see if the name already exists. If it does, tell the user: "A branch named '{name}' already exists. Choose a different name or discard the existing branch first with `/scry discard {name}`."
+
+#### Step F3: Create Fork Directory and Copy Game-State
+
+1. Create the fork directory structure:
+   ```
+   grimoires/gygax/forks/{branch-name}/
+     game-state/        # Full copy of main game-state
+     analysis/          # Will hold augury and cabal reports
+   ```
+2. Copy the ENTIRE contents of `grimoires/gygax/game-state/` into `grimoires/gygax/forks/{branch-name}/game-state/`. This is a full copy -- every file, every subdirectory. Use bash `cp -r` for the copy.
+3. Verify the copy by checking that `forks/{branch-name}/game-state/index.yaml` exists and matches main.
+
+#### Step F4: Apply Proposed Change to Fork
+
+1. Modify the forked game-state files to reflect the proposed change. This may involve:
+   - Changing values in existing YAML entity files
+   - Creating new entity files
+   - Removing entity files
+   - Updating `depends_on` and `affects` arrays in related entities
+2. After applying the change to forked game-state, check if the change affects any entities with intent set. If so, prompt the user: "This change affects entities with stated intent: [list]. Does this change preserve the original intent, or shift it?"
+
+   - **Preserve:** Intent fields unchanged in the fork
+   - **Shift:** Prompt for new intent summary and rationale for each affected entity; update in fork
+
+3. **Graph enforcement (v3.1):** Apply the same graph validation as `/attune` Phase 6 to the forked game-state:
+   - New dependencies must resolve to existing entities in the fork or trigger stub creation
+   - Update `graph_integrity` section in the fork's index.yaml
+   - If the change creates new stubs, report them: "Fork created N new stubs for unresolved references."
+4. Update the fork's `index.yaml` to reflect all changes:
+   - Update entity counts if entities were added or removed
+   - Update file list entries
+   - Update `last_modified_at` to current timestamp
+   - Set `last_modified_by: scry`
+   - Regenerate `graph_integrity` if the dependency structure changed
+4. Validate every modified YAML file: required fields present, cross-references point to files that exist within the fork, tradition is valid.
+
+Do NOT modify any files in `grimoires/gygax/game-state/` (the main game-state). All changes happen in the fork only.
+
+#### Step F5: Inline Augury Analysis (Scoped)
+
+Perform augury-style numerical analysis against the forked game-state, scoped to the changed entities and their dependents. This is inline analysis derived from `/augury` methodology -- it does not invoke the augury skill.
+
+1. Identify the analysis scope: the changed entities plus every entity in their `depends_on` and `affects` graph within the fork.
+2. Determine applicable analysis types based on what changed:
+
+| What Changed | Analysis Types |
+|-------------|---------------|
+| Combat mechanic (attack, damage, defense) | Combat analysis: hit probability, DPR, TTK |
+| Resource (pool, cost, recovery) | Resource economy: depletion rate, recovery rate, net pressure |
+| Progression (levels, scaling) | Scaling analysis: metric curves at breakpoints |
+| Pacing-relevant mechanic (triggers, timing) | Pacing analysis: trigger frequency, arc coverage |
+| Stat or modifier | Combat + resource recomputation for all dependents |
+
+3. Run the applicable calculations using the formulas from augury methodology:
+   - **Hit probability (d20):** `clamp((21 - (AC - attack_bonus)) / 20, 0.05, 0.95)`
+   - **DPR:** `hit_probability * average_damage * attacks_per_round`
+   - **TTK:** `target_HP / DPR`
+   - **Resource depletion:** `pool_max / consumption_per_round`
+   - **Net pressure:** `consumption_per_cycle - recovery_per_cycle`
+   - **PbtA probabilities:** 2d6+stat distribution (10+, 7-9, 6-)
+   - **FitD probabilities:** best-of-Nd6 distribution (crit, 6, 4-5, 1-3)
+   - Adapt methodology to the game's tradition. Do not force d20 math onto a PbtA game.
+
+4. Compute each metric for BOTH the fork and main game-state so deltas can be calculated.
+
+5. Write results to `grimoires/gygax/forks/{branch-name}/analysis/augury-report.md` using this format:
+
+```markdown
+# Augury Analysis: {branch-name}
+
+**Date:** YYYY-MM-DD
+**Game:** [game name]
+**Tradition:** [tradition]
+**Scope:** Changed entities and dependents
+**Entities Analyzed:** [count]
+
+## Changed Entities
+
+[List each entity that was modified, created, or removed, with a one-line description of the change.]
+
+## Numerical Analysis
+
+[Tables of computed metrics -- only include sections for which data exists.]
+
+### [Analysis Type]
+
+| Metric | Main Value | Fork Value | Delta | Assessment |
+|--------|-----------|------------|-------|------------|
+| ...    | ...       | ...        | ...   | Healthy / Warning / Critical |
+
+## Findings
+
+| # | Severity | Finding | Values |
+|---|----------|---------|--------|
+| 1 | ...      | ...     | ...    |
+
+## Methodology Notes
+
+[Assumptions, data gaps, tradition adaptations.]
+```
+
+#### Step F6: Inline Cabal Analysis (Context-Aware)
+
+Perform cabal-style archetype analysis against the forked game-state, with a context-aware panel based on what changed. This is inline analysis derived from `/cabal` methodology -- it does not invoke the cabal skill.
+
+1. Select the archetype panel based on what changed:
+
+| What Changed | Priority Archetypes | Rationale |
+|-------------|-------------------|-----------|
+| Combat mechanic | Optimizer, Rules Lawyer | Combat changes hit optimization and RAW edge cases hardest |
+| Resource economy | Optimizer, Explorer | Resource changes affect efficiency and viable build variety |
+| Narrative/social mechanic | Storyteller, Explorer | Narrative changes affect fiction alignment and design space |
+| Progression/scaling | Optimizer, Explorer | Scaling changes affect build planning and option breadth |
+| Core resolution | All four | Core changes affect everything |
+
+Always run at least the Optimizer and one other archetype. For core system changes, run all four.
+
+2. For each selected archetype, simulate their interaction with the CHANGED mechanics in the fork:
+
+**Optimizer:** Does this change create a new dominant strategy? Does it invalidate an existing optimized approach? Does the resource efficiency shift?
+
+**Explorer:** Does this change open or close design space? Are there new viable options, or did options disappear? Are there new edge case interactions?
+
+**Storyteller:** Does this change improve or worsen fiction-mechanics alignment? Does optimal play still produce interesting narrative? Are there new feel-bad moments?
+
+**Rules Lawyer:** Does this change introduce ambiguity? Are there undefined states? Do any two mechanics now contradict? Is the trigger language precise?
+
+3. For each archetype, produce at least one finding. Severity levels: Critical, Major, Minor, Observation, Non-obvious.
+
+4. Write results to `grimoires/gygax/forks/{branch-name}/analysis/cabal-report.md` using this format:
+
+```markdown
+# Cabal Analysis: {branch-name}
+
+**Date:** YYYY-MM-DD
+**Game:** [game name]
+**Tradition:** [tradition]
+**Scope:** Impact of proposed change on play experience
+**Panel:** [which archetypes were run and why]
+
+## Change Under Test
+
+[One-paragraph description of what changed in this fork.]
+
+## [Archetype Name]
+
+### Approach
+[1-2 sentences: what this archetype tried to do with the change.]
+
+### Findings
+[Each finding: severity, summary, description, evidence from forked game-state.]
+
+[Repeat for each archetype in the panel.]
+
+## Non-Obvious Findings
+
+[Dedicated section for second-order effects and emergent dynamics that arise specifically from this change.]
+```
+
+#### Step F7: Generate Delta Report
+
+Compare the fork's analysis results against main game-state to produce a unified delta report.
+
+1. Gather:
+   - Numerical deltas from the augury analysis (Step F5)
+   - Experience deltas from the cabal analysis (Step F6)
+   - Tension impacts: which design tensions shifted and in what direction
+2. Write the delta report to `grimoires/gygax/forks/{branch-name}/delta.md`:
+
+```markdown
+# Delta Report: {branch-name}
+
+**Date:** YYYY-MM-DD
+**Game:** [game name]
+**Proposed Change:** [one-line description]
+**Branch:** {branch-name}
+**Status:** Active
+
+## Summary
+
+[2-4 sentences: what changed, the most significant numerical impact, the most significant experiential impact, and an overall assessment.]
+
+## Graph Integrity Delta (v3.1)
+
+| Metric | Main | Fork | Delta |
+|--------|------|------|-------|
+| Resolved references | N | N | +/-N |
+| Stubs | N | N | +/-N |
+| Orphaned entities | N | N | +/-N |
+
+[If the fork created new stubs, list them. If the fork resolved existing stubs, note that.]
+
+## Numerical Deltas
+
+| Metric | Main | Fork | Delta | Severity |
+|--------|------|------|-------|----------|
+| ...    | ...  | ...  | ...   | ...      |
+
+## Experience Deltas
+
+| Archetype | Impact | Summary |
+|-----------|--------|---------|
+| Optimizer | Positive / Negative / Neutral | [one-line] |
+| Explorer  | ... | ... |
+| Storyteller | ... | ... |
+| Rules Lawyer | ... | ... |
+
+## Tension Impacts
+
+| Tension | Main State | Fork State | Shift |
+|---------|-----------|------------|-------|
+| ...     | balanced  | tilted-a   | ...   |
+
+## Intent Deltas
+
+[Only include this section if intent changed between main and fork]
+
+| Entity | Original Intent | Fork Intent | Shift Magnitude |
+|--------|----------------|-------------|-----------------|
+| tensions/foo.yaml | "deliberate asymmetry" | "balanced pole-swap" | Major |
+
+**Analysis:**
+[Does the intent shift align with the change's purpose? Or did the change inadvertently alter the design philosophy?]
+
+## Key Findings
+
+[Top 3-5 findings across both augury and cabal analysis, prioritized by severity.]
+
+## Recommended Next Steps
+
+[Specific, actionable recommendations. Examples:]
+- `/scry commit {branch-name}` -- if the change is clearly beneficial
+- `/scry discard {branch-name}` -- if the change causes more problems than it solves
+- `/scry "alternative approach"` -- if a variant might work better
+- `/homebrew [mechanic]` -- if a specific mechanic needs redesign before committing
+- `/augury [scope]` -- if deeper numerical analysis is needed on a specific metric
+- `/scry compare` -- if other forks exist and should be compared
+```
+
+3. Present the delta report to the user.
+
+---
+
+### Subcommand: Compare
+
+Compare all active forks against main game-state and against each other.
+
+**Convergence is coherence, not correctness.** When comparing forks (or any panel of
+analyses/playtest reads), agreement between readings is a *compression* signal — the
+thing is well-defined enough that independent eyes parse it the same — never proof
+the reading is right. The findings worth keeping live in the DIVERGENCE: design the
+comparison (and any operator seam) to maximize informative disagreement, and report
+convergence and divergence separately rather than blending them into one verdict.
+The method is symmetric — it applies to designers and players, humans and agents
+alike. (clew lrn-20260609-gygax-e72fbd, operator reframe at a live ratify-seam.)
+
+
+#### Step C1: Load Active Forks
+
+1. Glob `grimoires/gygax/forks/*/delta.md` to find all active forks with completed analysis.
+2. If no active forks exist, tell the user: "No active forks to compare. Create one with `/scry \"your proposed change\"`."
+3. If only one fork exists, note that comparison is most useful with multiple forks but proceed with a fork-vs-main comparison.
+4. Read each fork's `delta.md`.
+
+#### Step C2: Generate Cross-Branch Comparison
+
+1. Collect all numerical metrics that appear in any fork's delta report.
+2. Build a comparison table with main as the baseline:
+
+```markdown
+# Branch Comparison
+
+**Date:** YYYY-MM-DD
+**Game:** [game name]
+**Active Forks:** [count]
+
+## Metric Comparison
+
+| Metric | Main | {branch-1} | {branch-2} | ... |
+|--------|------|-------------|-------------|-----|
+| [metric] | [value] | [value] (delta) | [value] (delta) | ... |
+
+## Experience Comparison
+
+| Archetype | Main | {branch-1} | {branch-2} | ... |
+|-----------|------|-------------|-------------|-----|
+| Optimizer | baseline | [impact] | [impact] | ... |
+| Explorer  | baseline | [impact] | [impact] | ... |
+| Storyteller | baseline | [impact] | [impact] | ... |
+| Rules Lawyer | baseline | [impact] | [impact] | ... |
+
+## Tension Comparison
+
+| Tension | Main | {branch-1} | {branch-2} | ... |
+|---------|------|-------------|-------------|-----|
+| [tension] | [state] | [state] | [state] | ... |
+
+## Assessment
+
+[For each fork: 1-2 sentence summary of whether it improves the design and the primary tradeoff.]
+
+## Recommendation
+
+[Which fork (if any) should be committed, and why. If none are clearly better, suggest what to explore next.]
+```
+
+3. Present the comparison to the user.
+
+---
+
+### Subcommand: Commit
+
+Merge a fork's game-state into main.
+
+#### Step M1: Validate the Fork
+
+1. Check that the branch exists: `grimoires/gygax/forks/{branch-name}/` must exist and not be under `.archived/`.
+2. Check that analysis has been run: `forks/{branch-name}/analysis/augury-report.md` and `forks/{branch-name}/analysis/cabal-report.md` must exist. If they do not:
+   - Default behavior: "Branch '{name}' has no analysis results yet. Run `/scry` against it first, or force commit with `/scry commit {name} --no-analysis`."
+   - If `--no-analysis` flag is present, proceed without analysis.
+3. Check for staleness: read main `game-state/index.yaml` and compare its `last_modified_at` against the fork's creation time (from the fork's `delta.md` date). If main has been modified since the fork was created:
+   - Identify conflicting files: files that changed in BOTH main and the fork.
+   - Tell the user: "Main game-state has changed since this branch was created. The conflicting files are: {list}. Re-fork from current main, or force commit to overwrite."
+   - If the user confirms force commit, proceed. Otherwise, stop.
+
+#### Step M2: Copy Fork Game-State to Main
+
+1. Copy all files from `grimoires/gygax/forks/{branch-name}/game-state/` to `grimoires/gygax/game-state/`, overwriting existing files.
+2. Verify the copy: read the updated `game-state/index.yaml` and confirm it reflects the fork's state.
+
+When `/scry commit` merges a fork to main, all intent fields from the fork are copied to main — including intent changes. The changelog entry for the merge explicitly records intent deltas for full traceability.
+
+#### Step M3: Write Changelog Entry
+
+Write a changelog entry to `grimoires/gygax/changelog/YYYY-MM-DD-HHMMSS-scry-commit-{branch-name}.yaml`:
+
+```yaml
+timestamp: "ISO-8601"
+skill: scry
+action: merged
+summary: "Merged branch '{branch-name}' to main game-state"
+rationale: "[Summary of augury and cabal findings that justified the commit]"
+source: "scry branch comparison"
+branch: "{branch-name}"
+files_changed:
+  - [list of files that differ between fork and original main]
+affected_tensions:
+  - [list of tensions that shifted, from delta report]
+```
+
+#### Step M4: Clean Up
+
+1. Remove the fork directory: `grimoires/gygax/forks/{branch-name}/`. The fork's analysis and delta are preserved in the changelog rationale, and the fork's game-state is now main.
+2. Inform the user: "Branch '{branch-name}' merged to main game-state. Changelog entry written. Fork directory removed."
+
+---
+
+### Subcommand: Discard
+
+Archive a fork without merging.
+
+#### Step D1: Validate the Fork
+
+1. Check that the branch exists at `grimoires/gygax/forks/{branch-name}/`.
+2. If the branch is already under `.archived/`, tell the user: "Branch '{name}' is already archived."
+3. If the branch does not exist anywhere, tell the user: "No branch named '{name}' found. Run `/scry list` to see available branches."
+
+#### Step D2: Move to Archive
+
+1. Create `grimoires/gygax/forks/.archived/` if it does not exist.
+2. Move the fork directory: `mv grimoires/gygax/forks/{branch-name}/ grimoires/gygax/forks/.archived/{branch-name}/`
+3. No changelog entry is written (nothing changed in main game-state).
+4. Inform the user: "Branch '{branch-name}' archived. It can still be browsed at `forks/.archived/{branch-name}/`."
+
+---
+
+### Subcommand: List
+
+Show all active and archived branches.
+
+#### Step L1: Enumerate Branches
+
+1. Glob `grimoires/gygax/forks/*/delta.md` for active branches.
+2. Glob `grimoires/gygax/forks/.archived/*/delta.md` for archived branches.
+3. For each branch, read the first few lines of `delta.md` to extract: branch name, proposed change, date, and status.
+
+#### Step L2: Present List
+
+```markdown
+# Scry Branches
+
+## Active
+
+| Branch | Proposed Change | Date | Has Analysis |
+|--------|----------------|------|--------------|
+| {name} | [one-line description] | YYYY-MM-DD | Yes / No |
+
+## Archived
+
+| Branch | Proposed Change | Date | Reason |
+|--------|----------------|------|--------|
+| {name} | [one-line description] | YYYY-MM-DD | Discarded / Superseded |
+
+[If no branches exist in either category, say so.]
+```
+
+---
+
+## Inline Analysis Methodology
+
+Scry's inline analysis is derived from `/augury` and `/cabal` but scoped and adapted for fork comparison. Key differences from the full skills:
+
+### Augury-Derived Analysis
+
+- **Scope:** Only entities changed in the fork plus their immediate dependents. Not full-spectrum.
+- **Computation:** Same formulas as augury (hit probability, DPR, TTK, resource depletion, scaling curves). See augury SKILL.md for the complete methodology reference.
+- **Output:** Comparative tables (main vs. fork) rather than standalone balance reports.
+- **Severity:** Assessed relative to the delta, not absolute. A metric that was already "Warning" in main and stays "Warning" in the fork is "Unchanged," not a new finding.
+
+### Cabal-Derived Analysis
+
+- **Panel selection:** Context-aware based on what changed, not always all four archetypes.
+- **Scope:** Archetypes interact with the changed mechanics specifically, not the entire game.
+- **Regression awareness:** Not applicable (forks are new). Regression tracking happens in full `/cabal` runs against main game-state.
+- **Non-obvious findings:** Still required. At least one finding per fork run must surface something the designer likely did not anticipate about the proposed change.
+- **Output:** Per-archetype findings with evidence from forked game-state, following the same finding format as cabal (severity, summary, description, evidence, recommendation).
+
+## Boundaries
+
+- Does NOT modify main game-state until the user explicitly runs `/scry commit` -- forks are isolated
+- Does NOT invoke other skills (augury, cabal, homebrew, lore, attune) -- contains its own inline analysis logic derived from those skills
+- Does NOT write production game code or final prose
+- Does NOT make final creative decisions -- presents delta analysis, the designer decides whether to commit or discard
+- Does NOT perform full-spectrum analysis -- scopes to changed entities and dependents for speed and focus
+- Does NOT auto-commit or auto-discard -- every merge and archive is an explicit user action
+- DOES create persistent, browsable fork directories that are fully self-contained
+- DOES write presentable markdown throughout -- every artifact is human-readable
+- DOES track which entities changed and their full dependency graph within the fork
+- DOES handle any TTRPG tradition -- adapts analysis methodology to the game's tradition (d20, PbtA, FitD, OSR, freeform, custom)
+- DOES support multiple simultaneous forks for side-by-side comparison
+- DOES include "Recommended Next Steps" in every delta report for cross-skill chaining
+- DOES prompt about intent preservation when forks touch intent-annotated entities
+- DOES include intent deltas in comparison reports alongside numerical/experiential deltas
+- DOES preserve intent fields on commit (including any shifts)
+
+## Output
+
+| Artifact | Path | Format |
+|----------|------|--------|
+| Forked game-state | `grimoires/gygax/forks/{branch}/game-state/` | YAML (full copy) |
+| Augury analysis | `grimoires/gygax/forks/{branch}/analysis/augury-report.md` | Markdown with tables |
+| Cabal analysis | `grimoires/gygax/forks/{branch}/analysis/cabal-report.md` | Markdown with tables |
+| Delta report | `grimoires/gygax/forks/{branch}/delta.md` | Markdown |
+| Changelog (on commit) | `grimoires/gygax/changelog/YYYY-MM-DD-HHMMSS-scry-commit-{branch}.yaml` | YAML |
+
+## Error Handling
+
+| Error | Response | Recovery |
+|-------|----------|----------|
+| No game-state exists | "No game attuned yet. Run `/attune` first to build your game-state." | Redirect to `/attune` |
+| Branch name conflict | "A branch named '{name}' already exists. Choose a different name or discard the existing branch first with `/scry discard {name}`." | User renames or discards |
+| Commit with no analysis | "Branch '{name}' has no analysis results yet. Run `/scry` against it first, or force commit with `/scry commit {name} --no-analysis`." | User runs analysis or force commits |
+| Main game-state changed since fork (stale fork) | "Main game-state has changed since this branch was created. The conflicting files are: {list}. Re-fork from current main, or force commit to overwrite." | User re-forks or force commits |
+| Discard already-archived branch | "Branch '{name}' is already archived." | No action needed |
+| Branch not found | "No branch named '{name}' found. Run `/scry list` to see available branches." | User checks list |
+| Game-state too sparse for meaningful analysis | "Game-state has {N} entities. Analysis works best with stats, resources, and core mechanics defined. Proceeding with what exists -- findings may be limited." | Partial analysis with caveats |
+| Proposed change is ambiguous | Ask the user targeted questions to clarify exactly what should change in the fork. Do not guess. | Clarification loop |
+| Too many active forks (more than 5) | "You have {N} active forks. Consider discarding or committing some before creating more. Active forks: {list}." | Advisory, not blocking |

.codex/skills/polytopia-strategy-design/references/external/construct-gygax/skills/scry/index.yaml

@@ -0,0 +1,29 @@
+slug: scry
+name: "Scry"
+description: |
+  Use this skill IF user invokes /scry OR wants to explore a design change, fork the game state, compare alternatives, or ask "what if" about a mechanic.
+  Produces artifacts to grimoires/gygax/forks/.
+version: 1.0.0
+
+triggers:
+  - "/scry"
+  - "what if"
+  - "try changing"
+  - "fork the game state"
+  - "explore a design branch"
+
+capabilities:
+  model_tier: opus
+  danger_level: safe
+  effort_hint: large
+  downgrade_allowed: true
+  execution_hint: sequential
+  requires:
+    native_runtime: false
+    tool_calling: true
+    thinking_traces: false
+    vision: false
+
+dependencies:
+  grimoire_paths:
+    - grimoires/gygax/

.codex/skills/polytopia-strategy-design/references/external/orangeviolin-game-design/summary.md

@@ -0,0 +1,25 @@
+# OrangeViolin Game Design Gist Summary
+
+Source: https://gist.github.com/OrangeViolin/53ad898cdbc8734d8bb5c6a6ddf5cec4
+
+No explicit license was found, so the local skill keeps only this index/summary. Browse the source when exact wording is required.
+
+Relevant method references:
+
+- `game-design-methodology`: use structured design loops instead of isolated mechanic brainstorming.
+- `doubling-halving-balance`: stress-test balance by asking what happens if a value is doubled or halved; useful for Polytopia-like stars, unit costs, population thresholds, road costs, and tech costs.
+- `flow-state-design-framework`: examine challenge/skill pacing; useful for early-game onboarding and midgame complexity.
+- `reinforcement-feedback-systems`: check whether rewards teach the right behavior; useful for city upgrades, monuments, score, and combat feedback.
+- `player-psychology-decisions`: inspect biases and perceived value; useful for trap techs, visible resources, and score vs conquest goals.
+- `game-prototyping-testing`: prototype rule changes with targeted questions and observe behavior, not just stated preference.
+- `character-optimization-design`: adapt as faction/tribe optimization analysis.
+- `hicks-law-decision-optimization`: keep decision sets small enough for fast mobile-strategy play.
+
+Use these as prompts alongside the Polytopia-specific references:
+
+1. What behavior does this mechanic teach?
+2. Which number would break if doubled?
+3. Which number would become irrelevant if halved?
+4. Does the player understand why they won or lost?
+5. Does the best play match the intended fantasy?
+6. Does the choice count fit the turn's importance?

.codex/skills/polytopia-strategy-design/references/external/skillsbench-civ6lib/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: civ6lib
+description: Civilization 6 district mechanics library. Use when working with district placement validation, adjacency bonus calculations, or understanding Civ6 game rules.
+---
+
+# Understanding Civ6 District Mechanics
+
+Complete reference for Civilization 6 district placement and adjacency bonus systems (Gathering Storm).
+
+## Modules
+
+- **placement_rules.py** - District placement validation rules
+- **adjacency_rules.py** - Adjacency bonus calculation engine
+
+For hex grid utilities (neighbors, distance, etc.), use the `hex-grid-spatial` skill or import from `src.hex_utils`.
+
+## Usage
+
+```python
+from civ6lib import (
+    # Placement
+    DistrictType, Tile, PlacementRules, get_placement_rules,
+    validate_district_count, validate_district_uniqueness,
+    # Adjacency
+    AdjacencyCalculator, get_adjacency_calculator,
+)
+
+# Validate a placement
+rules = get_placement_rules(tiles, city_center=(21, 13), population=7)
+result = rules.validate_placement(DistrictType.CAMPUS, 21, 14, {})
+if result.valid:
+    print("Valid placement!")
+
+# Calculate adjacency bonus
+calculator = get_adjacency_calculator(tiles)
+total, per_district = calculator.calculate_total_adjacency(placements)
+```
+
+---
+
+# Part 1: Placement Rules
+
+## City Placement Rules
+
+### Minimum Distance Between Cities
+
+| Condition | Min Distance | Tiles Between |
+|-----------|--------------|---------------|
+| Same landmass | 4 tiles | 3 tiles |
+| Different landmasses | 3 tiles | 2 tiles |
+
+### Invalid Settlement Tiles
+- Water (Coast, Ocean, Lake)
+- Mountains
+- Natural Wonders
+
+### Note on City Center Features
+Settling a **City Center** on a tile with Geothermal Fissure or Luxury/Strategic Resources **preserves** them (they remain and provide adjacency bonuses to nearby districts). Districts cannot be placed on these tiles.
+
+## District Placement Rules
+
+### Universal Rules (All Districts)
+
+| Rule | Description |
+|------|-------------|
+| Distance | Within **3 tiles** of City Center |
+| Mountains | Cannot place |
+| Natural Wonders | Cannot place |
+| Strategic Resources | Cannot place (Iron, Horses, Niter, Coal, Oil, Aluminum, Uranium) |
+| Luxury Resources | Cannot place |
+| Existing District | Cannot place on occupied tile |
+| Bonus Resources | CAN place (resource destroyed) |
+| Woods/Rainforest/Marsh | CAN place (feature destroyed) |
+
+### District-Specific Rules
+
+| District | Special Requirement |
+|----------|---------------------|
+| Harbor | Must be on Coast/Lake, adjacent to land |
+| Water Park | Must be on Coast/Lake, adjacent to land |
+| Aerodrome | Must be on flat land |
+| Spaceport | Must be on flat land |
+| Encampment | NOT adjacent to City Center |
+| Preserve | NOT adjacent to City Center |
+| Aqueduct | Adjacent to City Center AND fresh water (Mountain, River, Lake, Oasis) |
+| Dam | On Floodplains, river crosses 2+ edges |
+
+## District Limits
+
+### Population Formula
+```
+max_specialty_districts = 1 + floor((population - 1) / 3)
+```
+
+| Population | Max Districts |
+|------------|---------------|
+| 1-3 | 1 |
+| 4-6 | 2 |
+| 7-9 | 3 |
+| 10-12 | 4 |
+
+
+### Non-Specialty Districts (Don't Count)
+These can be built regardless of population limit:
+- Aqueduct / Bath
+- Neighborhood / Mbanza
+- Canal
+- Dam
+- Spaceport
+
+### Uniqueness Rules
+
+| Rule | Districts |
+|------|-----------|
+| ONE per city | Campus, Holy Site, Theater Square, Commercial Hub, Harbor, Industrial Zone, Entertainment Complex, Water Park, Encampment, Aerodrome, Preserve |
+| Multiple per city | Neighborhood |
+| ONE per civilization | Government Plaza, Diplomatic Quarter |
+
+---
+
+# Part 2: Adjacency Bonus Rules
+
+## Critical Rule: Minor Bonus Calculation
+
+**Each +0.5 type is floored SEPARATELY, then summed!**
+
+```
+WRONG:
+  IZ with 1 Mine + 1 Lumber Mill + 1 District
+  = floor(3/2) = 1  ❌
+
+CORRECT:
+  Mine: floor(1/2) = 0
+  Lumber Mill: floor(1/2) = 0
+  District: floor(1/2) = 0
+  TOTAL = 0  ✓
+```
+
+## Adjacency Rules by District
+
+### Campus (+Science)
+| Bonus | Source |
+|-------|--------|
+| +2 each | Geothermal Fissure, Reef |
+| +1 each | Mountain |
+| +0.5 each | Rainforest (floor separately) |
+| +0.5 each | District (floor separately) |
+
+### Holy Site (+Faith)
+| Bonus | Source |
+|-------|--------|
+| +2 each | Natural Wonder |
+| +1 each | Mountain |
+| +0.5 each | Woods (floor separately) |
+| +0.5 each | District (floor separately) |
+
+### Theater Square (+Culture)
+| Bonus | Source |
+|-------|--------|
+| +2 each | Wonder (built wonder) |
+| +2 each | Entertainment Complex, Water Park |
+| +0.5 each | District (floor separately) |
+
+### Commercial Hub (+Gold)
+| Bonus | Source |
+|-------|--------|
+| +2 | If tile is ON a river (binary!) |
+| +2 each | Adjacent Harbor |
+| +0.5 each | District (floor separately) |
+
+### Harbor (+Gold)
+| Bonus | Source |
+|-------|--------|
+| +2 each | Adjacent City Center |
+| +1 each | Coastal Resource (Fish, Crabs, Whales, Pearls) |
+| +0.5 each | District (floor separately) |
+
+### Industrial Zone (+Production)
+| Bonus | Source |
+|-------|--------|
+| +2 each | Aqueduct, Dam, Canal |
+| +1 each | Quarry, Strategic Resource |
+| +0.5 each | Mine (floor separately) |
+| +0.5 each | Lumber Mill (floor separately) |
+| +0.5 each | District (floor separately) |
+
+### Districts with NO adjacency bonuses
+- Entertainment Complex
+- Water Park
+- Encampment
+- Aerodrome
+- Spaceport
+- Government Plaza
+- Preserve
+
+## Government Plaza Adjacency Bonus
+
+**Government Plaza gives +1 adjacency bonus to adjacent specialty districts.**
+
+Districts that benefit when adjacent to Government Plaza:
+- Campus (+1)
+- Holy Site (+1)
+- Theater Square (+1)
+- Commercial Hub (+1)
+- Harbor (+1)
+- Industrial Zone (+1)
+
+Note: Government Plaza also counts toward the +0.5 per district minor bonus.
+
+## Districts That Count for "+0.5 per District"
+
+**Counts:** Campus, Holy Site, Theater Square, Commercial Hub, Harbor, Industrial Zone, Entertainment Complex, Water Park, Encampment, Aerodrome, Spaceport, Government Plaza, Diplomatic Quarter, Preserve, City Center, Aqueduct, Dam, Canal, Neighborhood
+
+## Destruction Effects
+
+Placing ANY district destroys:
+- Woods (FEATURE_FOREST)
+- Rainforest (FEATURE_JUNGLE)
+- Marsh (FEATURE_MARSH)
+- Bonus Resources
+
+**This affects OTHER districts' adjacency!**
+
+---
+
+# Key Classes
+
+### DistrictType (Enum)
+All district types: CAMPUS, HOLY_SITE, THEATER_SQUARE, COMMERCIAL_HUB, HARBOR, INDUSTRIAL_ZONE, etc.
+
+### Tile (Dataclass)
+Represents a map tile with terrain, features, resources, rivers.
+
+### PlacementRules
+Validates district placements against all game rules.
+
+### AdjacencyCalculator
+Calculates adjacency bonuses based on surrounding tiles and districts.
+
+---
+
+# Quick Validation Checklist
+
+1. Is tile within 3 of city center?
+2. Is tile NOT a mountain/natural wonder?
+3. Is tile NOT a strategic/luxury resource?
+4. Is tile unoccupied?
+5. Does district meet special requirements?
+6. Does city have district slots available?
+7. Is this district unique and not already built?

.codex/skills/polytopia-strategy-design/references/external/skillsbench-civ6lib/scripts/adjacency_rules.py

@@ -0,0 +1,474 @@
+"""District adjacency bonus calculations for Civ6 (Gathering Storm).
+
+This module calculates adjacency bonuses based on wiki-verified rules.
+
+Reference: https://civilization.fandom.com/wiki/Adjacency_bonus_(Civ6)
+
+CRITICAL RULES:
+===============
+1. Minor bonuses (+1 per 2) are counted SEPARATELY by type, then EACH floored.
+   Example: 1 Mine + 1 Lumber Mill + 1 District for Industrial Zone
+   - Mine: floor(1/2) = 0
+   - Lumber Mill: floor(1/2) = 0
+   - District: floor(1/2) = 0
+   - TOTAL = 0 (NOT 1!)
+
+2. Placing a district DESTROYS: Woods, Rainforest, Marsh, Bonus Resources
+   This affects adjacency for OTHER districts!
+
+3. Final bonus is always an INTEGER (floored).
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Set, Tuple, Optional, Any
+
+from hex_utils import get_neighbors
+from placement_rules import Tile, DistrictType
+
+
+@dataclass
+class AdjacencyRule:
+    """Defines a single adjacency bonus rule.
+
+    Attributes:
+        sources: What provides this bonus (feature/terrain/district names)
+        bonus_per: How much bonus per count_required matches
+        count_required: How many matches needed for one bonus (1 = each, 2 = per 2)
+    """
+    sources: List[str]
+    bonus_per: int
+    count_required: int = 1
+
+
+@dataclass
+class AdjacencyResult:
+    """Result of adjacency calculation for a single district."""
+    total_bonus: int  # Always integer (floored)
+    breakdown: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+    # breakdown format: {"RULE_KEY": {"count": N, "bonus": B, "sources": [...]}}
+
+
+# ============================================================================
+# ADJACENCY RULES BY DISTRICT (Gathering Storm)
+# ============================================================================
+
+CAMPUS_RULES = [
+    # +2 each
+    AdjacencyRule(["FEATURE_GEOTHERMAL_FISSURE"], bonus_per=2, count_required=1),
+    AdjacencyRule(["FEATURE_REEF"], bonus_per=2, count_required=1),
+    AdjacencyRule(["GREAT_BARRIER_REEF"], bonus_per=2, count_required=1),  # Natural wonder
+    # +1 each
+    AdjacencyRule(["MOUNTAIN"], bonus_per=1, count_required=1),
+    AdjacencyRule(["GOVERNMENT_PLAZA"], bonus_per=1, count_required=1),
+    # +1 per 2 - SEPARATE counting for each type!
+    AdjacencyRule(["FEATURE_JUNGLE"], bonus_per=1, count_required=2),  # Rainforest
+    AdjacencyRule(["DISTRICT"], bonus_per=1, count_required=2),  # Generic district
+]
+
+HOLY_SITE_RULES = [
+    # +2 each natural wonder
+    AdjacencyRule(["NATURAL_WONDER"], bonus_per=2, count_required=1),
+    # +1 each mountain
+    AdjacencyRule(["MOUNTAIN"], bonus_per=1, count_required=1),
+    AdjacencyRule(["GOVERNMENT_PLAZA"], bonus_per=1, count_required=1),
+    # +1 per 2 - SEPARATE counting!
+    AdjacencyRule(["FEATURE_FOREST"], bonus_per=1, count_required=2),  # Woods
+    AdjacencyRule(["DISTRICT"], bonus_per=1, count_required=2),
+]
+
+THEATER_SQUARE_RULES = [
+    # +2 each built wonder
+    AdjacencyRule(["WONDER"], bonus_per=2, count_required=1),
+    # +2 each Entertainment Complex or Water Park
+    AdjacencyRule(["ENTERTAINMENT_COMPLEX", "WATER_PARK"], bonus_per=2, count_required=1),
+    # +1 each Government Plaza
+    AdjacencyRule(["GOVERNMENT_PLAZA"], bonus_per=1, count_required=1),
+    # +1 per 2 districts
+    AdjacencyRule(["DISTRICT"], bonus_per=1, count_required=2),
+]
+
+COMMERCIAL_HUB_RULES = [
+    # +2 each adjacent Harbor
+    AdjacencyRule(["HARBOR"], bonus_per=2, count_required=1),
+    # +2 if ON river (special - not per adjacent, handled separately)
+    # +1 each Government Plaza
+    AdjacencyRule(["GOVERNMENT_PLAZA"], bonus_per=1, count_required=1),
+    # +1 per 2 districts
+    AdjacencyRule(["DISTRICT"], bonus_per=1, count_required=2),
+]
+
+HARBOR_RULES = [
+    # +2 adjacent City Center
+    AdjacencyRule(["CITY_CENTER"], bonus_per=2, count_required=1),
+    # +1 each coastal resource
+    AdjacencyRule(["COASTAL_RESOURCE"], bonus_per=1, count_required=1),
+    AdjacencyRule(["GOVERNMENT_PLAZA"], bonus_per=1, count_required=1),
+    # +1 per 2 districts
+    AdjacencyRule(["DISTRICT"], bonus_per=1, count_required=2),
+]
+
+INDUSTRIAL_ZONE_RULES = [
+    # +2 each Aqueduct, Bath, Canal, Dam
+    AdjacencyRule(["AQUEDUCT", "BATH", "DAM", "CANAL"], bonus_per=2, count_required=1),
+    # +1 each Quarry
+    AdjacencyRule(["QUARRY"], bonus_per=1, count_required=1),
+    # +1 each Strategic Resource
+    AdjacencyRule(["STRATEGIC_RESOURCE"], bonus_per=1, count_required=1),
+    AdjacencyRule(["GOVERNMENT_PLAZA"], bonus_per=1, count_required=1),
+    # +1 per 2 - EACH type counted SEPARATELY then floored!
+    AdjacencyRule(["MINE"], bonus_per=1, count_required=2),
+    AdjacencyRule(["LUMBER_MILL"], bonus_per=1, count_required=2),
+    AdjacencyRule(["DISTRICT"], bonus_per=1, count_required=2),
+]
+
+# Master registry
+DISTRICT_ADJACENCY_RULES: Dict[DistrictType, List[AdjacencyRule]] = {
+    DistrictType.CAMPUS: CAMPUS_RULES,
+    DistrictType.HOLY_SITE: HOLY_SITE_RULES,
+    DistrictType.THEATER_SQUARE: THEATER_SQUARE_RULES,
+    DistrictType.COMMERCIAL_HUB: COMMERCIAL_HUB_RULES,
+    DistrictType.HARBOR: HARBOR_RULES,
+    DistrictType.INDUSTRIAL_ZONE: INDUSTRIAL_ZONE_RULES,
+}
+
+# Districts that count for the generic "DISTRICT" adjacency bonus
+# ALL districts count for adjacency, including City Center, Aqueduct, etc.
+# The distinction from NON_SPECIALTY (for population limit) is DIFFERENT
+DISTRICTS_FOR_ADJACENCY: Set[DistrictType] = {
+    # Specialty districts (count towards pop limit)
+    DistrictType.CAMPUS,
+    DistrictType.HOLY_SITE,
+    DistrictType.THEATER_SQUARE,
+    DistrictType.COMMERCIAL_HUB,
+    DistrictType.HARBOR,
+    DistrictType.INDUSTRIAL_ZONE,
+    DistrictType.GOVERNMENT_PLAZA,
+    DistrictType.ENTERTAINMENT_COMPLEX,
+    DistrictType.WATER_PARK,
+    DistrictType.ENCAMPMENT,
+    DistrictType.AERODROME,
+    DistrictType.PRESERVE,
+    DistrictType.DIPLOMATIC_QUARTER,
+    # Non-specialty districts (don't count towards pop limit, but DO count for adjacency!)
+    DistrictType.CITY_CENTER,
+    DistrictType.AQUEDUCT,
+    DistrictType.DAM,
+    DistrictType.CANAL,
+    DistrictType.NEIGHBORHOOD,
+    DistrictType.SPACEPORT,
+}
+
+# Note: Major and minor bonuses are ADDITIVE in Civ6!
+# An Industrial Zone adjacent to an Aqueduct gets BOTH +2 (major) AND
+# the Aqueduct counts toward the +1 per 2 districts (minor).
+
+# Keep old name for backwards compatibility (but it's now ALL districts)
+SPECIALTY_DISTRICTS = DISTRICTS_FOR_ADJACENCY
+
+# Features destroyed when placing a district
+DESTRUCTIBLE_FEATURES: Set[str] = {
+    "FEATURE_FOREST",   # Woods
+    "FEATURE_JUNGLE",   # Rainforest
+    "FEATURE_MARSH",    # Marsh
+}
+
+
+# ============================================================================
+# ADJACENCY CALCULATOR
+# ============================================================================
+
+class AdjacencyCalculator:
+    """Calculates adjacency bonuses for districts."""
+
+    def __init__(
+        self,
+        tiles: Dict[Tuple[int, int], Tile],
+    ):
+        self.tiles = tiles
+
+    def get_tile(self, x: int, y: int) -> Optional[Tile]:
+        return self.tiles.get((x, y))
+
+    def apply_destruction(
+        self,
+        placements: Dict[Tuple[int, int], DistrictType],
+    ) -> Dict[Tuple[int, int], Tile]:
+        """
+        Create modified tile dict with features/resources destroyed by placements.
+
+        When a district is placed on a tile:
+        - Woods, Rainforest, Marsh are destroyed
+        - Bonus resources are destroyed
+
+        EXCEPTION: City Center does NOT destroy features or resources!
+        - Settling on geothermal fissure keeps it for adjacency
+        - Settling on resources keeps them
+
+        Returns:
+            New tiles dict with modifications applied
+        """
+        modified = {}
+
+        for coord, tile in self.tiles.items():
+            if coord in placements:
+                district_type = placements[coord]
+
+                # City Center does NOT destroy features or resources
+                if district_type == DistrictType.CITY_CENTER:
+                    modified[coord] = tile  # Keep tile unchanged
+                else:
+                    # Other districts destroy certain features and bonus resources
+                    modified[coord] = Tile(
+                        x=tile.x,
+                        y=tile.y,
+                        terrain=tile.terrain,
+                        feature=None if tile.feature in DESTRUCTIBLE_FEATURES else tile.feature,
+                        is_hills=tile.is_hills,
+                        is_floodplains=tile.is_floodplains,
+                        river_edges=list(tile.river_edges),
+                        river_names=list(tile.river_names),
+                        resource=None if tile.resource_type == "BONUS" else tile.resource,
+                        resource_type=None if tile.resource_type == "BONUS" else tile.resource_type,
+                        improvement=None,  # District replaces improvement
+                    )
+            else:
+                modified[coord] = tile
+
+        return modified
+
+    def count_rule_sources(
+        self,
+        x: int,
+        y: int,
+        rule: AdjacencyRule,
+        tiles: Dict[Tuple[int, int], Tile],
+        placements: Dict[Tuple[int, int], DistrictType],
+    ) -> Tuple[int, List[str]]:
+        """
+        Count how many sources match a rule for a district at (x, y).
+
+        Returns:
+            (count, list of source descriptions)
+        """
+        count = 0
+        sources: List[str] = []
+
+        for nx, ny in get_neighbors(x, y):
+            ntile = tiles.get((nx, ny))
+            if ntile is None:
+                continue
+
+            for source_type in rule.sources:
+                matched = False
+
+                # Mountain
+                if source_type == "MOUNTAIN" and ntile.is_mountain:
+                    count += 1
+                    sources.append(f"Mountain@({nx},{ny})")
+                    matched = True
+
+                # Natural Wonder
+                elif source_type == "NATURAL_WONDER" and ntile.is_natural_wonder:
+                    count += 1
+                    sources.append(f"NaturalWonder@({nx},{ny})")
+                    matched = True
+
+                # Specific natural wonders
+                elif ntile.feature and source_type in ntile.feature:
+                    count += 1
+                    sources.append(f"{source_type}@({nx},{ny})")
+                    matched = True
+
+                # Features (Woods, Rainforest, Reef, etc.)
+                elif ntile.feature and ntile.feature == source_type:
+                    count += 1
+                    sources.append(f"{source_type}@({nx},{ny})")
+                    matched = True
+
+                # Improvements (Mine, Quarry, Lumber Mill)
+                elif ntile.improvement and ntile.improvement.upper() == source_type:
+                    count += 1
+                    sources.append(f"{source_type}@({nx},{ny})")
+                    matched = True
+
+                # Strategic Resources
+                elif source_type == "STRATEGIC_RESOURCE" and ntile.resource_type == "STRATEGIC":
+                    count += 1
+                    sources.append(f"Strategic({ntile.resource})@({nx},{ny})")
+                    matched = True
+
+                # Coastal Resources (for Harbor)
+                elif source_type == "COASTAL_RESOURCE":
+                    if ntile.is_water and ntile.resource:
+                        count += 1
+                        sources.append(f"CoastalResource({ntile.resource})@({nx},{ny})")
+                        matched = True
+
+                # Adjacent districts
+                elif (nx, ny) in placements:
+                    adj_district = placements[(nx, ny)]
+
+                    # Specific district type match
+                    if source_type == adj_district.name or source_type == adj_district.name.upper():
+                        count += 1
+                        sources.append(f"{adj_district.name}@({nx},{ny})")
+                        matched = True
+
+                    # Entertainment Complex / Water Park
+                    elif source_type == "ENTERTAINMENT_COMPLEX" and adj_district == DistrictType.ENTERTAINMENT_COMPLEX:
+                        count += 1
+                        sources.append(f"EntertainmentComplex@({nx},{ny})")
+                        matched = True
+                    elif source_type == "WATER_PARK" and adj_district == DistrictType.WATER_PARK:
+                        count += 1
+                        sources.append(f"WaterPark@({nx},{ny})")
+                        matched = True
+
+                    # Infrastructure districts
+                    elif source_type == "AQUEDUCT" and adj_district == DistrictType.AQUEDUCT:
+                        count += 1
+                        sources.append(f"Aqueduct@({nx},{ny})")
+                        matched = True
+                    elif source_type == "DAM" and adj_district == DistrictType.DAM:
+                        count += 1
+                        sources.append(f"Dam@({nx},{ny})")
+                        matched = True
+                    elif source_type == "CANAL" and adj_district == DistrictType.CANAL:
+                        count += 1
+                        sources.append(f"Canal@({nx},{ny})")
+                        matched = True
+
+                    # City Center
+                    elif source_type == "CITY_CENTER" and adj_district == DistrictType.CITY_CENTER:
+                        count += 1
+                        sources.append(f"CityCenter@({nx},{ny})")
+                        matched = True
+
+                    # Harbor
+                    elif source_type == "HARBOR" and adj_district == DistrictType.HARBOR:
+                        count += 1
+                        sources.append(f"Harbor@({nx},{ny})")
+                        matched = True
+
+                    # Government Plaza
+                    elif source_type == "GOVERNMENT_PLAZA" and adj_district == DistrictType.GOVERNMENT_PLAZA:
+                        count += 1
+                        sources.append(f"GovernmentPlaza@({nx},{ny})")
+                        matched = True
+
+                    # Generic DISTRICT bonus
+                    # Note: Major and minor bonuses are ADDITIVE - districts that give
+                    # major bonuses (e.g., Aqueduct for IZ) ALSO count for minor bonus
+                    elif source_type == "DISTRICT" and adj_district in SPECIALTY_DISTRICTS:
+                        count += 1
+                        sources.append(f"District({adj_district.name})@({nx},{ny})")
+                        matched = True
+
+                if matched:
+                    break  # Only count each neighbor once per rule
+
+        return count, sources
+
+    def calculate_district_adjacency(
+        self,
+        district_type: DistrictType,
+        x: int,
+        y: int,
+        tiles: Dict[Tuple[int, int], Tile],
+        placements: Dict[Tuple[int, int], DistrictType],
+    ) -> AdjacencyResult:
+        """
+        Calculate adjacency bonus for a single district.
+
+        Args:
+            district_type: Type of district
+            x, y: District position
+            tiles: Tile dict (should have destruction already applied)
+            placements: All placements including city center
+
+        Returns:
+            AdjacencyResult with total bonus and breakdown
+        """
+        rules = self.get_rules_for_district(district_type)
+        if not rules:
+            return AdjacencyResult(total_bonus=0)
+
+        tile = tiles.get((x, y))
+        if tile is None:
+            return AdjacencyResult(total_bonus=0)
+
+        total = 0
+        breakdown: Dict[str, Dict[str, Any]] = {}
+
+        # Special: Commercial Hub river bonus (+2 if ON river)
+        if district_type == DistrictType.COMMERCIAL_HUB and tile.has_river:
+            total += 2
+            breakdown["RIVER"] = {"count": 1, "bonus": 2, "sources": ["OnRiver"]}
+
+        # Process each rule
+        for rule in rules:
+            count, sources = self.count_rule_sources(x, y, rule, tiles, placements)
+
+            if count == 0:
+                continue
+
+            # Calculate bonus based on count_required
+            if rule.count_required == 1:
+                bonus = count * rule.bonus_per
+            else:
+                # +N per count_required (FLOORED!)
+                bonus = (count // rule.count_required) * rule.bonus_per
+
+            if bonus > 0:
+                rule_key = "+".join(rule.sources)
+                breakdown[rule_key] = {
+                    "count": count,
+                    "bonus": bonus,
+                    "count_required": rule.count_required,
+                    "bonus_per": rule.bonus_per,
+                    "sources": sources,
+                }
+                total += bonus
+
+        return AdjacencyResult(total_bonus=total, breakdown=breakdown)
+
+    def get_rules_for_district(self, district_type: DistrictType) -> List[AdjacencyRule]:
+        """Get adjacency rules for a district type."""
+        return DISTRICT_ADJACENCY_RULES.get(district_type, [])
+
+    def calculate_total_adjacency(
+        self,
+        placements: Dict[Tuple[int, int], DistrictType],
+    ) -> Tuple[int, Dict[str, AdjacencyResult]]:
+        """
+        Calculate total adjacency for all placed districts.
+
+        Applies destruction first, then calculates adjacency.
+
+        Returns:
+            (total_adjacency, per_district_results)
+        """
+        # Apply destruction from placements
+        modified_tiles = self.apply_destruction(placements)
+
+        total = 0
+        per_district: Dict[str, AdjacencyResult] = {}
+
+        for (x, y), district_type in placements.items():
+            if district_type == DistrictType.CITY_CENTER:
+                continue
+
+            result = self.calculate_district_adjacency(
+                district_type, x, y, modified_tiles, placements
+            )
+            total += result.total_bonus
+            per_district[f"{district_type.name}@({x},{y})"] = result
+
+        return total, per_district
+
+
+def get_adjacency_calculator(
+    tiles: Dict[Tuple[int, int], Tile],
+) -> AdjacencyCalculator:
+    """Factory function to get adjacency calculator."""
+    return AdjacencyCalculator(tiles)

.codex/skills/polytopia-strategy-design/references/external/skillsbench-civ6lib/scripts/hex_utils.py

@@ -0,0 +1,167 @@
+"""Hex grid utilities for Civ6 offset coordinate system.
+
+Civ6 uses an "odd-r" (odd-row) horizontal offset coordinate system.
+Odd rows are shifted right by half a hex.
+
+This module provides pure functions for hex math operations.
+All functions are stateless and easily unit testable.
+"""
+
+from typing import List, Tuple, Optional
+
+# Direction offsets for hex neighbors
+# Civ6 uses "odd-r" offset coordinates (odd ROWS shifted right)
+# Index corresponds to edge direction: 0=E, 1=NE, 2=NW, 3=W, 4=SW, 5=SE
+
+# For EVEN rows (y % 2 == 0)
+DIRECTIONS_EVEN_ROW = [
+    (1, 0),    # 0: East
+    (0, -1),   # 1: Northeast
+    (-1, -1),  # 2: Northwest
+    (-1, 0),   # 3: West
+    (-1, 1),   # 4: Southwest
+    (0, 1),    # 5: Southeast
+]
+
+# For ODD rows (y % 2 == 1)
+DIRECTIONS_ODD_ROW = [
+    (1, 0),    # 0: East
+    (1, -1),   # 1: Northeast (shifted right for odd rows)
+    (0, -1),   # 2: Northwest
+    (-1, 0),   # 3: West
+    (0, 1),    # 4: Southwest
+    (1, 1),    # 5: Southeast (shifted right for odd rows)
+]
+
+
+def get_neighbors(x: int, y: int) -> List[Tuple[int, int]]:
+    """Get all 6 neighboring hex coordinates.
+
+    Args:
+        x: Column
+        y: Row
+
+    Returns:
+        List of (x, y) tuples for all 6 neighbors
+
+    Example:
+        >>> get_neighbors(21, 14)  # y=14 is even row
+        [(22, 14), (21, 13), (20, 13), (20, 14), (20, 15), (21, 15)]
+    """
+    directions = DIRECTIONS_ODD_ROW if y % 2 == 1 else DIRECTIONS_EVEN_ROW
+    return [(x + dx, y + dy) for dx, dy in directions]
+
+
+def get_neighbor_at_direction(x: int, y: int, direction: int) -> Tuple[int, int]:
+    """Get neighbor coordinate in a specific direction.
+
+    Args:
+        x, y: Current position
+        direction: Edge direction (0-5)
+
+    Returns:
+        (x, y) of neighbor in that direction
+    """
+    directions = DIRECTIONS_ODD_ROW if y % 2 == 1 else DIRECTIONS_EVEN_ROW
+    dx, dy = directions[direction]
+    return (x + dx, y + dy)
+
+
+def get_direction_to_neighbor(x1: int, y1: int, x2: int, y2: int) -> Optional[int]:
+    """Get the direction from (x1,y1) to adjacent tile (x2,y2).
+
+    Args:
+        x1, y1: Source position
+        x2, y2: Target position (must be adjacent)
+
+    Returns:
+        Direction index (0-5) or None if not adjacent
+
+    Example:
+        >>> get_direction_to_neighbor(5, 5, 6, 5)
+        0  # East
+    """
+    neighbors = get_neighbors(x1, y1)
+    try:
+        return neighbors.index((x2, y2))
+    except ValueError:
+        return None
+
+
+def hex_distance(x1: int, y1: int, x2: int, y2: int) -> int:
+    """Calculate hex distance between two positions.
+
+    Uses cube coordinate conversion for accurate distance.
+    Civ6 uses "odd-r" offset coordinates (odd rows shifted right).
+
+    Args:
+        x1, y1: First position
+        x2, y2: Second position
+
+    Returns:
+        Integer distance in hex tiles
+
+    Example:
+        >>> hex_distance(0, 0, 3, 0)
+        3
+        >>> hex_distance(0, 0, 1, 1)
+        1
+    """
+    # Convert offset (odd-r) to cube coordinates
+    def offset_to_cube(col: int, row: int) -> Tuple[int, int, int]:
+        cx = col - (row - (row & 1)) // 2
+        cz = row
+        cy = -cx - cz
+        return cx, cy, cz
+
+    cx1, cy1, cz1 = offset_to_cube(x1, y1)
+    cx2, cy2, cz2 = offset_to_cube(x2, y2)
+
+    return (abs(cx1 - cx2) + abs(cy1 - cy2) + abs(cz1 - cz2)) // 2
+
+
+def is_adjacent(x1: int, y1: int, x2: int, y2: int) -> bool:
+    """Check if two hexes are adjacent.
+
+    Example:
+        >>> is_adjacent(5, 5, 6, 5)
+        True
+        >>> is_adjacent(0, 0, 2, 0)
+        False
+    """
+    return hex_distance(x1, y1, x2, y2) == 1
+
+
+def get_tiles_in_range(x: int, y: int, radius: int) -> List[Tuple[int, int]]:
+    """Get all tiles within a given range of a center tile.
+
+    Args:
+        x, y: Center position
+        radius: Maximum distance (inclusive)
+
+    Returns:
+        List of (x, y) positions within range (excluding center)
+
+    Example:
+        >>> len(get_tiles_in_range(5, 5, 1))
+        6  # Just the immediate neighbors
+        >>> len(get_tiles_in_range(5, 5, 2))
+        18  # Two rings
+    """
+    tiles = []
+    for dx in range(-radius, radius + 1):
+        for dy in range(-radius, radius + 1):
+            nx, ny = x + dx, y + dy
+            if (nx, ny) != (x, y) and hex_distance(x, y, nx, ny) <= radius:
+                tiles.append((nx, ny))
+    return tiles
+
+
+def get_opposite_direction(direction: int) -> int:
+    """Get the opposite direction (180 degrees).
+
+    Example:
+        >>> get_opposite_direction(0)  # East
+        3  # West
+    """
+    return (direction + 3) % 6

.codex/skills/polytopia-strategy-design/references/external/skillsbench-civ6lib/scripts/placement_rules.py

@@ -0,0 +1,716 @@
+"""District placement rules for Civ6 (Gathering Storm).
+
+This module defines which tiles are valid for each district type.
+Designed to be extensible for civilization-specific unique districts.
+
+Reference: https://civilization.fandom.com/wiki/District_(Civ6)
+
+PLACEMENT RULES SUMMARY:
+========================
+All Districts:
+- Must be within 3 tiles of City Center
+- Cannot be on: Mountains, Natural Wonders, Strategic/Luxury resources
+- Cannot be on tiles with existing districts/wonders
+- CAN be on: Bonus resources (destroys them), Woods/Rainforest/Marsh (destroys them)
+
+Specific District Rules:
+- Harbor, Water Park: Must be on Coast/Lake adjacent to land
+- Aerodrome, Spaceport: Must be on FLAT land (no hills)
+- Encampment, Preserve: Cannot be adjacent to City Center
+- Aqueduct: Must be adjacent to City Center AND fresh water source
+- Dam: Must be on Floodplains, river must traverse 2+ edges
+- Canal: Must connect water bodies or City Center to water
+"""
+
+from dataclasses import dataclass
+from enum import IntEnum, auto
+from typing import Dict, List, Optional, Set, Tuple, Callable, Any
+
+from hex_utils import hex_distance, get_neighbors, get_direction_to_neighbor, is_adjacent
+
+
+class DistrictType(IntEnum):
+    """All district types in Civ6."""
+    NONE = 0
+    CITY_CENTER = auto()
+    # Specialty districts (count towards population limit)
+    CAMPUS = auto()
+    HOLY_SITE = auto()
+    THEATER_SQUARE = auto()
+    COMMERCIAL_HUB = auto()
+    HARBOR = auto()
+    INDUSTRIAL_ZONE = auto()
+    ENTERTAINMENT_COMPLEX = auto()
+    WATER_PARK = auto()
+    ENCAMPMENT = auto()
+    AERODROME = auto()
+    GOVERNMENT_PLAZA = auto()
+    DIPLOMATIC_QUARTER = auto()
+    PRESERVE = auto()
+    # Non-specialty districts (no population limit)
+    AQUEDUCT = auto()
+    DAM = auto()
+    CANAL = auto()
+    SPACEPORT = auto()
+    NEIGHBORHOOD = auto()
+
+
+# Map string names to enum
+DISTRICT_NAME_MAP: Dict[str, DistrictType] = {
+    d.name: d for d in DistrictType if d != DistrictType.NONE
+}
+
+
+@dataclass
+class Tile:
+    """Represents a single map tile with all relevant properties."""
+    x: int
+    y: int
+    terrain: str  # GRASS, PLAINS, DESERT, TUNDRA, SNOW, COAST, OCEAN, MOUNTAIN
+    feature: Optional[str] = None  # FEATURE_FOREST, FEATURE_JUNGLE, etc.
+    is_hills: bool = False
+    is_floodplains: bool = False
+    river_edges: List[int] = None  # Which edges (0-5) have rivers
+    river_names: List[str] = None
+    resource: Optional[str] = None
+    resource_type: Optional[str] = None  # STRATEGIC, LUXURY, BONUS
+    improvement: Optional[str] = None  # MINE, QUARRY, LUMBER_MILL, etc.
+
+    def __post_init__(self):
+        if self.river_edges is None:
+            self.river_edges = []
+        if self.river_names is None:
+            self.river_names = []
+
+    @property
+    def is_water(self) -> bool:
+        return self.terrain in ("COAST", "OCEAN", "LAKE")
+
+    @property
+    def is_coast(self) -> bool:
+        return self.terrain == "COAST"
+
+    @property
+    def is_lake(self) -> bool:
+        return self.terrain == "LAKE"
+
+    @property
+    def is_mountain(self) -> bool:
+        return self.terrain == "MOUNTAIN"
+
+    @property
+    def is_natural_wonder(self) -> bool:
+        return self.feature is not None and "NATURAL_WONDER" in self.feature
+
+    @property
+    def has_river(self) -> bool:
+        return len(self.river_edges) > 0
+
+    @property
+    def is_flat_land(self) -> bool:
+        """Flat land = not water, not mountain, not hills."""
+        return not self.is_water and not self.is_mountain and not self.is_hills
+
+
+# =============================================================================
+# CITY DISTANCE RULES
+# =============================================================================
+
+# Minimum distance between city centers (same landmass)
+MIN_CITY_DISTANCE_SAME_LANDMASS = 4  # 4 tiles center-to-center (3 tiles between)
+
+# Minimum distance between city centers (different landmasses)
+MIN_CITY_DISTANCE_DIFFERENT_LANDMASS = 3  # 3 tiles center-to-center (2 tiles between)
+
+
+def validate_city_distances(
+    city_centers: List[Tuple[int, int]],
+    tiles: Dict[Tuple[int, int], Tile],
+) -> Tuple[bool, List[str]]:
+    """
+    Validate that all cities respect minimum distance requirements.
+
+    Args:
+        city_centers: List of (x, y) coordinates for each city center
+        tiles: Dictionary of all map tiles
+
+    Returns:
+        (valid, errors) tuple
+    """
+    errors = []
+
+    for i, city_a in enumerate(city_centers):
+        for j, city_b in enumerate(city_centers):
+            if j <= i:
+                continue  # Only check each pair once
+
+            distance = hex_distance(city_a[0], city_a[1], city_b[0], city_b[1])
+
+            # Determine if cities are on same or different landmasses
+            # Simple heuristic: check if there's water between them
+            same_landmass = _are_cities_on_same_landmass(city_a, city_b, tiles)
+
+            min_distance = (
+                MIN_CITY_DISTANCE_SAME_LANDMASS if same_landmass
+                else MIN_CITY_DISTANCE_DIFFERENT_LANDMASS
+            )
+
+            if distance < min_distance:
+                errors.append(
+                    f"Cities at {city_a} and {city_b} are too close: "
+                    f"distance={distance}, minimum={min_distance} "
+                    f"({'same' if same_landmass else 'different'} landmass)"
+                )
+
+    return len(errors) == 0, errors
+
+
+def _are_cities_on_same_landmass(
+    city_a: Tuple[int, int],
+    city_b: Tuple[int, int],
+    tiles: Dict[Tuple[int, int], Tile],
+) -> bool:
+    """
+    Determine if two cities are on the same landmass.
+
+    Uses simple heuristic: BFS from city_a to city_b through land tiles only.
+    If we can reach city_b, they're on the same landmass.
+
+    Note: This is a simplified check. The actual game uses area IDs.
+    For most scenarios, checking if both cities are on land suffices.
+    """
+    # Get tiles at city locations
+    tile_a = tiles.get(city_a)
+    tile_b = tiles.get(city_b)
+
+    # If either tile is water, they're on different "landmasses"
+    if tile_a is None or tile_b is None:
+        return True  # Assume same landmass if tiles not defined
+
+    if tile_a.is_water or tile_b.is_water:
+        return False
+
+    # Simple BFS to check land connectivity
+    visited = set()
+    queue = [city_a]
+
+    while queue:
+        current = queue.pop(0)
+        if current == city_b:
+            return True
+
+        if current in visited:
+            continue
+        visited.add(current)
+
+        # Check all neighbors
+        for nx, ny in get_neighbors(current[0], current[1]):
+            if (nx, ny) in visited:
+                continue
+
+            neighbor_tile = tiles.get((nx, ny))
+            if neighbor_tile is None:
+                continue
+
+            # Only traverse through land tiles
+            if not neighbor_tile.is_water:
+                queue.append((nx, ny))
+
+    return False
+
+
+# =============================================================================
+# DISTRICT LIMIT AND UNIQUENESS VALIDATION
+# =============================================================================
+
+def calculate_max_specialty_districts(population: int) -> int:
+    """
+    Calculate max specialty districts for a city.
+
+    Formula: 1 + floor((population - 1) / 3)
+
+    Args:
+        population: City population
+
+    Returns:
+        Maximum number of specialty districts allowed
+    """
+    return 1 + (population - 1) // 3
+
+
+def validate_district_count(
+    placements: Dict[str, Tuple[int, int]],
+    population: int,
+) -> Tuple[bool, List[str]]:
+    """
+    Validate that the number of specialty districts doesn't exceed the limit.
+
+    Args:
+        placements: Dict of district_name -> (x, y) coordinates
+        population: City population
+
+    Returns:
+        (valid, errors) tuple
+    """
+    errors = []
+
+    # Count specialty districts
+    specialty_count = 0
+    for district_name in placements:
+        if district_name not in DISTRICT_NAME_MAP:
+            continue
+        district_type = DISTRICT_NAME_MAP[district_name]
+        if district_type not in PlacementRules.NON_SPECIALTY_DISTRICTS:
+            specialty_count += 1
+
+    max_allowed = calculate_max_specialty_districts(population)
+
+    if specialty_count > max_allowed:
+        errors.append(
+            f"Too many specialty districts: {specialty_count} placed, "
+            f"but population {population} only allows {max_allowed} "
+            f"(formula: 1 + floor(({population}-1)/3))"
+        )
+
+    return len(errors) == 0, errors
+
+
+def validate_district_uniqueness(
+    placements: Dict[str, Tuple[int, int]],
+    city_id: str = "city",
+    all_placements: Optional[Dict[str, Dict[str, Tuple[int, int]]]] = None,
+) -> Tuple[bool, List[str]]:
+    """
+    Validate that districts aren't duplicated incorrectly.
+
+    Rules:
+    - Most specialty districts: ONE per city
+    - Neighborhood: Multiple per city allowed
+    - Government Plaza: ONE per civilization
+
+    Args:
+        placements: Dict of district_name -> (x, y) for this city
+        city_id: Identifier for this city (for error messages)
+        all_placements: For multi-city scenarios, dict of city_id -> placements
+                       Used to check one-per-civilization districts
+
+    Returns:
+        (valid, errors) tuple
+    """
+    errors = []
+
+    # Count districts by type for this city
+    district_counts: Dict[str, int] = {}
+    for district_name in placements:
+        district_counts[district_name] = district_counts.get(district_name, 0) + 1
+
+    # Check for duplicates within this city
+    for district_name, count in district_counts.items():
+        if district_name not in DISTRICT_NAME_MAP:
+            continue
+
+        district_type = DISTRICT_NAME_MAP[district_name]
+
+        # Skip districts that allow multiples
+        if district_type in PlacementRules.ALLOW_MULTIPLE_PER_CITY:
+            continue
+
+        if count > 1:
+            errors.append(
+                f"Duplicate district in {city_id}: {district_name} placed {count} times "
+                f"(only 1 allowed per city)"
+            )
+
+    # Check one-per-civilization districts across all cities
+    if all_placements is not None:
+        for district_type in PlacementRules.ONE_PER_CIVILIZATION:
+            district_name = district_type.name
+            civ_count = 0
+            cities_with_district = []
+
+            for cid, city_placements in all_placements.items():
+                if district_name in city_placements:
+                    civ_count += 1
+                    cities_with_district.append(cid)
+
+            if civ_count > 1:
+                errors.append(
+                    f"{district_name} can only be built once per civilization, "
+                    f"but found in {civ_count} cities: {cities_with_district}"
+                )
+
+    return len(errors) == 0, errors
+
+
+@dataclass
+class PlacementResult:
+    """Result of a placement validation check."""
+    valid: bool
+    errors: List[str] = None
+    warnings: List[str] = None
+
+    def __post_init__(self):
+        if self.errors is None:
+            self.errors = []
+        if self.warnings is None:
+            self.warnings = []
+
+
+class PlacementRules:
+    """
+    District placement rules engine.
+
+    Designed to be subclassed for civilization-specific rules.
+    Override methods like `_validate_unique_district()` for civ uniques.
+    """
+
+    # Districts that must be on water
+    WATER_DISTRICTS: Set[DistrictType] = {
+        DistrictType.HARBOR,
+        DistrictType.WATER_PARK,
+    }
+
+    # Districts that require flat land (no hills)
+    FLAT_LAND_DISTRICTS: Set[DistrictType] = {
+        DistrictType.AERODROME,
+        DistrictType.SPACEPORT,
+    }
+
+    # Districts that cannot be adjacent to City Center
+    NO_CITY_CENTER_ADJACENT: Set[DistrictType] = {
+        DistrictType.ENCAMPMENT,
+        DistrictType.PRESERVE,
+    }
+
+    # Districts that don't count towards population limit
+    NON_SPECIALTY_DISTRICTS: Set[DistrictType] = {
+        DistrictType.AQUEDUCT,
+        DistrictType.DAM,
+        DistrictType.CANAL,
+        DistrictType.SPACEPORT,
+        DistrictType.NEIGHBORHOOD,
+        DistrictType.CITY_CENTER,
+    }
+
+    # Districts that can be built multiple times per city
+    # Most specialty districts are limited to ONE per city
+    ALLOW_MULTIPLE_PER_CITY: Set[DistrictType] = {
+        DistrictType.NEIGHBORHOOD,  # Can build multiple
+        # Non-specialty districts can also have multiple
+        DistrictType.AQUEDUCT,
+        DistrictType.DAM,
+        DistrictType.CANAL,
+        DistrictType.SPACEPORT,
+    }
+
+    # Districts limited to ONE per civilization (not per city)
+    ONE_PER_CIVILIZATION: Set[DistrictType] = {
+        DistrictType.GOVERNMENT_PLAZA,
+        DistrictType.DIPLOMATIC_QUARTER,
+    }
+
+    # Features that are destroyed when placing a district
+    DESTRUCTIBLE_FEATURES: Set[str] = {
+        "FEATURE_FOREST",   # Woods
+        "FEATURE_JUNGLE",   # Rainforest
+        "FEATURE_MARSH",    # Marsh
+    }
+
+    def __init__(
+        self,
+        tiles: Dict[Tuple[int, int], Tile],
+        city_center: Tuple[int, int],
+        population: int,
+    ):
+        self.tiles = tiles
+        self.city_center = city_center
+        self.population = population
+
+    def get_tile(self, x: int, y: int) -> Optional[Tile]:
+        return self.tiles.get((x, y))
+
+    def max_specialty_districts(self) -> int:
+        """Calculate max specialty districts based on population.
+
+        Formula: 1 + floor((population - 1) / 3)
+
+            Pop 1: 1 district
+            Pop 4: 2 districts
+            Pop 7: 3 districts
+            Pop 10: 4 districts
+            etc.
+        """
+        return 1 + (self.population - 1) // 3
+
+    def validate_placement(
+        self,
+        district_type: DistrictType,
+        x: int,
+        y: int,
+        existing_placements: Dict[Tuple[int, int], DistrictType],
+    ) -> PlacementResult:
+        """
+        Validate if a district can be placed at (x, y).
+
+        Args:
+            district_type: Type of district to place
+            x, y: Target coordinates
+            existing_placements: Already placed districts {(x,y): type}
+
+        Returns:
+            PlacementResult with valid=True/False and error messages
+        """
+        errors: List[str] = []
+        warnings: List[str] = []
+
+        tile = self.get_tile(x, y)
+
+        # Basic checks
+        if tile is None:
+            errors.append(f"No tile data at ({x}, {y})")
+            return PlacementResult(valid=False, errors=errors)
+
+        # Distance from City Center (must be within 3 tiles)
+        distance = hex_distance(x, y, self.city_center[0], self.city_center[1])
+        if distance > 3:
+            errors.append(f"Too far from City Center (distance {distance} > 3)")
+
+        # Cannot place on mountains
+        if tile.is_mountain:
+            errors.append("Cannot place district on Mountain")
+
+        # Cannot place on natural wonders
+        if tile.is_natural_wonder:
+            errors.append("Cannot place district on Natural Wonder")
+
+        # Cannot place on geothermal fissures (except City Center which is pre-placed)
+        # Note: City Center CAN be settled on geothermal, and it's NOT destroyed
+        if tile.feature == "FEATURE_GEOTHERMAL_FISSURE":
+            errors.append("Cannot place district on Geothermal Fissure")
+
+        # Cannot place on existing district
+        if (x, y) in existing_placements:
+            existing = existing_placements[(x, y)]
+            errors.append(f"Tile already has district: {existing.name}")
+
+        # Cannot place on strategic/luxury resources
+        if tile.resource_type in ("STRATEGIC", "LUXURY"):
+            errors.append(f"Cannot place on {tile.resource_type.lower()} resource: {tile.resource}")
+
+        # Water district rules
+        if district_type in self.WATER_DISTRICTS:
+            if not (tile.is_coast or tile.is_lake):
+                errors.append(f"{district_type.name} must be on Coast or Lake")
+            # Check adjacent to land
+            has_land_neighbor = False
+            for nx, ny in get_neighbors(x, y):
+                ntile = self.get_tile(nx, ny)
+                if ntile and not ntile.is_water:
+                    has_land_neighbor = True
+                    break
+            if not has_land_neighbor:
+                errors.append(f"{district_type.name} must be adjacent to land")
+        else:
+            # Land districts cannot be on water
+            if tile.is_water:
+                errors.append(f"{district_type.name} cannot be placed on water")
+
+        # Flat land requirement
+        if district_type in self.FLAT_LAND_DISTRICTS:
+            if not tile.is_flat_land:
+                errors.append(f"{district_type.name} requires flat land (no hills, water, or mountains)")
+
+        # Cannot be adjacent to City Center
+        if district_type in self.NO_CITY_CENTER_ADJACENT:
+            if hex_distance(x, y, self.city_center[0], self.city_center[1]) == 1:
+                errors.append(f"{district_type.name} cannot be adjacent to City Center")
+
+        # Aqueduct special rules
+        if district_type == DistrictType.AQUEDUCT:
+            aqueduct_errors = self._validate_aqueduct(x, y, existing_placements)
+            errors.extend(aqueduct_errors)
+
+        # Dam special rules
+        if district_type == DistrictType.DAM:
+            dam_errors = self._validate_dam(x, y, existing_placements)
+            errors.extend(dam_errors)
+
+        # Canal special rules
+        if district_type == DistrictType.CANAL:
+            canal_errors = self._validate_canal(x, y, existing_placements)
+            errors.extend(canal_errors)
+
+        # Warnings for feature/resource destruction
+        if tile.feature in self.DESTRUCTIBLE_FEATURES:
+            warnings.append(f"Placing here will destroy {tile.feature}")
+        if tile.resource_type == "BONUS":
+            warnings.append(f"Placing here will destroy bonus resource: {tile.resource}")
+
+        # Allow civilization-specific validation (for subclasses)
+        civ_result = self._validate_civilization_specific(district_type, x, y, tile, existing_placements)
+        errors.extend(civ_result.errors)
+        warnings.extend(civ_result.warnings)
+
+        return PlacementResult(
+            valid=len(errors) == 0,
+            errors=errors,
+            warnings=warnings,
+        )
+
+    def _validate_aqueduct(
+        self,
+        x: int,
+        y: int,
+        existing_placements: Dict[Tuple[int, int], DistrictType],
+    ) -> List[str]:
+        """Validate Aqueduct placement rules."""
+        errors = []
+        tile = self.get_tile(x, y)
+
+        # Must be adjacent to City Center
+        if hex_distance(x, y, self.city_center[0], self.city_center[1]) != 1:
+            errors.append("Aqueduct must be adjacent to City Center")
+            return errors  # Can't check other rules without adjacency
+
+        # Must be adjacent to fresh water source
+        fresh_water_sources = []
+        for nx, ny in get_neighbors(x, y):
+            ntile = self.get_tile(nx, ny)
+            if ntile is None:
+                continue
+
+            # Fresh water sources: Mountain, Lake, Oasis
+            if ntile.is_mountain:
+                fresh_water_sources.append(("Mountain", nx, ny))
+            elif ntile.is_lake:
+                fresh_water_sources.append(("Lake", nx, ny))
+            elif ntile.feature == "FEATURE_OASIS":
+                fresh_water_sources.append(("Oasis", nx, ny))
+            # Adjacent river tile also provides fresh water
+            elif ntile.has_river:
+                fresh_water_sources.append(("River", nx, ny))
+
+        # River on the Aqueduct tile itself also counts
+        if tile.has_river:
+            fresh_water_sources.append(("River", x, y))
+
+        if not fresh_water_sources:
+            errors.append("Aqueduct requires adjacent fresh water (Mountain, River, Lake, or Oasis)")
+
+        # "No U-Turn" rule: fresh water cannot only be on the City Center edge
+        if fresh_water_sources:
+            cc_direction = get_direction_to_neighbor(x, y, self.city_center[0], self.city_center[1])
+            cc_neighbor = (self.city_center[0], self.city_center[1])
+
+            # Check if ALL fresh water is only from the CC direction
+            non_cc_sources = [
+                s for s in fresh_water_sources
+                if (s[1], s[2]) != cc_neighbor and not (s[0] == "River" and cc_direction in tile.river_edges)
+            ]
+
+            if not non_cc_sources and fresh_water_sources:
+                # Only source is toward CC - check if river is only on CC edge
+                if len(fresh_water_sources) == 1 and fresh_water_sources[0][0] == "River":
+                    if set(tile.river_edges) == {cc_direction}:
+                        errors.append("Aqueduct 'No U-Turn' rule: Fresh water cannot only be on City Center edge")
+
+        return errors
+
+    def _validate_dam(
+        self,
+        x: int,
+        y: int,
+        existing_placements: Dict[Tuple[int, int], DistrictType],
+    ) -> List[str]:
+        """Validate Dam placement rules."""
+        errors = []
+        tile = self.get_tile(x, y)
+
+        # Must be on Floodplains
+        if not tile.is_floodplains:
+            errors.append("Dam must be on Floodplains")
+            return errors
+
+        # River must traverse at least 2 edges of this hex
+        if len(tile.river_edges) < 2:
+            errors.append("Dam requires river to traverse at least 2 hex edges")
+
+        return errors
+
+    def _validate_canal(
+        self,
+        x: int,
+        y: int,
+        existing_placements: Dict[Tuple[int, int], DistrictType],
+    ) -> List[str]:
+        """Validate Canal placement rules.
+
+        Official rule: The Canal must be built on flat land with a Coast or Lake
+        tile on one side, and either a City Center or another body of water on
+        the other side.
+
+        This means Canal must:
+        1. Be adjacent to at least one water body (Coast/Ocean/Lake)
+        2. AND be adjacent to City Center OR another water body
+        """
+        errors = []
+
+        # Find adjacent City Center and water tiles
+        adjacent_city_center = False
+        adjacent_water_tiles = []
+
+        for nx, ny in get_neighbors(x, y):
+            # Check if adjacent to City Center
+            if (nx, ny) == self.city_center or existing_placements.get((nx, ny)) == DistrictType.CITY_CENTER:
+                adjacent_city_center = True
+
+            # Check for water tiles (Coast, Ocean, or Lake)
+            ntile = self.get_tile(nx, ny)
+            if ntile is not None and (ntile.is_water or ntile.is_lake):
+                adjacent_water_tiles.append((nx, ny))
+
+        # Must be adjacent to at least one water body
+        if not adjacent_water_tiles:
+            errors.append("Canal must be adjacent to at least one water body (Coast/Ocean/Lake)")
+            return errors
+
+        # Valid if: adjacent to City Center AND at least one water body
+        if adjacent_city_center and len(adjacent_water_tiles) >= 1:
+            return errors  # Valid: connects City Center to water
+
+        # Valid if: connects two SEPARATE water bodies (not adjacent to each other)
+        # If water tiles are adjacent, they're the same body - no canal needed
+        if len(adjacent_water_tiles) >= 2:
+            # Check if any pair of water tiles are NOT adjacent (separate bodies)
+            for i, (wx1, wy1) in enumerate(adjacent_water_tiles):
+                for wx2, wy2 in adjacent_water_tiles[i + 1:]:
+                    if not is_adjacent(wx1, wy1, wx2, wy2):
+                        return errors  # Valid: connects separate water bodies
+            # All water tiles are adjacent to each other - same water body
+            errors.append("Canal must connect separate water bodies (adjacent water tiles are the same body)")
+            return errors
+
+        # Invalid: only one water tile and no City Center adjacent
+        errors.append("Canal must connect City Center to water OR connect two separate water bodies")
+
+        return errors
+
+    def _validate_civilization_specific(
+        self,
+        district_type: DistrictType,
+        x: int,
+        y: int,
+        tile: Tile,
+        existing_placements: Dict[Tuple[int, int], DistrictType],
+    ) -> PlacementResult:
+        """Hook for subclasses to add custom validation rules."""
+        return PlacementResult(valid=True)
+
+
+def get_placement_rules(
+    tiles: Dict[Tuple[int, int], Tile],
+    city_center: Tuple[int, int],
+    population: int,
+) -> PlacementRules:
+    """Factory function to get placement rules."""
+    return PlacementRules(tiles, city_center, population)

.codex/skills/polytopia-strategy-design/references/polytopia-design-lessons.md

@@ -0,0 +1,119 @@
+# Polytopia Design Lessons
+
+Use this file when adapting Polytopia ideas into TH1 or another 4X/tactics game.
+
+## Compressed 4X Loop
+
+Polytopia compresses explore, expand, exploit, and exterminate into short repeated turns:
+
+- Explore: fog, explorers, scouts, mountains, water.
+- Expand: village capture and coastal reach.
+- Exploit: city population, SPT, markets, improvements.
+- Exterminate: unit roles, roads, sieges, super units.
+
+Design lesson: a small rule set can feel strategic if every rule touches multiple layers.
+
+TH1 adaptation: prefer mechanics that affect map, economy, unit tempo, and AI evaluation together. Avoid isolated bonuses that only change a number.
+
+## One Currency, Many Temptations
+
+Stars make opportunity cost readable. The player can easily compare tech, units, roads, and city growth because they share a budget.
+
+Design lesson: one primary currency creates clarity, but only works when sinks are meaningfully different in timing and risk.
+
+TH1 adaptation: if multiple resources exist, make each resource's strategic identity clear. Do not let one resource become the hidden universal best converter.
+
+## Tech Cost As Expansion Brake
+
+Tech cost scaling with city count creates a subtle timing puzzle: research before expansion can be efficient, but expansion produces SPT and unit capacity.
+
+Design lesson: expansion needs a brake that creates decisions without making expansion feel bad.
+
+TH1 adaptation: use tech/city/faction scaling to create "when to expand" questions, not "whether expansion is punished" resentment. AI must understand the breakpoint.
+
+## City Upgrades As Mini Drafts
+
+Each city upgrade asks the player to choose economy, vision, border, defense, score, growth, or a super unit. The choice is local but affects global tempo.
+
+Design lesson: city growth feels good because every upgrade is an immediate fork.
+
+TH1 adaptation: city or grid upgrades should produce a visible short-term change. Avoid upgrades that only promise far-future value unless the game has strong planning tools.
+
+## Roads As Tactical Economy
+
+Roads are not just infrastructure. They convert stars into future action reach, reinforcement speed, and threat projection.
+
+Design lesson: movement infrastructure is most interesting when it can be used offensively and defensively, and when bad placement has opportunity cost.
+
+TH1 adaptation: roads, canals, portals, or formation logistics should be evaluated by AI as attack range, defense rotation, and capture timing, not only as movement bonus.
+
+## Zone Of Control Creates Legibility
+
+Zone of control prevents movement systems from becoming too slippery. It lets units hold space even when they do not attack.
+
+Design lesson: board control needs passive rules, not only damage.
+
+TH1 adaptation: if mobile units dominate, add clear passive blocking, terrain friction, supply, or overwatch-like constraints. Make exceptions rare and readable.
+
+## Tribe Starts Create Replayability
+
+Standard tribes share a tech tree but start from different tech/resource/mobility contexts. This keeps rule learning cheap while making openings distinct.
+
+Design lesson: asymmetric starts can be enough; every faction does not need a unique full ruleset.
+
+TH1 adaptation: faction/empire identity can come from starting techs, map biases, early units, and resource access before adding bespoke systems.
+
+## Special Tribes Show Risk Of Exception Design
+
+Special tribes create excitement but also more balance, onboarding, and counterplay risk. Cymanti and Aquarion changes show how rule exceptions can require major rework.
+
+Design lesson: exception-heavy factions need explicit counterplay, UI clarity, and maintenance budget.
+
+TH1 adaptation: when adding a faction with unique mechanics, write its "counterplay contract" first: what common tools can scout it, delay it, punish it, and recover from it?
+
+## Path Of The Ocean As System Rework Pattern
+
+Path of the Ocean did not just buff ships. It changed tech tree access, transports, ship roles, water pickups, buildings, bridges, markets, and map type.
+
+Design lesson: a stale subsystem often needs a full loop rework, not a numeric patch.
+
+TH1 adaptation: if naval, diplomacy, espionage, or terrain feels optional, inspect the full loop:
+
+- access cost,
+- first useful action,
+- midgame payoff,
+- counterplay,
+- map support,
+- AI understanding,
+- UI feedback.
+
+## Balance Pass Pattern
+
+The 2025 balance pass changed starting stars, starting tech, backward tech research, building placement, temple score, burn forest cost, Polytaur cost, embassy scaling, and Polaris skills. It targeted opening viability, tech access, and overperforming movement.
+
+Design lesson: small opening numbers can matter more than late-game stats because they compound.
+
+TH1 adaptation: when a faction is weak, first inspect first-10-turn tempo: starting resources, first unit reach, first upgrade, first tech, first combat target. Late buffs may not fix a lost opening.
+
+## Strategy Skill As Design Tool
+
+To evaluate a TH1 mechanic through a Polytopia lens, ask:
+
+- What is the primary currency or tempo being spent?
+- What is the immediate payoff?
+- What delayed payoff competes with it?
+- What map information changes the decision?
+- What unit movement breakpoint changes?
+- What expansion breakpoint changes?
+- What is the opponent's counterplay?
+- Can the AI recognize the same value?
+
+## Red Flags
+
+- A tech is always bought immediately or never bought.
+- A city upgrade is always correct regardless of map/front.
+- A road/infrastructure rule has no downside or timing risk.
+- A faction exception cannot be countered by standard tools.
+- A super unit wins if obtained, regardless of support.
+- Naval/diplomacy/espionage systems are only useful on one map type or only for one faction.
+- Score-mode incentives contradict conquest-mode incentives without clear mode-specific rules.

.codex/skills/polytopia-strategy-design/references/polytopia-mechanics.md

@@ -0,0 +1,157 @@
+# Polytopia Mechanics
+
+Use this as a compact rule model, not a full stat database. For exact unit numbers, current tribe starts, and patch-sensitive details, verify against the wiki or in-game data.
+
+## Game Identity
+
+The Battle of Polytopia is a compressed 4X turn-based strategy game on a square-tile map. The player controls a tribe, explores fogged terrain, captures villages, researches technologies, upgrades cities, trains units, and wins through domination or score pressure.
+
+The key design compression is that almost every decision is paid from one currency, stars. Stars buy tech, units, resource harvesting, buildings, roads, ports, diplomacy tools, and city improvements. This makes opportunity cost legible.
+
+## Modes
+
+- Domination: eliminate all opposing tribes. Strategy prioritizes military tempo, expansion, and decisive city captures.
+- Perfection: maximize score in a 30-turn limit. Strategy values exploration, economy, monuments, temples, high-level cities, and efficient scoring.
+- Creative/custom/multiplayer variants: identify win condition and turn timer before giving advice.
+
+## Turn Economy
+
+Each turn is a conversion puzzle:
+
+- Unit actions convert position into villages, vision, kills, sieges, or defensive control.
+- Stars convert into future SPT, unit tempo, tech access, or tactical tools.
+- City upgrades convert local population into global economy, territory, units, or super units.
+- Tech purchases unlock new star sinks, so tech without immediate use is often wasted tempo.
+
+## Stars And SPT
+
+Stars are the general currency. Cities and some buildings produce stars per turn (SPT). One-time star sources can come from exploration and map features.
+
+Design implication: because almost everything uses stars, Polytopia creates clear pressure between "invest now" and "act now." A good move usually improves at least one of:
+
+- next-turn SPT,
+- city count,
+- useful tech access,
+- military reach,
+- unit survivability,
+- future upgrade path.
+
+## Cities, Villages, Population
+
+Villages become cities when captured. Cities generate stars, train units, and set unit capacity. Population fills bars toward city upgrades. The population needed for the next city level scales with the city level, so higher-level cities require larger local investment.
+
+City reward choices are the game's main pacing valves. Common categories:
+
+- immediate or recurring economy,
+- exploration/vision,
+- border growth,
+- defensive wall,
+- population growth,
+- park/score,
+- super unit when available.
+
+Strategic reading:
+
+- Early economy rewards are strongest when they accelerate the next 2-3 turns.
+- Explorer is strongest when vision can find villages, ruins, enemies, or route decisions.
+- Border growth is strongest when it captures multiple usable resources or creates a specific adjacency/building plan.
+- Walls are defensive tempo: choose them when a city is contested or must hold a choke.
+- Parks are mostly score/Perfection tools, not default conquest tools.
+
+## Technology
+
+All standard tribes share a technology tree but start with different techs or bonuses. Tech cost rises as the empire gains cities; each extra city increases the cost by a larger amount for higher-tier techs. This makes "research before capturing a village" a recurring optimization question.
+
+Polytopia tech should be evaluated by immediate unlock value:
+
+- Does it upgrade a city this turn?
+- Does it let a unit reach/capture/kill earlier?
+- Does it unlock the tribe's starting terrain/resource advantage?
+- Does it open a needed counter?
+- Does it create a repeatable economy engine?
+
+The September 1, 2025 balance pass added "backwards" tech research, letting a tribe with a deeper starting tech research prerequisite techs in reverse order. This matters for tribes such as Vengir.
+
+## Map And Terrain
+
+Terrain is both economy and tactics:
+
+- resources determine early city upgrade speed,
+- forests/mountains/water gate tech value,
+- roads and bridges create tempo,
+- chokepoints make defenders and ranged units stronger,
+- map type decides whether naval tech is optional, central, or urgent.
+
+Path of the Ocean changed naval play by making water access easier and more strategically central. Fishing and Sailing positions changed, Ports became cheaper, Bridges entered the Roads tech, and naval unit roles were rebuilt.
+
+## Movement
+
+Movement is one of the highest-skill systems:
+
+- roads multiply tempo when built in the right place,
+- zones of control stop movement when entering tiles adjacent to enemies,
+- terrain penalties and special skills alter reach,
+- ranged units need safe firing lanes,
+- fast units convert scouting into village tempo and fork threats.
+
+Roads can be built on many land terrain types, not on mountains or water. Bridges from Roads cross one-tile water gaps. Roads in neutral territory can be used by any player, so road building can help enemies if placed carelessly.
+
+## Units And Combat
+
+Units have attack, defense, health, movement, range, cost, and skills. Standard roles:
+
+- Warrior: baseline early explorer/fighter.
+- Rider: fast expansion and tactical reach.
+- Defender/Shield: hold cities and front lines.
+- Archer: ranged pressure and chip damage.
+- Catapult: long-range siege/control, fragile if exposed.
+- Swordsman-type: durable melee line.
+- Knight: high-mobility finisher and chain-kill threat.
+- Naval line: transport, scouting, ramming, bombardment, and sea control after Path of the Ocean.
+- Super units: city-upgrade payoff and strategic centerpiece, but must be screened.
+
+Combat is not only damage math. The strategic question is usually:
+
+- what tile is occupied after the attack,
+- whether retaliation makes the trade bad,
+- whether the attacker can be finished,
+- whether a kill opens Persist/chain value,
+- whether a city can be sieged or unsieged,
+- whether the unit blocks roads or zones of control.
+
+## Naval System After Path Of The Ocean
+
+Path of the Ocean redesigned water play:
+
+- Raft replaced Boat as the free transport base.
+- Rafts can upgrade in friendly territory into naval roles such as Scout, Rammer, or Bomber.
+- Bombers are Navigation-era long-range splash ships but need setup because they lack Dash.
+- Starfish replaced whale hunting as a more positional star pickup.
+- Markets replaced Custom Houses and reward adjacency to unique production buildings, doubled by a Port.
+- Pangea was added as a map type with central land fighting plus coastal pressure.
+
+Strategic result: naval is less of a late expensive detour and more of an early expansion/front option on water-relevant maps.
+
+## Tribes
+
+Tribes are asymmetrical starts layered on a shared tech tree. Standard tribes mostly differ by starting tech, resource distribution, starting stars, and terrain bias. Special tribes alter core rules and require separate analysis.
+
+Important current patch notes:
+
+- The 2025 balance pass gave several weaker tribes extra starting stars and changed Ai-Mo to start with Philosophy plus a Mind Bender.
+- Cymanti received a major October 2025 rework: Algae became a tile effect, Raychi split into Raychi/Boomchi roles, Living Island entered naval play, poison/creep/fungi/shaman/moth mechanics changed, and growing units inherit damage.
+
+## Design Takeaway
+
+Polytopia works because it makes strategic tradeoffs visible:
+
+- one currency,
+- few unit stats,
+- dense city reward choices,
+- strong map variance,
+- fast expansion snowball,
+- tech timing penalty,
+- high movement leverage,
+- asymmetric but readable tribe starts.
+
+When using this model for another game, preserve the decision pressure rather than the exact numbers.

.codex/skills/polytopia-strategy-design/references/polytopia-strategy-playbook.md

@@ -0,0 +1,167 @@
+# Polytopia Strategy Playbook
+
+This is a practical strategic model. Always adapt to mode, tribe, map type, spawn resources, opponent distance, and current patch.
+
+## Strategic Thesis
+
+Polytopia is mostly won by compounding small tempo advantages:
+
+- reveal villages earlier,
+- capture cities earlier,
+- buy useful tech before city-count cost increases,
+- convert city upgrades into SPT or decisive units,
+- build roads that create captures/kills one turn sooner,
+- avoid tech and unit purchases that do not change the next few turns.
+
+The strongest move is often not the biggest move; it is the move that makes the next turn much stronger.
+
+## First Principles
+
+- Stars are tempo. Do not spend them unless the spend creates immediate city growth, expansion, defense, or a tactical breakthrough.
+- Tech is a tool, not progress. Buy tech when you can use it now or next turn.
+- Vision is economy. Scouts, explorers, mountains, and fast units are valuable because they find villages and choose wars.
+- Villages are snowball points. Capturing a village usually matters more than a low-value skirmish.
+- Roads are delayed movement. A road is worth it when it changes capture timing, attack reach, defense rotation, or trade connection.
+- Unit trades are positional. A "good" kill can still be bad if the attacker dies on a key tile or opens your city.
+- Defense buys time; economy wins if time is used well.
+
+## Opening Plan
+
+### Turns 0-3
+
+Goal: identify the nearest village route and first city upgrade path.
+
+- Move starting unit to maximize revealed tiles, not just toward visible resources.
+- Check capital resources before buying tech.
+- If a tech upgrades the capital immediately, it is often correct.
+- If no immediate upgrade exists, consider saving stars for a unit, tech after exploration, or a village timing play.
+- Avoid training units that cannot reach useful tiles before a cheaper or faster alternative would matter.
+
+### Turns 4-7
+
+Goal: capture villages and set the economy curve.
+
+- Compare "research before capture" vs "capture first." Researching before a new city can save stars because tech cost rises with city count; capturing first can still be correct if the city immediately increases SPT or produces a needed unit.
+- Use city upgrade choices to solve the next bottleneck: SPT if star-starved, Explorer if blind, Border Growth if it unlocks several resources, Wall if contested.
+- Start roads only when they create a concrete one-turn swing.
+
+### Turns 8-12
+
+Goal: convert expansion into military or unstoppable SPT.
+
+- Identify the main front and backfill economy in safe cities.
+- Research counters only when the enemy composition requires them.
+- Do not overbuild slow units if fast units can fork cities.
+- Start planning super-unit timing if a city can reach it without starving the rest of the empire.
+
+## Tech Timing
+
+Ask these questions before every tech:
+
+1. What can I do with it this turn?
+2. How many city upgrades does it enable?
+3. Does it save a unit or capture a city within two turns?
+4. Will capturing a village first make this tech meaningfully more expensive?
+5. Does this tech commit me to a branch I cannot afford to exploit?
+
+Good early tech usually unlocks local resources or movement. Bad early tech is a nice future idea with no immediate spend path.
+
+## City Upgrade Choices
+
+- Workshop/economy: default when the city is safe and the extra SPT accelerates future actions.
+- Explorer: strong when fog hides villages, ruins, enemies, or map shape; weaker when vision is already solved.
+- Resources/population: good when it creates another upgrade soon or supports a super unit.
+- Border Growth: high value when it captures multiple resources, unlocks a port/market/forge/sawmill/windmill plan, or reaches a critical tile.
+- Wall: choose when a city is under credible threat or must hold a choke/front.
+- Park: Perfection/score priority, rarely the conquest default.
+- Super Unit: evaluate not just the unit, but whether you can protect and project it.
+
+## Roads And Movement
+
+Roads are best when they:
+
+- let a unit capture one turn earlier,
+- let riders/knights threaten multiple cities,
+- let defenders rotate into a siege,
+- connect front cities for reinforcement,
+- turn a city into a launch point.
+
+Roads are bad when they:
+
+- spend stars without a timing change,
+- give an enemy the same route,
+- stop at a tile blocked by zone of control,
+- support a front you are not actually fighting on.
+
+Always account for zone of control. A road route that passes adjacent to an enemy may not produce the movement you expect.
+
+## Combat
+
+### Attack Rules Of Thumb
+
+- Kill units that open city captures, protect your siege, or prevent enemy counterplay.
+- Chip high-value units before committing melee attackers.
+- Screen fragile ranged units and bombers.
+- Avoid leaving fast enemy units with chain-kill opportunities.
+- A city siege is only valuable if the opponent cannot cheaply unsiege or kill the sieger.
+
+### Defender Mindset
+
+- Hold cities with durable units, walls, terrain bonuses, or enough counter-damage.
+- Block road access and landing tiles.
+- Force enemy units to end turns in kill zones.
+- When losing a city is inevitable, trade for time, stars, or a stronger recapture.
+
+## Naval Play
+
+On water-heavy maps, naval tempo is often expansion tempo.
+
+- Get on water early when villages, lighthouses, starfish, or enemy coasts demand it.
+- Use Rafts for transport and upgrade into the naval role needed by the front.
+- Scouts find coastlines and targets; Rammers contest ships and landings; Bombers break clustered fronts but need protection and setup.
+- Bridges can convert "almost connected" land into surprise attack routes.
+- Ports and Markets are economy pieces, but only if the city has enough adjacent support to justify the investment.
+
+## Diplomacy And Cloak-Like Pressure
+
+Diplomacy tools add a hidden-front layer:
+
+- Peace can buy economy time but may give opponents freedom elsewhere.
+- Embassies convert information and opponent count into stars, but patch cost scaling matters.
+- Cloak/Moth-style infiltration punishes undefended large cities and weak vision.
+- Counter infiltration with city walls, patrols, fast finishers, splash, and not leaving core cities empty.
+
+## Tribe Archetypes
+
+Use these archetypes when giving advice:
+
+- Resource-economy starters: rush the starting resource tech payoff, then expand.
+- Mobility starters: convert early reach into villages and pressure before slower tribes stabilize.
+- Naval starters: exploit water if map supports it; pivot if spawn is landlocked.
+- Military starters: pressure early, but do not ignore economy or tech-cost timing.
+- Defensive/diplomatic starters: use survivability or diplomacy to buy SPT and information.
+- Special tribes: learn their exception mechanics first; generic build orders mislead.
+
+## Common Mistakes
+
+- Buying tech because it is "next" rather than immediately useful.
+- Capturing cities before buying a planned tech, making the tech more expensive for no reason.
+- Upgrading a city for score/elegance while the front needs units.
+- Building roads that do not change a timing breakpoint.
+- Sending super units unsupported.
+- Fighting over units while ignoring empty villages.
+- Letting fast enemy units chain kills.
+- Choosing Explorer when visible map already answers the next three turns.
+- Delaying naval on maps where water controls expansion.
+
+## Strategy Answer Template
+
+When asked "how should I play this?", answer in this order:
+
+1. Mode/map/tribe assumptions.
+2. First 5 turns.
+3. First tech priorities.
+4. City upgrade priorities.
+5. Unit composition and road plan.
+6. Midgame pivot.
+7. Specific mistakes to avoid.

.codex/skills/polytopia-strategy-design/references/source-index.md

@@ -0,0 +1,61 @@
+# Source Index
+
+Last researched: 2026-06-29.
+
+## Polytopia Sources
+
+Prefer official pages for current patch state and use the wiki for broad rule lookup. Fandom strategy pages can lag behind live patches, so treat them as strategy hypotheses unless confirmed by official news or current in-game data.
+
+- Official home page: https://polytopia.io/
+- Official Path of the Ocean naval update: https://polytopia.io/path-of-the-ocean/
+- Official 2025 balance pass: https://polytopia.io/2025-balance-pass/
+- Official Cymanti rework: https://polytopia.io/its-time-for-the-cymanti-rework/
+- Official Ai-Mo strategy guide pointer: https://polytopia.io/news/ai-mo-strategy-guide/
+- Official Aquarion strategy guide pointer: https://polytopia.io/news/aquarion-strategy-guide/
+- Polytopia Wiki main rule pages:
+  - https://polytopia.fandom.com/wiki/Technology
+  - https://polytopia.fandom.com/wiki/City
+  - https://polytopia.fandom.com/wiki/Population
+  - https://polytopia.fandom.com/wiki/Star
+  - https://polytopia.fandom.com/wiki/Units
+  - https://polytopia.fandom.com/wiki/List_of_Units
+  - https://polytopia.fandom.com/wiki/Unit_Skills
+  - https://polytopia.fandom.com/wiki/Movement
+  - https://polytopia.fandom.com/wiki/Roads_(Building)
+  - https://polytopia.fandom.com/wiki/Strategies
+  - https://polytopia.fandom.com/wiki/Strategies/Tribes
+  - https://polytopia.fandom.com/wiki/Strategies/Units
+- General encyclopedia overview: https://en.wikipedia.org/wiki/The_Battle_of_Polytopia
+
+## Downloaded External References
+
+These were downloaded as local reference material for this skill, not as automatic instructions.
+
+### 1. SkillsBench Civ6 `civ6lib`
+
+- Source: https://github.com/benchflow-ai/skillsbench/tree/main/tasks/civ6-adjacency-optimizer/environment/skills/civ6lib
+- Repository: https://github.com/benchflow-ai/skillsbench
+- Downloaded commit checked: `bf3793e9ec20e9682e6f18dbf4de3c69163dc9c7`
+- License reported by GitHub: Apache-2.0.
+- Local path: `references/external/skillsbench-civ6lib/`
+- Use for: district placement, adjacency, tile validity, and city-planning comparison against Polytopia or TH1.
+
+### 2. construct-gygax
+
+- Source: https://github.com/0xHoneyJar/construct-gygax
+- Downloaded commit checked: `95ccf2190ca6f61badeef71881f1f1c2dee7b1be`
+- License stated in README: MIT.
+- Local path: `references/external/construct-gygax/`
+- Use for: game-state ingestion, intent-aware mechanic design, math/balance analysis, player-archetype stress tests, and 4X/tactics/eurogame heuristics.
+
+### 3. OrangeViolin Game Design Skill Gist
+
+- Source: https://gist.github.com/OrangeViolin/53ad898cdbc8734d8bb5c6a6ddf5cec4
+- Downloaded commit checked: `0a2eae1c91f9a06a081de73f92f6ed86fbce1194`
+- Local path: `references/external/orangeviolin-game-design/summary.md`
+- License: no explicit license found in the gist, so only a local summary/index is kept.
+- Use for: methodology names and links such as doubling/halving balance, flow-state framing, player psychology, reinforcement feedback, and prototyping tests.
+
+## Currency Rule
+
+Before answering "current best tribe", "current meta", "latest patch", or "how does Cymanti/Aquarion work now", browse official Polytopia news first. The game has had major rules changes after Path of the Ocean, including the September 1, 2025 balance pass and October 29, 2025 Cymanti rework.

.codex/skills/th1-unity-mcp-workflow/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: th1-unity-mcp-workflow
+description: TH1 workflow for safe Unity MCP use with Funplay/IvanMurzak-style Unity Editor automation. Use when Codex configures, evaluates, updates, or operates Unity MCP tools for TH1 UI prefab work, scene/prefab inspection, screenshots, Play Mode validation, Console/compile diagnostics, MCP tool whitelisting, or project-specific Unity editor automation.
+---
+
+# TH1 Unity MCP Workflow
+
+## Core Rule
+
+Treat Unity MCP as a high-permission editor automation bridge, not as a normal read-only tool. It gives Codex live Unity Editor state, screenshots, Play Mode control, prefab/scene/component operations, and optional dynamic C# execution. Use it to shorten visual and prefab feedback loops, but keep changes reviewable through TH1's normal git, build, and Unity validation paths.
+
+## First Moves
+
+- Use `th1-base` first for broad Unity/package/build/resource changes.
+- Run `git status --short`; preserve unrelated Unity/OSS/tool changes.
+- Prefer read-only MCP tools first: editor state, hierarchy, selection, prefab stage, logs, compile errors, screenshots, and package list.
+- Before enabling write/destructive tools, identify the exact prefab, scene, DataAsset, or package file that may change.
+- Never use Unity MCP to edit export-flow outputs unless the user explicitly asks: `Unity/Assets/Resources/Export/*`, `Unity/Assets/BundleResources/Export/*`, `Tools/Multilingual.xlsx`, `Tools/MultilingualTxt.txt`.
+- Do not use MCP dynamic C# execution for MemoryPack, obfuscation, HybridCLR bootstrap, package manifests, or save/network format changes without explicit confirmation.
+
+## Installed Baseline
+
+TH1 currently pilots `FunplayAI/funplay-unity-mcp` through `Unity/Packages/manifest.json`:
+
+```json
+"com.gamebooom.unity.mcp": "https://github.com/FunplayAI/funplay-unity-mcp.git#v0.4.8"
+```
+
+Funplay is the first-stage default because it is Editor-only, Unity 2022.3 compatible, smaller than the IvanMurzak stack, and exposes a focused `core` tool profile. The IvanMurzak Unity-MCP project remains a candidate for later evaluation when TH1 needs broader CLI, Docker/cloud, runtime/in-game, or custom tool ecosystem support.
+
+For the research record and rollout notes, read `references/assessment-2026-06-29.md` when changing MCP selection, tool exposure, auth, or rollout policy.
+
+## Safe Operating Mode
+
+Use this order for UI/prefab work:
+
+1. Inspect static code and TH1 UI patterns first.
+2. Use MCP read tools to inspect live selection, hierarchy, prefab stage, component values, logs, compile errors, and screenshots.
+3. Make source/prefab edits through established Unity APIs or normal file edits, not ad-hoc YAML surgery.
+4. Use Unity screenshots or Play Mode only for validation, unless the task explicitly requires editor-side object creation.
+5. Check `git diff` after every MCP write action.
+
+For Funplay `execute_code`:
+
+- Keep default safety checks on.
+- Prefer dedicated tools and `execute_menu_item` before `execute_code`.
+- Use `execute_code` only for bounded inspection or a clearly named batch operation with explicit before/after logs.
+- Do not pass `safety_checks=false` unless the user explicitly approves that exact operation.
+
+For IvanMurzak-style tools if installed later:
+
+- Use `UNITY_MCP_TOOLS` to whitelist only the needed tool IDs.
+- Keep destructive tools disabled unless explicitly required: asset delete/move, script delete/update, package add/remove, reflection method call, dynamic script execute.
+- Require token auth for HTTP/standalone transport.
+
+## TH1 UI And Prefab Value
+
+Use Unity MCP especially for:
+
+- Inspecting actual prefab component state instead of guessing from YAML.
+- Opening prefab stage, reading `RectTransform`, image, TMP, controller binding, and button event state.
+- Capturing Game View or prefab screenshots after a UI edit.
+- Finding Missing Script, missing references, disabled objects, unexpected scale/alpha, and layout overflow.
+- Validating UI workflows in Play Mode with Console checks.
+
+Do not let MCP bypass TH1 architecture. UI behavior still follows `th1-ui-patterns`; gameplay mutations still go through action logic; text/localization still follows `th1-multilingual`.
+
+## Verification
+
+For package/config changes:
+
+- Prefer opening Unity 2022.3.53f1 and letting Package Manager resolve `Packages/packages-lock.json`.
+- Then run the relevant editor or hotfix build if scripts changed.
+- For pure skill/docs changes, run the skill creator validation script:
+
+```powershell
+python C:\Users\daixiawu\.codex\skills\.system\skill-creator\scripts\quick_validate.py C:\TH1\TH1\.codex\skills\th1-unity-mcp-workflow
+```
+
+Before finishing any MCP-assisted edit, report:
+
+- Which MCP server/tool profile was used.
+- Whether any dynamic code execution or destructive tools were used.
+- What Unity-side validation was performed.
+- Any remaining uncommitted files unrelated to the task.

.codex/skills/th1-unity-mcp-workflow/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "TH1 Unity MCP Workflow"
+  short_description: "Safe TH1 Unity MCP workflow."
+  default_prompt: "Use $th1-unity-mcp-workflow to plan or execute a safe TH1 Unity MCP UI/prefab automation task."
+policy:
+  allow_implicit_invocation: true

.codex/skills/th1-unity-mcp-workflow/references/assessment-2026-06-29.md

@@ -0,0 +1,95 @@
+# TH1 Unity MCP Assessment - 2026-06-29
+
+## Decision
+
+Pilot Funplay MCP for Unity first. Do not install both Funplay and IvanMurzak Unity-MCP into the TH1 main Unity project at the same time without a separate evaluation branch.
+
+## Why Funplay First
+
+- Repository: `FunplayAI/funplay-unity-mcp`
+- Package: `com.gamebooom.unity.mcp`
+- Version pinned in TH1: `v0.4.8`
+- License: MIT
+- Unity compatibility: `2022.3`
+- Runtime footprint: Editor-only asmdef
+- Default posture: focused `core` profile, loopback HTTP server, safety checks for `execute_code`
+
+Primary TH1 use cases:
+
+- Live Unity Editor inspection.
+- Console and compile diagnostics.
+- Hierarchy, selection, prefab stage, and component inspection.
+- Screenshot and Play Mode validation.
+- Prefab/UI verification after Codex edits.
+
+Main risk:
+
+- It includes `execute_code`, file, asset, package, and GameObject write tools. Its safety checks are defensive pattern checks, not a sandbox.
+
+## Why IvanMurzak Is Candidate, Not Default
+
+- Repository: `IvanMurzak/Unity-MCP`
+- Package: `com.ivanmurzak.unity.mcp`
+- Observed release during assessment: `0.82.2`
+- License: Apache-2.0
+- Unity compatibility: `2022.3`
+- Larger ecosystem: CLI, Docker/cloud deployment, runtime/in-game mode, many tools, tool enable/disable UI, token auth options.
+
+Reasons to delay in TH1 mainline:
+
+- Broader install footprint and additional dependencies.
+- Includes runtime direction, not just Editor-only workflow.
+- Supports powerful tools such as dynamic script execution, reflection method calls including private methods, package installation, and destructive asset/script operations.
+- HTTP auth defaults must be configured deliberately; do not rely on defaults.
+
+Install later only when TH1 needs one of:
+
+- CLI-managed Unity MCP lifecycle.
+- Runtime/in-game MCP integration.
+- Richer custom MCP tool ecosystem.
+- Docker/cloud MCP server deployment.
+
+## Rollout Plan
+
+1. Install Funplay Git package in `Unity/Packages/manifest.json`.
+2. Configure Codex MCP URL to `http://127.0.0.1:8765/`.
+3. Open Unity and start `Funplay > MCP Server`.
+4. First test only read-style calls: scene info, editor state, selection, compile errors, Console logs, screenshot.
+5. For UI/prefab tasks, require `git status` and `git diff` after any MCP write call.
+6. Keep IvanMurzak uninstalled until a task needs its extra capabilities.
+
+## MCP Safety Policy For TH1
+
+Default allowed categories:
+
+- Read editor state.
+- Read hierarchy/selection/prefab stage.
+- Read compile errors and Console logs.
+- Capture screenshots.
+- Enter/exit Play Mode for explicit validation.
+
+Requires explicit user intent:
+
+- Modify prefab/scene/component values.
+- Create/delete/copy/rename assets.
+- Install/remove packages.
+- Dynamic C# execution.
+- Reflection method calls.
+
+Avoid through MCP:
+
+- MemoryPack serialization format changes.
+- Obfuscation settings.
+- HybridCLR bootstrap or AOT metadata flow.
+- Network/save payload schema changes.
+- Manual edits to export-flow outputs.
+
+## Expected New Value Over Plain Codex
+
+Before MCP, Codex mostly reads and edits files, then verifies with command-line builds. After Unity MCP, Codex can inspect and validate the live Unity Editor state. The biggest TH1 gains are:
+
+- Safer prefab work via Unity APIs instead of YAML guessing.
+- Visual UI feedback through screenshots.
+- Faster compile/Console error loops.
+- Better detection of missing references, missing scripts, bad RectTransform values, wrong active state, and prefab-stage issues.
+- Foundation for future TH1-specific MCP tools, such as UI binding checks, prefab reference audits, and screenshot smoke tests.

.gitignore

@@ -129,3 +129,10 @@ __pycache__/
 # Dashboard private runtime config. Community-monitor sqlite is intentionally tracked for now.
 /Tools/Dashboard/private/*.env
 /Tools/Dashboard/data/community_monitor/twitter-runs/
+
+# Local OSS collect-data downloads and JSON exports.
+/Tools/OSS/Data/
+
+# Local player bug viewer cache and machine config.
+/Tools/PlayerBugViewer/Data/
+/Tools/PlayerBugViewer/config.local.json

DOC/bugs.json

@@ -1,5 +1,5 @@
 {
-  "nextId": 400,
+  "nextId": 401,
   "bugs": [
     {
       "id": 2,
@@ -4102,6 +4102,17 @@
       "longTerm": false,
       "createdAt": 1782653812569,
       "updatedAt": 1782653812569
+    },
+    {
+      "id": 400,
+      "title": "有帝国陨落的时候，单位死亡后周围的单位的高亮状态没有刷新",
+      "description": "",
+      "status": "open",
+      "priority": "medium",
+      "module": "",
+      "longTerm": false,
+      "createdAt": 1782725473077,
+      "updatedAt": 1782725473077
     }
   ]
 }

DOC/todos.json

@@ -1,5 +1,5 @@
 {
-  "nextId": 6,
+  "nextId": 7,
   "todos": [
     {
       "id": 1,
@@ -55,6 +55,17 @@
       "longTerm": false,
       "createdAt": 1781878847283,
       "updatedAt": 1781878847283
+    },
+    {
+      "id": 6,
+      "title": "1234",
+      "description": "以参考图的角色造型、画风、光影和大学操场跑道环境为准：高细节 3D 动漫 NPR 渲染，自然阳光，浅景深，真实布料，玻璃质感眼睛，细密发丝。一个连续镜头，镜头在跑道旁轻微跟随。金发少女拿着蓝绿色头发少女的蓝色圆扁帽子，从左侧跑入画面，笑着向右侧跑出；蓝绿色头发少女在后面追赶但追不上。随后两人从右侧远处再次入镜，这次都背对镜头沿跑道往远处跑，金发少女仍举着帽子，蓝绿色头发少女逐渐停下，气鼓鼓地从腰间小工具包里掏出一个无字小遥控器并按下一下；远处金发少女前方瞬间爆出夸张的动漫式火光和烟尘大爆炸，喜剧效果，烟尘遮住远处身影。全程无台词，无音乐，只保留奔跑脚步声、急促呼吸、少女轻微气声、按键声和远处爆炸声。画面不要出现文字、标识、数字或字幕。",
+      "status": "open",
+      "priority": "medium",
+      "module": "",
+      "longTerm": false,
+      "createdAt": 1782656503745,
+      "updatedAt": 1782656503745
     }
   ]
 }

MD/ChronicIssueList/2026-06-29-mokou-revived-ranged-move-kill.md

@@ -0,0 +1,59 @@
+# TH1-CI-2026-06-29-002 Mokou Revived Ranged Move-Kill Regression
+
+- Status: Fixed in code; guardrail added; Unity validation pending
+- First recorded date: 2026-06-29
+- Severity: High
+
+## Raw Symptom
+
+User feedback: after Fujiwara no Mokou revives from the flame/egg state, her attack range becomes longer. If she kills a unit from that revived state, she should move to the killed target's position, but this no longer happens even though it had been fixed before.
+
+Affected entrypoint: `UnitAttackAction` -> `UnitLogic.Attack` normal attack settlement.
+
+## Why This Is Recurring
+
+The June 13, 2026 fix added `MokouFrenchMoveKillSkill`, added it to Lv.3+ revived Mokou in `MokouFrenchReviveSkill`, and added ranged `FragmentMoveKill` presentation. The rule still lived inline inside the generic attack kill branch, beside the legacy near-melee `IsCanMoveKill` check.
+
+Later attack movement fixes, especially the June 28, 2026 Aunn attack move-kill desync fix, changed the move-kill path to depend on `MoveToLogic` success. That was correct for data safety, but the Mokou rule had no dedicated helper or guardrail, so future edits could again collapse the special revived-ranged path back into ordinary one-range move-kill behavior.
+
+## Root Cause
+
+Mokou's revived ranged move-kill was represented as a local special case inside `UnitLogic.Attack`, not as a named attack invariant. The attack branch also used the post-settlement target alive state instead of the settlement's kill result as the first-class kill fact, making death replacement paths fragile.
+
+## Root-Cause Fix
+
+- `UnitLogic.Attack` now treats `activeSettlement.IsKill || !unit2.IsAlive()` as the attack kill branch.
+- The movement decision is centralized in `TryMoveAttackerToKilledTarget` / `CanMoveAttackerToKilledTarget`.
+- The helper keeps both contracts explicit:
+  - ordinary move-kill stays one-range and uses existing `IsCanMoveKill`;
+  - revived Mokou can move-kill within current attack range only when `MokouFrenchMoveKill` allows it.
+- Revived Mokou still obeys ordinary standing rules through `CheckUnitAbleForGrid_RealTimeStatus`; the fix does not force movement onto invalid terrain, occupied grids, or blocked city-center cases.
+
+## Guardrail Added
+
+Added `Tools/CheckMokouRevivedMoveKill.ps1`.
+
+The guardrail checks:
+
+- Lv.3+ revived Mokou still receives `SkillType.MokouFrenchMoveKill`.
+- `MokouFrenchMoveKillSkill` is limited to `GiantType.FrenchMokou` and allows current attack range.
+- `UnitLogic.Attack` uses the centralized move-kill helper and still calls `MoveToLogic(..., MoveType.AttackMove)`.
+- The helper still includes ordinary standing validation.
+- `FragmentMoveKill` keeps the ranged projectile-then-move branch.
+
+`Tools/GitCheckpoint.ps1` now runs this guardrail when any of the relevant attack, Mokou skill, MoveKill fragment, or guardrail files change.
+
+## Verification Performed
+
+- `Tools/CheckMokouRevivedMoveKill.ps1`
+- `dotnet build Unity/TH1.Hotfix.csproj --no-restore`
+
+## Remaining Validation Gaps
+
+Unity Editor gameplay validation is still required:
+
+- Lv.3+ Mokou dies into flame/egg.
+- Mokou revives and receives the range and move-kill marker.
+- Mokou kills a normal land target from 2 range.
+- Data position, ranged projectile, move-kill animation, sight refresh, target grid, and old grid all update correctly.
+- Invalid target grids such as blocked terrain or occupied grids still do not force movement.

MD/ChronicIssueList/index.md

@@ -6,6 +6,7 @@
 
 | ID | 日期 | 状态 | 严重度 | 问题 | 根治方向 | 记录 |
 | --- | --- | --- | --- | --- | --- | --- |
+| TH1-CI-2026-06-29-002 | 2026-06-29 | Fixed in code; guardrail added; Unity validation pending | High | Lv.3+ Mokou revived from flame/egg could fail to move to a killed target after gaining longer range | Centralize attack move-kill rules and guard revived Mokou's ranged move-kill contract | [record](2026-06-29-mokou-revived-ranged-move-kill.md) |
 | TH1-CI-2026-06-29-001 | 2026-06-29 | Fixed in code; guardrail added; Unity validation pending | High | Movement/skill displacement sight refresh could fail to reveal the unit's final standing grid, exposed by Suika Lv4 falling splash side landing after a non-lethal 3-grid attack | Make the shared movement sight path include the standing grid and guard Suika landing sight handoff | [record](2026-06-29-movement-displacement-sight-refresh.md) |
 | TH1-CI-2026-06-28-002 | 2026-06-28 | Fixed in code; guardrail added; Unity validation pending | High | Momiji hunter movement could lose 2 movement when another rule replaced the movement range | Split normal movement from prey-adjacent hunter target movement and ban the old global add-then-payback formula | [record](2026-06-28-momiji-hunter-movement-payback.md) |
 | TH1-CI-2026-06-28-001 | 2026-06-28 | Fixed in code; guardrail added; Unity validation pending | High | Aunn twin levels could diverge when one body was on a ship and the other upgraded or later landed | Treat Aunn level as a player-hero invariant over all same-player land and ship bodies, synchronized after upgrade and landing | [record](2026-06-28-aunn-ship-level-sync.md) |

Tools/CheckMokouRevivedMoveKill.ps1

@@ -0,0 +1,50 @@
+param(
+    [string]$UnitLogicFile = "Unity/Assets/Scripts/TH1_Logic/Unit/UnitLogic.cs",
+    [string]$ReviveSkillFile = "Unity/Assets/Scripts/TH1_Logic/Skill/AllSkill/MokouFrenchReviveSkill.cs",
+    [string]$MoveKillSkillFile = "Unity/Assets/Scripts/TH1_Logic/Skill/AllSkill/MokouFrenchMoveKillSkill.cs",
+    [string]$MoveKillFragmentFile = "Unity/Assets/Scripts/TH1_Anim/Fragments/FragmentMoveKill.cs"
+)
+
+$ErrorActionPreference = "Stop"
+
+$repoRoot = git rev-parse --show-toplevel 2>$null
+if (-not $repoRoot) {
+    throw "Not inside a git repository."
+}
+$repoRoot = [System.IO.Path]::GetFullPath($repoRoot.Trim())
+
+function Read-RepoFile([string]$relativePath) {
+    $fullPath = Join-Path $repoRoot $relativePath
+    if (-not (Test-Path -LiteralPath $fullPath)) {
+        throw "Required file not found: $fullPath"
+    }
+    return Get-Content -LiteralPath $fullPath -Raw -Encoding UTF8
+}
+
+function Assert-Contains([string]$text, [string]$needle, [string]$label) {
+    if (-not $text.Contains($needle)) {
+        throw "Mokou revived move-kill guardrail failed: $label missing '$needle'."
+    }
+}
+
+$unitLogicText = Read-RepoFile $UnitLogicFile
+$reviveSkillText = Read-RepoFile $ReviveSkillFile
+$moveKillSkillText = Read-RepoFile $MoveKillSkillFile
+$fragmentText = Read-RepoFile $MoveKillFragmentFile
+
+Assert-Contains $reviveSkillText 'newUnit.AddSkill_Legacy(SkillType.MokouFrenchMoveKill' 'revived Lv3+ Mokou must receive the move-kill marker'
+Assert-Contains $moveKillSkillText 'self.GiantType != GiantType.FrenchMokou' 'move-kill marker must be limited to Mokou'
+Assert-Contains $moveKillSkillText 'attackDistance <= self.GetAttackRange(mapData)' 'Mokou move-kill must allow current attack range'
+
+Assert-Contains $unitLogicText 'activeSettlement.IsKill || !unit2.IsAlive()' 'attack settlement must treat death replacement kills as kills'
+Assert-Contains $unitLogicText 'TryMoveAttackerToKilledTarget(mapData, unit1, unit2, grid2, attackDistance, ref fragmentType)' 'attack kill path must use shared move-kill helper'
+Assert-Contains $unitLogicText 'private bool CanMoveAttackerToKilledTarget' 'move-kill predicate must stay centralized'
+Assert-Contains $unitLogicText 'SkillType.MokouFrenchMoveKill' 'central move-kill predicate must include revived Mokou'
+Assert-Contains $unitLogicText 'CheckUnitAbleForGrid_RealTimeStatus(mapData, attacker, targetGrid)' 'Mokou move-kill must still obey ordinary standing rules'
+Assert-Contains $unitLogicText 'MoveToLogic(mapData, attacker, targetGrid, MoveType.AttackMove)' 'move-kill helper must use attack move logic'
+Assert-Contains $unitLogicText 'fragmentType = FragmentType.MoveKill' 'successful helper movement must select MoveKill fragment'
+
+Assert-Contains $fragmentText 'if (_attackInfo.ProjectileType != ProjectileType.Melee)' 'MoveKill fragment must preserve ranged handling'
+Assert-Contains $fragmentText 'Data.OriginUnitRenderer.AnimManager.EnqueueAnim(UnitAtomAnimType.Move, animData)' 'ranged MoveKill must move the attacker renderer after impact'
+
+Write-Host "Mokou revived move-kill guardrail passed."

Tools/Dashboard/css/style.css

@@ -4080,6 +4080,10 @@ body::after {
     border-color: var(--accent-blue);
 }
 
+.codex-audio-file {
+    display: none;
+}
+
 .codex-runner-actions {
     display: flex;
     align-items: center;
@@ -4087,6 +4091,19 @@ body::after {
     flex-wrap: wrap;
 }
 
+.codex-voice-btn.recording {
+    border-color: #dc2626;
+    background: #dc2626;
+    color: #fff;
+}
+
+.codex-voice-status {
+    color: var(--text-secondary);
+    font-size: 12px;
+    font-weight: 700;
+    min-height: 18px;
+}
+
 .codex-job-status {
     color: var(--text-secondary);
     font-size: 12px;

Tools/Dashboard/index.html

@@ -837,15 +837,19 @@
                     <div class="codex-detail-head">
                         <div>
                             <div class="codex-detail-title" id="codex-detail-title">选择一个 TH1 会话</div>
-                            <div class="codex-detail-meta" id="codex-detail-meta">本面板只显示工作目录为 C:\TH1\TH1 的本机 Codex 会话。</div>
+                            <div class="codex-detail-meta" id="codex-detail-meta">本面板读取 ~/.codex/sessions 的本机 CLI 会话，只显示工作目录为 C:\TH1\TH1 的记录；这些记录不一定出现在桌面版侧栏线程里。</div>
                         </div>
                     </div>
 
                     <div class="codex-runner">
                         <textarea id="codex-prompt" class="codex-prompt" rows="5" placeholder="输入要交给本机 Codex 执行的任务..."></textarea>
+                        <input type="file" id="codex-audio-file" class="codex-audio-file" accept="audio/*" capture>
                         <div class="codex-runner-actions">
+                            <button class="bug-btn codex-voice-btn" id="codex-voice-toggle" type="button">语音输入</button>
+                            <button class="bug-btn" id="codex-audio-pick" type="button">音频文件</button>
                             <button class="bug-btn" id="codex-run-new" type="button">新会话执行</button>
                             <button class="bug-btn bug-btn-primary" id="codex-run-resume" type="button" disabled>续接所选会话执行</button>
+                            <span id="codex-voice-status" class="codex-voice-status"></span>
                             <span id="codex-job-status" class="codex-job-status"></span>
                         </div>
                         <pre id="codex-job-output" class="codex-job-output"></pre>

Tools/Dashboard/js/codex_threads.js

@@ -6,6 +6,9 @@ let codexSessions = [];
 let codexLoaded = false;
 let codexSelectedId = '';
 let codexPollTimer = null;
+let codexRecorder = null;
+let codexVoiceChunks = [];
+let codexVoiceStream = null;
 
 function codexEsc(value) {
     const div = document.createElement('div');
@@ -24,6 +27,174 @@ function codexShortId(id) {
     return id ? id.slice(0, 8) : '';
 }
 
+function codexPreferredAudioMimeType() {
+    const candidates = [
+        'audio/webm;codecs=opus',
+        'audio/webm',
+        'audio/mp4',
+        'audio/wav',
+    ];
+    if (!window.MediaRecorder || !MediaRecorder.isTypeSupported) return '';
+    return candidates.find(type => MediaRecorder.isTypeSupported(type)) || '';
+}
+
+function codexAudioExtension(mimeType) {
+    const lower = (mimeType || '').toLowerCase();
+    if (lower.includes('mp4')) return 'm4a';
+    if (lower.includes('wav')) return 'wav';
+    if (lower.includes('mpeg') || lower.includes('mp3')) return 'mp3';
+    if (lower.includes('ogg')) return 'ogg';
+    return 'webm';
+}
+
+function codexIsSecureVoiceContext() {
+    return window.isSecureContext || ['localhost', '127.0.0.1', '::1'].includes(window.location.hostname);
+}
+
+function codexSetVoiceStatus(text) {
+    const el = document.getElementById('codex-voice-status');
+    if (el) el.textContent = text || '';
+}
+
+function codexSetVoiceRecording(recording) {
+    const btn = document.getElementById('codex-voice-toggle');
+    if (!btn) return;
+    btn.classList.toggle('recording', recording);
+    btn.textContent = recording ? '停止录音' : '语音输入';
+}
+
+function codexCleanupVoiceStream() {
+    if (!codexVoiceStream) return;
+    codexVoiceStream.getTracks().forEach(track => track.stop());
+    codexVoiceStream = null;
+}
+
+function codexBlobToBase64(blob) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => {
+            const value = String(reader.result || '');
+            resolve(value.includes(',') ? value.split(',', 2)[1] : value);
+        };
+        reader.onerror = () => reject(reader.error || new Error('读取录音失败'));
+        reader.readAsDataURL(blob);
+    });
+}
+
+function codexAppendPromptText(text) {
+    const promptEl = document.getElementById('codex-prompt');
+    if (!promptEl || !text) return;
+    const current = promptEl.value || '';
+    const separator = current.trim() ? (current.endsWith('\n') ? '' : '\n') : '';
+    promptEl.value = current + separator + text.trim();
+    promptEl.focus();
+    promptEl.selectionStart = promptEl.selectionEnd = promptEl.value.length;
+}
+
+function codexOpenAudioFilePicker(message) {
+    const fileInput = document.getElementById('codex-audio-file');
+    if (!fileInput) {
+        codexSetVoiceStatus(message || '请改用安全来源或手动输入');
+        return;
+    }
+    if (message) codexSetVoiceStatus(message);
+    fileInput.value = '';
+    fileInput.click();
+}
+
+async function codexStartVoiceInput() {
+    if (!codexIsSecureVoiceContext()) {
+        codexOpenAudioFilePicker('手机 Chrome 需要 HTTPS 才能直接录音，请改用系统录音/音频文件');
+        return;
+    }
+    if (!navigator.mediaDevices?.getUserMedia || !window.MediaRecorder) {
+        codexOpenAudioFilePicker('当前浏览器不能直接录音，请改用系统录音/音频文件');
+        return;
+    }
+    try {
+        codexVoiceChunks = [];
+        const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+        codexVoiceStream = stream;
+        const mimeType = codexPreferredAudioMimeType();
+        codexRecorder = new MediaRecorder(stream, mimeType ? { mimeType } : undefined);
+        codexRecorder.addEventListener('dataavailable', event => {
+            if (event.data && event.data.size > 0) codexVoiceChunks.push(event.data);
+        });
+        codexRecorder.addEventListener('stop', () => {
+            const blob = new Blob(codexVoiceChunks, { type: codexRecorder?.mimeType || mimeType || 'audio/webm' });
+            codexRecorder = null;
+            codexCleanupVoiceStream();
+            codexSetVoiceRecording(false);
+            codexFinishVoiceInput(blob);
+        });
+        codexRecorder.addEventListener('error', event => {
+            codexSetVoiceStatus(event.error?.message || '录音失败');
+            codexRecorder = null;
+            codexCleanupVoiceStream();
+            codexSetVoiceRecording(false);
+        });
+        codexRecorder.start();
+        codexSetVoiceRecording(true);
+        codexSetVoiceStatus('录音中，再点一次停止');
+    } catch (err) {
+        codexRecorder = null;
+        codexCleanupVoiceStream();
+        codexSetVoiceRecording(false);
+        codexSetVoiceStatus(err?.message || '无法启动麦克风');
+    }
+}
+
+function codexStopVoiceInput() {
+    if (codexRecorder && codexRecorder.state !== 'inactive') {
+        codexRecorder.stop();
+    }
+}
+
+async function codexToggleVoiceInput() {
+    if (codexRecorder && codexRecorder.state === 'recording') {
+        codexStopVoiceInput();
+    } else {
+        await codexStartVoiceInput();
+    }
+}
+
+async function codexFinishVoiceInput(blob) {
+    if (!blob || blob.size === 0) {
+        codexSetVoiceStatus('没有录到声音');
+        return;
+    }
+    codexSetVoiceStatus('正在转写...');
+    try {
+        const audioBase64 = await codexBlobToBase64(blob);
+        const resp = await fetch('/api/codex/transcribe', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                audioBase64,
+                mimeType: blob.type || 'audio/webm',
+                filename: `codex-voice-${Date.now()}.${codexAudioExtension(blob.type)}`,
+                language: 'zh',
+            }),
+        });
+        const data = await resp.json();
+        if (!resp.ok || !data.success) throw new Error(data.error || `HTTP ${resp.status}`);
+        codexAppendPromptText(data.text || '');
+        codexSetVoiceStatus(data.model ? `已转成文字 · ${data.model}` : '已转成文字');
+    } catch (err) {
+        codexSetVoiceStatus(err?.message || '转写失败');
+    }
+}
+
+async function codexHandleAudioFilePicked(event) {
+    const file = event.target?.files?.[0];
+    if (!file) return;
+    if (!file.type.startsWith('audio/')) {
+        codexSetVoiceStatus('请选择音频文件');
+        return;
+    }
+    await codexFinishVoiceInput(file);
+}
+
 async function codexLoadSessions(force = false) {
     if (codexLoaded && !force) return;
     const list = document.getElementById('codex-session-list');
@@ -113,7 +284,7 @@ async function codexSelectSession(id) {
         const session = data.session || {};
         if (title) title.textContent = session.title || session.id || 'Codex 会话';
         if (meta) {
-            meta.textContent = `${codexFormatDate(session.updated_at || session.created_at)} · ${session.id || ''} · ${session.archived ? '归档' : '当前'}`;
+            meta.textContent = `${codexFormatDate(session.updated_at || session.created_at)} · ${session.id || ''} · ${session.archived ? '归档' : '当前'} · 本机 CLI 会话`;
         }
         codexRenderMessages(data.messages || []);
     } catch (err) {
@@ -237,6 +408,21 @@ function codexBind() {
         refresh.dataset.bound = '1';
         refresh.addEventListener('click', () => codexLoadSessions(true));
     }
+    const voice = document.getElementById('codex-voice-toggle');
+    if (voice && !voice.dataset.bound) {
+        voice.dataset.bound = '1';
+        voice.addEventListener('click', codexToggleVoiceInput);
+    }
+    const audioPick = document.getElementById('codex-audio-pick');
+    if (audioPick && !audioPick.dataset.bound) {
+        audioPick.dataset.bound = '1';
+        audioPick.addEventListener('click', () => codexOpenAudioFilePicker('选择或录制一段音频后自动转写'));
+    }
+    const audioFile = document.getElementById('codex-audio-file');
+    if (audioFile && !audioFile.dataset.bound) {
+        audioFile.dataset.bound = '1';
+        audioFile.addEventListener('change', codexHandleAudioFilePicked);
+    }
     const runNew = document.getElementById('codex-run-new');
     if (runNew && !runNew.dataset.bound) {
         runNew.dataset.bound = '1';
@@ -261,6 +447,7 @@ function codexBind() {
     if (panel) {
         observer.observe(panel, { attributes: true, attributeFilter: ['class'] });
     }
+    window.addEventListener('beforeunload', codexCleanupVoiceStream);
     document.addEventListener('DOMContentLoaded', () => {
         codexBind();
         const panelNow = document.getElementById('panel-codex');

Tools/Dashboard/serve.py

@@ -54,6 +54,8 @@ Usage:
 """
 
 import http.server
+import base64
+import binascii
 import csv
 import json
 import os
@@ -103,6 +105,10 @@ CODEX_HOME = os.path.join(os.path.expanduser('~'), '.codex')
 CODEX_SESSIONS_DIR = os.path.join(CODEX_HOME, 'sessions')
 CODEX_ARCHIVED_SESSIONS_DIR = os.path.join(CODEX_HOME, 'archived_sessions')
 CODEX_SESSION_INDEX = os.path.join(CODEX_HOME, 'session_index.jsonl')
+CODEX_TRANSCRIBE_MAX_BYTES = 25 * 1024 * 1024
+OPENROUTER_ENV_FILE = os.path.join(SCRIPT_DIR, 'private', 'community_monitor.env')
+OPENROUTER_TRANSCRIBE_ENDPOINT = 'https://openrouter.ai/api/v1/audio/transcriptions'
+OPENROUTER_TRANSCRIBE_DEFAULT_MODEL = 'openai/whisper-large-v3'
 CODEX_JOBS = {}
 CODEX_JOBS_LOCK = threading.Lock()
 COMMUNITY_MONITOR_API = None
@@ -418,6 +424,30 @@ def _read_jsonl_records(path, limit=None):
     return records
 
 
+def _load_dashboard_env_file(path):
+    if not os.path.exists(path):
+        return
+    try:
+        with open(path, 'r', encoding='utf-8-sig', errors='replace') as f:
+            for raw_line in f:
+                line = raw_line.strip()
+                if not line or line.startswith('#') or '=' not in line:
+                    continue
+                key, value = line.split('=', 1)
+                key = key.strip()
+                value = value.strip().strip('"').strip("'")
+                if key and key not in os.environ:
+                    os.environ[key] = value
+    except Exception:
+        pass
+
+
+def _openrouter_setting(name, default=''):
+    if name not in os.environ:
+        _load_dashboard_env_file(OPENROUTER_ENV_FILE)
+    return os.environ.get(name, default)
+
+
 def _message_text(content):
     if isinstance(content, str):
         return content
@@ -432,6 +462,90 @@ def _message_text(content):
     return '\n'.join(part for part in parts if part)
 
 
+def _decode_codex_audio_base64(value):
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError('audioBase64 required')
+    cleaned = value.strip()
+    if ',' in cleaned and cleaned[:80].lower().startswith('data:'):
+        cleaned = cleaned.split(',', 1)[1]
+    try:
+        data = base64.b64decode(cleaned, validate=True)
+    except (binascii.Error, ValueError):
+        raise ValueError('invalid audioBase64')
+    if not data:
+        raise ValueError('audio is empty')
+    if len(data) > CODEX_TRANSCRIBE_MAX_BYTES:
+        raise ValueError('audio too large')
+    return data
+
+
+def _codex_audio_format(filename='', mime_type=''):
+    source = f'{mime_type or ""} {filename or ""}'.lower()
+    for fmt in ('webm', 'wav', 'mp3', 'flac', 'm4a', 'ogg', 'aac'):
+        if fmt in source:
+            return fmt
+    return 'webm'
+
+
+def _codex_transcribe_audio(audio_base64, filename='', mime_type='', language=''):
+    api_key = _openrouter_setting('OPENROUTER_API_KEY', '').strip()
+    if not api_key:
+        raise RuntimeError('OPENROUTER_API_KEY is not configured')
+
+    audio_bytes = _decode_codex_audio_base64(audio_base64)
+    model = _openrouter_setting('OPENROUTER_TRANSCRIBE_MODEL', OPENROUTER_TRANSCRIBE_DEFAULT_MODEL).strip()
+    if not model:
+        model = OPENROUTER_TRANSCRIBE_DEFAULT_MODEL
+
+    payload = {
+        'model': model,
+        'input_audio': {
+            'data': base64.b64encode(audio_bytes).decode('ascii'),
+            'format': _codex_audio_format(filename, mime_type),
+        },
+    }
+    if language:
+        payload['language'] = str(language)[:32]
+
+    body = json.dumps(payload, ensure_ascii=False).encode('utf-8')
+    request = urllib.request.Request(
+        OPENROUTER_TRANSCRIBE_ENDPOINT,
+        data=body,
+        headers={
+            'Authorization': f'Bearer {api_key}',
+            'Content-Type': 'application/json',
+            'HTTP-Referer': _openrouter_setting('OPENROUTER_REFERER', 'http://localhost:8080'),
+            'X-Title': _openrouter_setting('OPENROUTER_TITLE', 'TH1 Dashboard Codex Voice Input'),
+        },
+        method='POST',
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=120) as resp:
+            raw = resp.read().decode('utf-8', errors='replace')
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode('utf-8', errors='replace')[:1200]
+        raise RuntimeError(f'OpenRouter transcription failed: HTTP {e.code} {detail}')
+    except urllib.error.URLError as e:
+        raise RuntimeError(f'OpenRouter transcription failed: {e.reason}')
+
+    try:
+        data = json.loads(raw)
+    except Exception:
+        raise RuntimeError('OpenRouter transcription returned invalid JSON')
+    text = str(data.get('text') or '').strip()
+    if not text and isinstance(data.get('choices'), list) and data['choices']:
+        choice = data['choices'][0] or {}
+        message = choice.get('message') if isinstance(choice.get('message'), dict) else {}
+        text = str(message.get('content') or choice.get('text') or '').strip()
+    if not text:
+        raise RuntimeError('OpenRouter transcription returned empty text')
+    return {
+        'text': text,
+        'model': data.get('model') or model,
+        'duration': data.get('duration'),
+    }
+
+
 def _is_codex_context_message(role, text):
     if role != 'user':
         return False
@@ -1112,6 +1226,8 @@ class DashboardHandler(http.server.SimpleHTTPRequestHandler):
             self._handle_dashboard_preferences_save()
         elif self.path == '/api/codex/run':
             self._handle_codex_run()
+        elif self.path == '/api/codex/transcribe':
+            self._handle_codex_transcribe()
         elif self.path.startswith('/api/community-monitor/'):
             self._handle_community_monitor_post()
         # SNS APIs
@@ -1516,6 +1632,21 @@ class DashboardHandler(http.server.SimpleHTTPRequestHandler):
         except Exception as e:
             self._send_json({'success': False, 'error': str(e)}, 500)
 
+    def _handle_codex_transcribe(self):
+        try:
+            payload = self._read_json_body()
+            result = _codex_transcribe_audio(
+                payload.get('audioBase64'),
+                filename=str(payload.get('filename') or ''),
+                mime_type=str(payload.get('mimeType') or ''),
+                language=str(payload.get('language') or 'zh'),
+            )
+            self._send_json({'success': True, **result})
+        except ValueError as e:
+            self._send_json({'success': False, 'error': str(e)}, 400)
+        except Exception as e:
+            self._send_json({'success': False, 'error': str(e)}, 500)
+
     def _handle_codex_job_get(self):
         try:
             parsed = urlparse(self.path)

Tools/GitCheckpoint.ps1

@@ -153,6 +153,13 @@ $touchedMomijiHunterMovement = @($paths | Where-Object {
     $_ -eq 'Unity/Assets/Scripts/TH1_Logic/Skill/AllSkill/MomijiHunterSkill.cs' -or
     $_ -eq 'Tools/CheckMomijiHunterMovement.ps1'
 })
+$touchedMokouRevivedMoveKill = @($paths | Where-Object {
+    $_ -eq 'Unity/Assets/Scripts/TH1_Logic/Unit/UnitLogic.cs' -or
+    $_ -eq 'Unity/Assets/Scripts/TH1_Logic/Skill/AllSkill/MokouFrenchReviveSkill.cs' -or
+    $_ -eq 'Unity/Assets/Scripts/TH1_Logic/Skill/AllSkill/MokouFrenchMoveKillSkill.cs' -or
+    $_ -eq 'Unity/Assets/Scripts/TH1_Anim/Fragments/FragmentMoveKill.cs' -or
+    $_ -eq 'Tools/CheckMokouRevivedMoveKill.ps1'
+})
 $touchedSkillDataAssets = @($paths | Where-Object {
     $_ -eq 'Unity/Assets/BundleResources/DataAssets/SkillDataAssets.asset' -or
     $_ -eq 'Unity/Assets/BundleResources/Export/SkillDataAssets.asset' -or
@@ -268,6 +275,19 @@ if ($touchedMomijiHunterMovement.Count -gt 0) {
     }
 }
 
+if ($touchedMokouRevivedMoveKill.Count -gt 0) {
+    Write-Host ""
+    Write-Host "Mokou revived move-kill check:"
+    $mokouRevivedMoveKillCheckPath = Join-Path $repoRoot "Tools/CheckMokouRevivedMoveKill.ps1"
+    try {
+        & $mokouRevivedMoveKillCheckPath
+    } catch {
+        $hasBlockingIssue = $true
+        Write-Host "  WARNING: Mokou revived move-kill guardrail failed:"
+        Write-Host "  $($_.Exception.Message)"
+    }
+}
+
 if ($touchedSkillDataAssets.Count -gt 0) {
     Write-Host ""
     Write-Host "SkillDataAssets integrity check:"
@@ -333,6 +353,9 @@ if ($touchedAunnPetrifiedDefenseAura.Count -gt 0) {
 if ($touchedSuikaFallingSplashAnimation.Count -gt 0) {
     Write-Host "  Tools/CheckSuikaFallingSplashAnimation.ps1"
 }
+if ($touchedMokouRevivedMoveKill.Count -gt 0) {
+    Write-Host "  Tools/CheckMokouRevivedMoveKill.ps1"
+}
 if ($touchedSkillDataAssets.Count -gt 0) {
     Write-Host "  Tools/CheckSkillDataAssetsIntegrity.ps1"
     Write-Host "  Tools/CheckSkillDataAssetsIntegrity.ps1 -CheckExport"

Tools/MultilingualTxt.txt

@@ -1,141 +1,141 @@
-30971%$#@!True%$#@!**<主动移动>**后消耗1层，获得**<攻击行动点>**。攻击行为则会直接清空层数。每回合开始时重置为1层。%$#@!**<主動移動>**後消耗1層，獲得**<攻擊行動點>**。攻擊行為則會直接清空層數。每回合開始時重置為1層。%$#@!After **<Active Movement>**, lose 1 stack and gain **<Attack Action Points>**. Attacking directly clears all stacks. Resets to 1 stack at the start of each turn.%$#@!**<主動移動>**後、1層を失い**<攻撃行動ポイント>**を獲得する。攻撃行動を行うと層数は直接0になる。毎ターン開始時に1層にリセットされる。%$#@!**<능동 이동>** 후 중첩 1을 소모하고 **<공격 행동 포인트>**를 획득한다. 공격 행동을 하면 중첩이 바로 모두 제거된다. 매 턴 시작 시 1중첩으로 초기화된다.%$#@!False%$#@!False%$#@!False%$#@!%$#@!False%$#@!False%$#@!False%$#@!%$#@!!@#$%30972%$#@!True%$#@!**<主动攻击>**后消耗1层，获得**<移动行动点>**。每回合开始时重置为1层。%$#@!**<主動攻擊>**後消耗1層，獲得**<移動行動點>**。每回合開始時重置為1層。%$#@!After **<Active Attack>**, lose 1 stack and gain **<Movement Action Points>**. Resets to 1 stack at the start of each turn.%$#@!**<主動攻撃>**後、1層を失い**<移動行動ポイント>**を獲得する。毎ターン開始時に1層にリセットされる。%$#@!**<능동 공격>** 후 중첩 1을 소모하고 **<이동 행동 포인트>**를 획득한다. 매 턴 시작 시 1중첩으로 초기화된다.%$#@!False%$#@!False%$#@!False%$#@!%$#@!False%$#@!False%$#@!False%$#@!%$#@!!@#$%30973%$#@!True%$#@!行动力提升%$#@!行動力提升%$#@!Action Boost%$#@!行動力上昇%$#@!행동력 증가%$#@!False%$#@!False%$#@!False%$#@!%$#@!False%$#@!False%$#@!True%$#@!%$#@!!@#$%30974%$#@!True%$#@!**<主动攻击>**后消耗1层，获得**<移动行动点>**与**<行动力提升>**。每回合开始时重置为1层。%$#@!**<主動攻擊>**後消耗1層，獲得**<移動行動點>**與**<行動力提升>**。每回合開始時重置為1層。%$#@!After **<Active Attack>**, lose 1 stack and gain **<Movement Action Points>** and **<Action Boost>**. Resets to 1 stack at the start of each turn.%$#@!**<主動攻撃>**後、1層を失い**<移動行動ポイント>**と**<行動力上昇>**を獲得する。毎ターン開始時に1層にリセットされる。%$#@!**<능동 공격>** 후 중첩 1을 소모하고 **<이동 행동 포인트>**와 **<행동력 증가>**를 획득한다. 매 턴 시작 시 1중첩으로 초기화된다.%$#@!False%$#@!False%$#@!False%$#@!%$#@!False%$#@!False%$#@!False%$#@!%$#@!!@#$%30975%$#@!True%$#@![版本V0.7.4i]
+30976%$#@!True%$#@!建造**<灌溉工程>**。不能与另一个**<灌溉工程>**相邻。每2回合在附近生成一片**<庄稼>**。附近每片**<农田>**额外提供1点**<城市发展度>**(上限2点)，为**<市场>**提供额外**<金币>**，需建在与**<山脉>**相邻，或至少与三块**<浅海>**相邻的**<平原>**地块上。研发**<排涝>**后，还可建造在至少与三块**<平原>**相邻的**<浅海>**地块上。%$#@!建造**<灌溉工程>**。不能與另一個**<灌溉工程>**相鄰。每2回合在附近生成一片**<莊稼>**。附近每片**<農田>**額外提供1點**<城市發展度>**(上限2點)，為**<市場>**提供額外**<金幣>**，需建在與**<山脈>**相鄰，或至少與三塊**<淺海>**相鄰的**<平原>**地塊上。研發**<排澇>**後，還可建造在至少與三塊**<平原>**相鄰的**<淺海>**地塊上。%$#@!Construct an **<Irrigation Project>**. Cannot be adjacent to another **<Irrigation Project>**. Every 2 turns, generates one **<Crops>** tile nearby. Each nearby **<Farm>** provides +1 **<City Development>** (up to 2), and provides **<Market>** with extra **<Gold>**. Must be built adjacent to **<Mountain>**, or on a **<Plains>** tile adjacent to at least three **<Water>** tiles. After researching **<Drainage>**, it can also be built on a **<Water>** tile adjacent to at least three **<Plains>** tiles.%$#@!**<灌漑整備>**を建設する。別の**<灌漑整備>**と隣接できない。2ターンごとに付近に**<穀物>**を1つ生成する。付近の**<農地>**1つにつき**<都市発展度>**+1(上限2)を追加提供し、**<市場>**に追加**<ゴールド>**を提供する。**<山脈>**に隣接する、または少なくとも3つの**<浅瀬>**に隣接する**<平原>**タイル上に建設する必要がある。**<排水>**を研究後、少なくとも3つの**<平原>**に隣接する**<浅瀬>**タイル上にも建設可能。%$#@!**<관개 공사>**를 건설한다. 다른 **<관개 공사>**와 인접할 수 없다. 2턴마다 주변에 **<곡물>** 1칸을 생성한다. 주변 **<농지>** 1칸마다 **<도시 발전도>** +1(최대 2)을 추가 제공하고, **<시장>**에 추가 **<골드>**를 제공한다. **<산맥>**과 인접하거나, 최소 세 개의 **<천해>**와 인접한 **<평원>** 타일에 건설해야 한다. **<배수>** 연구 후에는 최소 세 개의 **<평원>**과 인접한 **<천해>** 타일에도 건설할 수 있다.%$#@!False%$#@!False%$#@!False%$#@!%$#@!False%$#@!False%$#@!False%$#@!%$#@!!@#$%30977%$#@!True%$#@![版本V0.7.5]
 发布日期 26.6.28
 
----------新内容与调整-------------
+---------新内容-------------
-1.联机模式可选择随机阵营
+1.新增阵营：博丽帝国
-2.茨木华扇Lv.3兽引附加的增益效果黄帝攻势提供攻击力加成调整为0.5
+2.新增功能：可在联机或单人对战中选择随机阵营
-3.宇佐见堇子能同时维系的灵异珠数量上限与英雄等级相同，超出数额时将自动拆毁最早设置的灵异珠
+
-4.小萃香生成时拥有攻击行动点与移动行动点，而非通用行动点
+---------调整-------------
-5.宇佐见堇子&茨木华扇的Lv2/Lv3升级要求从5/10次达成特定条件调整为6/12次。
+1.完善了基础能力"移动攻击"的效果以及显示，每回合仅能为当前单位提供1次额外的“攻击行动点”
+2.补充了9个文明的地理资料系统文案
 
 ------- [bug修复与优化] -------
-1.修复了博丽帝国叛乱者单位下水后可能错误变为长船的bug
+1.修复了若干科技树/能力/行动的文字描述及图标错误
-2.修复了犬走椛在部分情况下移动/行动表现异常，移动能力不符预期的bug
+2.修复了若干文本翻译错误
-3.修复了组队状态下使用投掷相关能力时，可能没有正确刷新视野的bug
+3.修复联机对局中，城市连续升级导致不同步的bug
-4.修复了星熊勇仪使用推动效果后，可能没有正确刷新视野的bug
+4.修复图鉴和游戏记录读取不完整的bug
-5.修复了高丽野阿吽在距离另一个阿吽8格距离时击杀地方单位可能出现画面异常的bug
+5.修复铃仙在幻想较多时发起攻击，“再攻”buff 失效。
-6.修复了高丽野阿吽在船上与陆地上可能出现等级不一致的bug
+6.修复御射宫司大人不被视作英雄衍生物。
-7.修复了单位直接站在斯卡雷特行宫生成的红雾上时，不会正确获得加成的bug
+7.修复犬走椛移动选项/移动范围显示异常，以及部分情况下移动/行动表现异常。
-8.修复了东风谷早苗掷出"大凶"或者"大吉“获得通用行动点时，错误额外刷新了移动攻击和逃脱效果的bug
+8.修复星熊勇仪推动敌方单位时未产生溅射伤害、推动后视野未正确刷新等bug
-9.修复了攻击Lv.2及以上的高丽野阿吽时，伤害类英雄任务会双倍计算的bug
+9.修复灵乌路空飞行视野获取错误、迷雾中错误看到地形/敌控信息、核融合预热与心理创伤共存时移动出错、击杀船只创建精魄身时报错等bug
-10.修复了非古明地帝国也能看到地块状态栏显示隐脉的bug
+10.修复东风谷早苗投出“大凶/大吉”后击杀单位棋子残留，以及获得通用行动点时错误刷新移动攻击能力的bug
-11.修复了神奈子在御柱古战场状态下升级时会自动切回常规状态的bug
+11.修复守矢帝国可将敌方山脉视作道路的bug
-12.修复了宇佐见堇子可在射程距离外设置灵异珠的bug
+12.修复八坂神奈子可从敌方山脉建筑获得加成，及御柱古战场状态下升级会切回常规状态的bug
-13.修复了古明地恋可以通过文化点复活的bug
+13.修复满血但处于“恐惧”状态的单位，回合结束有行动点也不会自动治疗的bug
-14.完善了城墙相关的效果描述
+14.通用单位 / 地图 / 规则
-15.完善了移动攻击/逃脱的描述和状态栏显示，现在可以清晰看到本回合是否还可激活效果
+15.修复船只通过文化点升级时需求数额偏少的bug
-16.修复了吸收茨木华扇Lv.3的兽引效果后会刷新移动攻击状态的bug
+16.修复单位直接站在斯卡雷特行宫生成的红雾上时，不会正确获得加成。
-17.修复了伊吹萃香Lv.4时使用大江山悉皆杀进入空地时未造成范围溅射伤害的bug
+17.完善了特殊地块类型(红雾地块/隐脉/英灵符文等等)的状态栏显示%$#@![版本V0.7.5]
-18.修复了女武神为伊吹萃香承伤时，其收到的伤害计入萃香升级任务的bug%$#@![版本V0.7.4i]
 發佈日期 26.6.28
 
----------新內容與調整-------------
+---------新增內容-------------
-1.聯機模式可選擇隨機陣營
+1.新增陣營：博麗帝國
-2.茨木華扇Lv.3獸引附加的增益效果黃帝攻勢提供攻擊力加成調整為0.5
+2.新增功能：可在聯機或單人對戰中選擇隨機陣營
-3.宇佐見堇子能同時維繫的靈異珠數量上限與英雄等級相同，超出數額時將自動拆毀最早設置的靈異珠
+
-4.小萃香生成時擁有攻擊行動點與移動行動點，而非通用行動點
+---------調整-------------
-5.宇佐見堇子&茨木華扇的Lv2/Lv3升級要求從5/10次達成特定條件調整為6/12次。
+1.完善了基礎能力「移動攻擊」的效果以及顯示，每回合僅能為目前單位提供1次額外的「攻擊行動點」
+2.補充了9個文明的地理資料系統文案
 
 ------- [bug修復與優化] -------
-1.修復了博麗帝國叛亂者單位下水後可能錯誤變為長船的bug
+1.修復了若干科技樹/能力/行動的文字描述及圖標錯誤
-2.修復了犬走椛在部分情況下移動/行動表現異常，移動能力不符預期的bug
+2.修復了若干文本翻譯錯誤
-3.修復了組隊狀態下使用投擲相關能力時，可能沒有正確刷新視野的bug
+3.修復聯機對局中，城市連續升級導致不同步的bug
-4.修復了星熊勇儀使用推動效果後，可能沒有正確刷新視野的bug
+4.修復圖鑑和遊戲記錄讀取不完整的bug
-5.修復了高麗野阿吽在距離另一個阿吽8格距離時擊殺敵方單位可能出現畫面異常的bug
+5.修復鈴仙在幻想較多時發起攻擊，「再次攻擊」buff 失效。
-6.修復了高麗野阿吽在船上與陸地上可能出現等級不一致的bug
+6.修復禦射宮司大人不被視作英雄衍生物。
-7.修復了單位直接站在斯卡雷特行宮生成的紅霧上時，不會正確獲得加成的bug
+7.修復犬走椛移動選項/移動範圍顯示異常，以及部分情況下移動/行動表現異常。
-8.修復了東風谷早苗擲出"大凶"或者"大吉"獲得通用行動點時，錯誤額外刷新了移動攻擊和逃脫效果的bug
+8.修復星熊勇儀推動敵方單位時未產生濺射傷害、推動後視野未正確刷新等bug
-9.修復了攻擊Lv.2及以上的高麗野阿吽時，傷害類英雄任務會雙倍計算的bug
+9.修復靈烏路空飛行視野獲取錯誤、迷霧中錯誤看到地形/敵控信息、核融合預熱與心理創傷共存時移動出錯、擊殺船隻創建精微身時報錯等bug
-10.修復了非古明地帝國也能看到地塊狀態欄顯示隱脈的bug
+10.修復東風谷早苗投出「大凶/大吉」後擊殺單位棋子殘留，以及獲得通用行動點時錯誤刷新移動攻擊能力的bug
-11.修復了神奈子在御柱古戰場狀態下升級時會自動切回常規狀態的bug
+11.修復守矢帝國可將敵方山脈視作道路的bug
-12.修復了宇佐見堇子可在射程距離外設置靈異珠的bug
+12.修復八阪神奈子可從敵方山脈建築獲得加成，及禦柱古戰場狀態下升級會切回常規狀態的bug
-13.修復了古明地戀可以通過文化點復活的bug
+13.修復滿血但處於「恐懼」狀態的單位，回合結束有行動點也不會自動治療的bug
-14.完善了城牆相關的效果描述
+14.通用單位 / 地圖 / 規則
-15.完善了移動攻擊/逃脫的描述和狀態欄顯示，現在可以清晰看到本回合是否還可激活效果
+15.修復船隻透過文化點升級時需求數額偏少的bug
-16.修復了吸收茨木華扇Lv.3的獸引效果後會刷新移動攻擊狀態的bug
+16.修復單位直接站在斯卡雷特行宮生成的紅霧上時，不會正確獲得加成。
-17.修復了伊吹萃香Lv.4時使用大江山悉皆殺進入空地時未造成範圍濺射傷害的bug
+17.完善了特殊地塊類型(紅霧地塊/隱脈/英靈符文等等)的狀態欄顯示%$#@![Version V0.7.5]
-18.修復了女武神為伊吹萃香承傷時，其收到的傷害計入萃香升級任務的bug%$#@![Version V0.7.4i]
 Release Date: 2026.6.28
 
---------- New Content and Adjustments -------------
+--------- New Content -------------
-1. Random faction selection is now available in online mode.
+1. New faction: Hakurei Empire
-2. Adjusted the Attack bonus from the Yellow Emperor Offensive buff applied by Kasen Ibaraki Lv.3 Beast Lure to 0.5.
+2. New feature: random faction can be selected in multiplayer or single-player matches
-3. The maximum number of Occult Orbs Sumireko Usami can maintain at once is now equal to her hero level. If the limit is exceeded, the earliest placed Occult Orb will be automatically destroyed.
+
-4. Mini Suika now spawns with Attack Action Points and Movement Action Points instead of General Action Points.
+--------- Adjustments -------------
-5. The Lv.2/Lv.3 upgrade requirements for Sumireko Usami and Kasen Ibaraki have been adjusted from meeting the specific condition 5/10 times to 6/12 times.
+1. Improved the effect and display of the basic ability "Move & Attack". It can only grant the current unit 1 extra "Attack Action Point" per turn
+2. Added geography system text for 9 civilizations
 
 ------- [Bug Fixes and Improvements] -------
-1. Fixed a bug where Hakurei Empire Rebel units could incorrectly become Longships after entering water.
+1. Fixed several text description and icon errors in tech trees, abilities, and actions
-2. Fixed a bug where Momiji Inubashiri's movement/action behavior could be abnormal in some situations, causing her mobility to differ from expectations.
+2. Fixed several text translation errors
-3. Fixed a bug where vision might not refresh correctly when using throw-related abilities while teamed.
+3. Fixed an out-of-sync bug caused by consecutive city level-ups in multiplayer matches
-4. Fixed a bug where vision might not refresh correctly after Yuugi Hoshiguma used a push effect.
+4. Fixed incomplete loading of Gallery and game records
-5. Fixed a bug where visuals could become abnormal when Aunn Komano killed an enemy unit while 8 tiles away from another Aunn.
+5. Fixed the "Attack Again" buff failing when Reisen attacked with many Fantasy stacks.
-6. Fixed a bug where Aunn Komano could have inconsistent levels between ship and land forms.
+6. Fixed Lord Mishaguji not being treated as a hero-derived unit.
-7. Fixed a bug where units standing directly on red mist generated by Scarlet Palace did not correctly receive bonuses.
+7. Fixed abnormal move options/movement range display for Momiji Inubashiri, plus abnormal movement/action presentation in some cases.
-8. Fixed a bug where Sanae Kochiya throwing "Great Misfortune" or "Great Fortune" and gaining General Action Points would incorrectly also refresh Move & Attack and Escape effects.
+8. Fixed bugs where Yuugi Hoshiguma did not deal splash damage when pushing enemy units, and vision did not refresh correctly after pushing
-9. Fixed a bug where damage-based hero quests were counted twice when attacking Aunn Komano at Lv.2 or above.
+9. Fixed bugs for Utsuho Reiuji: incorrect flying vision acquisition, terrain/enemy-control info visible through fog, movement errors when Nuclear Fusion Warm-up and Psychological Trauma coexisted, and errors when creating Subtle Body after killing ships
-10. Fixed a bug where non-Komeiji Empire players could see Hidden Vein on the tile status bar.
+10. Fixed lingering unit tokens after Sanae Kochiya killed units after drawing "Great Misfortune/Great Fortune", and Move & Attack being refreshed incorrectly when gaining General Action Points
-11. Fixed a bug where Kanako would automatically switch back to normal state when leveling up in Onbashira Ancient Battlefield state.
+11. Fixed Moriya Empire being able to treat enemy Mountains as roads
-12. Fixed a bug where Sumireko Usami could place Occult Orbs outside her attack range.
+12. Fixed Kanako Yasaka gaining bonuses from enemy Mountain buildings, and leveling up in Onbashira Battlefield state switching her back to normal state
-13. Fixed a bug where Koishi Komeiji could be resurrected with Culture Points.
+13. Fixed full-HP units under "Fear" not auto-healing at turn end even with available Action Points
-14. Improved descriptions for wall-related effects.
+14. Common Units / Map / Rules
-15. Improved Move & Attack/Escape descriptions and status bar display, making it clear whether the effect can still be triggered this turn.
+15. Fixed ship culture-point upgrade requirements being too low
-16. Fixed a bug where absorbing Kasen Ibaraki Lv.3 Beast Lure's effect would refresh Move & Attack state.
+16. Fixed units standing directly on Scarlet Mist generated by Scarlet Palace not receiving bonuses correctly.
-17. Fixed a bug where Ibuki Suika Lv.4 using Ooe-yama Total Slaughter to enter an empty tile did not deal area splash damage.
+17. Improved status bar display for special tile types (Scarlet Mist tiles / Hidden Pulse / Heroic Runes, etc.)%$#@![バージョンV0.7.5]
-18. Fixed a bug where damage taken by a Valkyrie on behalf of Ibuki Suika counted toward Suika's upgrade quest.%$#@![バージョンV0.7.4i]
+リリース日 26.6.28
-リリース日 2026/6/28
 
----------新内容と調整-------------
+---------新規内容-------------
-1.オンラインモードでランダム陣営を選択可能に
+1.新陣営：博麗帝国を追加
-2.茨木華扇Lv.3「獣引」が付与するバフ「黄帝攻勢」の攻撃力ボーナスを0.5に調整
+2.新機能：マルチプレイまたはシングルプレイ対戦でランダム陣営を選択可能
-3.宇佐見菫子が同時に維持できる霊異珠の上限が英雄レベルと同じになり、上限を超えると最も早く設置した霊異珠が自動的に撤去される
-4.小萃香は生成時、汎用行動ポイントではなく攻撃行動ポイントと移動行動ポイントを持つように
-5.宇佐見菫子と茨木華扇のLv2/Lv3アップグレード条件を、特定条件の達成5/10回から6/12回に調整。
 
-------- [バグ修正と改善] -------
+---------調整-------------
-1.博麗帝国の反乱者ユニットが水上に入った後、誤ってロングシップになる場合がある不具合を修正
+1.基礎能力「移動攻撃」の効果と表示を改善。現在のユニットに毎ターン追加の「攻撃行動ポイント」を1回だけ付与するように変更
-2.犬走椛が一部状況で移動/行動の表示が異常になり、移動能力が想定と異なる不具合を修正
+2.9文明分の地理資料システム文言を追加
-3.チーム状態で投擲関連能力を使用した際、視界が正しく更新されない場合がある不具合を修正
-4.星熊勇儀が押し出し効果を使用した後、視界が正しく更新されない場合がある不具合を修正
-5.高麗野あうんが別のあうんから8マス離れた位置で敵ユニットを撃破した際、画面異常が発生する場合がある不具合を修正
-6.高麗野あうんの船上と陸上でレベルが一致しない場合がある不具合を修正
-7.ユニットがスカーレット行宮によって生成された紅霧の上に直接立っている場合、ボーナスを正しく獲得しない不具合を修正
-8.東風谷早苗が「大凶」または「大吉」を投げて汎用行動ポイントを獲得した際、移動攻撃と逃走効果が誤って追加更新される不具合を修正
-9.Lv.2以上の高麗野あうんを攻撃した際、ダメージ系英雄任務が二重にカウントされる不具合を修正
-10.古明地帝国以外でもタイルステータスバーに隠脈が表示される不具合を修正
-11.神奈子が御柱古戦場状態でレベルアップした際、自動的に通常状態へ戻る不具合を修正
-12.宇佐見菫子が射程外に霊異珠を設置できる不具合を修正
-13.古明地こいしが文化ポイントで復活できる不具合を修正
-14.城壁関連効果の説明を改善
-15.移動攻撃/逃走の説明とステータスバー表示を改善し、このターン中に効果をまだ発動できるか明確に確認できるように
-16.茨木華扇Lv.3「獣引」の効果を吸収した後、移動攻撃状態が更新される不具合を修正
-17.伊吹萃香Lv.4で大江山悉皆殺を使用して空きマスに入った際、範囲スプラッシュダメージを与えない不具合を修正
-18.ヴァルキリーが伊吹萃香の代わりにダメージを受けた際、そのダメージが萃香のアップグレード任務にカウントされる不具合を修正%$#@![버전 V0.7.4i]
-출시일 2026.6.28
 
----------신규 콘텐츠 및 조정-------------
+------- [バグ修正と最適化] -------
-1.온라인 모드에서 무작위 진영 선택 가능
+1.いくつかの技術ツリー/能力/行動の説明文とアイコンの誤りを修正
-2.이바라키 카센 Lv.3 '수인'이 부여하는 버프 '황제 공세'의 공격력 보너스를 0.5로 조정
+2.いくつかの翻訳ミスを修正
-3.우사미 스미레코가 동시에 유지할 수 있는 영이주 상한이 영웅 레벨과 같아졌으며, 초과 시 가장 먼저 설치한 영이주가 자동 철거됩니다
+3.マルチプレイ対局で、都市の連続レベルアップにより同期ずれが発生する不具合を修正
-4.꼬마 스이카는 생성 시 범용 행동 포인트가 아니라 공격 행동 포인트와 이동 행동 포인트를 보유합니다
+4.ギャラリーとゲーム記録の読み込みが不完全になる不具合を修正
-5.우사미 스미레코와 이바라키 카센의 Lv2/Lv3 업그레이드 요구 조건을 특정 조건 5/10회 달성에서 6/12회 달성으로 조정했습니다.
+5.鈴仙が幻想スタックの多い状態で攻撃した際、「再攻撃」バフが無効になる不具合を修正
+6.御射宮司様が英雄派生ユニットとして扱われない不具合を修正
+7.犬走椛の移動選択肢/移動範囲表示の異常、および一部状況での移動/行動演出の異常を修正
+8.星熊勇儀が敵ユニットを押し出す際にスプラッシュダメージが発生しない、押し出し後に視界が正しく更新されない等の不具合を修正
+9.霊烏路空の飛行視界取得エラー、霧の中で地形/敵支配情報が見えてしまう問題、核融合予熱と心的外傷が共存した際の移動エラー、船を撃破して精微身を生成する際のエラー等を修正
+10.東風谷早苗が「大凶/大吉」を引いた後にユニットを撃破した際の駒残り、および汎用行動ポイント獲得時に移動攻撃能力が誤って更新される不具合を修正
+11.守矢帝国が敵の山脈を道路として扱える不具合を修正
+12.八坂神奈子が敵の山脈建築物からボーナスを得られる不具合、および御柱古戦場状態でレベルアップすると通常状態に戻る不具合を修正
+13.HP満タンで「恐怖」状態のユニットが、行動ポイントを持っていてもターン終了時に自動治療しない不具合を修正
+14.汎用ユニット / マップ / ルール
+15.船が文化ポイントでレベルアップする際の必要量が少なすぎる不具合を修正
+16.ユニットがスカーレット離宮の生成した紅霧上に直接立っている場合、ボーナスを正しく得られない不具合を修正
+17.特殊タイル種別(紅霧タイル/隠脈/英霊ルーンなど)のステータスバー表示を改善%$#@![버전 V0.7.5]
+출시일 26.6.28
 
-------- [버그 수정 및 개선] -------
+--------- 신규 콘텐츠 -------------
-1.하쿠레이 제국 반란자 유닛이 물에 들어간 뒤 롱쉽으로 잘못 변할 수 있던 버그 수정
+1. 신규 진영: 하쿠레이 제국
-2.이누바시리 모미지가 일부 상황에서 이동/행동 연출이 비정상적이고 이동 능력이 의도와 다르게 보이던 버그 수정
+2. 신규 기능: 멀티플레이 또는 싱글 플레이 대전에서 랜덤 진영 선택 가능
-3.팀 상태에서 투척 관련 능력을 사용할 때 시야가 올바르게 갱신되지 않을 수 있던 버그 수정
+
-4.호시구마 유기가 밀어내기 효과를 사용한 뒤 시야가 올바르게 갱신되지 않을 수 있던 버그 수정
+--------- 조정 -------------
-5.코마노 아운이 다른 아운과 8칸 떨어진 거리에서 적 유닛을 처치할 때 화면 이상이 발생할 수 있던 버그 수정
+1. 기본 능력 "이동 공격"의 효과와 표시를 개선. 매 턴 현재 유닛에게 추가 "공격 행동 포인트"를 1회만 제공
-6.코마노 아운이 선박 위와 육지에서 레벨이 일치하지 않을 수 있던 버그 수정
+2. 9개 문명의 지리 자료 시스템 문구 보충
-7.유닛이 스칼렛 행궁이 생성한 붉은 안개 위에 직접 서 있을 때 보너스를 올바르게 받지 못하던 버그 수정
+
-8.코치야 사나에가 "대흉" 또는 "대길"을 던져 범용 행동 포인트를 얻을 때 이동 공격과 탈출 효과가 잘못 추가 갱신되던 버그 수정
+------- [버그 수정 및 최적화] -------
-9.Lv.2 이상의 코마노 아운을 공격할 때 피해형 영웅 임무가 두 배로 계산되던 버그 수정
+1. 여러 기술 트리/능력/행동의 설명문 및 아이콘 오류 수정
-10.코메이지 제국이 아닌 경우에도 타일 상태 표시줄에 숨은 맥이 표시되던 버그 수정
+2. 여러 텍스트 번역 오류 수정
-11.카나코가 온바시라 고전장 상태에서 레벨업할 때 자동으로 일반 상태로 돌아가던 버그 수정
+3. 멀티플레이 대전에서 도시 연속 레벨 업으로 동기화가 어긋나는 버그 수정
-12.우사미 스미레코가 사거리 밖에 영이주를 설치할 수 있던 버그 수정
+4. 갤러리와 게임 기록을 불완전하게 읽어오던 버그 수정
-13.코메이지 코이시가 문화 포인트로 부활할 수 있던 버그 수정
+5. 레이센이 환상 스택이 많은 상태에서 공격할 때 "재공격" 버프가 무효화되던 문제 수정.
-14.성벽 관련 효과 설명 보완
+6. 미샤구지 님이 영웅 파생 유닛으로 취급되지 않던 문제 수정.
-15.이동 공격/탈출 설명과 상태 표시줄 표시를 보완하여 이번 턴에 효과를 아직 발동할 수 있는지 명확히 확인할 수 있게 했습니다
+7. 이누바시리 모미지의 이동 선택지/이동 범위 표시 이상 및 일부 상황에서의 이동/행동 연출 이상 수정.
-16.이바라키 카센 Lv.3 수인 효과를 흡수한 뒤 이동 공격 상태가 갱신되던 버그 수정
+8. 호시구마 유우기가 적 유닛을 밀어낼 때 범위 공격 피해가 발생하지 않거나, 밀어낸 뒤 시야가 올바르게 갱신되지 않던 문제 등 수정
-17.이부키 스이카 Lv.4에서 오에산 싯카이고로시를 사용해 빈 타일로 들어갈 때 범위 스플래시 피해가 발생하지 않던 버그 수정
+9. 레이우지 우츠호의 비행 시야 획득 오류, 안개 속에서 지형/적 통제 정보가 잘못 보이던 문제, 핵융합 예열과 심리적 상처가 공존할 때 이동 오류, 선박 처치 후 정미신 생성 시 오류 등 수정
-18.발키리가 이부키 스이카 대신 피해를 받을 때 해당 피해가 스이카 업그레이드 임무에 계산되던 버그 수정%$#@!False%$#@!False%$#@!False%$#@!%$#@!False%$#@!False%$#@!False%$#@!%$#@!!@#$%
+10. 코치야 사나에가 "대흉/대길"을 뽑은 뒤 유닛을 처치했을 때 말이 남는 문제 및 범용 행동 포인트 획득 시 이동 공격 능력이 잘못 갱신되던 버그 수정
+11. 모리야 제국이 적 산맥을 도로처럼 취급할 수 있던 버그 수정
+12. 야사카 카나코가 적 산맥 건축물에서 보너스를 얻을 수 있던 문제 및 온바시라 고전장 상태에서 레벨 업하면 일반 상태로 돌아가던 버그 수정
+13. HP가 가득 찼지만 "공포" 상태인 유닛이 턴 종료 시 행동 포인트가 있어도 자동 치료하지 않던 버그 수정
+14. 범용 유닛 / 맵 / 규칙
+15. 선박이 문화 포인트로 레벨 업할 때 요구량이 지나치게 적던 버그 수정
+16. 유닛이 스칼렛 별궁이 생성한 홍무 위에 직접 서 있을 때 보너스를 올바르게 받지 못하던 문제 수정.
+17. 특수 타일 유형(홍무 타일/은맥/영령 룬 등)의 상태 표시줄 표시 개선%$#@!False%$#@!False%$#@!False%$#@!%$#@!False%$#@!False%$#@!False%$#@!%$#@!!@#$%