lords-of-ash/MASTERPLAN.md

# MASTERPLAN — Lords of Ash

## Vision

A Crusader Kings III total conversion set in Brandon Sanderson's Mistborn: The
Final Empire. The player experiences the world of Scadrial through the "End of
an Empire" bookmark — playing as Kelsier leading his unlanded crew, or as Vin
navigating a world of noble intrigue and Allomantic power. A game rule toggle
lets players choose between Narrative Mode (curated story arcs following the
book's plot) and Sandbox Mode (play any character, acquire metallic arts via
decision). The mod is rich with Sanderson lore, features a custom Scadrial map,
full graphics, and deep event content.

**Done** means: Steam Workshop release quality. A player installs the mod, picks
the "End of an Empire" bookmark, chooses Kelsier or Vin, and plays through a
complete Mistborn: The Final Empire experience — from crew assembly through the
Fall of Kredik Shaw — on a custom Scadrial map with custom art, polished
balance, and clean error logs. Alternatively, they can flip to Sandbox Mode and
play any house lord with full metallic arts mechanics.

**DLC dependencies:** Roads to Power (unlanded adventurer band system), Royal
Court (artifact system).

---

## Current State

Strong foundation, not yet playable.

**What exists:**
- 12 Misting traits + Mistborn + strength tiers + potentials
- Feruchemy (full Feruchemist + potential)
- Hemalurgy (5 spike types + Inquisitor creation)
- Compounding detection on yearly pulse
- Lord Ruler Attention system (0-100, 3-tier escalation events)
- 4 religions (Steel Ministry, Terris, Survivorism, Cult of Ruin), 5 holy sites
- 3 cultures (noble_scadrian, skaa, terris) with pillars and traditions
- 10 dynasties (Great Houses), 20+ placeholder characters
- 5 kingdoms, duchies, counties, baronies mapped to vanilla Swiss provinces
- 4 decisions (balls, snapping, kandra, hemalurgy)
- 8 event files (~2,700 lines, several are stubs)
- 4 men-at-arms types
- Full localization coverage (874 lines across 9 files)
- Bookmark definition (bm_end_of_an_empire) with 4 placeholder characters

**What's missing or broken:**
- Province history files are empty (mod may crash on load)
- `@#` comment syntax in several files (CK3 uses `#`)
- Characters are placeholders, not canonical Mistborn figures
- No custom map (using vanilla provinces)
- No graphics (trait icons, portraits, loading screens)
- No unlanded band system
- No custom name lists
- No vanilla content suppression (vanilla decisions bleed through)
- No game rule definitions
- No custom buildings, schemes, or casus belli
- Several event files are stubs (~20% content)
- Lord Ruler not implemented as a character
- `e_final_empire` has no holder

---

## Milestones

Each milestone is a **playtesting anchor** — the mod loads, the new features are
functional enough to test, and friends can give feedback. Rough edges and
placeholder content are acceptable. Steam-release polish happens in M8.

---

### M1: Foundation

*The mod loads and plays cleanly on the vanilla map.*

**Scope:**
- Fix province history — create `history/provinces/` files assigning culture,
  religion, and holdings for all mapped provinces
- Fix `@#` comment syntax to `#` in all affected files
- Verify all modifier definitions exist and match their localization keys
- Fix scripted trigger issues:
  - `is_feruchemist_trigger` should not match dormant potential
  - `has_allomantic_potential_trigger` should distinguish active vs dormant
- Unify the dual Lord Ruler attention system (variable-based + modifier-based)
- Suppress vanilla decisions that break immersion — create empty replacement
  files in `common/decisions/` for vanilla decision files
- Define game rule infrastructure in `common/game_rules/` (Narrative vs Sandbox
  toggle, even if not yet meaningful)
- Boot test — load mod, verify error.log is clean, play 5 years

**Key files:**
- `history/provinces/` — new files (one per province or grouped by dominance)
- `common/scripted_triggers/mistborn_triggers.txt`
- `common/scripted_effects/mistborn_effects.txt`
- `common/modifiers/00_mistborn_modifiers.txt`
- `common/game_rules/` — new directory and file
- `common/decisions/` — vanilla suppression files

**Exit criteria:** Mod loads with no errors. No vanilla decisions visible. Game
rule appears in setup screen. Play a landed noble for 5 years without crashes.

---

### M2: The Metallic Arts

*All metallic arts systems are complete and tested.*

**Scope:**
- Validate and polish all Allomancy traits — inheritance chances, trait
  interactions, icon references
- Complete the snapping event chain — all outcomes, edge cases, forced snapping
- Add Allomantic Training event chain (education-style, mentor teaches pupil,
  choices influence specialization, grants `allomantic_strong` on completion)
- Validate Feruchemy system — ensure Terris-only inheritance, Keeper mechanics
- Validate Hemalurgy — spike application events, Inquisitor creation, Ruin
  influence consequences
- Validate Compounding — yearly pulse detection, correct trait pair matching,
  compounder modifier balanced
- Add savant consequences (negative effects for `trait_allomantic_savant`)
- Add metal supply and scarcity system — Allomantic power depends on access to
  metals. Noble houses maintain reserves (gold cost), skaa use black markets
  (risk of discovery). Supply modifiers (abundant/low/depleted) affect combat
  stats. Wartime consumption, depletion events, resupply decisions.
- Balance men-at-arms types (Hazekillers, Koloss, Mistborn Agents) — damage,
  toughness, cost, terrain modifiers
- Polish existing event files — complete stub events in `hemalurgy_events.txt`,
  `atium_events.txt`, `skaa_events.txt`, `skaa_allomancer_events.txt`
- Add Sandbox Mode decision: "Discover Your Metallic Arts" — lets any character
  test for Allomantic/Feruchemical potential (only in Sandbox game rule)
- Localization for all new content

**Key files:**
- `common/traits/` — all 6 trait files
- `events/snapping_events.txt`
- `events/hemalurgy_events.txt`, `atium_events.txt`, `skaa_events.txt`,
  `skaa_allomancer_events.txt`
- `common/on_action/mistborn_on_actions.txt`
- `common/decisions/00_mistborn_decisions.txt`
- `localization/english/mistborn_traits_l_english.yml`
- `localization/english/mistborn_events_l_english.yml`

**Exit criteria:** Snap a character into a Misting or Mistborn. Train an
Allomancer pupil. Create a Steel Inquisitor via Hemalurgy. Trigger Compounding.
Use Sandbox decision to gain powers. All metallic arts events fire correctly.

---

### M3: The Final Empire

*Canonical characters populate the world. The Lord Ruler looms over everything.*

**Scope:**
- Design and implement the Lord Ruler as off-map religious head:
  - Change Steel Ministry doctrine from `doctrine_no_head` to spiritual head
  - Create Lord Ruler as immortal character (Compounder: Allomancy + Feruchemy +
    atium bracers)
  - Assign as `e_final_empire` holder and Steel Ministry religious head
  - Make non-playable via scripted trigger or game rule
  - Lord Ruler attention events now reference him directly
- Create canonical characters with appropriate traits:
  - **Kelsier** — Mistborn, ambitious, brave, scarred (Pits survivor)
  - **Vin** — Mistborn potential (pre-snap), paranoid, young
  - **Sazed** — Feruchemist, Terris Keeper, scholarly
  - **Breeze** — Soother, noble-born skaa
  - **Ham** — Thug, philosophical
  - **Clubs** — Smoker, gruff veteran
  - **Dockson** — no Allomancy, organizer
  - **Marsh** — Seeker, later Inquisitor
  - **Yeden** — skaa rebel leader
  - **OreSeur** — kandra (needs kandra trait)
  - **Elend Venture** — heir to House Venture, bookish
  - **Straff Venture** — head of House Venture, Tineye
  - **Shan Elariel** — Mistborn, noble rival
  - **Steel Inquisitors** — Hemalurgic super-soldiers
  - Other Great House heads matching existing dynasties
- Keep or rework existing placeholder characters as minor nobles where they fit
- Create custom name lists for all 3 cultures in
  `common/culture/name_lists/` — male, female, dynasty names drawn from
  Mistborn lore
- Create special buildings in `common/buildings/`:
  - **Kredik Shaw** (Luthadel) — unique palace, prestige and control bonuses,
    holy site building
  - **Pits of Hathsin** — atium generation, tyranny cost, built by Lord Ruler
  - **Conventical of Seran** — Inquisitor base, dread and martial bonuses
- Deep religion overhaul with custom tenets and doctrines:
  - 12 custom tenets (3 per faith) replacing vanilla placeholders: Obligator
    Hierarchy, Allomantic Oversight, Imperial Mandate (Steel Ministry); Keeper's
    Vow, Metalmic Preservation, Worldbringer Mission (Terris); Kelsier's
    Sacrifice, Hope in Ash, Underground Network (Survivorism); Hemalurgic Rites,
    Embrace Destruction, Ruin's Whispers (Cult of Ruin)
  - 2 custom doctrine groups: Allomantic Stance (Divine/Controlled/Forbidden),
    Caste Doctrine (Divine Order/Irrelevant/Tool)
  - Expanded holy sites (~10 total, differentiated by faith) with conditional
    sites (Kelsier's Pyre activates on martyrdom, Well of Ascension on endgame)
  - Terris Keepers: secret faith mechanics
  - Survivorism: rebellion bonuses
  - Cult of Ruin: Hemalurgy bonuses
- Holy orders: Steel Inquisitor order (hireable MaA + individual Inquisitor
  request mechanic with unique interactions) and Keeper Network (secret society
  with joining, progression, coppermind sharing, Ministry discovery risk)
- Add kandra trait and kandra Contract mechanics (kandra characters are
  shapeshifters bound by Contracts)
- Custom education system with 5 tracks mapped to lifestyles: Allomantic
  Training (→Metallic Arts), Noble Court Education (→Noble Intrigue), Ministry
  Indoctrination (→Steel Ministry), Skaa Survival (→Underground), Keeper
  Apprenticeship (→Scholarship). 20 education traits (4 tiers × 5 tracks),
  snapping can trigger during Allomantic Training, Keeper education produces
  network initiates. Suppress vanilla education.
- Dynasty legacies: 5 universal legacy trees (Allomantic Bloodline, Political
  Dominance, Ministry Connections, Metallurgic Wealth, Underground Network) with
  5 tiers each, plus 10 house-specific 3-tier legacies for each Great House.
- Custom death reasons (12 Mistborn-specific causes) and ~15 character nicknames
  ("the Survivor," "Ash Lord," "the Liberator," etc.).
- Create artifact system (Royal Court DLC) with 9 core types: mistcloaks,
  metal vial sets, glass/obsidian weapons, dueling canes, koloss swords,
  copperminds, metalmind sets, Lord Ruler's atium bracers (unique legendary),
  Inquisitor spike sets. Crafting decisions, equipment restrictions by trait,
  starting artifacts for canonical characters.

**Key files:**
- `history/characters/00_mistborn_characters.txt` — major rewrite
- `history/titles/00_mistborn_titles.txt` — reassign to canonical characters
- `common/religion/religions/00_scadrial_religions.txt`
- `common/culture/name_lists/` — new directory
- `common/buildings/` — new directory
- `common/landed_titles/00_landed_titles.txt` — add special building slots
- `localization/english/` — significant new localization

**Exit criteria:** Start the game. Kelsier, Vin, Elend, and the Lord Ruler
exist in the world. Lord Ruler is religious head of Steel Ministry. Kredik Shaw
and Pits of Hathsin have special buildings. Names are Scadrial-appropriate.

---

### M4: Scadrial on the Map

*The vanilla map feels like Scadrial. The mod is shareable.*

**Scope:**
- Relabel all vanilla provinces with Scadrial names in localization (players see
  "Luthadel" not "Bern")
- Set terrain types that evoke Scadrial:
  - Mountains → Ashmounts
  - Wasteland/desert → Ash plains
  - Urban → Luthadel, major cities
  - Hills → mining regions
- Add province modifiers:
  - `ash_blight` on ashmount-adjacent provinces
  - `mist_heavy` on certain provinces (Allomancer snapping bonus)
  - `fertile_ashland` on the few productive regions
- Suppress remaining vanilla bleed-through:
  - Empty replacement files for vanilla events that break immersion
  - Suppress vanilla GUI text where possible via localization overrides
- Create custom casus belli in `common/casus_belli_types/`:
  - House War (noble house vs noble house)
  - Rebellion (skaa vs noble/Lord Ruler)
  - Inquisition Purge (Steel Ministry vs heretics)
  - Dominance Claim (claim a Dominance title)
- Create custom schemes in `common/schemes/`:
  - Noble Infiltration (spy on a house via balls and agents)
  - Raid House Vault (steal gold, reduce control)
  - False Flag (hostile action that frames a third party)
- Replace all 5 vanilla lifestyles with Mistborn-themed ones: Metallic Arts
  (Allomantic Mastery / Feruchemical Study / Hemalurgic Research), Noble
  Intrigue (Ball Culture / House Espionage / Contract & Commerce), Steel
  Ministry (Obligator's Path / Inquisition / Canton Authority), Underground
  (Crew Leadership / Guerrilla Warfare / Shadow Network), Scholarship
  (Keeper's Path / Metallurgic Theory / Imperial History). ~75 perks, ~75
  lifestyle events, full perk trees with synergies to other mod systems.
- Replace/retheme vanilla activities: suppress pilgrimage/tournament/grand tour,
  retheme feast (Noble Banquet), hunt (Mist Patrol), wedding (House Alliance
  Ceremony). Promote Noble Ball to full multi-phase activity (7 phases: guest
  selection through departure, with Allomantic interactions at every phase).
- Full custom council system: retheme all 5 council positions (Obligator
  Liaison, Hazemaster, House Comptroller, House Informant, Ministry Preceptor)
  with 10 custom council tasks that interact with Lord Ruler attention, metal
  supply, skaa unrest, and Allomantic trait systems. 7 custom court positions
  (Royal Court): Terris Steward, Kandra Agent, Allomantic Advisor, Hazekiller
  Captain, Obligator Witness, Court Smoker, Master of Revels. Each with
  passive bonuses and special effects. Suppress/retheme vanilla positions.
- Caste law system: 3-tier caste laws (Strict/Relaxed/Abolished) enforcing the
  noble/skaa divide. Cross-caste consequence events (affair discovery, half-skaa
  children, hidden heritage exposure). Post-rebellion law repeal pathway.
- Cultural innovation system: "Age of the Lord Ruler" era (~8 pre-unlocked
  innovations representing Imperial stagnation) and "Age of Liberation" era (~8
  innovations locked until the Lord Ruler falls). Keeper Network accelerates
  post-rebellion research. Vanilla eras fully suppressed.
- Custom government types: Imperial Appointment (noble houses, no partition,
  Lord Ruler appoints), Theocratic Ministry (Steel Ministry cantons, piety
  focus), Post-Rebellion Elective (council election after Lord Ruler falls).
  Suppress vanilla feudal/tribal.
- Custom factions: Skaa Rebellion, Ministry Loyalist, Noble Reform, Keeper
  Underground, Cult of Ruin. Each with setting-appropriate demands and
  ultimatums. Lord Ruler can intervene against factions.
- Custom vassal contracts: Plantation Tribute, House Guard Obligation, Atium
  Tithe, Allomantic Service, Inquisition Access, Title Revocation. Mistborn-
  specific terms with Lord Ruler attention interactions.
- Custom secret types (8): secret Allomancer, hidden skaa heritage, Keeper
  identity, kandra imposter, atium hoard, crew membership, Ministry informant,
  secret Survivorist. Custom hooks from secret discovery. Integrates with
  Inquisitor investigation and council tasks.
- Custom court types (Royal Court): Noble Keep (grand, political), Ministry
  Canton (austere, bureaucratic), Underground Hideout (rebel, secretive).
- Portrait modifier system (triggers defined, art in M8): hemalurgic spike
  eyes, Allomancer burn marks, ash-stained clothing, Terris robes, mistcloaks.
- Full testing pass — error.log review, 20-year playthrough, verify no vanilla
  anachronisms visible

**Key files:**
- `localization/english/mistborn_titles_l_english.yml` — province renames
- `common/casus_belli_types/` — new directory
- `common/schemes/` — new directory
- `common/council_positions/00_mistborn_council.txt` — rethemed council
- `common/council_tasks/00_mistborn_council_tasks.txt` — custom tasks
- `common/court_positions/00_mistborn_court_positions.txt` — court roles
- `common/laws/00_mistborn_laws.txt` — caste laws
- `common/culture/innovations/00_scadrial_innovations.txt` — custom eras
- `common/governments/00_mistborn_governments.txt` — custom governments
- `common/factions/00_mistborn_factions.txt` — custom factions
- `common/vassal_contracts/00_mistborn_contracts.txt` — custom contracts
- `common/secret_types/00_mistborn_secrets.txt` — custom secrets
- `common/court_types/00_mistborn_court_types.txt` — court types
- Province modifier definitions in `common/modifiers/`
- `localization/english/` — massive expansion

**Exit criteria:** A friend can install the mod and play. The world feels like
Scadrial — Scadrial names, ash terrain, Mistborn mechanics, caste system,
Imperial government, custom factions, no vanilla anachronisms. All core CK3
systems are Mistborn-themed.

---

### M5: The Crew

*Play as Kelsier's unlanded band. The bookmark works.*

**Scope:**
- Research Roads to Power adventurer band mechanics — understand band creation,
  member management, decisions, event scoping, interaction with landed system
- Implement Kelsier's crew as adventurer band:
  - Kelsier as band leader
  - Vin, Breeze, Ham, Clubs, Dockson, Marsh, Yeden, OreSeur as band members
  - Vin playable as non-leader (investigate if CK3 supports this natively or if
    events/decisions must simulate it)
  - On Kelsier's death: Vin becomes band leader via event (martyrdom mechanic)
- Create/update the "End of an Empire" bookmark:
  - Kelsier (unlanded crew, difficulty: medium)
  - Vin (crew member, difficulty: hard) — if non-leader play is feasible;
    otherwise Vin is Kelsier's heir and unlocks on death
  - Optional: keep 1-2 landed starts for house play (Elend Venture, etc.)
- Activate game rule toggle:
  - Narrative Mode: Kelsier/Vin bookmark, curated events fire
  - Sandbox Mode: any character, "Discover Your Metallic Arts" decision
    available, narrative events suppressed
- Crew-specific decisions:
  - Recruit a crew member (if starting with partial crew)
  - Plan the next operation (menu decision branching to arcs)
  - Lay low (reduce Lord Ruler attention at cost of momentum)
- Non-DLC fallback: if Roads to Power not detected, Kelsier starts as landed
  minor lord of a Luthadel slum barony

- Band council system: 7 crew roles (Crew Leader, Crew Second, Smoker,
  Soother/Rioter, Tineye Scout, Enforcer, Infiltrator) with mechanical bonuses,
  vacancy penalties when roles are unfilled, ~14 crew role events, and 5 band
  tasks. Each crew member's Allomantic ability enhances their role. Default
  assignments match the books (Clubs=Smoker, Ham=Enforcer, Vin=Infiltrator).

**Key files:**
- `common/bookmarks/00_mistborn_bookmarks.txt` — major rewrite
- `common/decisions/` — crew decisions
- `common/game_rules/` — activate toggle
- `common/council_positions/01_crew_council.txt` — band council roles
- `events/crew_role_events.txt` — crew role events
- `events/` — crew-specific events
- `localization/english/` — bookmark text, crew decisions, crew roles

**Exit criteria:** Select "End of an Empire" bookmark. Play as Kelsier with
crew. Crew roles assigned with mechanical effects. Recruit members. Game rule
toggle works. If Kelsier dies, Vin takes over.

---

### M6: The Plan

*The core story of Mistborn: The Final Empire is playable.*

**Scope:**
- **Crew Assembly arc** — recruit named crew members through skill checks and
  events. Each recruitment has a cost (gold/prestige) and a narrative moment.
  Completing the full crew grants a modifier and unlocks rebellion decisions.
- **Skaa Army arc** — decision to raise hidden levy in caves. Multi-year
  building via events. Lord Ruler attention checks at each stage. Discovery =
  army destroyed + attention spike. Success = war option unlocked.
- **Noble House Infiltration arc** — spy scheme targeting noble courts. Ball
  events where player chooses which house to approach. Rumor-spreading. Failure
  risks cover being blown. Success undermines house alliances.
- **Rebellion arc** — faction-style mechanic for skaa uprising. Builds over
  time based on tyranny/crackdowns. Civil war trigger when conditions met.
  Military confrontation with the Final Empire's forces.
- **Kelsier's Martyrdom** — if Kelsier dies during the rebellion, his death
  creates a Survivorism religious event. The rebellion strengthens (not ends).
  Vin inherits leadership. A new religious icon appears in the faith.
- All events gated by game rule (Narrative Mode only; Sandbox players get the
  mechanical systems but not the scripted story beats)
- Each arc needs: events, decisions, scripted triggers, scripted effects,
  localization, on_action hooks

**Key files:**
- `events/` — new event files per arc (or expand existing ones)
- `common/decisions/` — arc-triggering decisions
- `common/scripted_effects/mistborn_effects.txt`
- `common/scripted_triggers/mistborn_triggers.txt`
- `common/on_action/mistborn_on_actions.txt`
- `localization/english/mistborn_events_l_english.yml` — major expansion

**Exit criteria:** Play as Kelsier from bookmark. Assemble the crew. Train the
skaa army. Infiltrate noble society. Trigger the rebellion. Experience Kelsier's
martyrdom. Vin takes over as leader. The core plot of Book 1 plays out.

---

### M7: The Deepness

*All event arcs implemented. Deep Sanderson lore throughout.*

**Scope:**
- **Raids on Noble Houses** — hostile scheme/decision chain. Steal gold, reduce
  county control, lower prestige. Escalating consequences if caught.
- **The Eleventh Metal** — rare event chain for Mistborn/Augur characters.
  Discover malatium. Reveals hidden information about powerful characters.
  Grants intrigue advantage.
- **Mistborn Duels in the Mists** — personal combat events. Metal-type specific
  options (Coinshots get ranged, Thugs get endurance, Tineyes detect ambushes).
- **Ball Assassination** — variant ball event with assassination attempt. Vin vs
  Shan Elariel fight. Reveals hidden Mistborn status. Major political fallout.
- **Political Intrigue** — false flag scheme (frame a third house). Atium
  contract auction (houses bid prestige/gold). Obligator oversight events
  (bribe/intimidate/accept). Skaa mistress scandal chain.
- **Atium Economy** — atium supply modifier. Pits of Hathsin generation. Atium
  contract as decision. Atium trading events. Atium as strategic resource.
- **Fall of Kredik Shaw** — endgame event chain. Requires understanding of
  Compounding. Must identify and remove Lord Ruler's atium bracers. Triggers
  unique war where Lord Ruler becomes mortal. Victory collapses `e_final_empire`.
  New era begins.
- **Atmosphere & Flavor:**
  - Ash falls — province events, ash blight modifier, clearing decisions
  - The Mists — yearly encounters, Allomancer empowerment, skaa fear, rare
    snapping triggers
  - The Flower — rare positive morale event (hope in the ash)
  - Sazed's Knowledge — Feruchemist learning events about lost religions and
    history, coppermind mechanics
  - Kandra Contracts — deepen kandra mechanics, impersonation events, Contract
    obligations
- Rare and lore-extrapolated artifacts (~20 additional types): lerasium beads
  (consumable, transforms user into Mistborn), Alendi's logbook (reveals Lord
  Ruler origins), lord_ruler_metal_plates, individual metalminds (gold, pewter,
  zinc, bronze, tin), noble house items (seal rings, contract portfolios, ball
  finery, keep blueprints), Allomantic gear (upgraded bandoliers, tin
  spectacles, bronze detection charms, emotional allomancy journals, pewter
  training weights), Steel Ministry items (obsidian axes, writs of authority,
  tattoo kits), skaa underground items (rebellion banner, crew toolkit,
  network map, preserved flower), Terris items (worldbringer robes, prophecy
  scrolls). Artifact discovery events, looting integration, metalmind
  tapping/recharging cycle.
- 8 Mistborn-specific activities: Atium Auction (multi-round bidding for the
  atium contract), Crew Heist (multi-phase job with Allomantic crew roles),
  Steel Inquisitor Tribunal (tense heresy trial), Mistborn Night Raid (tactical
  keep assault), Skaa Underground Rally (secret rebel gathering with betrayal
  risk), Pits of Hathsin Expedition (atium mining death trap), Terris Synod
  Gathering (secret Keeper conclave with coppermind sharing and Feruchemical
  training), Allomantic Exhibition (competitive Allomancer showcase — the
  Mistborn equivalent of a tournament).
- Advanced council and court interactions (~25 events): kandra "Replace a
  Courtier" interaction with discovery chain, Court Smoker protection against
  enemy Seekers, Obligator Witness betrayal/loyalty events, Terris Steward
  secret Keeper reveal, metal-type specific Allomantic Advisor events, council
  composition synergy with Lord Ruler attention, crew council advanced events
  (full crew meetings, role conflicts, role evolution).
- Additional Sanderson lore events:
  - Terris breeding program (Lord Ruler's suppression of Feruchemy)
  - Obligator spy network flavor
  - Skaa plantation life events
  - Noble ball politics and gossip
  - Koloss army events (uncontrollable berserkers)
  - Steel Inquisitor encounters (terror events)
  - Ashfall seasons affecting agriculture
  - Deepness myths and Alendi's journal fragments

**Key files:**
- `events/` — many new event files
- `common/schemes/` — expand with new scheme types
- `common/decisions/` — atium decisions, endgame decisions
- `common/modifiers/` — atium supply, ash blight, mist modifiers
- `localization/english/` — massive expansion (hundreds of new keys)

**Exit criteria:** All 13+ event arcs from `events.md` are implemented plus
additional lore events. Play through the complete story including the Fall of
Kredik Shaw. Atmosphere events fire regularly. The world feels deeply Mistborn.

---

### M8: The Art of Metals

*Custom Scadrial map. Full graphics. Publication quality.*

**Scope:**
- **Custom Map:**
  - Create `provinces.png` — Scadrial landmass with province borders matching
    the Dominance structure. Central Dominance around Luthadel, Northern
    (Urteau), Western (Fadrex), Eastern, Southern Dominances, Terris in the
    north, Pits of Hathsin location.
  - Create `definitions.csv` — province ID to RGB mapping
  - Create `heightmap.bmp` — terrain elevation (Ashmounts as peaks, Central
    Dominance as plains, Terris mountains in the north)
  - Create `rivers.png` — River Channerel and tributaries
  - Define terrain types, geographic regions, climate zones
  - Remap all `province = XXXX` references in `00_landed_titles.txt`
  - Rewrite province history files for new province IDs
  - Extensive map testing (broken rivers and province borders crash CK3)
- **Graphics:**
  - Custom trait icons (`.dds` files) for all metallic arts traits — 12 Misting
    types, Mistborn, Feruchemist, Hemalurgist, spike types, strength tiers,
    potentials (~25-30 icons)
  - Custom modifier icons for lord_ruler_attention, ruin_influence, ash_blight,
    atium_supply, etc.
  - Loading screen art (Luthadel skyline, mists, ashmounts)
  - Bookmark art (Kelsier and Vin character portraits, the Final Empire backdrop)
  - Decision icons for major decisions
- **Portraits:**
  - Custom ethnicity definitions for Scadrial cultures (noble_scadrian pale
    skin, skaa darker features, terris dark skin per lore)
  - Portrait modifiers for Hemalurgic spikes (eye spikes for Inquisitors)
  - Ash-stained clothing/accessories
- **Polish:**
  - Balance pass on all mechanics — play multiple full campaigns
  - Localization review — consistent tone, no typos, all keys present
  - Error.log must be completely clean
  - Performance check — no excessive event firing or script loops
  - Community feedback integration (share with testers)

**Key files:**
- `map_data/` — new directory (provinces.png, heightmap.bmp, rivers.png,
  definitions.csv, default.map, geographical_regions/)
- `gfx/` — new directory (interface/icons/traits/, interface/icons/modifiers/,
  loadingscreens/, portraits/)
- `common/landed_titles/00_landed_titles.txt` — province remapping
- `history/provinces/` — rewrite for new province IDs
- All localization files — final review pass

**Exit criteria:** The mod is publication quality. Custom Scadrial map looks
good. All traits have custom icons. Loading screens show Mistborn art.
Characters look like Scadrians. No errors. Ready for Steam Workshop.

---

## Dependency Map

```
M1 Foundation
 └─► M2 Metallic Arts
      └─► M3 The Final Empire
           ├─► M4 Scadrial on the Map ──► (shareable v1)
           └─► M5 The Crew
                └─► M6 The Plan
                     └─► M7 The Deepness
                          └─► M8 The Art of Metals ──► (done)
```

M4 and M5 can run in parallel after M3. M6 depends on M5 (band system required
for narrative arcs). M7 depends on M6 (extended arcs build on core narrative).
M8 depends on M7 (all content must exist before final polish and map swap).

---

## Risks & Open Questions

### Technical Risks

1. **Lord Ruler as off-map entity.** CK3 does not have a clean off-map power
   mechanic like EU4. Options: (a) immortal emperor holding `e_final_empire`,
   made non-playable; (b) religious head via spiritual doctrine; (c) hidden
   title + event-only interactions. The right approach affects the attention
   system, rebellion arc, and endgame. Must be resolved in M3.

2. **Vin as non-leader band member.** Roads to Power may not support playing as
   a non-leader in an adventurer band. If not natively supported, Vin's gameplay
   must be simulated via events and decisions (Kelsier as event-driven NPC when
   playing Vin). Must be researched in M5.

3. **Custom map stability.** Broken province borders or rivers crash CK3 hard.
   Map work requires pixel-level accuracy and extensive testing. This is the
   highest-risk single task in the project.

4. **Vanilla content bleed-through.** Every vanilla decision, event, and name
   that isn't suppressed breaks immersion. Total conversion requires systematic
   suppression via empty replacement files. This is tedious but critical.

5. **Roads to Power DLC dependency.** Friends without the DLC cannot play
   Kelsier's crew. A non-DLC fallback (landed minor barony) must exist in M5.

### Design Questions

6. **Government type.** The Final Empire is not feudal — the Lord Ruler appoints
   governors, Great Houses hold land by his grace. A custom government type in
   `common/governments/` may be needed to restrict war declaration and modify
   succession. Scope TBD in M3.

7. **Succession laws.** Titles should not freely inherit by partition. The Lord
   Ruler controls title distribution. Custom succession laws or realm laws may
   be needed.

8. **Era 2 metals.** The REVIEW_NOTES mention missing chromium, aluminum,
   cadmium, and bendalloy traits. These are not known in the Final Empire era
   per lore. Decision: omit them (lore-accurate) or include as ultra-rare
   hidden knowledge.

9. **Kandra depth.** Kandra are shapeshifters bound by Contracts. How deep
   should this system go? A full kandra trait with impersonation mechanics, or
   flavor events only?

10. **Mod size and performance.** 13+ event arcs with hundreds of events, plus
    atmosphere events on yearly pulses, could cause performance issues on slower
    machines. Events should be gated efficiently.