diff --git a/docs/ck3-modding/ck3-modding-reference.md b/docs/ck3-modding/ck3-modding-reference.md
index d27c41d..2e70222 100644
--- a/docs/ck3-modding/ck3-modding-reference.md
+++ b/docs/ck3-modding/ck3-modding-reference.md
@@ -37,6 +37,7 @@ my_mod/                              # Mod root folder
 │   ├── laws/                        # Realm laws
 │   ├── lifestyles/                  # Lifestyle focuses and perks
 │   ├── men_at_arms_types/           # Custom troop types
+│   ├── modifier_icons/               # Icon definitions for modifiers
 │   ├── modifiers/                   # Static modifiers
 │   ├── nicknames/                   # Character nicknames
 │   ├── on_action/                   # Event hooks (game triggers)
@@ -232,6 +233,51 @@ the county name loc.
 language pillars need `_name` variants; traditions need `_name` variants
 and `culture_parameter_*` bonus description keys.
 
+**Modifier icons use indirection via `common/modifier_icons/`.** Do NOT put
+full DDS paths in modifier `icon =` fields. CK3 resolves modifier icons
+through definition files in `common/modifier_icons/`. Each definition maps a
+bare name to a DDS path:
+
+```
+# common/modifier_icons/00_my_modifier_icons.txt
+my_modifier_icon = {
+    positive = "gfx/interface/icons/modifiers/my_modifier_icon.dds"
+}
+```
+
+Then reference the bare name in your modifier:
+
+```
+# common/modifiers/00_my_modifiers.txt
+my_modifier = {
+    icon = my_modifier_icon
+    prowess = 5
+}
+```
+
+If you use `icon = "gfx/interface/icons/modifiers/my_icon.dds"` directly, CK3
+auto-prepends the path and appends `.dds` again, producing a doubled path like
+`gfx/.../gfx/.../my_icon.dds.dds` that generates dozens of `missing-file`
+warnings.
+
+**`on_game_start` has no character scope.** Events listed in `on_game_start`
+must use `scope = none`. They cannot be `type = character_event`. To
+initialize characters at game start, use `every_living_character` inside the
+event's `immediate` block:
+
+```
+my_init.0001 = {
+    scope = none
+    hidden = yes
+    immediate = {
+        every_living_character = {
+            limit = { is_ruler = yes }
+            # character-scoped effects here
+        }
+    }
+}
+```
+
 **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
@@ -569,6 +615,8 @@ To update: make changes locally, then re-upload through the launcher.
 | 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) |
+| Modifier icon doubled paths | Full DDS path in modifier `icon =` field | Use bare names via `common/modifier_icons/` definitions (see Gotchas) |
+| on_game_start scope errors | Character events/triggers in `on_game_start` | Use `scope = none` events with `every_living_character` inside |
 
 ## Resources