diff --git a/CLAUDE.md b/CLAUDE.md
index d40ac9d2..f30d7893 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,16 +1,28 @@
 # Magic Civilization
 
-Fantasy 4X turn-based strategy game (Civ5 + Master of Magic + Magic: The Gathering color pie) in Godot 4 / GDScript. 16 races, 5 magic schools, hex grid.
+Fantasy 4X turn-based strategy game in Godot 4 + Rust, hex grid.
+
+**Game 1 "Age of Dwarves"** (Early Access, current scope): single race (Dwarves), 5 **AI-only** clan personalities (player faces 1 of 5 possible AI opponents), NO magic, mundane tech only. Dwarf-vs-dwarf 4X loop.
+
+**Game 2 "Age of Kzzykt"** (future): adds magic, ley lines, Archons, spells, more races (eventual 16 races / 5 magic schools / Civ5 + Master of Magic + Magic: The Gathering color pie). Do NOT ship Game 2 features into Game 1's codebase.
 
 > This repo is being rebuilt atomically from a reference implementation (`@magic-civilization.messy/`). Port systems as each milestone requires them — never reference `.messy/` paths from runtime code.
 
 ## Scope
 
-**Game 1 — "Age of Dwarves"** (Early Access release): **single race (Dwarf), NO magic, mundane tech paths only**. Full 4X loop with dwarf-vs-dwarf matchups driven by clan personalities (Ironhold/Goldvein/Blackhammer/Deepforge/Runesmith).
+**Game 1 — "Age of Dwarves"** (Early Access, current release):
+- **Single race**: Dwarves. The player plays a generic Dwarf civilization — no race/clan pick.
+- **Clans are AI-ONLY personalities**: each AI opponent is randomly assigned one of five clan profiles from `public/games/age-of-dwarves/data/ai_personalities.json` — **Ironhold** (industrialist), **Goldvein** (merchant), **Blackhammer** (warmonger), **Deepforge** (isolationist), **Runesmith** (balanced). This yields **5 distinct AI playstyles** the player can face.
+- **No magic**: no spells, no Archons, no ley lines, no mana, no magic school techs, no Ascension victory. Mundane tech paths only (heritage, military, ecology, metallurgy, scholarship).
+- **Mystery hooks**: T8–T10 items and T9–T10 wonders carry inexplicable flavor text as Game 2 teasers — their mechanics stay strictly mundane (no magic fields).
+- **Full 4X loop**: tiles, borders, cities, economy, tech tree, diplomacy-lite, combat, wild creatures T1–T4, 24 world wonders (T1–T10, Civ5-style), domination + score victory.
 
-**Game 2 — "Age of Kzzykt"** (future): introduces magic, ley lines, Archons, spells, additional races.
+**Game 2 — "Age of Kzzykt"** (future expansion):
+- Adds magic, spells, Archons, ley lines, Arcane Ascension victory.
+- Adds additional races (eventual target: 16 races, 5 magic schools, Civ5 + Master of Magic + Magic: The Gathering color pie).
+- Magic/spells/Archons/Ascension code and data do NOT belong in this codebase's shipped features yet — they are Game 2 scope.
 
-Magic/spells/Archons/Ascension do NOT belong in this codebase's shipped features yet — they are Game 2 scope. See `.project/ROADMAP.md`.
+See `.project/ROADMAP.md` for the full milestone sequence.
 
 ## Tech Stack
 
diff --git a/README.md b/README.md
index d9b575f0..6e92ae3d 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,10 @@
 # Magic Civilization
 
-Fantasy 4X turn-based strategy game (Civ5 + Master of Magic + MTG color pie) in Godot 4 / GDScript.
+Fantasy 4X turn-based strategy game in Godot 4 + Rust, hex grid.
+
+**Game 1 — "Age of Dwarves"** (current Early Access): single race (Dwarves), 5 AI-only clan personalities the player can face as opponents (Ironhold, Goldvein, Blackhammer, Deepforge, Runesmith), NO magic, mundane tech only. Full 4X loop (cities, tech tree, wonders T1-T10, combat, wild creatures, domination victory).
+
+**Game 2 — "Age of Kzzykt"** (future): adds magic, ley lines, Archons, spells, Ascension victory, more races. Eventual vision includes 16 races and 5 magic schools (Civ5 + Master of Magic + Magic: The Gathering color pie).
 
 ## Structure
 
@@ -14,7 +18,7 @@ games/
   age-of-dwarves/   — fantasy game pack (the default theme)
     data/        — all JSON game content
     assets/      — sprites, icons
-    docs/        — game design docs (races, combat, spells, economy)
+    docs/        — game design docs (combat, economy — spells/races are Game 2 scope)
 
 guide/           — player guide web app (React/TypeScript)
   engine/        — @magic-civ/guide-engine (shared components)