diff --git a/MASTERPLAN.md b/MASTERPLAN.md
index e24d897..4c4901a 100644
--- a/MASTERPLAN.md
+++ b/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.
 
 ---
 
diff --git a/docs/milestones/M3-the-final-empire.md b/docs/milestones/M3-the-final-empire.md
index 06bdd32..cd52b86 100644
--- a/docs/milestones/M3-the-final-empire.md
+++ b/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
 
diff --git a/docs/milestones/M4-scadrial-on-the-map.md b/docs/milestones/M4-scadrial-on-the-map.md
index 3677d3f..a034483 100644
--- a/docs/milestones/M4-scadrial-on-the-map.md
+++ b/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