diff --git a/docs/ADDON_COMPAT.md b/docs/ADDON_COMPAT.md
index 45d1ac15..98025a36 100644
--- a/docs/ADDON_COMPAT.md
+++ b/docs/ADDON_COMPAT.md
@@ -1836,3 +1836,61 @@ their own — it is on the list — but it cannot be the whole answer while any
   Quest tracker row, exactly as the Questie file does it. No `own`/`hook`: pfQuest fades the
   *regions* inside its tracker (`tracker.lua:178`, `:373`) and never the tracker frame, so there is
   no second owner of the thing Cinematic writes.
+
+## The realm's LibStub hardcodes `minor = 2`, so the first copy of a library wins outright
+
+This one explains a class of failures, not one bug. `Interface\FrameXML\AIO\Dep_LibWindow-1.1\
+LibStub.lua` is the realm's own, it loads **before every addon**, and it is the LibStub the whole
+install runs on. Its `NewLibrary` has had the upstream minor-version parse replaced by a literal:
+
+```lua
+	function LibStub:NewLibrary(major, minor)
+		assert(type(major) == "string", "Bad argument #2 to `NewLibrary' (string expected)")
+		minor = 2                       -- upstream: tonumber(strmatch(minor, "%d+"))
+		local oldminor = self.minors[major]
+		if oldminor and oldminor >= minor then return nil end
+```
+
+So every library registers as minor **2**, every later copy is refused (`2 >= 2`), and **the first
+copy of a library to load wins regardless of version**. Measured in the whole-corpus harness: all 22
+registered libraries carry minor 2, and `NewLibrary("Probe", 41)` then `NewLibrary("Probe", 49)`
+gives the second call nil.
+
+The consequence that reached grom: three copies of AceGUI-3.0 are installed — two 1.12 backports at
+widget-core minor 34 and OpenMapClassic's retail copy at 41. A backport's core wins by load order.
+But widget **files** are separate files that never go through LibStub — `RegisterWidgetType`
+compares widget versions itself — so the retail tree's widgets load and win. The install therefore
+runs **newer widgets against an older core**, and the two disagree about what the core provides:
+
+- `AceGUI.tooltip` is created by the retail core and by neither backport, so it was nil, and
+  `AceGUIContainer-TreeGroup`'s `Button_OnEnter`/`OnLeave` raised on every category row the mouse
+  touched (`attempt to index field 'tooltip'`, visible in grom's chat).
+- `OptionsListButtonTemplate.toggle` is the same shape of disagreement one layer out, between the
+  retail widget and this realm's 1.12 template.
+
+Fixed in the port, where the odd copy is: when `NewLibrary` refuses this tree's AceGUI, it now
+takes the library that *did* win and gives it the one thing this tree's widgets need of it. The
+whole-corpus harness confirms `AceGUI.tooltip` is a real tooltip again and `SetOwner`/`SetText`/
+`Show`/`Hide` all answer.
+
+**The rule worth carrying:** on this client, "which copy of a library is newest" does not decide
+anything — **load order does**. Before reasoning about a library's behaviour here, find the copy
+that registered, not the copy with the highest version.
+
+## `WOW_MAP_TRACE=1`: what the map's base art actually is
+
+A player's report about how the map *looks* cannot be answered from this side. The offline addon
+harness seats no renderer, the capture harness seats no UI or addons, and a login as anyone but the
+player would kick them off their own account — so a full day of offline audit (art present and
+correct, catalog right, canvas geometry right, overlay tiling arithmetic right, addon setup
+complete) still could not say why grom's Dun Morogh map came up magnified, clipped and grey.
+
+Every number that decides the picture *is* readable from the VM, so `WOW_MAP_TRACE=1` now prints
+them once per map change (`ui_world_map.rs`): the detail frame's rect and effective scale, then per
+tile its rect, the texture path it holds, and the **decoded size of that file** — measured through
+a scratch texture with no size of its own, because the tile declares 256x256 in
+`WorldMapFrame.xml` and would answer that whatever the file holds (this install's art is a 512²
+upscale pack). A tile whose rect is not 256x256 at a 256 pitch, or whose file is not the size the
+layout assumes, names the fault outright instead of being guessed at from a screenshot.
+
+Off unless the variable is set: it runs a Lua chunk per map change.