diff --git a/docs/ck3-modding/ck3-modding-reference.md b/docs/ck3-modding/ck3-modding-reference.md
index bf29150..d27c41d 100644
--- a/docs/ck3-modding/ck3-modding-reference.md
+++ b/docs/ck3-modding/ck3-modding-reference.md
@@ -189,6 +189,55 @@ for tracking translation updates. For mods, use `0` or `1`.
   needs a localization entry
 - Missing keys display as raw key names in-game (e.g., `trait_misting_coinshot`)
 
+### Localization Gotchas
+
+**Religion custom loc requires mapping blocks.** Simply adding faith-prefixed
+keys to your `.yml` files (e.g., `my_faith_HighGodName:0 "The Creator"`) is
+NOT sufficient. You must also add a `localization = { }` block to each
+religion in the definition file that maps generic key names to your prefixed
+loc strings:
+
+```
+my_religion = {
+    localization = {
+        HighGodName = my_faith_HighGodName
+        HighGodNamePossessive = my_faith_HighGodNamePossessive
+        PriestMale = my_faith_PriestMale
+        PriestFemale = my_faith_PriestFemale
+        # ... 128 keys total (see vanilla 00_christianity.txt for full list)
+    }
+    faiths = { ... }
+}
+```
+
+Without these mapping blocks, CK3 cannot find your faith-specific loc keys
+and ck3-tiger reports hundreds of `missing-localization` warnings.
+
+**Trait keys are looked up with double prefix.** CK3 looks up traits as both
+`trait_name` and `trait_trait_name`. If your traits use a `trait_` prefix
+(e.g., `trait_misting_coinshot`), you need loc entries for both
+`trait_misting_coinshot` and `trait_trait_misting_coinshot` (name + desc).
+
+**Name list names need loc keys.** Every name in `male_names` and
+`female_names` blocks of a name list requires a localization entry
+(`Kelsier:0 "Kelsier"`). Names without loc still work but generate
+ck3-tiger warnings.
+
+**County titles need adjective keys.** CK3 uses `<county_key>_adj` for
+demonyms (e.g., `c_luthadel_adj:0 "Luthadel"`). These are separate from
+the county name loc.
+
+**Culture/heritage/language need extra keys.** Beyond the base key and
+`_desc`, cultures need `_prefix` and `_collective_noun`; heritage and
+language pillars need `_name` variants; traditions need `_name` variants
+and `culture_parameter_*` bonus description keys.
+
+**Province history for total conversions.** Vanilla provinces without any
+history definition generate "Province with no county data" errors. Provide
+`holding = none` defaults for unused provinces. But do NOT redefine provinces
+that vanilla already has history for — that creates `duplicate-field` warnings.
+Only cover the gap: provinces with zero history anywhere.
+
 ## Events
 
 ### Namespace Declaration
@@ -517,6 +566,9 @@ To update: make changes locally, then re-upload through the launcher.
 | `replace_path` not working | Known CK3 bug/limitation | Use empty file replacement instead |
 | Wrong trait activating | LIOS override — file sort order wrong | Name files to sort correctly (00_, 01_ prefix) |
 | Mod not detected | `.mod` file path wrong or uses backslashes | Use forward slashes only in path field |
+| Religion loc not found | Missing `localization = { }` mapping block in religion definition | Add mapping block to each religion (see Localization Gotchas) |
+| Hundreds of trait loc warnings | CK3 looks up `trait_trait_X` in addition to `trait_X` | Add double-prefix loc entries for all traits |
+| Province log flooding | Vanilla provinces without history in your TC | Add `holding = none` defaults for unused province IDs (skip vanilla-defined ones) |
 
 ## Resources