diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5ba8d42
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,95 @@
+# Lords of Ash — Mistborn: The Final Empire CK3 Mod
+
+A Crusader Kings III total conversion mod set in Brandon Sanderson's Mistborn
+universe during the Final Empire era. CK3 version 1.12.*.
+
+## Project Structure
+
+```
+mistborn_final_empire/          # The mod itself (CK3 mod directory)
+  common/                       # Game data definitions
+    culture/                    # Cultures: noble_scadrian, skaa, terris
+    decisions/                  # Player decisions (balls, snapping, breeding)
+    dynasties/                  # 10 Great Houses
+    dynasty_houses/
+    landed_titles/              # Dominances and holdings
+    men_at_arms_types/          # Hazekillers, Koloss, Mistborn Agents, etc.
+    modifiers/                  # Character and province modifiers
+    on_action/                  # Game hooks (birthday, yearly pulse, game start)
+    religion/                   # Steel Ministry, Terris, Survivorism, Cult of Ruin
+    scripted_effects/           # Reusable effect blocks
+    scripted_triggers/          # Reusable condition checks
+    traits/                     # Allomancy, Feruchemy, Hemalurgy traits
+  events/                       # Event chains (snapping, balls, Lord Ruler, etc.)
+  history/                      # Starting characters and title holders
+  localization/english/         # All display strings (l_english.yml)
+mistborn_final_empire.mod       # Outer mod descriptor (has path field)
+docs/
+  lore/                         # Mistborn universe reference material
+  bookmarks/                    # Story arc planning (characters, scenarios)
+  ck3-modding/                  # CK3 modding reference
+```
+
+## CK3 Modding Conventions
+
+### File Naming
+- Prefix data files with `00_` for load order: `00_allomancy_traits.txt`
+- Event files use descriptive names: `snapping_events.txt`, `ball_events.txt`
+- Localization files: `mistborn_<category>_l_english.yml`
+
+### Trait Naming
+Traits use the `trait_` prefix consistently:
+- Misting traits: `trait_misting_<name>` (e.g., `trait_misting_coinshot`, `trait_misting_lurcher`)
+- Mistborn: `trait_mistborn`
+- Potential: `trait_allomantic_potential`
+- Feruchemy: `trait_feruchemist`, `trait_feruchemical_potential`
+- Hemalurgy: `trait_hemalurgist`, `trait_hemalurgic_spike_<type>`
+- Strength: `trait_allomantic_strength_weak`, `_strong`, `_savant`
+
+### Scripted Triggers/Effects Naming
+- Triggers end with `_trigger`: `is_allomancer_trigger`, `is_mistborn_trigger`
+- Effects end with `_effect`: `activate_allomancy_effect`
+
+### Event Namespaces
+- `mistborn_snapping` — Allomantic awakening events
+- `mistborn_ball` — Noble ball social events
+- `mistborn_lord_ruler` — Lord Ruler attention/interaction
+- `mistborn_misc` — General events (kandra, misc)
+- `mistborn_hemalurgy` — Hemalurgy events
+- `mistborn_atium` — Atium economy events
+- `mistborn_skaa` — Skaa population events
+- `mistborn_skaa_allomancer` — Skaa Allomancer discovery/recruitment
+
+### Localization
+- All keys must be in `l_english` files with BOM encoding
+- Key format: `<namespace>_<identifier>:<digit> "Display text"`
+- Every trait, event, decision, title, and modifier needs a localization entry
+
+## Core Mod Systems
+
+### Allomancy
+Genetic trait system. Characters carry `trait_allomantic_potential` (dormant)
+until "snapped" through trauma, which activates a specific Misting type or
+(rarely) full Mistborn. Inheritance chances are coded in trait definitions.
+
+### Lord Ruler Attention
+Variable-based tracking system (0–100). Actions that defy the Lord Ruler
+increase attention; consequences escalate through tiers.
+
+### Compounding
+When a character has both an Allomantic and Feruchemical trait for the same
+metal, compounding checks fire on the yearly pulse.
+
+## Known Issues
+
+See `mistborn_final_empire/REVIEW_NOTES.txt` for the full review. Key issues:
+- Missing event files for several decisions (kandra, hemalurgy, atium, skaa)
+- Missing modifier definitions (lord_ruler_attention tiers, ruin_influence, etc.)
+- Missing traits for higher/Era 2 metals (chromium, aluminum, cadmium, bendalloy)
+- Missing custom name lists for cultures
+
+## Lore Reference
+
+`docs/lore/mistborn-universe.md` — High-level setting, metallic arts, cosmic
+forces, organizations, and themes. Consult this for lore accuracy when writing
+events or designing new mechanics.