docs(milestones): add education, legacies, governments, factions, and more

Expand M3 with custom education system (5 tracks × 4 tiers), dynasty
legacies (5 universal + 10 house-specific), custom death reasons (12),
and character nicknames (~15). Expand M4 with custom government types
(3), factions (5), vassal contracts (6 terms), secret types (8), hooks
(3), court types (3), and portrait modifier system (10 triggers).
Update MASTERPLAN scope to reflect all new systems.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

MASTERPLAN.md

@@ -200,6 +200,17 @@ Use Sandbox decision to gain powers. All metallic arts events fire correctly.
   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),
@@ -274,6 +285,24 @@ and Pits of Hathsin have special buildings. Names are Scadrial-appropriate.
   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
 
@@ -286,14 +315,18 @@ and Pits of Hathsin have special buildings. Names are Scadrial-appropriate.
 - `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/` — new localization for CB, schemes, provinces, council,
-  laws, innovations
+- `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, no
-vanilla anachronisms. Custom wars, schemes, council, and laws work. Innovation
-system shows Imperial stagnation.
+Scadrial — Scadrial names, ash terrain, Mistborn mechanics, caste system,
+Imperial government, custom factions, no vanilla anachronisms. All core CK3
+systems are Mistborn-themed.
 
 ---
 

docs/milestones/M3-the-final-empire.md

@@ -1345,8 +1345,308 @@ creates both as religious orders with distinct mechanics.
 
 ---
 
+### 3.12 -- Custom Education System
+
+**Context:** CK3's education system shapes every character from age 6-16 through
+guardian assignment and education focus selection. The resulting education trait
+(e.g., `education_diplomacy_4`) determines stat bonuses and lifestyle affinity.
+For Mistborn, education must reflect the setting's social strata: noble children
+learn politics and Allomancy at keeps, skaa children learn survival on
+plantations, and Terris children are put through the breeding program or secretly
+trained as Keepers. Education tracks must map to the 5 custom lifestyles (M4
+task 4.6) so the system forms a cohesive character development pipeline.
+
+**Steps:**
+
+1. **Define 5 custom education focuses.** In `common/education/` (new directory),
+   replace vanilla education focuses with Mistborn tracks. Each focus maps to
+   one of the 5 custom lifestyles:
+
+   | Education Track | Maps to Lifestyle | Target Culture | Key Stats | Description |
+   |-----------------|-------------------|----------------|-----------|-------------|
+   | **Allomantic Training** | Metallic Arts | Any with potential | martial, prowess | Intense physical and mental training designed to awaken Allomantic ability. Guardians push wards to their limits — snapping can trigger as the "graduation trauma." |
+   | **Noble Court Education** | Noble Intrigue | noble_scadrian | diplomacy, intrigue | Learn the Great Game: ball etiquette, house politics, contract negotiation, social manipulation. The standard education for noble heirs. |
+   | **Ministry Indoctrination** | Steel Ministry | Any (Steel Ministry faith) | learning, stewardship | Obligator academy training: canton administration, theological doctrine, record-keeping, loyalty to the Lord Ruler. Produces future obligators and ministry officials. |
+   | **Skaa Survival** | Underground | skaa | intrigue, prowess | Plantation survival, street smarts, hiding from Inquisitors, underground network navigation. Not formal education — learned through hardship. |
+   | **Keeper Apprenticeship** | Scholarship | terris | learning, stewardship | Secret training in Feruchemy, coppermind use, and pre-Ascension history. Extremely dangerous — discovery by the Ministry means death. |
+
+2. **Define education traits.** Each track produces 4 tiers of education trait
+   (matching vanilla's `education_X_1` through `education_X_4`):
+
+   - `education_allomantic_1/2/3/4` — "Allomantic Novice" through "Allomantic
+     Master." Stat bonuses: martial +1/+2/+3/+4, prowess +1/+2/+3/+4. Tier 4
+     grants +10% Mistborn chance on snapping (if `trait_allomantic_potential`).
+   - `education_noble_court_1/2/3/4` — "Court Trainee" through "Master of the
+     Great Game." Stat bonuses: diplomacy +1/+2/+3/+4, intrigue +0/+1/+2/+3.
+   - `education_ministry_1/2/3/4` — "Obligator Initiate" through "High
+     Preceptor." Stat bonuses: learning +1/+2/+3/+4, stewardship +0/+1/+2/+3.
+     Tier 3+ grants `can_become_obligator` flag.
+   - `education_skaa_1/2/3/4` — "Street Urchin" through "Underground Veteran."
+     Stat bonuses: intrigue +1/+2/+3/+4, prowess +0/+1/+1/+2. Tier 4 grants
+     +15% hostile scheme resistance.
+   - `education_keeper_1/2/3/4` — "Keeper Initiate" through "Master Keeper."
+     Stat bonuses: learning +2/+3/+4/+6, stewardship +0/+1/+1/+2. Tier 3+
+     grants `keeper_initiate` flag (ties into M3.11 Keeper Network). Tier 4
+     grants access to coppermind events.
+
+3. **Create education events.** In `events/education_events.txt`, namespace
+   `mistborn_education`:
+
+   **Allomantic Training events:**
+   - `mistborn_education.0001` — Guardian pushes ward to the breaking point.
+     Options: intensify training (risk injury, +chance of higher tier), ease
+     off (safer, -1 tier chance), focus on fundamentals (balanced).
+   - `mistborn_education.0002` — **Snapping during training.** If the ward
+     has `trait_allomantic_potential`, 25% chance of triggering the snapping
+     event chain (M2) during year 14-16 of education. This is the lore-
+     appropriate moment — nobles deliberately traumatize their children to
+     trigger snapping. If snapping succeeds, +1 education tier.
+   - `mistborn_education.0003` — Ward shows exceptional metal instinct. If
+     guardian is Mistborn or Misting, +15% chance of tier 4 education.
+
+   **Noble Court Education events:**
+   - `mistborn_education.0010` — Ward attends first ball. Social check
+     (diplomacy). Success: +1 diplomacy, opinion boost with guardian. Failure:
+     embarrassing incident, stress +10.
+   - `mistborn_education.0011` — Ward observes a scheme in action. Intrigue
+     check. Success: learns about the Great Game (+1 intrigue). Failure:
+     gets caught watching, guardian must intervene.
+
+   **Ministry Indoctrination events:**
+   - `mistborn_education.0020` — Canton examination. Learning check. Success:
+     +1 piety, recognition from the Ministry. Failure: extra study imposed,
+     stress +5.
+   - `mistborn_education.0021` — Ward questions doctrine. Choice: encourage
+     questioning (risk heresy flag, +1 learning), punish doubt (+1 piety,
+     stress +10), explain patiently (balanced, opinion +5).
+
+   **Skaa Survival events:**
+   - `mistborn_education.0030` — Close call with Inquisitor patrol. Intrigue
+     check. Success: learn evasion (+1 intrigue). Failure: beaten, stress +15,
+     but learn toughness (+1 prowess).
+   - `mistborn_education.0031` — Ward discovers the underground network.
+     Options: join (early access to Underground lifestyle perks), stay
+     independent, report to nobles (betrayal, gain noble favor).
+
+   **Keeper Apprenticeship events:**
+   - `mistborn_education.0040` — First coppermind lesson. Learning check.
+     Success: store first memory (+1 learning). Failure: headaches, retry
+     next year.
+   - `mistborn_education.0041` — Ministry investigation near the training
+     site. Options: hide and wait (lose 6 months training), relocate (gold
+     cost), continue in secret (intrigue check, discovery risk). If
+     discovered: ward and guardian both face Ministry punishment.
+
+4. **Guardian compatibility.** Add scripted triggers for guardian-ward matching:
+   - Allomantic Training: guardian should have Allomantic trait (or
+     `education_allomantic_3+`). Non-Allomancer guardians give -1 tier penalty.
+   - Keeper Apprenticeship: guardian must be a Keeper (has `keeper_identity`
+     flag). Non-Keeper guardians cannot teach this track.
+   - Ministry Indoctrination: guardian should have Steel Ministry faith.
+   - Noble Court: guardian should be `noble_scadrian` culture.
+   - Skaa Survival: no requirements (life teaches).
+
+5. **Suppress vanilla education.** Create empty replacement files for vanilla
+   education focus definitions. Override education-related localization keys.
+   Ensure vanilla education events don't fire.
+
+6. **Localization.** Add entries for:
+   - 5 education focus names + descriptions (~20 keys)
+   - 20 education trait names + descriptions (4 tiers × 5 tracks, ~40 keys)
+   - ~12 education events (~60 keys)
+   - Guardian compatibility tooltips (~10 keys)
+   - Total: ~130 new localization keys
+
+**Files:**
+- `common/education/00_mistborn_education.txt` -- create
+- `common/traits/00_education_traits.txt` -- create (or add to existing)
+- `events/education_events.txt` -- create
+- `common/scripted_triggers/mistborn_triggers.txt` -- modify (guardian checks)
+- Vanilla education suppression files -- create (empty replacements)
+- `localization/english/mistborn_education_l_english.yml` -- create
+
+**References:**
+- Vanilla education system: CK3 game install `common/education/`
+- Custom lifestyles: M4 task 4.6 (education maps to lifestyle)
+- Snapping event chain: M2 (snapping triggers during Allomantic Training)
+- Keeper Network: M3 task 3.11 (Keeper education produces initiates)
+- Allomantic traits: `common/traits/00_allomancy_traits.txt`
+
+---
+
+### 3.13 -- Dynasty Legacies
+
+**Context:** CK3's dynasty legacy system gives permanent bonuses as dynasties
+invest renown over generations. The 10 Great Houses of the Final Empire each
+have distinct identities — House Venture dominates commerce, House Hasting
+excels at military, House Elariel masters intrigue. Universal legacy trees
+available to all dynasties provide broad Mistborn-themed progression, while
+short house-specific legacies give each Great House a unique mechanical
+identity.
+
+**Steps:**
+
+1. **Define 5 universal legacy trees.** In `common/dynasty_legacies/` (new
+   directory), create Mistborn-themed legacy trees replacing vanilla ones
+   (Blood, Law, Guile, Glory, Kin). Each has 5 tiers:
+
+   **Allomantic Bloodline** (replaces Blood):
+   - Tier 1: +5% chance of `trait_allomantic_potential` in children
+   - Tier 2: +1 prowess for all Misting dynasty members
+   - Tier 3: +10% snapping success rate for dynasty members
+   - Tier 4: +5% Mistborn chance on snapping
+   - Tier 5: Dynasty members can attempt snapping at any age (not just youth)
+
+   **Political Dominance** (replaces Law):
+   - Tier 1: +5 vassal opinion
+   - Tier 2: +0.1 monthly prestige for dynasty head
+   - Tier 3: -10% short reign penalty
+   - Tier 4: +1 domain limit for dynasty head
+   - Tier 5: "Dominant House" modifier: +20 opinion with same-culture rulers
+
+   **Ministry Connections** (replaces Glory):
+   - Tier 1: -5% Lord Ruler attention gain
+   - Tier 2: +0.1 monthly piety
+   - Tier 3: Obligator Witness court position costs 50% less salary
+   - Tier 4: -10% Inquisitor investigation success against dynasty
+   - Tier 5: "Ministry Favorite" modifier: can request Inquisitor at half cost
+
+   **Metallurgic Wealth** (replaces Kin):
+   - Tier 1: +5% income from holdings
+   - Tier 2: Metal supply depletion rate -10% (M2 metal system)
+   - Tier 3: Artifact crafting costs -25%
+   - Tier 4: +0.3 monthly gold for dynasty head
+   - Tier 5: "Atium Magnate" modifier: atium reserve bonuses doubled
+
+   **Underground Network** (replaces Guile):
+   - Tier 1: +5% hostile scheme resistance
+   - Tier 2: +1 intrigue for all dynasty members
+   - Tier 3: +10% scheme power for dynasty members
+   - Tier 4: "Hidden Resources" decision: spend gold to reduce attention
+   - Tier 5: Dynasty members can never have their secrets exposed by
+     Inquisitor investigation (auto-succeed cover checks)
+
+2. **Define 10 house-specific legacy trees.** Each Great House gets a short
+   3-tier legacy reflecting their lore identity. These are cheaper than
+   universal legacies (50%/75%/100% of base cost per tier):
+
+   | House | Legacy Name | Tier 1 | Tier 2 | Tier 3 |
+   |-------|-------------|--------|--------|--------|
+   | **Venture** | Venture Supremacy | +10% tax income | +1 stewardship for house head | "First Among Houses" — can use Dominance Claim CB at half prestige cost |
+   | **Hasting** | Hasting War Machine | +10% MaA damage | +2 martial for house head | "Iron Discipline" — Hazekiller MaA gain +1 regiment size |
+   | **Elariel** | Elariel Shadow Court | +10% scheme power | +2 intrigue for house head | "Invisible Hand" — False Flag scheme costs no gold |
+   | **Lekal** | Lekal Traditionalism | +5 same-faith opinion | +1 diplomacy for house head | "Lord Ruler's Favored" — attention gain -20% |
+   | **Tekiel** | Tekiel Trade Empire | +0.2 monthly gold | +1 stewardship for house head | "Canal Monopoly" — trade route income +25% |
+   | **Urbain** | Urbain Military Caste | +5% levy size | +1 martial for house head | "Fortress Builders" — fort level +1 in capital |
+   | **Bylerum** | Bylerum Intelligence | +10% scheme discovery | +1 learning for house head | "Information Brokers" — gain hooks 15% faster |
+   | **Erikeller** | Erikeller Allomantic Line | +5% allomantic potential inheritance | +1 prowess for Allomancer members | "Pureblooded" — Mistborn chance +10% on snapping |
+   | **Haught** | Haught Diplomatic Corps | +5 different-culture opinion | +1 diplomacy for house head | "Bridge Builders" — can use House War CB defensively (counter-claim) |
+   | **Conrad** | Conrad Plantation Lords | +10% holding construction speed | +1 stewardship for house head | "Agricultural Mastery" — `fertile_ashland` provinces gain +0.1 dev growth |
+
+3. **Suppress vanilla legacy trees.** Create empty replacement files for
+   vanilla dynasty legacy definitions. Verify exact file names against game
+   install.
+
+4. **Localization.** Add entries for:
+   - 5 universal legacy tree names + descriptions (~10 keys)
+   - 25 universal legacy perk names + descriptions (~50 keys)
+   - 10 house legacy tree names + descriptions (~20 keys)
+   - 30 house legacy perk names + descriptions (~60 keys)
+   - Total: ~140 new localization keys
+
+**Files:**
+- `common/dynasty_legacies/00_mistborn_legacies.txt` -- create
+- `common/dynasty_legacies/01_house_legacies.txt` -- create
+- Vanilla legacy suppression files -- create (empty replacements)
+- `localization/english/mistborn_legacies_l_english.yml` -- create
+
+**References:**
+- Vanilla dynasty legacy format: CK3 game install `common/dynasty_legacies/`
+- Great House dynasties: M3 task 3.4
+- Metal supply system: M2 task 2.7
+- Allomantic traits: `common/traits/00_allomancy_traits.txt`
+- Lord Ruler attention system: `common/scripted_effects/mistborn_effects.txt`
+- Lore: `docs/lore/mistborn-universe.md` — Great Houses, noble society
+
+---
+
+### 3.14 -- Custom Death Reasons and Nicknames
+
+**Context:** CK3 tracks how characters die and gives notable characters
+nicknames. Vanilla death reasons ("died in battle," "murdered") and nicknames
+("the Conqueror," "the Wise") are generic medieval. Mistborn needs custom death
+causes that reflect the setting's violence and custom nicknames that honor
+Allomantic achievement and political status.
+
+**Steps:**
+
+1. **Define custom death reasons.** In `common/deathreasons/` (new directory),
+   create Mistborn-specific death causes:
+
+   | Death Reason | Trigger Context | Description |
+   |---|---|---|
+   | `death_allomantic_combat` | Killed by an Allomancer in duel/battle | "Killed by Allomantic power" |
+   | `death_inquisitor_execution` | Executed by Steel Inquisitor | "Executed by a Steel Inquisitor" |
+   | `death_mist_sickness` | Random health event in mist-heavy province | "Succumbed to the mists" |
+   | `death_pewter_drag` | Thug/Pewterarm overuses pewter | "Died of pewter drag" |
+   | `death_hemalurgic_sacrifice` | Killed in hemalurgic ritual | "Sacrificed in a hemalurgic rite" |
+   | `death_atium_overdose` | Excessive atium burning | "Burned out by atium" |
+   | `death_ashfall` | Ashfall province event | "Buried in ash" |
+   | `death_koloss_attack` | Killed by koloss | "Torn apart by koloss" |
+   | `death_pits_of_hathsin` | Died in the Pits | "Perished in the Pits of Hathsin" |
+   | `death_rebellion` | Killed during skaa rebellion | "Killed in the rebellion" |
+   | `death_lord_ruler_wrath` | Lord Ruler attention reaches max | "Destroyed by the Lord Ruler" |
+   | `death_smoker_failure` | Coppercloud dropped, discovered | "Exposed and eliminated" |
+
+2. **Define custom nicknames.** In `common/nicknames/00_mistborn_nicknames.txt`,
+   create character nicknames earned through events and achievements:
+
+   | Nickname | Trigger Condition | Localization |
+   |---|---|---|
+   | `nick_the_survivor` | Escape the Pits of Hathsin | "the Survivor" |
+   | `nick_the_heir` | Inherit house leadership as firstborn | "the Heir" |
+   | `nick_ash_lord` | Hold kingdom+ title for 20+ years | "the Ash Lord" |
+   | `nick_sliver_of_infinity` | Lord Ruler only | "the Sliver of Infinity" |
+   | `nick_the_ascendant` | Reach highest Allomantic strength tier | "the Ascendant" |
+   | `nick_mistborn_of_X` | Become Mistborn + hold a specific city | "Mistborn of [City]" |
+   | `nick_the_inquisitor` | Survive hemalurgic transformation | "the Inquisitor" |
+   | `nick_keeper_of_ages` | Reach Keeper tier 4 education | "Keeper of Ages" |
+   | `nick_the_liberator` | Lead successful rebellion (M6) | "the Liberator" |
+   | `nick_house_destroyer` | Win 5+ House War CBs | "the House Destroyer" |
+   | `nick_steel_hand` | Hold Ministry Preceptor + high piety | "the Steel Hand" |
+   | `nick_the_underground` | Lead crew with 5+ members for 10 years | "the Underground" |
+   | `nick_atium_king` | Control Pits of Hathsin for 10+ years | "the Atium King" |
+   | `nick_last_obligator` | Only Steel Ministry character remaining after Lord Ruler falls | "the Last Obligator" |
+   | `nick_new_emperor` | Seize `e_final_empire` after Lord Ruler falls | "the New Emperor" |
+
+3. **Suppress vanilla nicknames** that break immersion ("the Crusader," "the
+   Holy," "the Viking," etc.). Create empty replacement files. Keep
+   culture-neutral nicknames if any exist ("the Great," "the Wise" can be
+   rethemed via localization).
+
+4. **Localization.** Add entries for:
+   - 12 death reason names + descriptions (~24 keys)
+   - ~15 nickname localization keys
+   - Total: ~39 new localization keys
+
+**Files:**
+- `common/deathreasons/00_mistborn_deathreasons.txt` -- create
+- `common/nicknames/00_mistborn_nicknames.txt` -- create
+- Vanilla nickname suppression files -- create (empty replacements)
+- `localization/english/mistborn_nicknames_l_english.yml` -- create
+
+**References:**
+- Vanilla death reasons: CK3 game install `common/deathreasons/`
+- Vanilla nicknames: CK3 game install `common/nicknames/`
+- Mistborn combat and death lore: `docs/lore/mistborn-universe.md`
+
+---
+
 ## Testing Checkpoints
 
+> See [`docs/TESTING.md`](../TESTING.md) for the full testing protocol, debug
+> decisions, log analysis commands, and helper scripts.
+
 - **After 3.1 + 3.2 (Lord Ruler + Religious Head):**
   - **Test:** Load the mod, open the religion view for Steel Ministry.
   - **Expected:** The Lord Ruler appears as the religious head "Sliver of
@@ -1403,6 +1703,33 @@ creates both as religious orders with distinct mechanics.
     unique interactions, Keeper Network is joinable with progression. Inquisitor
     yearly report to Canton fires. Keeper discovery risk events fire.
 
+- **After 3.12 (Education):**
+  - **Test:** Start a game. Assign a guardian to a noble child age 6. Verify 5
+    Mistborn education focuses appear (no vanilla Diplomacy/Martial/etc.).
+    Select Allomantic Training for a child with `trait_allomantic_potential`.
+    Play to age 16. Verify education trait is awarded (`education_allomantic_X`).
+    Check if snapping event triggered during training. Assign Keeper
+    Apprenticeship to a Terris child with a Keeper guardian.
+  - **Expected:** 5 custom education tracks with correct stat bonuses per tier.
+    Allomantic Training can trigger snapping. Keeper Apprenticeship grants
+    `keeper_initiate` flag at tier 3+. No vanilla education content visible.
+
+- **After 3.13 (Legacies):**
+  - **Test:** Open dynasty view for House Venture. Verify 5 universal legacy
+    trees and 1 house-specific tree ("Venture Supremacy") are available. No
+    vanilla legacy trees visible. Purchase tier 1 of Allomantic Bloodline.
+    Verify +5% allomantic potential inheritance bonus applies.
+  - **Expected:** 5 universal + 10 house-specific legacy trees. Perks grant
+    correct bonuses. House-specific trees are shorter (3 tiers) and cheaper.
+
+- **After 3.14 (Death Reasons + Nicknames):**
+  - **Test:** Kill a character via Inquisitor execution. Check death screen —
+    verify "Executed by a Steel Inquisitor" death reason. Use console to give a
+    character the Survivor nickname. Check that vanilla nicknames like "the
+    Crusader" don't appear on any characters.
+  - **Expected:** Custom death reasons show in character history. Custom
+    nicknames display correctly. Vanilla nicknames suppressed.
+
 - **After 3.9 (Title History + Bookmark):**
   - **Test:** Start a new game from the "End of an Empire" bookmark. Try each
     recommended character.
@@ -1484,6 +1811,29 @@ creates both as religious orders with distinct mechanics.
 - [ ] Artifact equipment restrictions work (copperminds require Feruchemist,
       mistcloaks require Allomancer)
 - [ ] Craft Mistcloak and Forge Glass Weapons decisions function
+- [ ] 5 custom education tracks defined: Allomantic Training, Noble Court,
+      Ministry Indoctrination, Skaa Survival, Keeper Apprenticeship
+- [ ] Education tracks map to lifestyles: Allomantic→Metallic Arts, Noble
+      Court→Noble Intrigue, Ministry→Steel Ministry, Skaa→Underground,
+      Keeper→Scholarship
+- [ ] 20 education traits defined (4 tiers × 5 tracks) with appropriate stats
+- [ ] Allomantic Training can trigger snapping during education (25% chance)
+- [ ] Keeper Apprenticeship tier 3+ grants `keeper_initiate` flag
+- [ ] Guardian compatibility checks enforce trait requirements
+- [ ] Vanilla education focuses and events suppressed
+- [ ] Education localization complete (~130 keys)
+- [ ] 5 universal dynasty legacy trees (5 tiers each): Allomantic Bloodline,
+      Political Dominance, Ministry Connections, Metallurgic Wealth,
+      Underground Network
+- [ ] 10 house-specific legacy trees (3 tiers each) for all Great Houses
+- [ ] Vanilla legacy trees suppressed
+- [ ] Legacy localization complete (~140 keys)
+- [ ] 12 custom death reasons defined (Allomantic combat, Inquisitor execution,
+      mist sickness, pewter drag, etc.)
+- [ ] ~15 custom nicknames defined (the Survivor, Ash Lord, Sliver of Infinity,
+      the Liberator, etc.)
+- [ ] Vanilla nicknames that break immersion suppressed
+- [ ] Death reason and nickname localization complete (~39 keys)
 - [ ] The mod loads with no critical errors in `error.log`
 - [ ] Playing as Straff Venture for 5 years produces no crashes
 

docs/milestones/M4-scadrial-on-the-map.md

@@ -2041,7 +2041,438 @@ the suffocating status quo and the explosive potential of liberation.
 
 ---
 
-### 4.11 -- Full Testing Pass and Error Cleanup
+### 4.11 -- Custom Government Types
+
+**Context:** The Final Empire is not feudal. The Lord Ruler appoints house lords,
+there is no partition inheritance, and the Steel Ministry runs a parallel
+theocratic governance structure. CK3 supports custom government types that
+change succession rules, available laws, council behavior, and UI presentation.
+Multiple government types are needed to reflect the different power structures
+at play.
+
+**Steps:**
+
+1. **Define "Imperial Appointment" government.** In `common/governments/` (new
+   directory), create the primary government type for noble houses:
+   ```
+   imperial_appointment_government = {
+       # No partition — succession is by appointment
+       # The Lord Ruler (or liege) designates the heir
+       # Vassals cannot change succession law while Lord Ruler lives
+   }
+   ```
+   Properties:
+   - Succession: designated heir (liege picks). Under Lord Ruler: the Lord
+     Ruler technically appoints all lords. Mechanically: realm succession is
+     "House Seniority" or "Designation" to prevent partition.
+   - No elective, no partition, no gavelkind
+   - Cannot change succession law while `lord_ruler_fallen` is false
+   - Domain limit: based on title tier (duchy +2, kingdom +4, empire +8)
+   - Available laws: caste laws (M4.9), Standard obligation laws (rethemed)
+   - Council: uses rethemed council positions from M4.8
+   - UI flag: custom government icon (placeholder until M8)
+
+2. **Define "Theocratic Ministry" government.** For Steel Ministry holdings
+   (Conventical of Seran, any canton holdings):
+   ```
+   theocratic_ministry_government = {
+       # Succession: appointment by religious head (Lord Ruler)
+       # Cannot declare war independently
+       # Can excommunicate and investigate
+   }
+   ```
+   Properties:
+   - Succession: theocratic appointment (religious head picks)
+   - Cannot declare war independently (must have Lord Ruler's approval or
+     use Inquisition Purge CB)
+   - Gets +50% piety income
+   - Gets access to Inquisitor interactions without "Request" decision
+   - Available laws: Ministry-specific laws (canton administration)
+   - Reduced tax income but high levy contribution from faithful
+
+3. **Define "Post-Rebellion Elective" government.** Available only after
+   `lord_ruler_fallen` flag is set:
+   ```
+   elective_council_government = {
+       # Succession: council election (like CK3 Scandinavian Elective)
+       # Available after the Lord Ruler falls
+       # Represents the power vacuum and transition period
+   }
+   ```
+   Properties:
+   - Succession: elective among council members and powerful vassals
+   - Can change laws freely
+   - Unlocks `caste_law_abolished`
+   - Unlocks new council tasks (M4.8) for post-rebellion governance
+   - Unlocks Age of Liberation innovations (M4.10)
+
+4. **Adventurer government** (Roads to Power) is already handled by M5 for
+   Kelsier's crew. No custom definition needed — use vanilla RtP adventurer.
+
+5. **Assign governments at game start.** Update `on_game_start` effects:
+   - All noble house holders: `imperial_appointment_government`
+   - Steel Ministry holdings: `theocratic_ministry_government`
+   - After Lord Ruler falls: event offers transition to
+     `elective_council_government` or keeping `imperial_appointment_government`
+     (the "seize the throne" choice from M7)
+
+6. **Suppress vanilla governments** that don't fit (tribal, republic if
+   present). Keep feudal as a hidden fallback.
+
+7. **Localization.** ~30 keys (3 government names + descriptions, succession
+   descriptions, law availability tooltips).
+
+**Files:**
+- `common/governments/00_mistborn_governments.txt` -- create
+- `common/on_action/mistborn_on_actions.txt` -- modify (government assignment)
+- Vanilla government suppression files -- create (empty replacements)
+- `localization/english/mistborn_governments_l_english.yml` -- create
+
+**References:**
+- Vanilla government format: CK3 game install `common/governments/`
+- Caste laws: M4 task 4.9
+- Innovation eras: M4 task 4.10
+- Lord Ruler attention: `common/scripted_effects/mistborn_effects.txt`
+- Post-endgame choice: M7 task 7.7
+
+---
+
+### 4.12 -- Custom Factions
+
+**Context:** CK3's faction system lets characters organize against their liege
+with demands and ultimatums. The Final Empire has natural factions: skaa rebels
+plotting in secret, Ministry loyalists enforcing orthodoxy, reform-minded nobles
+questioning the status quo, and Keeper preservationists working underground.
+Custom factions replace vanilla ones (independence, claimant, liberty) with
+Mistborn-specific organizations that interact with Lord Ruler attention,
+Allomantic traits, and the rebellion arc.
+
+**Steps:**
+
+1. **Define 5 custom factions.** In `common/factions/00_mistborn_factions.txt`
+   (new directory):
+
+   **Skaa Rebellion Faction** (`faction_skaa_rebellion`):
+   - Join condition: skaa culture OR Survivorist faith OR has
+     `rebel_sympathy` flag
+   - Demand: abolish caste laws, remove liege from power
+   - Ultimatum: civil war with Rebellion CB
+   - Power threshold: 80% of liege's military (standard)
+   - Special: faction members share intelligence (scheme power bonus). If
+     Kelsier is alive, he is always faction leader. Ties directly into M6
+     rebellion arc.
+   - Lord Ruler attention: faction activity increases attention for all
+     members (+2/year while faction exists)
+   - Discontent driver: strict caste laws, high lord_ruler_attention in
+     realm, skaa population events
+
+   **Ministry Loyalist Faction** (`faction_ministry_loyalist`):
+   - Join condition: Steel Ministry faith, piety >= 100, NOT faction leader
+     of any other faction
+   - Demand: liege must appoint Obligator Witness court position AND increase
+     Ministry tithe (vassal contract change)
+   - Ultimatum: if refused, faction members refuse levy contribution and
+     report liege to the Lord Ruler (attention +20)
+   - Power threshold: 50% (lower — they have Lord Ruler backing)
+   - Special: Ministry Loyalists can request Inquisitor investigation of
+     their liege. If liege's attention is > 75, the Lord Ruler may intervene
+     directly (event chain).
+
+   **Noble Reform Faction** (`faction_noble_reform`):
+   - Join condition: noble_scadrian culture, diplomacy >= 10 OR has
+     `reformist` trait, NOT Steel Ministry faith (or secret Survivorist)
+   - Demand: liege must change to `caste_law_relaxed` AND reduce Ministry
+     influence (remove Obligator Witness)
+   - Ultimatum: faction members form a coalition and demand reform. If
+     refused, they join the rebellion or attempt to replace the liege with
+     a reformist claimant.
+   - Power threshold: 60%
+   - Special: reformists gain scheme power bonus against Ministry loyalists.
+     Post-rebellion, reformists push for `elective_council_government`.
+
+   **Keeper Underground Faction** (`faction_keeper_underground`):
+   - Join condition: has `keeper_identity` or `keeper_initiate` flag, terris
+     culture, OR learning >= 15 with Terris Worldbringer faith
+   - Demand: no direct demand on liege. This is a passive/defensive faction.
+     Members share knowledge (learning bonus +1 per member, up to +5).
+   - Special: NOT a traditional faction — operates more like a secret
+     society. Members don't make demands but pool resources for knowledge
+     preservation. If a Keeper is captured, other faction members can attempt
+     a rescue scheme (special faction scheme).
+   - Discovery risk: if the faction grows too large (>10 members), yearly
+     5% chance of Ministry discovering the network. Discovery triggers
+     a purge event chain.
+
+   **Cult of Ruin Faction** (`faction_cult_of_ruin`):
+   - Join condition: `cult_of_ruin` faith OR has hemalurgic spike traits,
+     intrigue >= 12
+   - Demand: liege must allow hemalurgic experimentation (remove heresy
+     laws) OR sacrifice prisoners for Ruin
+   - Ultimatum: if refused, faction members begin hemalurgic assassinations
+     (murder schemes against liege's court)
+   - Power threshold: 40% (they're desperate and violent)
+   - Special: faction members gain +5 dread while active. Faction generates
+     "Ruin's Influence" modifier in provinces where members hold titles.
+     Extremely dangerous but small.
+
+2. **Suppress vanilla factions.** Create empty replacement files for vanilla
+   faction definitions (independence, claimant, liberty, populist).
+
+3. **Faction interaction with Lord Ruler.** Add scripted triggers:
+   - If the Lord Ruler detects a faction (attention-based check), he can
+     send Inquisitors to disband it. Event chain: Inquisitor arrives,
+     investigates faction members, arrests or kills leaders.
+   - Post-rebellion: the Lord Ruler no longer suppresses factions. All
+     factions can operate freely.
+
+4. **Localization.** ~80 keys (5 faction names + descriptions, demands,
+   ultimatums, event text for faction activities).
+
+**Files:**
+- `common/factions/00_mistborn_factions.txt` -- create
+- Vanilla faction suppression files -- create (empty replacements)
+- `common/scripted_triggers/mistborn_triggers.txt` -- modify (faction checks)
+- `events/faction_events.txt` -- create (faction-specific events)
+- `localization/english/mistborn_factions_l_english.yml` -- create
+
+**References:**
+- Vanilla faction format: CK3 game install `common/factions/`
+- Rebellion arc: M6 (skaa rebellion faction drives the plot)
+- Caste laws: M4 task 4.9 (faction demands reference law changes)
+- Keeper Network: M3 task 3.11 (Keeper faction is the network's political arm)
+- Lord Ruler attention: `common/scripted_effects/mistborn_effects.txt`
+
+---
+
+### 4.13 -- Custom Vassal Contracts
+
+**Context:** CK3 vassal contracts define obligations between lord and vassal:
+tax rates, levy contributions, title revocation rights, etc. In the Final
+Empire, these obligations are dictated by the Lord Ruler through the Steel
+Ministry. Custom contract terms reflect Mistborn's unique power dynamics:
+atium tithes, Allomantic service requirements, and Ministry access rights.
+
+**Steps:**
+
+1. **Define custom contract obligations.** In `common/vassal_contracts/` (new
+   directory), replace vanilla contract terms with Mistborn equivalents:
+
+   | Contract Term | Levels | Effect | Lore |
+   |---|---|---|---|
+   | **Plantation Tribute** (replaces Tax) | Low/Medium/High/Extortionate | 10%/20%/30%/50% tax to liege | Skaa plantation output flows upward |
+   | **House Guard Obligation** (replaces Levy) | Minimal/Standard/Extended/Total | 10%/25%/40%/60% levy to liege | Military service to the Lord Ruler |
+   | **Atium Tithe** (new) | None/Symbolic/Significant/Ruinous | 0/5%/15%/30% of atium income | The most valuable resource in the Empire — lords who hold atium sources must share |
+   | **Allomantic Service** (new) | None/Voluntary/Required/Conscription | Various | None: no obligation. Voluntary: lord can offer Mistings for wars. Required: must provide Mistings when called (+5 opinion). Conscription: all Allomancers drafted in wartime (-15 opinion, +Mistborn Agent MaA) |
+   | **Inquisition Access** (new) | Denied/Limited/Full | Various | Denied: Inquisitors cannot investigate your court (-0.2 monthly piety, attention +3/year). Limited: Inquisitors can investigate with your permission (default). Full: Inquisitors have unrestricted access (-10% hostile scheme in court, attention -2/year, but your secrets are at risk) |
+   | **Title Revocation** (rethemed) | Protected/Standard/Vulnerable | Various | Protected: liege cannot revoke titles (costs prestige to demand). Vulnerable: liege can revoke freely (vassal lives in fear) |
+
+2. **Default contract templates by government type.**
+   - `imperial_appointment_government`: Medium Tribute, Standard Guard,
+     Symbolic Atium Tithe, Voluntary Allomantic Service, Limited Inquisition
+   - `theocratic_ministry_government`: High Tribute, Extended Guard, no Atium
+     (Ministry doesn't mine), Required Allomantic Service, Full Inquisition
+   - Post-rebellion: contracts become negotiable (vassal can propose changes)
+
+3. **Contract negotiation events.** When a vassal proposes changing contract
+   terms, events fire:
+   - `mistborn_contract.0001` — Vassal requests reduced Atium Tithe. Options:
+     accept (lose atium income, +10 opinion), refuse (attention check — are
+     you hoarding?), counter-offer (diplomacy check).
+   - `mistborn_contract.0002` — Lord Ruler demands increased Inquisition
+     Access (yearly event if attention > 50). Options: comply (Full Access,
+     attention -10), negotiate (diplomacy check for Limited), refuse
+     (attention +15, risk Inquisitor arriving anyway).
+
+4. **Localization.** ~50 keys (6 contract terms × multiple levels + event text).
+
+**Files:**
+- `common/vassal_contracts/00_mistborn_contracts.txt` -- create
+- Vanilla vassal contract suppression files -- create (empty replacements)
+- `events/contract_events.txt` -- create
+- `localization/english/mistborn_contracts_l_english.yml` -- create
+
+**References:**
+- Vanilla vassal contract format: CK3 game install `common/vassal_contracts/`
+- Atium economy: M2 task 2.7, M7 task 7.6
+- Inquisitor mechanics: M3 task 3.11
+- Government types: M4 task 4.11
+
+---
+
+### 4.14 -- Custom Secret Types and Hooks
+
+**Context:** CK3 tracks character secrets (hidden faith, lovers, crimes) and
+hooks (leverage for demands). Mistborn is built on secrets — hidden Allomancers,
+concealed skaa heritage, Keeper identities, kandra imposters. Custom secret
+types formalize these into the CK3 secret system so they interact properly with
+schemes, Inquisitor investigations, and the intrigue lifestyle.
+
+**Steps:**
+
+1. **Define custom secret types.** In `common/secret_types/` (new directory):
+
+   | Secret Type | Who Has It | Discovery Method | Blackmail Value |
+   |---|---|---|---|
+   | `secret_allomancer` | Characters hiding Allomantic ability (skaa Mistings, nobles hiding weak abilities) | Seeker detection, Inquisitor investigation, Ministry Preceptor "Inspect Bloodlines" | High — can be reported to Ministry or recruited |
+   | `secret_skaa_heritage` | Half-skaa characters passing as noble (Vin's backstory) | Inquisitor investigation, random exposure event, genealogy research | Very High — exposure means loss of titles and possible execution |
+   | `secret_keeper_identity` | Terris Keepers hiding their true role | Inquisitor investigation (enhanced detection), Seeker probing | Critical — exposure means death and network compromise |
+   | `secret_kandra_imposter` | Kandra who has replaced a character (M4.8 court position, M7 interactions) | Observation events (behavioral slip-ups), Seeker detection (kandra don't burn metals normally) | Critical — total identity collapse on exposure |
+   | `secret_atium_hoard` | Characters hiding private atium reserves from the Lord Ruler | Stewardship investigation, Inquisitor search, informant event | High — Lord Ruler demands all atium |
+   | `secret_crew_membership` | Characters secretly part of a rebel crew | Informant betrayal, Inquisitor interrogation of captured members | High — membership means execution under strict caste law |
+   | `secret_ministry_informant` | Characters secretly reporting to the Steel Ministry | Counter-intelligence (Smoker detection), behavioral observation | Moderate — discovery by rebels means death |
+   | `secret_survivorist` | Characters secretly following Survivorism while publicly Steel Ministry | Secret faith mechanic, Seeker/Inquisitor detection | High — heresy under strict caste law |
+
+2. **Wire secrets into existing systems.** Update:
+   - Inquisitor "Investigate Heresy" interaction (M3.11): now discovers
+     formal secrets, not just flags
+   - Ministry Preceptor "Inspect Bloodlines" task (M4.8): discovers
+     `secret_allomancer` and `secret_skaa_heritage`
+   - Smoker council task (M4.8): protects secrets from discovery
+   - Kandra replacement interaction (M7.12): creates `secret_kandra_imposter`
+   - Caste events (M4.9): `secret_skaa_heritage` replaces ad-hoc
+     `hidden_skaa_heritage` flag
+
+3. **Define custom hook types.** Hooks created from discovering secrets:
+   - `hook_allomancer_knowledge` — you know someone is a hidden Allomancer.
+     Can demand: Allomantic service, gold, or silence.
+   - `hook_heritage_knowledge` — you know someone's skaa heritage. Can
+     demand: anything (this is existential leverage).
+   - `hook_crew_knowledge` — you know someone is in a rebel crew. Can
+     demand: information about the crew, or betray them to the Ministry.
+
+4. **Localization.** ~60 keys (8 secret types + descriptions, 3 hook types,
+   discovery event text, blackmail options).
+
+**Files:**
+- `common/secret_types/00_mistborn_secrets.txt` -- create
+- `common/hooks/00_mistborn_hooks.txt` -- create (or modify vanilla)
+- `common/scripted_triggers/mistborn_triggers.txt` -- modify (secret checks)
+- `localization/english/mistborn_secrets_l_english.yml` -- create
+
+**References:**
+- Vanilla secret types: CK3 game install `common/secret_types/`
+- Inquisitor investigation: M3 task 3.11
+- Council tasks: M4 task 4.8
+- Kandra replacement: M7 task 7.12
+- Caste events: M4 task 4.9
+
+---
+
+### 4.15 -- Court Types (Royal Court)
+
+**Context:** Royal Court DLC defines court types that affect court grandeur,
+available events, and visual presentation. The Final Empire has distinct spaces
+of power: grand noble keeps where houses scheme and display wealth, austere
+Ministry cantons where obligators administer the Empire, and cramped underground
+hideouts where rebels plot in secret. Each should feel mechanically and
+atmospherically different.
+
+**Steps:**
+
+1. **Define 3 custom court types.** In `common/court_types/` (new directory):
+
+   **Noble Keep** (`court_type_noble_keep`):
+   - Available to: `imperial_appointment_government`, noble_scadrian culture
+   - Grandeur bonuses: +0.3 monthly prestige, +5 attraction opinion
+   - Court events: ball invitations, house rivalry gossip, Allomantic
+     demonstrations, marriage proposals, artisan metalworker visits
+   - Amenities: best food (plantation cuisine), fine clothing, musicians
+   - Unique: "Display House Power" interaction — spend gold to increase
+     grandeur temporarily (+20 for 1 year). Impresses visitors.
+   - Visual theme: grand, opulent, ash-dusted luxury (M8 art)
+
+   **Ministry Canton** (`court_type_ministry_canton`):
+   - Available to: `theocratic_ministry_government`, Steel Ministry faith
+   - Grandeur bonuses: +0.2 monthly piety, +5 same-faith opinion
+   - Court events: obligator petitions, doctrinal debates, heresy reports,
+     breeding program reviews, tithe collections
+   - Amenities: austere food, practical clothing, no entertainment
+   - Unique: "Canton Inspection" interaction — inspect a vassal's books.
+     Stewardship check. Success: discover tax fraud (hook) or confirm
+     compliance (+5 opinion).
+   - Visual theme: bureaucratic, grey stone, iron records (M8 art)
+
+   **Underground Hideout** (`court_type_underground_hideout`):
+   - Available to: adventurer government (Kelsier's crew), skaa culture
+     rulers, any ruler with `rebel_leader` flag
+   - Grandeur: minimal (grandeur doesn't matter in a cave). Replace grandeur
+     with "Crew Morale" if Royal Court supports custom metrics, otherwise
+     use low base grandeur with morale-as-prestige.
+   - Court events: crew planning sessions, informant reports, supply runs,
+     close calls with patrols, underground network rumors
+   - Amenities: scrounged food, practical gear, no luxury
+   - Unique: "Secure the Hideout" interaction — spend gold to improve
+     security. Reduces Inquisitor discovery chance for 2 years.
+   - Visual theme: cave/basement, dim lighting, maps on walls (M8 art)
+
+2. **Suppress vanilla court types** that don't fit. Create empty replacement
+   files. Keep any that are sufficiently generic.
+
+3. **Localization.** ~40 keys (3 court type names + descriptions, amenity
+   names, unique interaction tooltips).
+
+**Files:**
+- `common/court_types/00_mistborn_court_types.txt` -- create
+- Vanilla court type suppression files -- create (empty replacements)
+- `localization/english/mistborn_court_types_l_english.yml` -- create
+
+**References:**
+- Vanilla court types: CK3 game install `common/court_types/`
+- Government types: M4 task 4.11
+- Royal Court DLC: required dependency
+- Council/court positions: M4 task 4.8
+- Band system: M5 (underground hideout is the crew's court type)
+
+---
+
+### 4.16 -- Portrait Modifiers (System Definition)
+
+**Context:** CK3's portrait modifier system allows dynamic visual changes to
+characters based on traits, modifiers, or conditions. For Mistborn, this means
+hemalurgic spike eyes on Inquisitors, ash-stained clothing on frontier
+characters, Allomancer burn marks, Terris robes, and mistcloaks. The actual
+art assets are M8 scope, but the system definitions (which conditions trigger
+which visual changes) should be defined in M4 so M8 artists know what to
+create.
+
+**Steps:**
+
+1. **Define portrait modifier triggers.** In
+   `common/portrait_modifiers/00_mistborn_portrait_modifiers.txt` (new file):
+
+   | Modifier | Trigger Condition | Visual Effect (M8) |
+   |---|---|---|
+   | `portrait_hemalurgic_eyes` | Has any `trait_hemalurgic_spike_*` trait | Steel spikes through eyes, pale skin |
+   | `portrait_allomancer_marks` | Has `trait_allomantic_strength_savant` | Burn marks on hands, intense eyes |
+   | `portrait_ash_stained` | Lives in province with `ash_blight` modifier | Grey dust on clothing, darker skin tone |
+   | `portrait_mistcloak` | Has `mistcloak` artifact equipped | Tasseled cloak visible on portrait |
+   | `portrait_terris_robes` | Culture = terris | Traditional Terris robes and jewelry |
+   | `portrait_ministry_tattoos` | Steel Ministry faith + `theocratic_ministry_government` | Facial tattoos (obligator rank markings) |
+   | `portrait_noble_finery` | noble_scadrian culture + tier >= duchy | Elaborate noble clothing, house colors |
+   | `portrait_skaa_rags` | skaa culture + no title OR tier = barony | Worn clothing, lean appearance |
+   | `portrait_pewter_build` | Has `trait_misting_thug` or savant strength | Noticeably muscular build |
+   | `portrait_keeper_earrings` | Has `keeper_identity` flag | Multiple metallic earrings (metalminds) |
+
+2. This task defines the system only — placeholder icon references that M8
+   will replace with actual art assets. The triggers and conditions are what
+   matter for M4.
+
+3. **Localization.** Minimal — portrait modifiers don't have player-facing text.
+   ~10 keys for tooltip descriptions if any.
+
+**Files:**
+- `common/portrait_modifiers/00_mistborn_portrait_modifiers.txt` -- create
+- `localization/english/mistborn_portraits_l_english.yml` -- create (minimal)
+
+**References:**
+- Vanilla portrait modifiers: CK3 game install `common/portrait_modifiers/`
+- Hemalurgic traits: `common/traits/` (spike types)
+- Allomantic strength: `common/traits/` (savant tier)
+- M8 graphics scope: docs/milestones/M8-the-art-of-metals.md
+
+---
+
+### 4.17 -- Full Testing Pass and Error Cleanup
 
 **Context:** With all M4 features in place, a thorough testing pass ensures the
 mod is shareable. The goal is: a friend can install the mod, start a game, and
@@ -2102,6 +2533,9 @@ experience Scadrial with no vanilla anachronisms and no error.log noise.
 
 ## Testing Checkpoints
 
+> See [`docs/TESTING.md`](../TESTING.md) for the full testing protocol, debug
+> decisions, log analysis commands, and helper scripts.
+
 - **After 4.1 (Province Relabeling):**
   - **Test:** Start a game, open the province map mode, hover over every province
     within the mod's borders.
@@ -2190,7 +2624,54 @@ experience Scadrial with no vanilla anachronisms and no error.log noise.
     innovations are gated behind Lord Ruler's fall. Vanilla eras suppressed.
     Keeper characters in realm provide innovation speed bonus.
 
-- **After 4.11 (Full Testing Pass):**
+- **After 4.11 (Government Types):**
+  - **Test:** Start a game. Check government type for Straff Venture — verify
+    "Imperial Appointment" (not feudal). Check succession law — verify no
+    partition. Check a Ministry holding — verify "Theocratic Ministry." Use
+    console to set `lord_ruler_fallen`. Verify Elective Council becomes
+    available as a government transition option.
+  - **Expected:** 3 custom government types functional. Succession rules
+    match government type. Post-rebellion transition works.
+
+- **After 4.12 (Factions):**
+  - **Test:** Start as a skaa character. Verify Skaa Rebellion faction is
+    joinable. As a noble, verify Ministry Loyalist and Noble Reform factions
+    exist. Check that vanilla factions (independence, claimant) are gone.
+    Let rebellion faction reach power threshold — verify ultimatum fires.
+  - **Expected:** 5 custom factions replace vanilla ones. Faction demands
+    match Mistborn setting. Lord Ruler can intervene against factions.
+
+- **After 4.13 (Vassal Contracts):**
+  - **Test:** Open vassal contract view. Verify custom terms appear (Atium
+    Tithe, Allomantic Service, Inquisition Access). Change Inquisition
+    Access to "Denied" — verify attention increases. Set Allomantic Service
+    to "Conscription" — verify opinion penalty.
+  - **Expected:** 6 custom contract terms with multiple levels. Contract
+    changes produce correct mechanical effects.
+
+- **After 4.14 (Secrets/Hooks):**
+  - **Test:** Use console to give a character `secret_allomancer`. Verify
+    it appears in the secrets screen. Use Inquisitor "Investigate" — verify
+    it can discover the secret. Check that discovering a secret creates the
+    appropriate hook type.
+  - **Expected:** 8 custom secret types functional. Secrets integrate with
+    Inquisitor investigation and council tasks. 3 custom hook types work.
+
+- **After 4.15 (Court Types):**
+  - **Test:** As a noble house lord with Royal Court, check court type —
+    verify "Noble Keep." Check a Ministry holding — verify "Ministry Canton."
+    As Kelsier (if playable) — verify "Underground Hideout." Use "Display
+    House Power" interaction.
+  - **Expected:** 3 court types with distinct events and amenities. Vanilla
+    court types suppressed.
+
+- **After 4.16 (Portrait Modifiers):**
+  - **Test:** Verify portrait modifier file loads without errors. Triggers
+    are defined correctly (console check: add spike trait, verify modifier
+    activates). Actual visual changes are M8 scope — system only.
+  - **Expected:** Portrait modifier triggers defined. No error.log entries.
+
+- **After 4.17 (Full Testing Pass):**
   - **Test:** Start a fresh game, play 20 years. Review error.log.
   - **Expected:** Error.log has no mod-related errors. No vanilla anachronisms
     observed. Game runs at acceptable speed. The world feels like Scadrial.
@@ -2279,6 +2760,32 @@ experience Scadrial with no vanilla anachronisms and no error.log noise.
 - [ ] Innovation era gate tooltip explains Lord Ruler's stagnation
 - [ ] Keeper Network provides +5% innovation speed per Keeper (post-rebellion)
 - [ ] Innovation localization complete (~76 keys)
+- [ ] 3 custom government types: Imperial Appointment, Theocratic Ministry,
+      Post-Rebellion Elective
+- [ ] Imperial Appointment prevents partition and locks succession while
+      Lord Ruler lives
+- [ ] Theocratic Ministry grants piety bonuses and Inquisitor access
+- [ ] Elective Council available only after `lord_ruler_fallen`
+- [ ] Vanilla governments suppressed (no feudal/tribal in UI)
+- [ ] 5 custom factions: Skaa Rebellion, Ministry Loyalist, Noble Reform,
+      Keeper Underground, Cult of Ruin
+- [ ] Faction demands match Mistborn setting (caste law changes, Ministry
+      influence, hemalurgic rights)
+- [ ] Lord Ruler can intervene against factions via Inquisitor events
+- [ ] Vanilla factions suppressed
+- [ ] 6 custom vassal contract terms: Plantation Tribute, House Guard,
+      Atium Tithe, Allomantic Service, Inquisition Access, Title Revocation
+- [ ] Contract terms have correct mechanical effects (attention, opinion,
+      income changes)
+- [ ] Contract negotiation events fire for Atium Tithe and Inquisition Access
+- [ ] 8 custom secret types: secret_allomancer, secret_skaa_heritage,
+      secret_keeper_identity, secret_kandra_imposter, secret_atium_hoard,
+      secret_crew_membership, secret_ministry_informant, secret_survivorist
+- [ ] Secrets integrate with Inquisitor investigation and council tasks
+- [ ] 3 custom hook types created from secret discovery
+- [ ] 3 custom court types: Noble Keep, Ministry Canton, Underground Hideout
+- [ ] Court types have distinct events and amenities
+- [ ] Portrait modifier system defined with ~10 triggers for M8 art assets
 - [ ] A 20-year playthrough as Straff Venture completes without crashes
 - [ ] No vanilla anachronisms (names, events, decisions) visible during
       normal gameplay