# 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.18.*.

## Project Structure

```
lords_of_ash/          # The mod itself (CK3 mod directory)
  common/                       # Game data definitions
    artifacts/                  # Artifact types, slots, visuals (9 Mistborn artifacts)
    bookmarks/bookmarks/        # Bookmark definitions (CK3 nested convention)
    buildings/                  # Special buildings (Kredik Shaw, Pits, Conventical)
    character_interactions/      # Inquisitor interactions (investigate, interrogate)
    culture/                    # Cultures: noble_scadrian, skaa, terris
      name_lists/               # Custom name lists per culture
    deathreasons/               # Custom Mistborn death causes
    decisions/                  # Player decisions (balls, snapping, breeding, crafting)
    dynasty_legacies/           # Universal + house-specific legacy trees
    dynasties/                  # 10 Great Houses + Rashek + Terris Stewards
    dynasty_houses/
    education/                  # Custom education focuses (5 Mistborn tracks)
    holy_orders/                # Steel Inquisitor order, Keeper Network
    landed_titles/              # Dominances and holdings
    men_at_arms_types/          # Hazekillers, Koloss, Mistborn Agents, Inquisitor Squad
    modifiers/                  # Character and province modifiers
    nicknames/                  # Custom Mistborn nicknames
    on_action/                  # Game hooks (birthday, yearly pulse, game start)
    opinion_modifiers/          # Opinion modifiers (e.g., disapproves_skaa_mercy)
    religion/                   # Steel Ministry, Terris, Survivorism, Cult of Ruin
      doctrines/                # Custom Scadrial doctrines and tenets
      holy_sites/               # 10 faith-differentiated holy sites
      religion_families/        # Religion family definitions (rf_scadrial)
    scripted_effects/           # Reusable effect blocks
    scripted_triggers/          # Reusable condition checks
    traits/                     # Allomancy, Feruchemy, Hemalurgy, Kandra, Education traits
  events/                       # Event chains (snapping, balls, Lord Ruler, etc.)
  history/                      # Starting characters and title holders
  localization/english/         # All display strings (l_english.yml)
lords-of-ash.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
- `mistborn_inquisitor` — Steel Inquisitor interactions and events
- `mistborn_keeper` — Keeper Network events
- `mistborn_education` — Custom education track events

### 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 `lords_of_ash/REVIEW_NOTES.txt` for the full review. Key open issues:
- No custom map data — mod reuses vanilla Swiss provinces (NOTE-02, planned for M8)
- Vanilla dependencies remain for ethoses, traits, and GFX (WARNING-02/03/04)

## Committing

Always use the `/commit` skill when committing changes. Never commit without
invoking it — it enforces conventional commit format, logical grouping, and
changelog maintenance.

## Skills

Always create skills in project scope (`.claude/skills/`) for this project, not
in user scope (`~/.claude/skills/`).

## 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.