diff --git a/crates/benilla-app/Cargo.toml b/crates/benilla-app/Cargo.toml
index e61c481a..c6b65cd4 100644
--- a/crates/benilla-app/Cargo.toml
+++ b/crates/benilla-app/Cargo.toml
@@ -9,40 +9,34 @@ description = "The Bevy app as a library: everything but the build-id stamp, whi
 workspace = true
 
 [features]
-# `dev` compiles in the instruments: the debug panel, perf HUD, inspector, capture harness and
-# probes. Nothing may depend on it; `scripts/gates.sh` builds `benilla` with no default features.
+# `dev` compiles in the instruments; the player build (`scripts/gates.sh`) has no defaults.
 default = ["dev"]
-# `benilla-assets`, `-formats` and `-world` come in without default features and their `dev` is
-# forwarded here: it is on by default in each, so unification would put it back in a player build.
+# The asset, format and world crates default `dev` on, so they come in without it, forwarded here.
 dev = ["benilla-assets/dev", "benilla-formats/dev", "benilla-world/dev", "dep:bevy_egui"]
 tracy = ["bevy/trace_tracy"]
-# `--features trace_chrome` writes every system's per-run span to `trace-<ts>.json` in the cwd.
+# Writes every system's per-run span to `trace-<ts>.json` in the cwd.
 trace_chrome = ["bevy/trace_chrome"]
 
 [dependencies]
 anyhow.workspace = true
-# The EditBox clipboard chords, read on the main thread as macOS NSPasteboard requires; Wayland
-# goes through `smithay-clipboard`. The 3.x bevy_egui uses, so the graph has one copy.
+# The EditBox clipboard, on the main thread as NSPasteboard requires; bevy_egui's 3.x.
 arboard = "3"
 benilla-ui = { path = "../benilla-ui" }
 bevy.workspace = true
 wgpu.workspace = true
 bevy_egui = { version = "0.39", optional = true }
 bytemuck = { version = "1", features = ["derive"] }
-# `f16` decode for the `WOW_BOOTH_DUMP` dump of the `Rgba16Float` booth render targets.
+# `f16` decode for the `WOW_BOOTH_DUMP` dump of the `Rgba16Float` booth targets.
 half = "2"
 # Compiles `assets/ui` into the binary, so the interface loads on a machine without the source.
 include_dir = "0.7"
-# The 1.12 chat filters (`text_filter`): the DBCs' 2289 profanity and 28 spam patterns, with one
-# `RegexSet` for the any-match pass over every chat line.
+# The 1.12 chat filters (`text_filter`), with one `RegexSet` for the any-match pass per line.
 regex = "1"
-# `getrusage` for the perf probes' process CPU time; `mach_absolute_time` and `thread_policy_set`
-# for the audio output's meter clock and its render thread's realtime policy.
+# `getrusage` for perf CPU time; the audio clock and render thread's realtime policy on macOS.
 libc = "0.2"
-# PNG encoding only: the macOS hardware cursor's NSImage data and screenshots.
+# PNG encoding only: the macOS cursor's NSImage data and screenshots.
 image = { version = "0.25", default-features = false, features = ["png"] }
-# Thread-to-ECS channels such as the net bridge's: crossbeam's `Receiver` is `Sync`, so either end
-# can be a Bevy resource without a mutex.
+# Thread-to-ECS channels: crossbeam's `Receiver` is `Sync`, so it is a resource without a mutex.
 crossbeam-channel = "0.5"
 benilla-assets = { path = "../benilla-assets", default-features = false }
 benilla-formats = { path = "../benilla-formats", default-features = false }
@@ -55,33 +49,29 @@ toml = "0.8"
 avian3d = "0.6"
 # Shapes and rasterizes `FontString` text standalone (`ui_text`), at bevy_text's own 0.16.
 cosmic-text = "0.16"
-# `cosmic-text`'s font database, whose types `ui_text` names; must stay the version it depends on.
+# `cosmic-text`'s font database, named by `ui_text`; must stay the version it depends on.
 fontdb = "0.23"
 # The mixer. Its `cpal` backend stays off on every target: `sound::output` is our own backend.
 kira = { version = "0.12", default-features = false, features = ["mp3", "wav", "pcm", "adpcm"] }
 # Aborts a debug build on an allocation in the audio IO callback or render pass; off in release.
 assert_no_alloc = "1.1"
-# For `MediaSource`: kira's decode thread reads through our source, which raises the thread's QoS
-# so the world-entry burst cannot starve it. Must stay kira's version, or the trait won't match.
+# `MediaSource`: our source raises kira's decode thread's QoS; must stay kira's version.
 symphonia = { version = "0.5", default-features = false }
 # The audio threads' lock-free SPSC rings (output, mix tap); kira's version, so the graph has one.
 rtrb = "0.3"
 mint = "0.5"
-# The gossip greeting's weighted draw, re-rolled per open as in the reference; `benilla-srp`'s 0.8.
+# The gossip greeting's weighted draw, re-rolled per open as in the reference.
 rand = "0.8"
 
-# Linux/BSD Wayland clipboard: smithay-clipboard drives the standard `wl_data_device` on our own
-# `wl_display`, read through raw-window-handle (bevy's 0.6). arboard's Wayland feature speaks
-# `wlr-data-control`, which GNOME does not implement.
+# Wayland clipboard over the standard `wl_data_device`; arboard's speaks `wlr-data-control`,
+# which GNOME does not implement.
 [target.'cfg(all(unix, not(any(target_os = "macos", target_os = "android"))))'.dependencies]
 raw-window-handle = "0.6"
 smithay-clipboard = "0.7"
 
-# macOS: AppKit through objc2 drives a native NSCursor with the window's cursor rects disabled;
-# winit's cursor rects revert to the arrow under our continuous render loop (`cursor.rs`).
+# A native NSCursor: winit's cursor rects revert to the arrow under a continuous render loop.
 [target.'cfg(target_os = "macos")'.dependencies]
-# The audio device layer (`sound::output::coreaudio`): the HAL output unit through coreaudio-rs,
-# the AudioObject property API through objc2-core-audio, at the versions and features cpal uses.
+# The audio device layer (`sound::output::coreaudio`), at the versions and features cpal uses.
 coreaudio-rs = { version = "0.13", default-features = false, features = ["audio_unit", "core_audio"] }
 objc2-core-audio = { version = "0.3", default-features = false, features = ["std", "AudioHardware"] }
 objc2-core-audio-types = { version = "0.3", default-features = false, features = ["std", "CoreAudioBaseTypes"] }
@@ -89,7 +79,6 @@ objc2 = "0.5"
 objc2-app-kit = { version = "0.2", features = [
     "NSApplication",
     "NSResponder",
-    # NSApplicationActivationPolicy (bgwin's Accessory demotion) is declared in this header.
     "NSRunningApplication",
     "NSWindow",
     "NSView",
@@ -99,12 +88,11 @@ objc2-app-kit = { version = "0.2", features = [
 ] }
 objc2-foundation = { version = "0.2", features = ["NSArray", "NSData", "NSGeometry"] }
 
-# Off macOS the device layer's last hop runs over cpal (`sound::output::cpal`). macOS goes direct:
-# there cpal cannot report or rebuild on a lost default device and drops the IO-cycle timestamp.
-# An unsupported target gets cpal's Null host, which reports no device.
+# The audio device layer off macOS (`sound::output::cpal`); on macOS cpal cannot rebuild on a
+# lost default device and drops the IO-cycle timestamp.
 [target.'cfg(not(target_os = "macos"))'.dependencies]
 cpal = "0.17"
 
-# Windows CPU clocks for `perf::clock`: `GetProcessTimes`, `GetThreadTimes`, `GetSystemTimes`.
+# Windows CPU clocks for `perf::clock`.
 [target.'cfg(windows)'.dependencies]
 windows-sys = { version = "0.59", features = ["Win32_Foundation", "Win32_System_Threading"] }
diff --git a/crates/benilla-app/assets/ui/ContainerFrameAdapters.xml b/crates/benilla-app/assets/ui/ContainerFrameAdapters.xml
index d6f168ae..26466581 100644
--- a/crates/benilla-app/assets/ui/ContainerFrameAdapters.xml
+++ b/crates/benilla-app/assets/ui/ContainerFrameAdapters.xml
@@ -1,19 +1,13 @@
 <!--
-    Our adapters over the stock `Interface\FrameXML\ContainerFrame.xml` and `.lua`, which run off
-    the player's patch chain: the bag windows are the stock `ContainerFrame1..12`. This file loads
-    after them, so its definitions win; a stock body that needs a benilla answer is wrapped here.
-    Deviation: benilla's keyring is a container (id -2) where the reference's is inventory slots,
-    so a keyring slot's tooltip comes from `GameTooltip:SetBagItem` like any bag's; the stock
-    keyring fork in `ContainerFrameItemButton_OnEnter` (ContainerFrame.lua l.615-620) reads the
-    inventory-slot space, which our keyring items are not in.
-    A full keyring prints the reference's empty error line: its `PutKeyInKeyRing` reads
-    `NO_EMPTY_KEYRING_SLOTS`, which 1.12 does not ship (it has `NO_EMPTY_KEYRING_SLOTS_ERROR`).
-    That is the reference's behaviour, kept.
+    Adapters over the stock ContainerFrame.xml and .lua; loaded after them, so these win.
+    Deviation: our keyring is a container (id -2), not inventory slots as in the reference, so its
+    tooltip comes from `SetBagItem`; the stock fork (ContainerFrame.lua:615-620) reads the slots.
+    A full keyring prints an empty error line as the reference does: `PutKeyInKeyRing` reads
+    `NO_EMPTY_KEYRING_SLOTS`, which 1.12 does not ship.
 -->
 <Ui xmlns="http://www.blizzard.com/wow/ui/">
     <Script><![CDATA[
-        -- The stock body, captured before the name is shadowed. It is nil when no client data was
-        -- sourced, and the call then says so rather than doing nothing.
+        -- The stock body, captured before it is shadowed; nil when no client data was sourced.
         local refItemButtonOnEnter = ContainerFrameItemButton_OnEnter
 
         function ContainerFrameItemButton_OnEnter(button)
@@ -22,8 +16,7 @@
             end
             if not button then return end
 
-            -- Our keyring is a container, so its slot takes the stock general path's calls for a
-            -- bag slot instead of the inventory-slot detour.
+            -- The stock bag-slot path, not its inventory-slot keyring detour.
             if button:GetParent():GetID() == KEYRING_CONTAINER then
                 if (button:GetRight() or 0) >= (GetScreenWidth() / 2) then
                     GameTooltip:SetOwner(button, "ANCHOR_LEFT")
@@ -44,29 +37,22 @@
         end
 
         -- ══ The three bag verbs benilla answers differently ═══════════════════════════════════
-        -- Deviation: `OpenBackpack` opens every equipped bag, not only the backpack, so the
-        -- vendor, bank, mail and trade windows that call it from OnShow bring up every bag to sell
-        -- or deposit from; `CloseBackpack` is its inverse, `CloseAllBags` the unconditional form.
-        -- The was-open memory is keyed by bag id because `ContainerFrame1..12` are recycled across
-        -- bags, and every open and close goes through the stock `OpenBag`/`CloseBag`/`IsBagOpen`,
-        -- so their guards and any addon that replaces them apply.
+        -- Deviation: `OpenBackpack` opens every equipped bag, not only the backpack, so the vendor,
+        -- bank, mail and trade windows that call it bring up every bag to sell or deposit from.
+        -- The was-open memory is keyed by bag id: `ContainerFrame1..12` are recycled across bags.
         BENILLA_BAG_WAS_OPEN = {}
 
-        -- The unconditional close, from the stock ShowUIPanel's centre branch: it ignores the
-        -- was-open memory and covers the bank bags, as the reference's CloseAllBags does
-        -- (l.702-707).
+        -- Ignores the was-open memory and covers the bank bags, as ContainerFrame.lua:702-707 does.
         function BenillaCloseAllBags()
             for bagId = 0, (NUM_CONTAINER_FRAMES or -1) do
                 CloseBag(bagId)
             end
         end
 
-        -- A bag already open is remembered and left alone, so CloseBackpack leaves open a window
-        -- the player opened; the reference's `backpackWasOpen`, one entry per bag.
+        -- The reference's `backpackWasOpen`, one entry per bag: CloseBackpack leaves those open.
         function BenillaOpenBackpack()
             for bagId = 0, (NUM_BAG_FRAMES or -1) do
-                -- OpenBag's own test, repeated so the memory agrees with it: the backpack always,
-                -- another bag only when its slot holds one.
+                -- OpenBag's own test, repeated so the memory agrees with it.
                 if bagId == 0 or GetContainerNumSlots(bagId) > 0 then
                     if IsBagOpen(bagId) then
                         BENILLA_BAG_WAS_OPEN[bagId] = 1
@@ -86,8 +72,7 @@
             end
         end
 
-        -- Published after the stock ContainerFrame.lua has loaded, so these are the definitions its
-        -- callers reach (the stock `ShowUIPanel`'s `CloseAllBags`, a vendor's `OpenBackpack`).
+        -- After the stock ContainerFrame.lua has loaded, so its callers reach these.
         OpenBackpack = BenillaOpenBackpack
         CloseBackpack = BenillaCloseBackpack
         CloseAllBags = BenillaCloseAllBags
diff --git a/crates/benilla-app/assets/ui/GameMenuFrame.xml b/crates/benilla-app/assets/ui/GameMenuFrame.xml
index 72422d9b..955fa369 100644
--- a/crates/benilla-app/assets/ui/GameMenuFrame.xml
+++ b/crates/benilla-app/assets/ui/GameMenuFrame.xml
@@ -1,17 +1,9 @@
 <Ui>
     <!--
-        The game menu, the frame ESC opens. Its chrome is the reference GameMenuFrame.xml's: DIALOG
-        strata, the UI-DialogBox backdrop (insets 11/12/12/11, 32px tile and edge), the 256x64
-        header at TOP +12 with the title 14px down it, the reference's click sounds, and the stock
-        `GameMenuButtonTemplate`, which the era's MainMenuFrameButtonTemplate matches in art,
-        size and label fonts.
-        Deviation: the ladder is the 1.15 era client's ESC menu (GameMenuFrame.lua l.62-162),
-        because its settings screens replace 1.12's, which are much worse to use. It keeps the
-        era's layout numbers, padding 32 top and 28 elsewhere (MainMenuFrameTemplates.xml
-        l.18-33) and a 20-unit gap between groups (MainMenuFrameTemplates.lua l.61-71), and drops
-        the era's AddOns rung, because the character-select AddOns screen is the only addon UI;
-        Key Bindings is in the options window, as in the era.
-        Names are the reference's, unprefixed: addons address `GameMenuFrame` by name.
+        The game menu ESC opens, in the chrome of the reference's GameMenuFrame.xml.
+        Deviation: the rungs are the 1.15 era client's ESC menu, because its settings screens
+        replace 1.12's, which are much worse to use; the era's AddOns rung is dropped, since the
+        character-select AddOns screen is the only addon UI. Addons address `GameMenuFrame` by name.
     -->
     <Script><![CDATA[
         -- Label strings as `X = X or "..."`, so a stock GlobalStrings value wins where one exists.
@@ -24,18 +16,15 @@
         RETURN_TO_GAME = RETURN_TO_GAME or "Return to Game"
         CANCEL = CANCEL or "Cancel"
 
-        -- Labels and disables a rung with nothing behind it yet (Edit Mode, Support), greyed on the
-        -- template's -Disabled art the way the era menu greys a dead entry.
+        -- A rung with nothing behind it yet (Edit Mode, Support), disabled.
         function GameMenuButton_Pending(button, text)
             button:SetText(text)
             button:Disable()
         end
 
         -- ══ Our options window in the stock "is an options window open?" checks ══
-        -- The three stock functions name the reference's options windows, which here are hidden
-        -- stock frames, so each is wrapped to add `BenillaOptionsFrame` and still runs the stock
-        -- body. Wrapped here because this file loads last: `UpdateMicroButtons`
-        -- (MainMenuBarMicroButtons.xml) loads after our options window.
+        -- Each wraps the stock body to add `BenillaOptionsFrame`; here because this file loads
+        -- last, after MainMenuBarMicroButtons.xml.
         local Ref_IsOptionFrameOpen = IsOptionFrameOpen
         local Ref_ToggleGameMenu = ToggleGameMenu
         local Ref_UpdateMicroButtons = UpdateMicroButtons
@@ -45,8 +34,7 @@
             return BenillaOptionsFrame and BenillaOptionsFrame:IsVisible()
         end
 
-        -- `UIParent.lua:996`, read by `CloseAllWindows_WithExceptions`: a yes keeps the ESC sweep
-        -- off the centre panel, which our window is, so ESC closes it through its own rung.
+        -- `UIParent.lua:996`: a yes keeps the ESC sweep off the centre panel, which our window is.
         function IsOptionFrameOpen()
             if BenillaOptions_IsOpen() then
                 return 1
@@ -54,13 +42,11 @@
             return Ref_IsOptionFrameOpen()
         end
 
-        -- `UIParent.lua:1465-1497`, the ESC ladder: static popup first, then an open options
-        -- window, then the rest of the stock ladder. The stock body re-runs the popup rung, a pure
-        -- scan when nothing is shown (`StaticPopup.lua:1879-1893`). Our Close button's click is
-        -- the discard-and-hide the reference reaches through `OptionsFrameCancel:Click()`.
+        -- `UIParent.lua:1465-1497`: static popup, then an open options window, then the stock
+        -- ladder. Our Close click is the discard-and-hide of the reference's `OptionsFrameCancel`.
         function ToggleGameMenu(clicked)
             if clicked then
-                -- As the reference's `clicked` arm: close an options window, then still toggle.
+                -- As the reference's `clicked` arm: close an options window, then toggle.
                 if BenillaOptions_IsOpen() then
                     BenillaOptionsFrameCloseButton:Click()
                 end
@@ -76,9 +62,8 @@
             return Ref_ToggleGameMenu(clicked)
         end
 
-        -- `MainMenuBarMicroButtons.lua:47-58`: a post-hook that only ever pushes the Main Menu
-        -- button, never releases it, so the stock decision over its six frames stands and ours adds
-        -- the seventh. Guarded for a test kit that loads this file without the micro bar.
+        -- `MainMenuBarMicroButtons.lua:47-58`: only ever pushes the button, so the stock decision
+        -- stands and ours adds our window.
         function UpdateMicroButtons()
             if Ref_UpdateMicroButtons then
                 Ref_UpdateMicroButtons()
@@ -90,18 +75,15 @@
 
     ]]></Script>
 
-    <!-- The era's header font, GameFontNormalMed1 (FRIZQT 13, gold): an era name 1.12's Fonts.xml
-         lacks, declared beside its one consumer. -->
+    <!-- The era's header font, which 1.12's Fonts.xml lacks. -->
     <Font name="GameFontNormalMed1" inherits="GameFontNormal" virtual="true">
         <FontHeight><AbsValue val="13"/></FontHeight>
     </Font>
 
 
-    <!-- The reference frame's attributes (GameMenuFrame.xml l.3) except `movable`, which is inert
-         there: the reference defines no drag scripts. -->
+    <!-- GameMenuFrame.xml:4's attributes but `movable`, inert there: it has no drag scripts. -->
     <Frame name="GameMenuFrame" parent="UIParent" frameStrata="DIALOG" toplevel="true" enableMouse="true" hidden="true">
-        <!-- The era layout: 28+144+28 wide; 32 top and 28 bottom padding around seven 21-unit
-             rungs and three 20-unit section gaps. -->
+        <!-- The era layout: 28+144+28 wide, 32 top, 28 bottom, 7 rungs of 21, 3 gaps of 20. -->
         <Size><AbsDimension x="200" y="267"/></Size>
         <Anchors><Anchor point="CENTER"/></Anchors>
         <Backdrop bgFile="Interface\DialogFrame\UI-DialogBox-Background" edgeFile="Interface\DialogFrame\UI-DialogBox-Border" tile="true">
@@ -115,8 +97,7 @@
                     <Size><AbsDimension x="256" y="64"/></Size>
                     <Anchors><Anchor point="TOP"><Offset><AbsDimension x="0" y="12"/></Offset></Anchor></Anchors>
                 </Texture>
-                <!-- The era's 13px header font (MainMenuFrameMixin:OnLoad) on the 1.12 seat, which
-                     is within half a unit of the era's. -->
+                <!-- The era's 13px font on the 1.12 seat, within half a unit of the era's. -->
                 <FontString name="GameMenuFrameTitle" inherits="GameFontNormalMed1" text="MAIN_MENU">
                     <Anchors>
                         <Anchor point="TOP" relativeTo="GameMenuFrameHeader"><Offset><AbsDimension x="0" y="-14"/></Offset></Anchor>
@@ -126,9 +107,7 @@
         </Layers>
         <Frames>
 
-            <!-- The era's Options entry (GameMenuFrame.lua l.88), opening our options window. A
-                 literal label: 1.12 has no GAMEMENU_OPTIONS, and its OPTIONS_MENU is a different
-                 string, "Options Menu". -->
+            <!-- Literal: 1.12 has no GAMEMENU_OPTIONS; its OPTIONS_MENU is "Options Menu". -->
             <Button name="GameMenuButtonOptions" inherits="GameMenuButtonTemplate" text="Options">
                 <Anchors>
                     <Anchor point="TOPLEFT"><Offset><AbsDimension x="28" y="-32"/></Offset></Anchor>
@@ -158,7 +137,7 @@
                 <Anchors>
                     <Anchor point="TOPLEFT" relativeTo="GameMenuButtonSupport" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="0"/></Offset></Anchor>
                 </Anchors>
-                <!-- The reference's body (GameMenuFrame.xml l.118-122). -->
+                <!-- GameMenuFrame.xml:118-122. -->
                 <Scripts>
                     <OnClick>
                         PlaySound("igMainMenuOption")
@@ -168,8 +147,7 @@
                 </Scripts>
             </Button>
 
-            <!-- The reference's OnShow disables Logout and Exit Game while a CAMP or QUIT countdown
-                 is up, so a running countdown cannot be re-armed. -->
+            <!-- As the reference: disabled while a CAMP or QUIT countdown is up. -->
             <Button name="GameMenuButtonLogout" inherits="GameMenuButtonTemplate" text="LOGOUT">
                 <Anchors>
                     <Anchor point="TOPLEFT" relativeTo="GameMenuButtonMacros" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-20"/></Offset></Anchor>
@@ -220,14 +198,11 @@
                 </Scripts>
             </Button>
         </Frames>
-        <!-- The reference's OnShow/OnHide: the Main Menu micro button pushes in and the bag
-             buttons grey out while the menu is up. Guarded for a test that loads this file
-             without the action bar. -->
+        <!-- The reference's OnShow/OnHide, guarded for a test that loads no action bar. -->
         <Scripts>
             <OnShow>
-                -- Deviation: ERA_WINDOW_SCALE (OptionsFrame.xml, loaded earlier) stands in for the
-                -- UIParent scale the era draws this menu and its options window at.
-                -- A second OnShow on this frame would replace this one: the last SetScript wins.
+                -- ERA_WINDOW_SCALE (OptionsFrame.xml) stands in for the era's UIParent scale. A
+                -- second OnShow on this frame would replace this one.
                 this:SetScale(ERA_WINDOW_SCALE or 1)
                 if UpdateMicroButtons then UpdateMicroButtons() end
                 if Disable_BagButtons then Disable_BagButtons() end
diff --git a/crates/benilla-app/assets/ui/KeyBindingsPage.xml b/crates/benilla-app/assets/ui/KeyBindingsPage.xml
index 2c316954..a89fa332 100644
--- a/crates/benilla-app/assets/ui/KeyBindingsPage.xml
+++ b/crates/benilla-app/assets/ui/KeyBindingsPage.xml
@@ -1,24 +1,16 @@
 <Ui>
     <!--
-        The key bindings page: the options window's Keybindings category, over the engine's
-        binding table and the 1.12 binding API. This file holds the templates and the script; the
-        rows are children of the Keybindings body in OptionsFrame.xml, which loads after it. Only
-        commands the engine dispatches are registered, so only they and their categories appear.
-        Deviation: the page is the era Settings panel's Keybindings page (Keybindings.lua,
-        KeybindingsOverrides.lua), because 1.12's settings screens are much worse to use. It is
-        one list of collapsible category sections, the Character Specific Keybindings checkbox as
-        its first row, and search results that open this page.
-        Capture and set follow 1.12's Blizzard_BindingUI where the two differ: a capsule click
-        arms, the next key or mouse 3/4/5 press binds at once, left and right clicks only select,
-        the wheel binds like any key, and ESC while armed binds Escape (1.12's OnKeyDown has no
-        ESCAPE filter; Unbind Key clears).
+        The options window's Keybindings page: templates and script; its rows live in
+        OptionsFrame.xml, which loads after. Only commands the engine dispatches appear.
+        Deviation: the layout is the era Settings panel's Keybindings page (collapsible category
+        sections), because 1.12's settings screens are much worse to use. Capture follows 1.12's
+        Blizzard_BindingUI: the next key or mouse 3/4/5 press binds, left and right clicks only
+        select, and ESC while armed binds Escape (its OnKeyDown has no ESCAPE filter).
         Deviation: every bind, unbind and reset saves at once, as the era panel commits, where
         1.12 had Okay and Cancel; only Reset To Default and leaving the character set confirm.
     -->
 
-    <!-- A key capsule, 1.12's KeyBindingFrameBindingButtonTemplate: UIPanelButtonTemplate2 art at
-         180x22 with the small font trio, registered for all five buttons so a middle, 4 or 5
-         press reaches the capture. Selected is its LockHighlight, the ADD highlight held on. -->
+    <!-- 1.12's KeyBindingFrameBindingButtonTemplate; all five buttons reach the capture. -->
     <Button name="KeyBindingButtonTemplate" virtual="true">
         <Size><AbsDimension x="180" y="22"/></Size>
         <ButtonText name="$parentText"/>
@@ -34,10 +26,8 @@
         </Scripts>
     </Button>
 
-    <!-- A list row, painted as a binding (name, two capsules) or as a section header: one toggle
-         in 1.12's QuestLogTitleButton dress, the 16x16 plus/minus square and gold label, since
-         the era's expand arrows are not in 1.12. Both are 25 tall, the era's one row height
-         (SettingsKeybindingSectionInitializer:GetExtent). -->
+    <!-- A binding row or a section header in 1.12's QuestLogTitleButton dress, since the era's
+         expand arrows are not in 1.12; 25 tall, the era's row height. -->
     <Frame name="KeyBindingRowTemplate" virtual="true">
         <Size><AbsDimension x="560" y="25"/></Size>
         <Layers>
@@ -91,10 +81,8 @@
             return fallback
         end
 
-        -- ── Key display ── 1.12's GetBindingText in full form, as the reference shows it here and
-        -- in tooltips (the action bar's abbreviated form is the stock GetBindingText): modifier
-        -- prefixes stay uppercase tokens, the base key reads its KEY_* global, else itself.
-        -- "CTRL--" is CTRL plus the minus key.
+        -- ── Key display ── 1.12's GetBindingText in full form: modifier prefixes stay tokens, the
+        -- base key reads its KEY_* global. "CTRL--" is CTRL plus the minus key.
         function KeyBindings_KeyText(key)
             if not key then
                 return NORMAL_FONT_COLOR_CODE .. KeyBindings_String("NOT_BOUND", "Not Bound") .. FONT_COLOR_CODE_CLOSE
@@ -119,9 +107,7 @@
             return prefix .. KeyBindings_String("KEY_" .. rest, rest)
         end
 
-        -- ── Page state ── `sections` is the era section model, `selected`/`keyID` the 1.12
-        -- selection, and `searchPainted` maps OptionsFrame.xml's live search rows (row name to
-        -- binding index).
+        -- ── Page state ── `searchPainted` maps OptionsFrame.xml's search rows to binding indices.
         KeyBindingsPage = { sections = {}, items = {} }
 
         KEYBINDINGS_ROW_BASE = "BenillaOptionsFrameContainerBodyKeybindingsRow"
@@ -129,9 +115,8 @@
         KEYBINDINGS_ROW_HEIGHT = 25
         KEYBINDINGS_SEARCH_ROWS = 8
 
-        -- ── Section model ── the era's CreateKeybindingInitializers: one section per category
-        -- token in first-appearance order, which is 1.12's Bindings.xml order. Sections start
-        -- collapsed (the era's Classic overrides pass no `expanded`); a rebuild keeps each state.
+        -- ── Section model ── one section per category in Bindings.xml order, collapsed at first
+        -- as in the era; a rebuild keeps each state.
         function KeyBindings_BuildSections()
             local page = KeyBindingsPage
             local was = {}
@@ -153,8 +138,7 @@
             KeyBindings_Flatten()
         end
 
-        -- The visible list the faux scroll runs over (the era's EvaluateVisibility): each header,
-        -- then its rows when expanded.
+        -- The visible list the faux scroll runs over.
         function KeyBindings_Flatten()
             local page = KeyBindingsPage
             page.items = {}
@@ -168,7 +152,7 @@
             end
         end
 
-        -- A header click (the era's OnExpandedChanged), voiced with the checkbox sound.
+        -- A header click, voiced with the checkbox sound.
         function KeyBindings_ToggleSection(n)
             local sec = KeyBindingsPage.sections[n]
             if not sec then return end
@@ -178,7 +162,7 @@
             KeyBindingsPage_Update()
         end
 
-        -- Expands or collapses a section silently; the capture fixture opens sections with it.
+        -- Silent, for the capture fixture.
         function KeyBindings_ExpandSection(n, on)
             local sec = KeyBindingsPage.sections[n]
             if not sec then return end
@@ -186,8 +170,7 @@
             KeyBindings_Flatten()
         end
 
-        -- ── Painters ── one row in one mode, shared by the list and the search rows, whose
-        -- capsules capture in place as the era's live results do.
+        -- ── Painters ── shared by the list and the search rows, which capture in place.
         function KeyBindings_PaintBindRow(name, index)
             local command, _, key1, key2 = GetBinding(index)
             local b1 = getglobal(name .. "Key1Button")
@@ -234,7 +217,7 @@
             getglobal(name .. "Key2Button"):Hide()
         end
 
-        -- ── The list repaint (1.12 KeyBindingFrame_Update over the era section list). ──
+        -- ── The list repaint (1.12 KeyBindingFrame_Update) ──
         function KeyBindingsPage_Update()
             local page = KeyBindingsPage
             local scroll = getglobal("BenillaOptionsFrameContainerBodyKeybindingsScrollFrame")
@@ -255,14 +238,12 @@
             end
             FauxScrollFrame_Update(scroll, table.getn(page.items),
                 KEYBINDINGS_DISPLAYED, KEYBINDINGS_ROW_HEIGHT)
-            -- The trough is ours and the stock kit never shows one, so it follows the bar
-            -- `FauxScrollFrame_Update` has just shown or hidden.
+            -- Our trough follows the bar `FauxScrollFrame_Update` has just shown or hidden.
             BenillaScrollTrough_Follow(scroll:GetName())
             KeyBindings_UpdateUnbindKey()
         end
 
-        -- The page entry (BenillaOptionsFrame_SelectCategory): rebuilds the sections, since a
-        -- rebind or a set switch may have changed the table, then repaints from the top.
+        -- The page entry: a rebind or a set switch may have changed the table.
         function KeyBindingsPage_Refresh()
             KeyBindings_BuildSections()
             local box = getglobal("BenillaOptionsFrameContainerBodyKeybindingsCharacterRowCheck")
@@ -279,9 +260,7 @@
             getglobal("BenillaOptionsFrameContainerBodyKeybindingsOutput"):SetText(text)
         end
 
-        -- ── Selection ── selecting a capsule arms the host's capture (BenillaBindCapture), which
-        -- swallows raw input and hands the canonical chord to KeyBindings_OnHostKey; deselecting
-        -- disarms.
+        -- ── Selection ── arms the host's capture, which hands its chord to KeyBindings_OnHostKey.
         function KeyBindings_SetSelected(command, keyID)
             KeyBindingsPage.selected = command
             KeyBindingsPage.keyID = keyID
@@ -297,8 +276,7 @@
             end
         end
 
-        -- Repaints whichever view shows binding rows, the list or every search row, since a bind
-        -- from one search row can unbind a victim shown on another.
+        -- Every search row: a bind from one can unbind a victim shown on another.
         function KeyBindings_RepaintVisible()
             if KeyBindingsPage.searchPainted then
                 for name, index in pairs(KeyBindingsPage.searchPainted) do
@@ -311,9 +289,7 @@
         end
 
         function KeyBindingButton_OnClick(button)
-            -- As 1.12: while armed, only a left or right click reselects or deselects. A middle,
-            -- 4 or 5 press is a bind that the armed capture takes after this click, so it must
-            -- leave the selection alone.
+            -- As 1.12: while armed, a middle, 4 or 5 press is a bind the capture takes after this.
             local page = KeyBindingsPage
             if page.selected then
                 if button ~= "LeftButton" and button ~= "RightButton" then
@@ -337,14 +313,11 @@
             KeyBindings_RepaintVisible()
         end
 
-        -- The live commit: saves the set a bind, unbind or reset has just changed.
         function KeyBindings_Commit()
             SaveBindings(GetCurrentBindingSet())
         end
 
-        -- The host's capture callback, `chord` canonical (ALT-CTRL-SHIFT-TOKEN): 1.12's OnKeyDown
-        -- armed branch, then the live commit. A stolen chord names its victim in red only when it
-        -- was the victim's last key; the command's keys rebind in slot order.
+        -- `chord` is ALT-CTRL-SHIFT-TOKEN; 1.12's OnKeyDown armed branch, then the live commit.
         function KeyBindings_OnHostKey(chord)
             local page = KeyBindingsPage
             if not page.selected then
@@ -379,9 +352,7 @@
             KeyBindings_RepaintVisible()
         end
 
-        -- 1.12's KeyBindingFrame_SetBinding: a refused bind restores the slot's old key. SetBinding
-        -- refuses only a string that is not a key, so this fires for a chord the capture could not
-        -- name, never for the wheel; the message stays 1.12's wheel text.
+        -- 1.12's KeyBindingFrame_SetBinding, message and all; SetBinding refuses only a non-key.
         function KeyBindings_SetOrRestore(key, command, oldKey)
             if not SetBinding(key, command) then
                 if oldKey then SetBinding(oldKey, command) end
@@ -391,8 +362,7 @@
             end
         end
 
-        -- The Unbind Key button (OptionsFrame.xml): 1.12's body, which empties the selected slot
-        -- and slides the other into slot order, then the live commit.
+        -- 1.12's Unbind Key body, then the live commit.
         function KeyBindings_Unbind()
             local page = KeyBindingsPage
             local key1, key2 = GetBindingKey(page.selected)
@@ -409,12 +379,9 @@
             KeyBindings_RepaintVisible()
         end
 
-        -- ── Character-specific set ── 1.12's binding sets under the era's checkbox. Checking
-        -- saves set 2 at once, a copy of the current binds (LoadBindings(2) falls back to the
-        -- account set), and that saved set is what the checkbox reads. Unchecking deletes it, so
-        -- it confirms (the era confirms only on uncheck) and the box stays checked meanwhile.
-        -- The accept loads set 1 before saving it; saving first would write the character binds
-        -- into the account set.
+        -- ── Character-specific set ── checking saves set 2 at once (LoadBindings(2) falls back
+        -- to the account set); unchecking confirms first, as the era does. The accept loads set 1
+        -- before saving it, or the character binds would be written into the account set.
         function KeyBindings_CharacterToggle(box)
             PlaySound("igMainMenuOptionCheckBoxOn")
             if box:GetChecked() then
@@ -442,8 +409,7 @@
                 KeyBindingsPage_Refresh()
             end,
         }
-        -- Reset To Default, the page's Defaults button: it confirms, as the era's does, with our
-        -- own string since 1.12 has none, and resets the current set with a live commit.
+        -- Reset To Default confirms, as the era's does; our string, since 1.12 has none.
         StaticPopupDialogs["CONFIRM_RESET_KEYBINDINGS"] = {
             text = "Are you sure you want to reset all keybindings to their defaults?",
             button1 = KeyBindings_String("OKAY", "Okay"),
@@ -458,11 +424,8 @@
             end,
         }
 
-        -- ── Search ── a binding's tag is its display name uppercased (the era's
-        -- AddSearchTags(GetBindingName(action))); matches list under the Keybindings group head,
-        -- which opens this page (the era's `redirectCategory`, Blizzard_SettingsPanel.lua l.578).
-        -- OptionsFrame.xml paints them as live rows. Deviation: a static pool of
-        -- KEYBINDINGS_SEARCH_ROWS rows, where the era's results scroll.
+        -- ── Search ── a binding's tag is its display name uppercased, as the era's.
+        -- A static pool of KEYBINDINGS_SEARCH_ROWS rows, where the era's results scroll.
         function KeyBindings_SearchMatches(words)
             local out = {}
             for i = 1, GetNumBindings() do
diff --git a/crates/benilla-app/assets/ui/OptionsFrame.xml b/crates/benilla-app/assets/ui/OptionsFrame.xml
index 6a3af262..1bfb34ee 100644
--- a/crates/benilla-app/assets/ui/OptionsFrame.xml
+++ b/crates/benilla-app/assets/ui/OptionsFrame.xml
@@ -1,18 +1,13 @@
 <Ui>
     <!--
-        The Options window, opened from the game menu. Deviation: the 1.15 era client's single
-        settings window replaces the 1.12 four-panel family, which is much worse to use; the 1.12
-        frames still load, hidden, for addons.
-        Structure follows the era UI source (1.15.9), surfaces the 1.14 System window
-        (OptionsFrameTemplates.xml); every art byte is 1.12-native or a colour fill, so era atlas
-        names below cite geometry only. Cut from the era window: the corner close X, live tabs,
-        the Accessibility, Languages and Network pages, and the close-with-pending confirm and
-        revert timer, so hiding discards pending edits and Apply commits outright. A slider shows
-        the 1.12 range; an out-of-range config value displays clamped and is not written back.
+        The Options window the game menu opens. Deviation: the 1.15 era client's single settings
+        window replaces the 1.12 four-panel family, which is much worse to use; the 1.12 frames
+        still load, hidden, for addons. Every art byte is 1.12-native or a colour fill, so era
+        names below cite geometry only. Hiding discards pending edits and Apply commits outright.
+        A slider shows the 1.12 range; an out-of-range value displays clamped, not written back.
     -->
 
-    <!-- The era GameFontHighlightMedium/Huge (FRIZQT 14 and 20, white) under Options* names, so
-         Fonts.xml stays the 1.12 set; the shadow is MasterFont's (Fonts.xml l.62). -->
+    <!-- The era's 14 and 20 white fonts, outside Fonts.xml's 1.12 set; MasterFont's shadow. -->
     <Font name="OptionsFontHighlightMedium" font="Fonts\FRIZQT__.TTF" virtual="true">
         <Shadow>
             <Offset><AbsDimension x="1" y="-1"/></Offset>
@@ -31,17 +26,14 @@
     </Font>
 
     <Script><![CDATA[
-        -- The stock UIOptionsFrame.xml loads hidden before this file and owns the options uvars
-        -- (UIOptionsFrame_Init, UIOptionsFrame.lua l.93-185) and UIOptionsFrameCheckButtons;
-        -- each uvar row captures its default at OnLoad, after that file ran.
+        -- UIOptionsFrame.xml loads first and owns the uvars; each row captures its default at
+        -- OnLoad.
         -- Deviation: AUTO_QUEST_WATCH is the string "1". 1.12 assigns the number 1 (l.122) but
-        -- every consumer compares against "1" (QuestLogFrame.lua:64/68), and 1 ~= "1" in Lua 5.0.
-        -- The RegisterForSave repeats the stock one, which is idempotent.
+        -- every consumer compares against "1" (QuestLogFrame.lua:64/68); 1 ~= "1" in Lua 5.0.
         AUTO_QUEST_WATCH = "1"
         RegisterForSave("AUTO_QUEST_WATCH")
 
-        -- Every combat-text row's applyFunc, UIOptionsFrame_Save l.371-376: Blizzard_CombatText
-        -- is LoadOnDemand, so the master loads it, and the update runs only once it exists.
+        -- UIOptionsFrame.lua:370-376: Blizzard_CombatText is LoadOnDemand, so the master loads it.
         function CombatText_UpdateOrLoad()
             if ( SHOW_COMBAT_TEXT == "1" ) then
                 UIParentLoadAddOn("Blizzard_CombatText")
@@ -50,17 +42,15 @@
                 CombatText_UpdateDisplayedMessages()
             end
         end
-        -- The Remove Chat Hover Delay row's applyFunc (UIOptionsFrame.lua l.216).
+        -- The Remove Chat Hover Delay row's applyFunc (UIOptionsFrame.lua:216).
         function ChatFrame_ApplyMouseOverDelay()
             if SetChatMouseOverDelay then -- nil in a VM loaded without the chat files
                 SetChatMouseOverDelay(REMOVE_CHAT_DELAY)
             end
         end
 
-        -- Show Tutorials' setter (UIOptionsFrame.lua l.318-327). There is no tutorial CVar: the
-        -- store is the _Load/_Save/_SetDefaults special arms, and disabling marks the whole bank.
-        -- The `~=` guard is the reference's: TutorialsEnabled() is 1 or nil, and re-ticking an
-        -- on row must not ResetTutorials() and re-arm dismissed tutorials.
+        -- Show Tutorials' setter (UIOptionsFrame.lua:318-327); there is no tutorial CVar. The `~=`
+        -- guard is the reference's: re-ticking an on row must not re-arm dismissed tutorials.
         function BenillaOptionsFrame_SetTutorialsEnabled(value)
             if ( tonumber(value) ~= TutorialsEnabled() ) then
                 if ( value == "1" ) then
@@ -73,11 +63,9 @@
             end
         end
 
-        -- UpdateNameplates, over the stock UIOptionsFrame.lua l.768-780. Deviation: stock l.776
-        -- is dropped. Stock l.774-776 shows then hides the friendly plates; on 1.12 that clears
-        -- volatile bits (`[0xc4da34]`), but here the verbs write the CVar pair that is the store,
-        -- so it would erase the saved setting at every world entry. The body stays for addons
-        -- that set NAMEPLATES_ON and call this.
+        -- UIOptionsFrame.lua:768-780. Deviation: stock l.776 is dropped. On 1.12 its show-then-hide
+        -- clears volatile bits (`[0xc4da34]`); here the verbs write the CVar pair that is the
+        -- store, so it would erase the saved setting at every world entry.
         function UpdateNameplates()
             if ( NAMEPLATES_ON ) then
                 ShowNameplates()
@@ -92,18 +80,18 @@
         end
 
 
-        -- The category tree (the era Game tab) in list order; keys are the row name suffixes.
+        -- The category tree in list order; keys are the row name suffixes.
         OPTIONS_CATEGORY_KEYS = {
             "Controls", "Interface", "ActionBars", "Combat", "Chat", "Keybindings", "Nameplates",
             "Graphics", "Audio",
         }
 
-        -- The era-window scale: the era UIParent draws smaller than our 768-unit canvas on modern
-        -- screens, and every era-shaped window wears this (GameMenuFrame too). Set by eye.
+        -- The era UIParent draws smaller than our 768-unit canvas; a chosen value, not the
+        -- reference's.
         ERA_WINDOW_SCALE = 0.78
 
         function BenillaOptionsFrame_UpdateScale()
-            -- The era panel's checkFit = 1: UIPanelUpdateScaleForFit also shrinks it to fit.
+            -- The era panel's checkFit: it also shrinks to fit the screen.
             local k = ERA_WINDOW_SCALE
             local wFit = GetScreenWidth() / 940
             local hFit = GetScreenHeight() / 744
@@ -112,16 +100,12 @@
             BenillaOptionsFrame:SetScale(k)
         end
 
-        -- The era tab width (MinimalTab.lua l.7): label width + 40, measured in the tabs' OnShow
-        -- as 1.12's PanelTemplates_TabResize is, since it depends on the scale the window's
-        -- OnShow sets first. Deviation: the era measures the medium font it swaps away (about 6
-        -- wider); this measures the small font the label wears.
+        -- The era tab width, label + 40, measured after OnShow sets the scale.
         function OptionsTab_FitWidth(tab)
             tab:SetWidth(getglobal(tab:GetName() .. "Text"):GetStringWidth() + 40)
         end
 
-        -- A category row: the wash at the era atlas size (187x21), in the 1.14 hover steel-blue
-        -- (OptionsFrameTemplates.lua l.130-131). A new category is one XML row plus one key.
+        -- The wash at the era atlas size, in the 1.14 hover steel-blue.
         function OptionsCategoryRow_OnLoad(row, key, label)
             row.categoryKey = key
             row.pageTitle = label
@@ -132,10 +116,7 @@
             bg:SetVertexColor(0.196, 0.388, 0.8)
         end
 
-        -- Select a category: 1.14's OptionsList_SelectButton (OptionsFrameTemplates.lua
-        -- l.107-121), the selected wash gold and locked, the rest blue. Picking a category ends a
-        -- search (Blizzard_SettingsPanel.lua l.793); SetText("") re-enters here through the
-        -- restore, so the outer call returns early.
+        -- 1.14's OptionsList_SelectButton. SetText("") ends a search and re-enters here.
         function BenillaOptionsFrame_SelectCategory(key)
             BenillaOptionsFrame.selectedCategory = key
             if BenillaOptionsFrameSearchBox:GetText() ~= "" then
@@ -162,8 +143,7 @@
             end
             -- A category switch starts at the top, as the era ScrollBox does per category.
             BenillaOptionsFrameContainerScroll:SetVerticalScroll(0)
-            -- Keybindings: entering rebuilds the section tree; leaving disarms a pending capture,
-            -- which must never outlive the page.
+            -- Leaving Keybindings disarms a pending capture, which must never outlive the page.
             local kb = getglobal("BenillaOptionsFrameContainerBodyKeybindings")
             if key == "Keybindings" then
                 kb:Show()
@@ -184,12 +164,10 @@
             end
         end
 
-        -- ── Search: the era SettingsPanel search (Blizzard_SettingsPanel.lua l.566-692) ──
-        -- A row's tag is its label uppercased; a query matches by plain substring, scored by
-        -- matched length, grouped under clickable category heads in best-score order. Results
-        -- are the live row frames re-anchored, so values and writes work mid-search.
+        -- ── Search: the era SettingsPanel search ──
+        -- Tags are labels uppercased, matched by plain substring and scored by matched length.
+        -- Results are the live rows, so writes work mid-search.
 
-        -- The era word list (l.569-572): the whole query, then each comma- or space-separated word.
         function OptionsSearch_Words(text)
             local up = string.upper(text)
             local words = { up }
@@ -199,7 +177,7 @@
             return words
         end
 
-        -- The era score (MatchesSearchTags, Blizzard_Settings.lua l.65-77), with a plain find.
+        -- The era's MatchesSearchTags score, with a plain find.
         function OptionsSearch_Score(tag, words)
             for _, w in ipairs(words) do
                 local first, last = string.find(tag, w, 1, true)
@@ -208,7 +186,6 @@
             return nil
         end
 
-        -- The era gather (l.575-636): scores walked high to low give the groups' order.
         function OptionsSearch_FindMatches(text)
             local words = OptionsSearch_Words(text)
             local buckets, scores = {}, {}
@@ -227,7 +204,7 @@
                     end
                 end
             end
-            -- Keybinding matches join the buckets, as in the era; their rkey is the binding index.
+            -- Keybinding matches join the buckets; their rkey is the binding index.
             for _, m in ipairs(KeyBindings_SearchMatches(words)) do
                 if not buckets[m.score] then
                     buckets[m.score] = {}
@@ -250,9 +227,7 @@
         end
 
         -- ── The page scroll ──
-        -- The body is as tall as the larger of the page rect and the content. Only frames hung
-        -- off the body's top are measured, so the size converges: one anchored to its bottom
-        -- would move as it grows. IsVisible, since a hidden page's rows keep their shown flag.
+        -- Only frames hung off the body's top are measured, so the size converges.
         function OptionsScroll_ContentBottom()
             local bottom = nil
             local function take(name)
@@ -277,8 +252,7 @@
             return bottom
         end
 
-        -- Size the body from OnUpdate, off the previous frame's rects; writes are gated because
-        -- SetWidth and SetHeight invalidate layout.
+        -- From OnUpdate, off the previous frame's rects; SetWidth and SetHeight invalidate layout.
         function OptionsScroll_Fit()
             local sf = BenillaOptionsFrameContainerScroll
             local body = BenillaOptionsFrameContainerBody
@@ -297,8 +271,7 @@
             end
         end
 
-        -- The page layout (era SettingsList: verticalPad 10, padLeft 25, spacing 9): the head at
-        -- (10,-12), each next at (0,-9), as the rows' XML anchors state; `prev` nil is the head.
+        -- The era SettingsList layout: the head at (10,-12), each next at (0,-9), as in the XML.
         function OptionsSearch_Place(name, prev)
             local f = getglobal(name)
             f:ClearAllPoints()
@@ -311,7 +284,7 @@
             end
         end
 
-        -- Lay a page's rows back on their XML chain after a search; a test holds the two equal.
+        -- Back on the XML chain after a search; a test holds the two equal.
         function OptionsPage_Layout(key)
             local prev = nil
             for _, rkey in ipairs(OPTIONS_PAGE_ROWS[key]) do
@@ -322,8 +295,6 @@
             end
         end
 
-        -- The results view (era OnSearchTextChanged, l.659-691): page bodies shown, rows hidden,
-        -- then each group chained, head then matches, a child pulling its parent in (l.665-670).
         -- The title and no-match strings are ours: the era's are not in its UI source.
         function OptionsSearch_Display(text)
             BenillaOptionsFrameContainerScroll:SetVerticalScroll(0)
@@ -334,7 +305,6 @@
                 end
                 getglobal("BenillaOptionsFrameContainerBodySearchHead" .. k):Hide()
             end
-            -- The Keybindings body hides too; matched bindings paint onto the search pool.
             getglobal("BenillaOptionsFrameContainerBodyKeybindings"):Hide()
             getglobal("BenillaOptionsFrameContainerBodySearchHeadKeybindings"):Hide()
             for i = 1, KEYBINDINGS_SEARCH_ROWS do
@@ -359,7 +329,6 @@
                 getglobal(head):Show()
                 prev = head
                 if key == "Keybindings" then
-                    -- Matched bindings paint onto the pool, capped at its size.
                     KeyBindingsPage.searchPainted = {}
                     local shown = 0
                     for _, index in ipairs(groups[key]) do
@@ -397,7 +366,6 @@
             end
         end
 
-        -- Ending a search (the era's empty-text arm, l.655-658).
         function OptionsSearch_Restore()
             BenillaOptionsFrameContainerScroll:SetVerticalScroll(0)
             for k in pairs(OPTIONS_PAGE_ROWS) do
@@ -414,7 +382,6 @@
             BenillaOptionsFrame_SelectCategory(BenillaOptionsFrame.selectedCategory or "Controls")
         end
 
-        -- The era text gate (OnSearchTextChanged l.640-652).
         function OptionsSearch_OnTextChanged(text)
             if text == BenillaOptionsFrame.searchText then return end
             local had = BenillaOptionsFrame.searchText and BenillaOptionsFrame.searchText ~= ""
@@ -427,31 +394,28 @@
         end
 
         -- ── The setting pages: 1.12 rows in the era Settings grammar ──
-        -- Rows, CVars, labels and dependencies are the 1.12 panels'; geometry is the era
-        -- settings list (Blizzard_SettingControls, Blizzard_SettingsList): 26-tall rows on a 9
-        -- spacing, label LEFT+37 to CENTER-85, control at CENTER-80.
-        -- Descriptions 1.12 lacks take a BENILLA_ prefix, so OPTION_TOOLTIP_* stays 1.12's own.
+        -- Descriptions 1.12 lacks take a BENILLA_ prefix.
         BENILLA_TOOLTIP_RENDER_SCALE =
             "Draws the 3D world at a fraction of the window's resolution, or larger than it. "
             .. "The interface is unaffected at any setting.\n\n"
             .. "Below 100% trades sharpness for frame rate; above 100% is supersampling, which "
             .. "smooths edges at the cost of frame rate. Applies when you click Apply."
 
-        -- Enable Sound in Background: 1.12 has no checkbox; silenced sounds keep running.
+        -- 1.12 has no such checkbox.
         BENILLA_TOOLTIP_BACKGROUND_SOUND =
             "Keeps the game's sound playing while you are working in another window.\n\n"
             .. "With this off, switching away silences the game and switching back restores it. "
             .. "Sounds keep running while they are silenced, so a long one may have finished by "
             .. "the time you return."
 
-        -- Display Mode: 1.12's WINDOWED_MODE text describes a checkbox and exclusive-mode gamma.
+        -- 1.12's WINDOWED_MODE text describes a checkbox and exclusive-mode gamma.
         BENILLA_TOOLTIP_DISPLAY_MODE =
             "Windowed (Fullscreen) fills the screen with a borderless window; Windowed runs in "
             .. "an ordinary one.\n\n"
             .. "There is no exclusive fullscreen mode. WoW itself removed one in 8.0.1, and "
             .. "modern Classic offers these same two."
 
-        -- Brightness: 1.12's GAMMA text points at gray-bar art this page does not have.
+        -- 1.12's GAMMA text points at gray-bar art this page does not have.
         BENILLA_TOOLTIP_BRIGHTNESS =
             "Lightens or darkens the whole picture — nights, caves and interiors are what it is "
             .. "for.\n\n"
@@ -460,10 +424,7 @@
             .. "finished image instead, so it works in both display modes."
 
         OPTIONS_PAGE_ROWS = {
-            -- The era Controls order for Sticky Targeting, Auto Loot, Invert Mouse and Mouse
-            -- Sensitivity; the rest follow their 1.12 box's columns left to right, General
-            -- 45 -> 3 -> 16 and 14 -> 61, then Camera: the style dropdown -> 24 -> 26,
-            -- Slider2 -> 27 -> 15, Slider3 -> Slider4.
+            -- The era Controls order first; the rest follow their 1.12 box's columns.
             Controls = {
                 "RowStickyTarget", "RowAssistAttack", "RowClearAFK",
                 "RowBlockTrades", "RowAutoSelfCast",
@@ -482,14 +443,12 @@
                 "RowWeatherDensity",
                 "RowDisplayMode", "RowVerticalSync", "RowRenderScale",
             },
-            -- Player Guild Names is a child of Player Names, as in 1.12 (l.702-708).
+            -- Guild Names is a child of Player Names (UIOptionsFrame.lua:703-709).
             Nameplates = {
                 "RowEnemyPlates", "RowFriendlyPlates",
                 "RowPlayerNames", "RowGuildNames", "RowNpcNames", "RowOwnName",
             },
-            -- 1.12's Display box by column (12 -> 2, 31 -> 20, 42 -> 39 -> 66 -> 5), then Help
-            -- (28 -> 44 -> 29). The target-of-target pair, from Advanced Options' Raid and Party
-            -- box, sits under Status Text, the other unit-frame readout.
+            -- 1.12's Display box by column, then Help; target-of-target sits under Status Text.
             Interface = {
                 "RowEnhancedTooltips", "RowStatusText", "RowTargetOfTarget", "RowTargetOfTargetMode",
                 "RowShowCloak", "RowShowHelm",
@@ -497,42 +456,39 @@
                 "RowProfanityFilter",
                 "RowShowTutorials", "RowTipOfTheDay", "RowNewbieTips",
             },
-            -- 1.12's chat box in anchor order (UIOptionsFrame.xml l.751-840). Not shipped: 7
-            -- Simple Chat, which needs FCF_Set_SimpleChat's re-layout, and 8 Lock Chat Settings
-            -- and 51 Guild Recruitment Channel, whose verbs exist.
+            -- 1.12's chat box (UIOptionsFrame.xml:751-840). Not shipped: Simple Chat, which needs
+            -- FCF_Set_SimpleChat's re-layout, Lock Chat Settings and Guild Recruitment.
             Chat = {
                 "RowGuildMemberAlert", "RowRemoveChatDelay", "RowChatBubbles", "RowLootSpam",
                 "RowPartyChatBubbles", "RowSpamFilter",
             },
-            -- Deviation: the bar toggles and grid switch precede the lock, which 1.12's two-column
-            -- box leads with (CheckButton32), so what is on screen reads first.
+            -- Deviation: the bar toggles precede the lock, which 1.12's box leads with, so what is
+            -- on screen reads first.
             ActionBars = {
                 "RowMultiBar1", "RowMultiBar2", "RowMultiBar3", "RowMultiBar4",
                 "RowAlwaysShowMultibars", "RowLockActionBar",
             },
-            -- The combat-text box in its anchor-chain order, not its CheckButton index order.
+            -- The combat-text box in its anchor-chain order.
             Combat = {
                 "RowCombatText", "RowFloatMode", "RowLowHealthMana", "RowAuras", "RowAuraFade",
                 "RowCombatState", "RowDodgeParryMiss", "RowResistances", "RowReputation",
                 "RowReactives", "RowFriendlyNames", "RowComboPoints", "RowEnergyGains",
                 "RowHonorGained",
-                -- 19 -> 11 -> 9 close the chain under their own master (l.709-714).
+                -- Under their own master (UIOptionsFrame.lua:710-716).
                 "RowShowDamage", "RowPeriodicDamage", "RowPetDamage",
             },
         }
 
-        -- `tip` is a GlobalStrings key, resolved at hover as UIOptionsFrame.lua l.265 does.
+        -- `tip` is a GlobalStrings key, resolved at hover as UIOptionsFrame.lua:265 does.
         function OptionsRow_OnLoad(row, cvar, label, tip, child)
             row.cvar = cvar
             row.tip = tip
-            -- The era search tag: the display name (SettingControls.lua l.773), uppercased.
             row.searchTag = string.upper(label)
-            -- Kept for OptionsRow_SetEnabled, whose disabled font must keep the child size.
+            -- OptionsRow_SetEnabled's disabled font must keep the child size.
             row.child = child
             local l = getglobal(row:GetName() .. "Label")
             l:SetText(label)
             if child then
-                -- Era child rows (SettingControls.lua l.319-322): the label indents, in small font.
                 l:SetFontObject("GameFontNormalSmall")
                 l:ClearAllPoints()
                 l:SetPoint("LEFT", row:GetName(), "LEFT", 52, 0)
@@ -540,10 +496,9 @@
             end
         end
 
-        -- ── The row's store: a CVar, a saved global, or an API pair ──
-        -- 1.12's three stores (UIOptionsFrame.lua l.230-377): `cvar`, `uvar` or a
-        -- `func`/`setFunc` pair, all as strings, "1"/"0" for a toggle.
-        -- Whether the row has a store, in OptionsRow_Set's order; keep the two in step.
+        -- ── The row's store ──
+        -- 1.12's `cvar`, `uvar` or `func`/`setFunc` (UIOptionsFrame.lua:230-377), all strings. Keep
+        -- OptionsRow_HasStore in OptionsRow_Set's order.
         function OptionsRow_HasStore(row)
             return row.uvar or row.setFunc or row.cvar
         end
@@ -551,8 +506,8 @@
         function OptionsRow_Get(row)
             if row.uvar then return getglobal(row.uvar) end
             if row.getFunc then
-                -- A numeric API row, 1.12's video-panel `func` fork (OptionsFrame.lua l.110/135),
-                -- formatted like the slider's write so it compares equal as a string.
+                -- OptionsFrame.lua:110/135, formatted like the slider's write so strings compare
+                -- equal.
                 if row.numeric then
                     return (string.gsub(string.format("%.2f", row.getFunc()), "%.?0+$", ""))
                 end
@@ -561,22 +516,19 @@
             return GetCVar(row.cvar)
         end
 
-        -- The write. A uvar row runs its applyFunc, the reference's side effect from
-        -- UIOptionsFrame_Save, on the click. `cvarEvent` is SetCVar's third argument, returned as
-        -- CVAR_UPDATE's arg1 (1.12 passes its CheckButtons key).
+        -- A uvar row applies on the click; `cvarEvent` is CVAR_UPDATE's arg1.
         function OptionsRow_Set(row, value)
             if row.uvar then
                 setglobal(row.uvar, value)
-                -- `applyFunc` is a global's name, looked up when applied: most definers load
-                -- after this file. A name with no global behind it applies nothing.
+                -- Looked up when applied: most definers load after this file.
                 local apply = row.applyFunc
                 if type(apply) == "string" then apply = getglobal(apply) end
                 if apply then apply() end
                 return
             end
-            -- An API row passes the "1"/"0" string, as UIOptionsFrame_Save l.290-297 does.
+            -- The "1"/"0" string, as UIOptionsFrame.lua:291-297.
             if row.setFunc then
-                -- A numeric one passes a number, as OptionsFrame_Save does (l.206-226).
+                -- A number, as OptionsFrame.lua:206-226.
                 if row.numeric then
                     row.setFunc(tonumber(value))
                 else
@@ -588,10 +540,8 @@
             OptionsRow_WritePartner(row, value)
         end
 
-        -- The partner write, from UIOptionsFrame_Save's special arms: Pet Melee Damage also
-        -- writes PetSpellDamage (l.334-336); the camera speeds write their pitch twin at yaw/4
-        -- and yaw/2 (l.351-356). A scaled value is formatted like the slider's write, so a
-        -- partner at its default compares equal and stays out of the config file.
+        -- UIOptionsFrame_Save's partner writes: Pet Melee Damage also writes PetSpellDamage
+        -- (l.334-336); the camera speeds write their pitch twin at yaw/4 and yaw/2 (l.351-356).
         function OptionsRow_WritePartner(row, value)
             if not row.partner then return end
             local v = value
@@ -602,23 +552,21 @@
             SetCVar(row.partner.cvar, v)
         end
 
-        -- The registered default. A uvar's is the value its defining file assigned, captured at
-        -- the row's OnLoad: all UI XML loads before the saved-variables chunk runs over it.
+        -- A uvar's default is captured at OnLoad, before the saved-variables chunk runs.
         function OptionsRow_Default(row)
             if row.uvar then return row.udefault end
             if row.getFunc then return row.fdefault end
             return GetCVarDefault(row.cvar)
         end
 
-        -- A uvar row: OptionsRow_OnLoad's signature with the global's name in the cvar seat.
+        -- OptionsRow_OnLoad's signature with the global's name in the cvar seat.
         function OptionsGlobalRow_OnLoad(row, uvar, label, tip, child)
             OptionsRow_OnLoad(row, nil, label, tip, child)
             row.uvar = uvar
             row.udefault = getglobal(uvar)
         end
 
-        -- An API row, 1.12's `func`/`setFunc` shape. `default` is stated because nothing is
-        -- registered; the reference hand-writes it too (UIOptionsFrame_SetDefaults l.631-634).
+        -- Stated, as UIOptionsFrame_SetDefaults hand-writes it (l.631-634).
         function OptionsFuncRow_OnLoad(row, getFunc, setFunc, default, label, tip, child)
             OptionsRow_OnLoad(row, nil, label, tip, child)
             row.getFunc = getFunc
@@ -626,33 +574,29 @@
             row.fdefault = default
         end
 
-        -- A numeric API row; `default` is still a string, since rows compare strings.
+        -- `default` is still a string, since rows compare strings.
         function OptionsNumFuncRow_OnLoad(row, getFunc, setFunc, default, label, tip, child)
             OptionsFuncRow_OnLoad(row, getFunc, setFunc, default, label, tip, child)
             row.numeric = 1
         end
 
-        -- Saved uvars land after their file-scope consumers ran; the stock VARIABLES_LOADED arm
-        -- (UIOptionsFrame.lua l.193-227) re-applies them, so this window has no load ladder.
+        -- UIOptionsFrame.lua:193-227 re-applies saved uvars, so this window has no load ladder.
 
-        -- OptionsFrameSliders is the stock video window's table (OptionsFrame.lua l.24-34),
-        -- which addons write; a declaration here would replace it. This maps its slider index to
-        -- our Graphics row; 4, 5, 7 and 8 have none, and the holes are why the OnShow loop uses
-        -- Lua 5.0's `for i, name in` pairs form: ipairs would stop at 3.
+        -- OptionsFrameSliders is the stock table (OptionsFrame.lua:24-34), which addons write.
+        -- Holes at 4, 5, 7 and 8, so the OnShow loop uses the pairs form: ipairs would stop at 3.
         BENILLA_GRAPHICS_SLIDER_ROWS = {
             "RowUiScale", "RowFarclip", "RowWorldDetail",
             [6] = "RowBrightness", [9] = "RowWeatherDensity",
         }
 
-        -- A slider's range and readout where the template's is not it. The refreshing guard:
         -- SetMinMaxValues re-clamps and fires OnValueChanged, which must not write back.
         function OptionsSliderRow_Setup(row, min, max, step, fmt, stops)
             local slider = getglobal(row:GetName() .. "ControlSlider")
             row.fmt = fmt
             -- Kept for the "travel" readout, a share of the row's own range.
             row.minv, row.maxv = min, max
-            -- A named ladder reads out its stop (Low/Medium/High). Deviation: 1.12's slider
-            -- labels only its ends; a bare index would mean nothing to a player.
+            -- Deviation: a named ladder reads out its stop; 1.12's slider labels only its ends, and
+            -- a bare index would mean nothing to a player.
             row.stops = stops
             row.refreshing = 1
             slider:SetMinMaxValues(min, max)
@@ -660,8 +604,7 @@
             row.refreshing = nil
         end
 
-        -- ── The dropdown rows: the 1.12 UIDropDownMenu kit in the era row grammar ──
-        -- Entry values are the store's strings; AddButton checks the one equal to selectedValue.
+        -- ── The dropdown rows: the 1.12 UIDropDownMenu kit ──
         function OptionsDropdownRow_Setup(row, entries)
             row.entries = entries
             local dd = getglobal(row:GetName() .. "Dropdown")
@@ -685,7 +628,7 @@
             end
         end
 
-        -- An entry click (`this` is the list button); the kit closes the list and plays the click.
+        -- `this` is the list button; the kit closes the list and plays the click.
         function OptionsDropdownEntry_OnClick()
             local dd = UIDropDownMenu_GetCurrentDropDown()
             local row = dd:GetParent()
@@ -693,16 +636,14 @@
             OptionsDropdown_ShowValue(row)
         end
 
-        -- Paint the capsule from the store. selectedValue is set as a field: SetSelectedValue's
-        -- Refresh walks the shared DropDownList1 and could match another dropdown's buttons. An
-        -- off-grid value shows the nearest entry and is not written back.
+        -- A field, not SetSelectedValue, whose Refresh walks the shared DropDownList1. An off-grid
+        -- value shows the nearest entry.
         function OptionsDropdown_ShowValue(row)
             local dd = getglobal(row:GetName() .. "Dropdown")
             local v = OptionsRow_Get(row)
             local match
             for _, e in ipairs(row.entries) do
-                -- `alt`: a stored "3" (in range, no entry's value) shows as Never, where the
-                -- nearest-value fallback would show Always. `e.alt ~= nil` keeps nil matching none.
+                -- `alt`: a stored "3" shows as Never, where the nearest value would show Always.
                 if e.value == v or (e.alt ~= nil and e.alt == v) then match = e end
             end
             if not match and tonumber(v) then
@@ -718,8 +659,7 @@
             if match then
                 dd.selectedValue = match.value
                 UIDropDownMenu_SetText(match.text, dd)
-                -- An entry with its own `tip` retargets the row's description, as
-                -- UIOptionsFrameCameraDropDown_OnClick does with OPTION_TOOLTIP_CAMERA<id>.
+                -- As UIOptionsFrameCameraDropDown_OnClick retargets OPTION_TOOLTIP_CAMERA<id>.
                 if match.tip then row.tip = match.tip end
             else
                 dd.selectedValue = v
@@ -727,12 +667,11 @@
             end
         end
 
-        -- The readout (era MinimalSlider): rounded percent (FormatPercentage, Audio.lua l.406-411).
         function OptionsRow_FormatValue(row, value)
             if row.fmt == "raw" then
                 return string.format("%d", math.floor(value + 0.5))
             end
-            -- A named ladder reads its stop's name; the clamp guards a short stops table.
+            -- The clamp guards a short stops table.
             if row.stops then
                 local i = math.floor(value + 0.5) + 1
                 if i < 1 then i = 1 end
@@ -745,15 +684,14 @@
                 return string.format("%d%%",
                     math.floor((value - row.minv) / (row.maxv - row.minv) * 100 + 0.5))
             end
-            -- "yards": cameraDistanceMaxFactor shown as the distance it sets over the 15 yd base.
+            -- "yards": cameraDistanceMaxFactor over the 15 yd base.
             if row.fmt == "yards" then
                 return string.format("%d yd", math.floor(value * 15 + 0.5))
             end
             return string.format("%d%%", math.floor(value * 100 + 0.5))
         end
 
-        -- The era row-wide hover wash (HoverBackgroundTemplate) and the tooltip, from one seam;
-        -- crossing controls does not blink, as OnLeave fires before OnEnter within a move.
+        -- Crossing controls does not blink: OnLeave fires before OnEnter within a move.
         function OptionsRow_Hover(row, on)
             local hover = getglobal(row:GetName() .. "Hover")
             if on then
@@ -765,17 +703,15 @@
             end
         end
 
-        -- The description: 1.12's per-option string alone in the default gold
-        -- (OptionsFrameTemplates.xml l.52-64), seated the era way (ANCHOR_RIGHT, x -10).
-        -- Deviation: the era's white name line is cut, as it repeats the label.
+        -- 1.12's per-option string alone in gold (OptionsFrameTemplates.xml:52-64).
         function OptionsRow_ShowTooltip(row)
             local text = row.tip and getglobal(row.tip)
             if text then
                 GameTooltip:SetOwner(getglobal(row:GetName() .. "Tip"), "ANCHOR_RIGHT", -10, 0)
                 GameTooltip:SetText(text, nil, nil, nil, nil, 1)
             else
-                -- Deviation: 1.12 returns early here. A mute row hides the last plate, so a hover
-                -- entered without the old row's OnLeave cannot leave a neighbour's text standing.
+                -- Deviation: 1.12 returns early here; a mute row hides the last plate, so a
+                -- neighbour's text cannot stand when its OnLeave was missed.
                 GameTooltip:Hide()
             end
         end
@@ -784,7 +720,7 @@
             local row = box:GetParent()
             local checked = box:GetChecked()
             -- The 1.12 panels disagree: the interface panel plays CheckBoxOn when checked
-            -- (OptionsFrame.lua l.509), the sound panel CheckBoxOff; Audio rows carry soundQuirk.
+            -- (OptionsFrame.lua:509-515), the sound panel CheckBoxOff; Audio rows carry soundQuirk.
             local kitOn = checked
             if row.soundQuirk then kitOn = not kitOn end
             if kitOn then
@@ -807,8 +743,8 @@
             local control = slider:GetParent()
             local row = control:GetParent()
             if not row.refreshing then
-                -- Era obeyStepOnDrag (MinimalSlider.xml l.5-7): a move snaps to the grid from the
-                -- minimum (farclip's 1.12 grid is 177+n*60); a refresh sets the stored value raw.
+                -- Snaps to the grid from the minimum (farclip's is 177+n*60); a refresh sets it
+                -- raw.
                 local step = slider:GetValueStep()
                 if step and step > 0 then
                     local minv = slider:GetMinMaxValues()
@@ -822,12 +758,10 @@
             end
             getglobal(control:GetName() .. "Value"):SetText(OptionsRow_FormatValue(row, value))
             if OptionsRow_HasStore(row) and not row.refreshing then
-                -- Two decimals, trailing zeros stripped, so a value at its default compares
-                -- equal as a string and stays out of the config file.
+                -- Trailing zeros stripped, so a value at its default stays out of the config file.
                 local str = string.gsub(string.format("%.2f", value), "%.?0+$", "")
                 if row.deferred then
-                    -- Era CommitFlag.Apply: shown at once, stored on Apply. A pending equal to
-                    -- the committed value is dropped, as the era's IsModified does.
+                    -- Stored on Apply; a pending equal to the committed value is dropped.
                     if str == OptionsRow_Get(row) then
                         row.pending = nil
                     else
@@ -846,8 +780,7 @@
                 local row = getglobal(base .. rkey)
                 local box = getglobal(base .. rkey .. "Check")
                 if box then
-                    -- SetChecked takes the store's string as the 1.12 panel does: "0" unchecks.
-                    -- An inverted row checks on "0" (UIOptionsFrame.lua's GAMEFIELD_DESELECT arm).
+                    -- "0" unchecks; an inverted row checks on "0".
                     if row.invert then
                         local checked
                         if OptionsRow_Get(row) == "0" then checked = 1 end
@@ -863,8 +796,7 @@
                     -- A staged value shows first, as the era's GetValue returns it.
                     slider:SetValue(tonumber(row.pending or OptionsRow_Get(row) or "0") or 0)
                     row.refreshing = nil
-                    -- SetValue fires only on a change, so the readout is written here, from the
-                    -- slider's own (clamped) value.
+                    -- SetValue fires only on a change, so the readout is written here.
                     getglobal(base .. rkey .. "ControlValue"):SetText(
                         OptionsRow_FormatValue(row, slider:GetValue()))
                 end
@@ -873,16 +805,15 @@
             OptionsApply_Update()
         end
 
-        -- Per-page dependency rules, each the 1.12 panel's own.
+        -- Each page's dependency rules, the 1.12 panel's own.
         function OptionsPage_UpdateDependencies(key)
             if key == "Combat" then
-                -- The combat-text block: the master off greys the floating-text rows, and Combo
-                -- Points is greyed for anyone but a rogue or druid.
+                -- Combo Points is for rogues and druids only.
                 local on = SHOW_COMBAT_TEXT ~= "0"
                 local _, class = UnitClass("player")
                 class = class and string.upper(class)
                 local combo = class == "ROGUE" or class == "DRUID"
-                -- The damage-number trio is not under this master: that block names 53..69 only.
+                -- The damage-number trio is not under this master.
                 local damage = {
                     RowShowDamage = 1, RowPeriodicDamage = 1, RowPetDamage = 1,
                 }
@@ -894,34 +825,33 @@
                             getglobal("BenillaOptionsFrameContainerBodyCombat" .. rkey), live)
                     end
                 end
-                -- l.709-714: Show Target Damage off greys Periodic and Pet Damage.
+                -- UIOptionsFrame.lua:710-716: Show Target Damage off greys Periodic and Pet Damage.
                 local dmg = GetCVar("CombatDamage") ~= "0"
                 OptionsRow_SetEnabled(BenillaOptionsFrameContainerBodyCombatRowPeriodicDamage, dmg)
                 OptionsRow_SetEnabled(BenillaOptionsFrameContainerBodyCombatRowPetDamage, dmg)
                 return
             end
             if key == "Controls" then
-                -- l.715-719: Auto-Follow Speed is dead while the style is Never: "0", or a stray
-                -- "3", which the validator also accepts and which reads as Never.
+                -- UIOptionsFrame.lua:717-721: dead while the style is Never, "0" or a stray "3".
                 local style = GetCVar("cameraSmoothStyle")
                 OptionsRow_SetEnabled(BenillaOptionsFrameContainerBodyControlsRowAutoFollowSpeed,
                     style ~= "0" and style ~= "3")
                 return
             end
             if key == "Nameplates" then
-                -- l.702-708: Player Names off greys Player Guild Names.
+                -- UIOptionsFrame.lua:703-709: Player Names off greys Player Guild Names.
                 OptionsRow_SetEnabled(BenillaOptionsFrameContainerBodyNameplatesRowGuildNames,
                     GetCVar("UnitNamePlayer") ~= "0")
                 return
             end
             if key == "Interface" then
-                -- l.694-700: the target-of-target mode is dead while its switch is off.
+                -- UIOptionsFrame.lua:697-701: the mode is dead while its switch is off.
                 OptionsRow_SetEnabled(BenillaOptionsFrameContainerBodyInterfaceRowTargetOfTargetMode,
                     SHOW_TARGET_OF_TARGET ~= "0")
                 return
             end
             if key == "ActionBars" then
-                -- l.722-726: Right ActionBar 2 is dead while Right ActionBar is off.
+                -- UIOptionsFrame.lua:722-726: Right ActionBar 2 needs Right ActionBar.
                 OptionsRow_SetEnabled(BenillaOptionsFrameContainerBodyActionBarsRowMultiBar4,
                     SHOW_MULTI_ACTIONBAR_3)
                 return
@@ -942,14 +872,12 @@
             end
         end
 
-        -- Grey or wake one row. A dropdown greys as OptionsFrame_DisableDropDown does, button
-        -- disabled and text gray; 1.12 has no UIDropDownMenu_DisableDropDown.
+        -- As OptionsFrame_DisableDropDown; 1.12 has no UIDropDownMenu_DisableDropDown.
         function OptionsRow_SetEnabled(row, on)
             local name = row:GetName()
             local box = getglobal(name .. "Check")
             local dd = getglobal(name .. "Dropdown")
-            -- A slider greys as OptionsFrame_DisableSlider does (l.481-486), thumb hidden; it
-            -- also drops the mouse, since a press anywhere on this track seats the value.
+            -- As OptionsFrame_DisableSlider (l.481-486); a press on the track would seat the value.
             local sl = getglobal(name .. "ControlSlider")
             if box then
                 if on then box:Enable() else box:Disable() end
@@ -985,7 +913,7 @@
             end
         end
 
-        -- Defaults: the visible page back to its registered defaults, pending edits dropped.
+        -- Pending edits dropped.
         function OptionsPage_Defaults(key)
             local base = "BenillaOptionsFrameContainerBody" .. key
             for _, rkey in ipairs(OPTIONS_PAGE_ROWS[key]) do
@@ -996,10 +924,9 @@
             OptionsPage_Refresh(key)
         end
 
-        -- ── The Apply flow: era CommitFlag.Apply ──
-        -- Pending edits are panel-wide: they survive a category switch; hiding discards them.
+        -- ── The Apply flow ──
+        -- Pending edits survive a category switch; hiding discards them.
 
-        -- The era Apply gate (HasUnappliedSettings): shown only while an edit is pending.
         function OptionsApply_Update()
             local pending
             for key, rows in pairs(OPTIONS_PAGE_ROWS) do
@@ -1017,7 +944,6 @@
             end
         end
 
-        -- Commit every pending edit (era SettingsPanelMixin:CommitSettings).
         function OptionsPage_Apply()
             for key, rows in pairs(OPTIONS_PAGE_ROWS) do
                 local base = "BenillaOptionsFrameContainerBody" .. key
@@ -1032,7 +958,6 @@
             OptionsApply_Update()
         end
 
-        -- Hiding discards pending edits (the era's WipeModifiedTable on hide).
         function OptionsPage_DiscardPending()
             for key, rows in pairs(OPTIONS_PAGE_ROWS) do
                 local base = "BenillaOptionsFrameContainerBody" .. key
@@ -1044,8 +969,8 @@
         end
     ]]></Script>
 
-    <!-- The red panel button (era UIPanelButtonTemplate, 96x22), a copy of
-         GameMenuButtonTemplate (GameMenuFrame.xml l.145), which loads after this file. -->
+    <!-- A copy of the stock GameMenuButtonTemplate (UIPanelTemplates.xml:403) at the era's
+         96x22. -->
     <Button name="OptionsRedButtonTemplate" virtual="true">
         <Size><AbsDimension x="96" y="22"/></Size>
         <ButtonText name="$parentText"/>
@@ -1058,9 +983,7 @@
         <DisabledFont inherits="GameFontDisable"/>
     </Button>
 
-    <!-- A category row (era Blizzard_CategoryList.xml), 199 wide as the era ScrollBox stretches
-         it. The wash is 1.14's OptionsListButtonTemplate (OptionsFrameTemplates.xml l.216-229):
-         one UI-QuestLogTitleHighlight quad in ADD blend, blue on hover, gold when selected. -->
+    <!-- The wash is 1.14's OptionsListButtonTemplate: blue on hover, gold when selected. -->
     <Button name="OptionsCategoryRowTemplate" virtual="true">
         <Size><AbsDimension x="199" y="20"/></Size>
         <Layers>
@@ -1070,8 +993,7 @@
                 </Texture>
             </Layer>
         </Layers>
-        <!-- The era label box spans the row (CategoryList.xml l.72-77), so the default middle
-             justify centres the text vertically; justifyH LEFT keeps it from centring across. -->
+        <!-- The label box spans the row, so the text centres vertically but not across. -->
         <ButtonText name="$parentText" justifyH="LEFT">
             <Anchors>
                 <Anchor point="TOPLEFT"><Offset><AbsDimension x="36" y="1"/></Offset></Anchor>
@@ -1083,7 +1005,7 @@
         <DisabledFont inherits="GameFontDisable"/>
         <Scripts>
             <OnClick>BenillaOptionsFrame_SelectCategory(this.categoryKey)</OnClick>
-            <!-- The hover wash; the selected row keeps its locked gold. -->
+            <!-- The selected row keeps its locked gold. -->
             <OnEnter>
                 if BenillaOptionsFrame.selectedCategory ~= this.categoryKey then
                     getglobal(this:GetName() .. "Bg"):Show()
@@ -1097,8 +1019,7 @@
         </Scripts>
     </Button>
 
-    <!-- A category header (era SettingsCategoryListHeaderTemplate); the era's
-         Options_CategoryHeader_<n> wash has no 1.12 art and is dropped. -->
+    <!-- A category header; the era's wash has no 1.12 art. -->
     <Frame name="OptionsCategoryHeaderTemplate" virtual="true">
         <Size><AbsDimension x="199" y="30"/></Size>
         <Layers>
@@ -1110,9 +1031,7 @@
         </Layers>
     </Frame>
 
-    <!-- A search group head (era SettingsListSearchCategoryTemplate, Blizzard_SettingsList.xml
-         l.65-87); a click selects the category, ending the search. Deviation: the hover is the
-         rows' white 0.1 wash, not the era's gray ADD overlay. -->
+    <!-- A search group head; a click selects the category, ending the search. -->
     <Button name="OptionsSearchHeadTemplate" virtual="true" hidden="true">
         <Size><AbsDimension y="45"/></Size>
         <Layers>
@@ -1138,9 +1057,7 @@
         </Scripts>
     </Button>
 
-    <!-- A checkbox setting row (era SettingsCheckboxControlTemplate, SettingControls.lua
-         l.322-323, l.473) with the 1.12 UI-CheckBox set. No HighlightTexture: the era row-wide
-         wash (HoverBackgroundTemplate) is the hover. -->
+    <!-- A checkbox row with the 1.12 UI-CheckBox set; the row-wide wash is the hover. -->
     <Frame name="OptionsCheckboxRowTemplate" virtual="true" enableMouse="true">
         <Size><AbsDimension y="26"/></Size>
         <Layers>
@@ -1163,8 +1080,8 @@
             </Layer>
         </Layers>
         <Frames>
-            <!-- The tooltip seat, the era's label-half region (Blizzard_SettingControls.xml
-                 l.57-61); mouse-less so it never steals the row's hover. -->
+            <!-- The tooltip seat, the label half; mouse-less so it never steals the row's
+                 hover. -->
             <Frame name="$parentTip">
                 <Anchors>
                     <Anchor point="TOPLEFT"/>
@@ -1191,11 +1108,8 @@
         </Scripts>
     </Frame>
 
-    <!-- A slider setting row (era SettingsSliderControlTemplate, SettingControls.lua l.550-552):
-         the 1.12 OptionsSliderTemplate groove (OptionsFrameTemplates.xml l.74) and 32x32 thumb,
-         and the era readout 6 right (MinimalSlider.xml l.73-77). No era steppers, as in 1.12; a
-         press anywhere on the track seats the thumb. The +3 seats the art, not the control, so
-         the readout stays level with the label. -->
+    <!-- 1.12's OptionsSliderTemplate groove (OptionsFrameTemplates.xml:74); no steppers, as in
+         1.12. The +3 seats the art, so the readout stays level with the label. -->
     <Frame name="OptionsSliderRowTemplate" virtual="true" enableMouse="true">
         <Size><AbsDimension y="26"/></Size>
         <Layers>
@@ -1218,8 +1132,7 @@
             </Layer>
         </Layers>
         <Frames>
-            <!-- The tooltip seat. Deviation: the era hangs a slider's plate off the slider
-                 (SettingControls.lua l.556); one column keeps it still down a page. -->
+            <!-- The tooltip seat: one column keeps the plate still down a page. -->
             <Frame name="$parentTip">
                 <Anchors>
                     <Anchor point="TOPLEFT"/>
@@ -1273,9 +1186,7 @@
         </Scripts>
     </Frame>
 
-    <!-- A dropdown setting row (era SettingsDropdownControlTemplate): the 1.12
-         UIDropDownMenuTemplate capsule at CENTER-71, so its ink (after about 10 units of cap)
-         opens at the groove's column, 180 wide to match the track. -->
+    <!-- At CENTER-71, so the capsule's ink opens at the groove's column. -->
     <Frame name="OptionsDropdownRowTemplate" virtual="true" enableMouse="true">
         <Size><AbsDimension y="26"/></Size>
         <Layers>
@@ -1315,13 +1226,12 @@
         </Scripts>
     </Frame>
 
-    <!-- The window (era SettingsPanel: 920x724, CENTER), toplevel as 1.12's OptionsFrame.xml
-         l.3. Deviation: strata HIGH, the era SettingsPanel's, where 1.12's is DIALOG. -->
+    <!-- The era SettingsPanel's size and strata, HIGH, where 1.12's OptionsFrame is DIALOG;
+         toplevel as 1.12's OptionsFrame.xml:5. -->
     <Frame name="BenillaOptionsFrame" parent="UIParent" frameStrata="HIGH" toplevel="true" enableMouse="true" hidden="true">
         <Size><AbsDimension x="920" y="724"/></Size>
         <Anchors><Anchor point="CENTER"/></Anchors>
-        <!-- The 1.14 System window backdrop, BACKDROP_DIALOG_32_32 (Backdrop.lua l.17-25): the
-             UI-DialogBox-Background tile, uniform black at 0.6 alpha, inside the rope border. -->
+        <!-- The 1.14 System window backdrop, BACKDROP_DIALOG_32_32. -->
         <Backdrop bgFile="Interface\DialogFrame\UI-DialogBox-Background" edgeFile="Interface\DialogFrame\UI-DialogBox-Border" tile="true">
             <TileSize><AbsValue val="32"/></TileSize>
             <EdgeSize><AbsValue val="32"/></EdgeSize>
@@ -1329,9 +1239,8 @@
         </Backdrop>
         <Layers>
             <Layer level="BACKGROUND">
-                <!-- A black 0.7 fill over the 0.6 tile (0.88 combined) so labels read over bright
-                     terrain. Inset 15, not the bg insets: regions draw over the border, whose ink
-                     ends by texel 14. -->
+                <!-- 0.88 combined with the tile, so labels read over bright terrain. Inset 15:
+                     regions draw over the border, whose ink ends by texel 14. -->
                 <Texture name="$parentGroundDim">
                     <Anchors>
                         <Anchor point="TOPLEFT"><Offset><AbsDimension x="15" y="-15"/></Offset></Anchor>
@@ -1341,15 +1250,13 @@
                 </Texture>
             </Layer>
             <Layer level="ARTWORK">
-                <!-- The title plate at the 1.14 seat (OptionsFrameTemplates.xml l.244-255). -->
                 <Texture name="$parentHeader" file="Interface\DialogFrame\UI-DialogBox-Header">
                     <Size><AbsDimension x="300" y="68"/></Size>
                     <Anchors><Anchor point="TOP"><Offset><AbsDimension x="0" y="12"/></Offset></Anchor></Anchors>
                 </Texture>
             </Layer>
             <Layer level="OVERLAY">
-                <!-- The title on the plate, as a 1.12 dialog carries it. Not GameFontNormalMed1:
-                     GameMenuFrame.xml declares that after this file. -->
+                <!-- Not GameFontNormalMed1: GameMenuFrame.xml declares that after this file. -->
                 <FontString name="$parentTitleText" inherits="GameFontNormal" text="Options">
                     <Anchors>
                         <Anchor point="TOP" relativeTo="$parentHeader"><Offset><AbsDimension x="0" y="-14"/></Offset></Anchor>
@@ -1358,10 +1265,8 @@
             </Layer>
         </Layers>
         <Frames>
-            <!-- The two boxes, 1.14's OptionsFrameListTemplate (OptionsFrameTemplates.xml
-                 l.113-116): outlines, fill alpha 0, border LIGHTGRAY_FONT_COLOR. Declared first
-                 so siblings draw above. Deviation: tops at -52, not 1.14's -40, to clear the
-                 search box. -->
+            <!-- 1.14's OptionsFrameListTemplate outlines, declared first so siblings draw above;
+                 tops at -52 to clear the search box. -->
             <Frame name="$parentCategoryBox">
                 <Anchors>
                     <Anchor point="TOPLEFT"><Offset><AbsDimension x="10" y="-52"/></Offset></Anchor>
@@ -1396,10 +1301,8 @@
                     </OnLoad>
                 </Scripts>
             </Frame>
-            <!-- The tabs, seated the 1.14 way on the category box (InterfaceOptionsFrame.xml
-                 l.152-158), with the era MinimalTab's width and text. Static: only Game has pages.
-                 Each plate is one UI-Character tab piece at the era heights, flipped vertically,
-                 since 1.12 ships only bottom-tab plates. -->
+            <!-- Static: only Game has pages. Each plate is a UI-Character tab piece flipped, since
+                 1.12 ships only bottom-tab plates. -->
             <Button name="$parentGameTab">
                 <Size><AbsDimension x="72" y="37"/></Size>
                 <Anchors>
@@ -1450,17 +1353,17 @@
                 <NormalFont inherits="GameFontNormalSmall"/>
                 <HighlightFont inherits="GameFontNormalSmall"/>
                 <DisabledFont inherits="GameFontNormalSmall"/>
-                <!-- No addon list behind it: disabled, but in the era's unselected gold. -->
+                <!-- No addon list behind it: disabled, in the era's unselected gold. -->
                 <Scripts>
                     <OnLoad>self:Disable()</OnLoad>
                     <OnShow>OptionsTab_FitWidth(self)</OnShow>
                 </Scripts>
             </Button>
 
-            <!-- ── The category list (era CategoryList; static, it fits) ── -->
+            <!-- ── The category list ── -->
             <Frame name="$parentCategoryList">
                 <Size><AbsDimension x="199"/></Size>
-                <!-- The top: the box top (-52) plus the era's 12-unit list-to-box pad. -->
+                <!-- The box top (-52) plus the era's 12-unit pad. -->
                 <Anchors>
                     <Anchor point="TOPLEFT"><Offset><AbsDimension x="18" y="-64"/></Offset></Anchor>
                     <Anchor point="BOTTOMLEFT"><Offset><AbsDimension x="18" y="46"/></Offset></Anchor>
@@ -1521,7 +1424,7 @@
                 </Frames>
             </Frame>
 
-            <!-- ── The page area (era SettingsList) ── -->
+            <!-- ── The page area ── -->
             <Frame name="$parentContainer">
                 <Anchors>
                     <Anchor point="TOPLEFT" relativeTo="$parentCategoryList" relativePoint="TOPRIGHT"><Offset><AbsDimension x="16" y="0"/></Offset></Anchor>
@@ -1529,8 +1432,7 @@
                 </Anchors>
                 <Layers>
                     <Layer level="ARTWORK">
-                        <!-- The era options_horizontaldivider at (TOP, -50), as the colour fill
-                             it is: a 630x1 white row at about 0.3 alpha (atlas fdid 1318750). -->
+                        <!-- The era divider as a fill: 630x1 white at about 0.3. -->
                         <Texture name="$parentDivider">
                             <Size><AbsDimension y="1"/></Size>
                             <Anchors>
@@ -1576,9 +1478,7 @@
                             </OnClick>
                         </Scripts>
                     </Button>
-                    <!-- The page area scrolls, as the era SettingsList's ScrollBox does
-                         (Blizzard_SettingsList.xml l.48-58); a bar shows only when content
-                         outgrows the rect. enableMouse catches the wheel over blank area. -->
+                    <!-- enableMouse catches the wheel over blank area. -->
                     <ScrollFrame name="$parentScroll" enableMouse="true">
                         <Anchors>
                             <Anchor point="TOPLEFT"><Offset><AbsDimension x="0" y="-50"/></Offset></Anchor>
@@ -1593,28 +1493,23 @@
                             <OnScrollRangeChanged>BenillaScroll_SyncBar(this)</OnScrollRangeChanged>
                         </Scripts>
                         <Frames>
-                            <!-- The bar's trough seats itself on the bar its name minus "Trough"
-                                 names (BenillaScrollTrough_Seat). Declared before the body and the
-                                 bar so it draws beneath both. -->
+                            <!-- Declared before the body and the bar so it draws beneath both. -->
                             <Frame name="$parentBarTrough" inherits="BenillaScrollTroughTemplate"/>
-                            <!-- The page body. Named in full so every page and row name derives
-                                 from it. Sized, not anchored: SetScrollChild pins its TOPLEFT and
-                                 OptionsScroll_Fit keeps the size. -->
+                            <!-- Sized, not anchored: SetScrollChild pins its TOPLEFT and
+                                 OptionsScroll_Fit sizes it. -->
                             <Frame name="BenillaOptionsFrameContainerBody">
                                 <Size><AbsDimension x="665" y="563"/></Size>
                             <Layers>
                                 <Layer level="OVERLAY">
-                                    <!-- The no-match line (era SETTINGS_SEARCH_NOTHING_FOUND, at
-                                         the section header's seat). -->
+                                    <!-- The no-match line, at the section header's seat. -->
                                     <FontString name="$parentNoResults" inherits="GameFontHighlightLarge" justifyH="LEFT" hidden="true" text="No results found.">
                                         <Anchors><Anchor point="TOPLEFT"><Offset><AbsDimension x="17" y="-28"/></Offset></Anchor></Anchors>
                                     </FontString>
                                 </Layer>
                             </Layers>
                             <Frames>
-                                <!-- The Controls page. Labels are 1.12's GlobalStrings, the
-                                     era's for Auto Loot. Sticky Targeting is inverted in both
-                                     clients (1.12 checks it on deselectOnClick "0"). -->
+                                <!-- Sticky Targeting is inverted, as 1.12 checks it on
+                                     deselectOnClick "0". -->
                                 <Frame name="$parentControls" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -1661,9 +1556,9 @@
                                             <Scripts><OnLoad>OptionsRow_OnLoad(self, "BlockTrades", "Block Trades",
                                                 "OPTION_TOOLTIP_BLOCK_TRADES")</OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Deviation: ships "1" where 1.12 registers "0"
-                                             (`cvars::REGISTERED`): off, a friendly cast falls
-                                             into the targeting cursor, which is not modelled. -->
+                                        <!-- Deviation: ships "1" where 1.12 registers "0": off, a
+                                             friendly cast falls into the targeting cursor, which is
+                                             not modelled. -->
                                         <Frame name="$parentRowAutoSelfCast" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowBlockTrades" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -1702,9 +1597,8 @@
                                                 OptionsSliderRow_Setup(self, 0.5, 1.5, 0.05)
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- 1.12's UIOptionsFrameCameraDropDown, with its
-                                             tooltips and values: Smart 1, Always 2, Never 0
-                                             (UIOptionsFrame.lua:525, 536, 547). -->
+                                        <!-- Smart 1, Always 2, Never 0 (UIOptionsFrame.lua:525,
+                                             536, 547). -->
                                         <Frame name="$parentRowCameraFollowStyle" inherits="OptionsDropdownRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowMouseSpeed" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -1720,7 +1614,6 @@
                                                 })
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- The 1.12 camera toggles and speed sliders. -->
                                         <Frame name="$parentRowFollowTerrain" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowCameraFollowStyle" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -1757,9 +1650,9 @@
                                                 OptionsSliderRow_Setup(self, 90, 270, 10, "raw")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- One CVar, two consumers that move together: the
-                                             `0xf0000` nibble in `0x50e570`'s trace mask, and
-                                             `0x50e629`'s pivot floor and cap test. -->
+                                        <!-- One CVar, two consumers: the `0xf0000` nibble in
+                                             `0x50e570`'s trace mask and `0x50e629`'s pivot floor
+                                             and cap test. -->
                                         <Frame name="$parentRowWaterCollision" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowAutoFollowSpeed" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -1780,8 +1673,7 @@
                                                     "OPTION_TOOLTIP_SMART_PIVOT")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- UIOptionsFrameSliders row 3, with the partner write
-                                             of cameraPitchMoveSpeed at half (l.355-356). -->
+                                        <!-- Writes cameraPitchMoveSpeed at half (l.354-356). -->
                                         <Frame name="$parentRowMouseLookSpeed" inherits="OptionsSliderRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowSmartPivot" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -1807,9 +1699,7 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The Audio page: the era order (volumes, then enables) over
-                                     the 1.12 rows; the three volumes are children of Master, in
-                                     SoundOptionsFrame.lua's order. -->
+                                <!-- The three volumes are children of Master. -->
                                 <Frame name="$parentAudio" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -1843,7 +1733,6 @@
                                             <Scripts><OnLoad>
                                                 OptionsRow_OnLoad(self, "SoundVolume", "Sound Volume",
                                                     "OPTION_TOOLTIP_SOUND_VOLUME", 1)
-                                                -- Era parentInitializer (SettingsPanel.lua l.665).
                                                 self.parentRow = "RowMaster"
                                             </OnLoad></Scripts>
                                         </Frame>
@@ -1891,7 +1780,7 @@
                                                 self.soundQuirk = 1
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- 1.12's checkbox 4 (SoundOptionsFrame.lua l.2). -->
+                                        <!-- 1.12's checkbox 4 (SoundOptionsFrame.lua:3). -->
                                         <Frame name="$parentRowEnableErrorSpeech" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowEnableAmbience" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -1903,9 +1792,8 @@
                                                 self.soundQuirk = 1
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Deviation: an era row; 1.12 always mutes when the
-                                             window loses focus, which off matches. soundQuirk is
-                                             the panel's, so it applies here too. -->
+                                        <!-- An era row, not in 1.12, which always mutes when
+                                             the window loses focus; off matches it. -->
                                         <Frame name="$parentRowBackgroundSound" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowEnableErrorSpeech" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -1920,9 +1808,8 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The Graphics page: 1.12's OptionsFrameSliders rows that have
-                                     a knob, bounds read from the table. Deviation: no useUiScale
-                                     checkbox; the UI scale always applies. -->
+                                <!-- No useUiScale checkbox, which 1.12 has: benilla has no
+                                     useUiScale, so the UI scale always applies. -->
                                 <Frame name="$parentGraphics" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -1940,8 +1827,7 @@
                                                 OptionsSliderRow_Setup(self, OptionsFrameSliders[1].minValue,
                                                     OptionsFrameSliders[1].maxValue,
                                                     OptionsFrameSliders[1].valueStep)
-                                                -- Era CommitFlag.Apply (Graphics.lua l.684): a
-                                                -- live write would rescale the slider mid-drag.
+                                                -- A live write would rescale the slider mid-drag.
                                                 self.deferred = 1
                                             </OnLoad></Scripts>
                                         </Frame>
@@ -1973,16 +1859,16 @@
                                                     { "Low", "Medium", "High" })
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- The reference's slider 6 (`func = "Gamma"`): an API
-                                             row over GetGamma/SetGamma, whose unit is 1 - gamma;
-                                             writing `gamma` directly would invert the control. -->
+                                        <!-- An API row over GetGamma/SetGamma, whose unit is
+                                             `1 - gamma`; writing `gamma` would invert the
+                                             control. -->
                                         <Frame name="$parentRowBrightness" inherits="OptionsSliderRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowWorldDetail" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                                 <Anchor point="TOPRIGHT" relativeTo="$parentRowWorldDetail" relativePoint="BOTTOMRIGHT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                             </Anchors>
                                             <Scripts><OnLoad>
-                                                -- OptionsFrame_SetDefaults' default (l.441-445);
+                                                -- OptionsFrame_SetDefaults' default (l.444-445);
                                                 -- `or 1` covers a VM with no CVars.
                                                 local gd = tonumber(GetCVarDefault("gamma")) or 1
                                                 OptionsNumFuncRow_OnLoad(self, GetGamma, SetGamma,
@@ -1993,9 +1879,8 @@
                                                     OptionsFrameSliders[6].valueStep, "travel")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- The reference's slider 9, on the CVar directly, as
-                                             1.12's lands: with no SetweatherDensity global,
-                                             OptionsFrame_Save falls through to SetCVar. -->
+                                        <!-- On the CVar, as 1.12's lands: there is no
+                                             SetweatherDensity global. -->
                                         <Frame name="$parentRowWeatherDensity" inherits="OptionsSliderRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowBrightness" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -2004,9 +1889,8 @@
                                             <Scripts><OnLoad>
                                                 OptionsRow_OnLoad(self, "weatherDensity", "Weather Intensity",
                                                     "OPTION_TOOLTIP_WEATHER_DETAIL")
-                                                -- Our stop names for the reference's rates:
-                                                -- `0x67b870` maps 0 to 3 onto the spawn-rate gains
-                                                -- {0.1, 0.33, 0.66, 1.0} in `[0x8680ec]`.
+                                                -- Our names for `0x67b870`'s spawn-rate gains
+                                                -- `{0.1, 0.33, 0.66, 1.0}` (`[0x8680ec]`).
                                                 OptionsSliderRow_Setup(self, OptionsFrameSliders[9].minValue,
                                                     OptionsFrameSliders[9].maxValue,
                                                     OptionsFrameSliders[9].valueStep, nil,
@@ -2020,10 +1904,8 @@
                                             </Anchors>
                                             <Scripts><OnLoad>
                                                 -- Deviation: modern Classic's two-entry Display
-                                                -- Mode dropdown (Graphics.lua in
-                                                -- Blizzard_SettingsDefinitions_Shared), as there
-                                                -- is no exclusive fullscreen; gxWindow "0" is the
-                                                -- borderless window. Applies on the click.
+                                                -- Mode, as there is no exclusive fullscreen;
+                                                -- gxWindow "0" is the borderless window.
                                                 OptionsRow_OnLoad(self, "gxWindow", "Display Mode",
                                                     "BENILLA_TOOLTIP_DISPLAY_MODE")
                                                 OptionsDropdownRow_Setup(self, {
@@ -2038,9 +1920,8 @@
                                                 <Anchor point="TOPRIGHT" relativeTo="$parentRowDisplayMode" relativePoint="BOTTOMRIGHT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                             </Anchors>
                                             <Scripts><OnLoad>
-                                                -- 1.12's Video Options checkbox 5. Not deferred
-                                                -- despite its gxRestart = 1: the present mode
-                                                -- changes live.
+                                                -- Not deferred despite gxRestart: vsync changes
+                                                -- live.
                                                 OptionsRow_OnLoad(self, "gxVSync", "Vertical Sync",
                                                     "OPTION_TOOLTIP_VERTICAL_SYNC")
                                             </OnLoad></Scripts>
@@ -2051,11 +1932,10 @@
                                                 <Anchor point="TOPRIGHT" relativeTo="$parentRowVerticalSync" relativePoint="BOTTOMRIGHT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                             </Anchors>
                                             <Scripts><OnLoad>
-                                                -- Deviation: benilla's own row (the reference draws
-                                                -- to the backbuffer), and no Multisampling row,
-                                                -- which misses alpha-tested cutouts. Deferred: a
-                                                -- live write rebuilds the world render target on
-                                                -- every drag tick.
+                                                -- Deviation: our own row (the reference draws to
+                                                -- the backbuffer), and no Multisampling, which
+                                                -- misses alpha-tested cutouts. Deferred: a write
+                                                -- rebuilds the render target.
                                                 OptionsRow_OnLoad(self, "renderScale", "Render Scale",
                                                     "BENILLA_TOOLTIP_RENDER_SCALE")
                                                 OptionsSliderRow_Setup(self, 0.5, 2.0, 0.05)
@@ -2063,9 +1943,8 @@
                                             </OnLoad></Scripts>
                                         </Frame>
                                     </Frames>
-                                    <!-- Re-apply OptionsFrameSliders' bounds on show, as
-                                         OptionsFrame_Load does, so an addon's write (pfUI's
-                                         hdgraphic) reaches the slider. fmt and stops are ours. -->
+                                    <!-- Re-apply the bounds on show, as OptionsFrame_Load does, so
+                                         an addon's write lands. -->
                                     <Scripts>
                                         <OnShow>
                                             for i, name in BENILLA_GRAPHICS_SLIDER_ROWS do
@@ -2079,8 +1958,7 @@
                                         </OnShow>
                                     </Scripts>
                                 </Frame>
-                                <!-- The Combat page: 1.12's AdvancedOptionsCombatText box as uvar
-                                     rows, each applying CombatText_UpdateOrLoad on the click. -->
+                                <!-- 1.12's AdvancedOptionsCombatText box, as uvar rows. -->
                                 <Frame name="$parentCombat" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -2272,8 +2150,8 @@
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <!-- CombatDamage masters what floats over a unit, apart
-                                             from SHOW_COMBAT_TEXT (l.709-714); at "0" neither
-                                             `0x607140` nor `0x6128b0` floats anything. -->
+                                             from SHOW_COMBAT_TEXT; at "0" neither `0x607140` nor
+                                             `0x6128b0` floats anything. -->
                                         <Frame name="$parentRowShowDamage" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowHonorGained" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -2284,8 +2162,8 @@
                                                     "OPTION_TOOLTIP_SHOW_DAMAGE")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Off drops the whole SMSG_PERIODICAURALOG body
-                                             (`0x626dee`): lines, tick numbers and misses. -->
+                                        <!-- Off drops the SMSG_PERIODICAURALOG body
+                                             (`0x626dee`). -->
                                         <Frame name="$parentRowPeriodicDamage" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowShowDamage" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -2312,11 +2190,9 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The Action Bars page. Bar rows are API rows over the
-                                     character's PLAYER_FIELD_BYTES byte 2, re-sent on change;
-                                     Always Show ActionBars is a uvar, since SetActionBarToggles
-                                     drops a fifth argument (`cmp esi,4` at `0x4e770e`). The
-                                     closures resolve their callees at click time, not load. -->
+                                <!-- Bar rows are API rows over PLAYER_FIELD_BYTES byte 2, resolved
+                                     at click time. Always Show is a uvar: SetActionBarToggles drops
+                                     a fifth argument (`0x4e770e`). -->
                                 <Frame name="$parentActionBars" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -2383,8 +2259,7 @@
                                                     "0", "Show Right ActionBar", "OPTION_TOOLTIP_SHOW_MULTIBAR3")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- A child of bar 3: MultiBarLeft shows only beside
-                                             MultiBarRight (l.722-726). -->
+                                        <!-- Needs Right ActionBar (UIOptionsFrame.lua:722-726). -->
                                         <Frame name="$parentRowMultiBar4" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowMultiBar3" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -2413,8 +2288,7 @@
                                             <Scripts><OnLoad>
                                                 OptionsGlobalRow_OnLoad(self, "ALWAYS_SHOW_MULTIBARS",
                                                     "Always Show ActionBars", "OPTION_TOOLTIP_ALWAYS_SHOW_MULTIBARS")
-                                                -- The click arm (UIOptionsFrame.xml:683); the load
-                                                -- arm is the stock VARIABLES_LOADED one.
+                                                -- UIOptionsFrame.xml:680-683's click arm.
                                                 self.applyFunc = "MultiActionBar_UpdateGridVisibility"
                                             </OnLoad></Scripts>
                                         </Frame>
@@ -2430,17 +2304,15 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The Interface page. 62 (HIDE_OUTDOOR_WORLD_STATE) is absent:
-                                     no zone-objective tracker. A row has an applyFunc only when
-                                     something derived from it is set once and kept. -->
+                                <!-- No HIDE_OUTDOOR_WORLD_STATE row: there is no zone-objective
+                                     tracker. -->
                                 <Frame name="$parentInterface" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
                                         <Anchor point="BOTTOMRIGHT"/>
                                     </Anchors>
                                     <Frames>
-                                        <!-- CheckButtons 12 and 2 head the Display box; the
-                                             cvarEvent wakes TextStatusBar.xml's CVAR_UPDATE. -->
+                                        <!-- cvarEvent wakes TextStatusBar's CVAR_UPDATE. -->
                                         <Frame name="$parentRowEnhancedTooltips" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT"><Offset><AbsDimension x="10" y="-12"/></Offset></Anchor>
@@ -2460,9 +2332,8 @@
                                                 self.cvarEvent = "STATUS_BAR_TEXT"
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Saved globals in 1.12, not CVars. The mode row is a
-                                             child, as 1.12's dropdown hangs off CheckButton50 and
-                                             greys with it (l.694-700). -->
+                                        <!-- Saved globals in 1.12; the mode greys with its switch
+                                             (UIOptionsFrame.lua:697-701). -->
                                         <Frame name="$parentRowTargetOfTarget" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowStatusText" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -2474,8 +2345,8 @@
                                                 self.applyFunc = "TargetofTarget_Update"
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Deviation: the label is ours; 1.12 never sets this
-                                             dropdown's. Entries are its strings in its order. -->
+                                        <!-- The label is ours, since 1.12 never sets this
+                                             dropdown's; entries are its strings in its order. -->
                                         <Frame name="$parentRowTargetOfTargetMode" inherits="OptionsDropdownRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowTargetOfTarget" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -2494,8 +2365,8 @@
                                                 self.applyFunc = "TargetofTarget_Update"
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Bits of the character's PLAYER_FLAGS: API rows, as
-                                             1.12's `func` pair (UIOptionsFrame.lua l.18-19). -->
+                                        <!-- PLAYER_FLAGS bits, API rows
+                                             (UIOptionsFrame.lua:18-19). -->
                                         <Frame name="$parentRowShowCloak" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowTargetOfTargetMode" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -2548,8 +2419,7 @@
                                                     "Automatic Quest Tracking", "OPTION_TOOLTIP_AUTO_QUEST_WATCH")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- CheckButton5, closing the chain under 66. The CVar
-                                             gates in the shared masker (`0x4a1a66`). -->
+                                        <!-- The CVar gates in the shared masker (`0x4a1a66`). -->
                                         <Frame name="$parentRowProfanityFilter" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowAutoQuestWatch" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -2558,23 +2428,22 @@
                                             <Scripts><OnLoad>OptionsRow_OnLoad(self, "profanityFilter", "Profanity Filter",
                                                 "OPTION_TOOLTIP_PROFANITY_FILTER")</OnLoad></Scripts>
                                         </Frame>
-                                        <!-- The Help box, 28 -> 44 -> 29. Reset Tutorials does
-                                             not ship: ticking this row resets them. -->
+                                        <!-- No Reset Tutorials button: ticking this row resets
+                                             them. -->
                                         <Frame name="$parentRowShowTutorials" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowProfanityFilter" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                                 <Anchor point="TOPRIGHT" relativeTo="$parentRowProfanityFilter" relativePoint="BOTTOMRIGHT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                             </Anchors>
-                                            <!-- An API row over the tutorial bank, default "1"
-                                                 (UIOptionsFrame_SetDefaults l.645). -->
+                                            <!-- Default "1" (UIOptionsFrame.lua:645-646). -->
                                             <Scripts><OnLoad>
                                                 OptionsFuncRow_OnLoad(self, TutorialsEnabled,
                                                     BenillaOptionsFrame_SetTutorialsEnabled, "1",
                                                     "Show Tutorials", "OPTION_TOOLTIP_SHOW_TUTORIALS")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- The label and its tooltip name the tips
-                                             differently; both are 1.12's strings. -->
+                                        <!-- Label and tooltip name the tips differently; both are
+                                             1.12's. -->
                                         <Frame name="$parentRowTipOfTheDay" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowShowTutorials" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -2596,9 +2465,8 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The Chat page. The chat window's look stays on the chat tab's
-                                     menu, as in 1.12. Party Chat Bubbles is not a child: the
-                                     client gates party bubbles on their own CVar. -->
+                                <!-- Party Chat Bubbles is not a child: the client gates party
+                                     bubbles on their own CVar. -->
                                 <Frame name="$parentChat" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -2611,7 +2479,7 @@
                                                 <Anchor point="TOPRIGHT"><Offset><AbsDimension x="-20" y="-12"/></Offset></Anchor>
                                             </Anchors>
                                             <Scripts><OnLoad>
-                                                <!-- 1.12 registers it "0" (cvars.rs cites it). -->
+                                                <!-- 1.12 registers it "0". -->
                                                 OptionsRow_OnLoad(self, "guildMemberNotify",
                                                     "Guild Member Alert",
                                                     "OPTION_TOOLTIP_GUILDMEMBER_ALERT")
@@ -2663,9 +2531,9 @@
                                                     "Show Party Chat Bubbles", "OPTION_TOOLTIP_PARTY_CHAT_BUBBLES")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Inverted, as 1.12 checks it on "0" (l.253) and flips
-                                             the write (l.337). The filter drops a line matching
-                                             SpamMessages.dbc, in every chat type but
+                                        <!-- Inverted, as 1.12 reads (UIOptionsFrame.lua:253-255)
+                                             and writes it (l.337). The filter drops a
+                                             SpamMessages.dbc match in every chat type but
                                              CHAT_MSG_FILTERED (`0x49aad2`). -->
                                         <Frame name="$parentRowSpamFilter" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
@@ -2680,10 +2548,9 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The Nameplates page: the V-key plates (`[0xc4da34]` bits 0
-                                     and 3), then the 1.12 UnitName* checkboxes. Deviation: 1.12
-                                     has no plate rows, only the keybinding; these are era rows
-                                     named after BINDING_NAME_NAMEPLATES. -->
+                                <!-- The Nameplates page: the V-key plates (`[0xc4da34]` bits 0 and
+                                     3), then 1.12's UnitName* checkboxes. The plate rows are era
+                                     rows: 1.12 has only the keybinding. -->
                                 <Frame name="$parentNameplates" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -2714,8 +2581,7 @@
                                             <Scripts><OnLoad>OptionsRow_OnLoad(self, "UnitNamePlayer", "Player Names",
                                                 "OPTION_TOOLTIP_SHOW_PLAYER_NAMES")</OnLoad></Scripts>
                                         </Frame>
-                                        <!-- A child of Player Names, as CheckButton22 hangs off
-                                             21; it gates the guild line of the name stack. -->
+                                        <!-- A child of Player Names, as CheckButton22 of 21. -->
                                         <Frame name="$parentRowGuildNames" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowPlayerNames" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -2745,9 +2611,8 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The Keybindings page (its logic is KeyBindingsPage.xml).
-                                     enableMouse: rows are plain Frames, so the page itself
-                                     catches the wheel. -->
+                                <!-- enableMouse: rows are plain Frames, so the page catches the
+                                     wheel. -->
                                 <Frame name="$parentKeybindings" hidden="true" enableMouse="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -2761,8 +2626,7 @@
                                         </Layer>
                                     </Layers>
                                     <Frames>
-                                        <!-- The box at CENTER-40, not CENTER-80: the 1.12
-                                             string is longer than the era's and clips there. -->
+                                        <!-- CENTER-40: the 1.12 string clips at CENTER-80. -->
                                         <Frame name="$parentCharacterRow" enableMouse="true">
                                             <Size><AbsDimension y="26"/></Size>
                                             <Anchors>
@@ -2919,12 +2783,11 @@
                                         <Anchor point="TOPRIGHT" relativeTo="$parentRow18" relativePoint="BOTTOMRIGHT"/>
                                     </Anchors>
                                 </Frame>
-                                        <!-- The bar's trough (1.12 authors it per window), named
-                                             off the bar for BenillaScrollBar_SetShown. Declared
-                                             before the faux frame so it draws beneath it. -->
+                                        <!-- Declared before the faux frame so it draws beneath
+                                             it. -->
                                         <Frame name="$parentScrollFrameScrollBarTrough" inherits="BenillaScrollTroughTemplate"/>
-                                        <!-- Ends at -32 so the kit's bar, hung 6 right, rides
-                                             the -26..-10 gutter (the TrainerFrame seating). -->
+                                        <!-- Ends at -32, so the kit's bar rides the -26..-10
+                                             gutter. -->
                                         <ScrollFrame name="$parentScrollFrame" inherits="FauxScrollFrameTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT"><Offset><AbsDimension x="10" y="-47"/></Offset></Anchor>
@@ -2932,13 +2795,11 @@
                                             </Anchors>
                                             <Scripts>
                                                 <OnLoad>ScrollFrame_OnLoad()</OnLoad>
-                                                <!-- The 1.12 kit updates `offset` only here.
-                                                     KEYBINDINGS_ROW_HEIGHT must stay a global:
-                                                     this chunk cannot see another file's local. -->
+                                                <!-- KEYBINDINGS_ROW_HEIGHT must stay a global: this
+                                                     chunk cannot see another file's local. -->
                                                 <OnVerticalScroll>FauxScrollFrame_OnVerticalScroll(KEYBINDINGS_ROW_HEIGHT, KeyBindingsPage_Update)</OnVerticalScroll>
-                                                <!-- Replaces the inherited wheel handler, which
-                                                     fires before the page's guard: while a capsule
-                                                     is armed the wheel binds, never scrolls. -->
+                                                <!-- Fires before the page's guard, so it is
+                                                     replaced: an armed capsule binds the wheel. -->
                                                 <OnMouseWheel>
                                                     if not KeyBindingsPage.selected then
                                                         ScrollFrameTemplate_OnMouseWheel(arg1)
@@ -2947,8 +2808,7 @@
                                             </Scripts>
                                         </ScrollFrame>
                                     </Frames>
-                                    <!-- Rows and the bar bubble the wheel here; an armed
-                                         capsule binds it instead. -->
+                                    <!-- Rows and the bar bubble the wheel here. -->
                                     <Scripts>
                                         <OnMouseWheel>
                                             if not KeyBindingsPage.selected then
@@ -2957,8 +2817,7 @@
                                         </OnMouseWheel>
                                     </Scripts>
                                 </Frame>
-                                <!-- The search heads, one per OPTIONS_PAGE_ROWS page; a new
-                                     page needs one here. -->
+                                <!-- One per OPTIONS_PAGE_ROWS page. -->
                                 <Button name="$parentSearchHeadControls" inherits="OptionsSearchHeadTemplate">
                                     <Scripts><OnLoad>
                                         self.categoryKey = "Controls"
@@ -3013,8 +2872,7 @@
                                         getglobal(self:GetName() .. "Label"):SetText("Keybindings")
                                     </OnLoad></Scripts>
                                 </Button>
-                                <!-- The keybinding search pool: one frame per
-                                     KEYBINDINGS_SEARCH_ROWS (8). -->
+                                <!-- KEYBINDINGS_SEARCH_ROWS (8) frames. -->
                                 <Frame name="$parentKeybindSearch1" inherits="KeyBindingRowTemplate" hidden="true"/>
                                 <Frame name="$parentKeybindSearch2" inherits="KeyBindingRowTemplate" hidden="true"/>
                                 <Frame name="$parentKeybindSearch3" inherits="KeyBindingRowTemplate" hidden="true"/>
@@ -3025,9 +2883,8 @@
                                 <Frame name="$parentKeybindSearch8" inherits="KeyBindingRowTemplate" hidden="true"/>
                             </Frames>
                             </Frame>
-                            <!-- The page scroll bar, inside the right edge in the rows' free
-                                 -26..-10 gutter. Inset 21/20 so the trough, which hangs 21 above
-                                 and 20 below the bar, lands flush on the page rect. -->
+                            <!-- Inset 21/20 so the trough, which hangs 21 above and 20 below the
+                                 bar, lands flush. -->
                             <Slider name="$parentBar" inherits="BenillaScrollBarTemplate" hidden="true">
                                 <Anchors>
                                     <Anchor point="TOPRIGHT"><Offset><AbsDimension x="-10" y="-21"/></Offset></Anchor>
@@ -3040,12 +2897,10 @@
                 </Frames>
             </Frame>
 
-            <!-- The search box: the era SearchBoxTemplate geometry in the 1.12 Common-Input-Border
-                 (InputBoxTemplate UVs). Deviation: no magnifier, which has no 1.12 art, so the
-                 text inset is 5, not 16. -->
+            <!-- The search box: the era geometry in the 1.12 Common-Input-Border; no magnifier,
+                 which has no 1.12 art, so the text inset is 5, not 16. -->
             <EditBox name="$parentSearchBox" autoFocus="false" letters="64">
                 <Size><AbsDimension x="350" y="22"/></Size>
-                <!-- The era seat (SettingsPanel.xml l.76-81). -->
                 <Anchors>
                     <Anchor point="BOTTOMRIGHT" relativeTo="$parentContainer" relativePoint="TOPRIGHT"><Offset><AbsDimension x="4" y="20"/></Offset></Anchor>
                 </Anchors>
@@ -3122,7 +2977,6 @@
             </EditBox>
 
             <!-- ── Close: no corner X; the red button and ESC close the window ── -->
-            <!-- The red Close (era SettingsPanel.CloseButton). -->
             <Button name="$parentCloseButton" inherits="OptionsRedButtonTemplate" text="Close">
                 <Anchors><Anchor point="BOTTOMRIGHT"><Offset><AbsDimension x="-16" y="16"/></Offset></Anchor></Anchors>
                 <Scripts>
@@ -3132,7 +2986,7 @@
                     </OnClick>
                 </Scripts>
             </Button>
-            <!-- The era Apply (Blizzard_SettingsPanel.xml l.52-57), shown with a pending edit. -->
+            <!-- The era Apply, shown with a pending edit. -->
             <Button name="$parentApplyButton" inherits="OptionsRedButtonTemplate" text="Apply" hidden="true">
                 <Anchors><Anchor point="RIGHT" relativeTo="$parentCloseButton" relativePoint="LEFT"><Offset><AbsDimension x="-2" y="0"/></Offset></Anchor></Anchors>
                 <Scripts>
@@ -3148,8 +3002,8 @@
                 BenillaOptionsFrame_SelectCategory(this.selectedCategory or "Controls")
                 if UpdateMicroButtons then UpdateMicroButtons() end
             </OnShow>
-            <!-- Hiding ends a search (the era's ClearSearchBox), discards pending edits, and
-                 disarms a bind capture, which would otherwise swallow all input. -->
+            <!-- Hiding ends a search, discards pending edits, and disarms a bind capture, which
+                 would otherwise swallow all input. -->
             <OnHide>
                 BenillaOptionsFrameSearchBox:SetText("")
                 OptionsPage_DiscardPending()
@@ -3159,16 +3013,11 @@
             </OnHide>
         </Scripts>
     </Frame>
-    <!-- The reference's three options windows load hidden off the player's chain; nothing
-         aliases a stock name onto this window or shows a stock frame. This one is
-         BenillaOptionsFrame because the stock OptionsFrame.xml owns `OptionsFrame`.
-         GameMenuFrame.xml wraps ToggleGameMenu, IsOptionFrameOpen and UpdateMicroButtons, which
-         name only the stock three. Chat-tab hover (FloatingChatFrame.lua l.842/860) reads the
-         hidden UIOptionsFrame, so it works while this window, which does not cover the chat, is
-         open. -->
+    <!-- BenillaOptionsFrame, because the stock OptionsFrame.xml owns `OptionsFrame`. Chat-tab hover
+         (FloatingChatFrame.lua:842/860) reads the hidden UIOptionsFrame, so it works while this
+         window, which does not cover the chat, is open. -->
     <Script><![CDATA[
-        -- This window's UIPanelWindows row, the reference's OptionsFrame values (UIParent.lua:16):
-        -- the centre slot, openable while dead. UIParent.xml, which makes the table, loads first.
+        -- The reference's OptionsFrame row (UIParent.lua:16): the centre slot, openable while dead.
         UIPanelWindows["BenillaOptionsFrame"] = { area = "center", pushable = 0, whileDead = 1 }
     ]]></Script>
 </Ui>
diff --git a/crates/benilla-app/assets/ui/ScriptLogFrame.xml b/crates/benilla-app/assets/ui/ScriptLogFrame.xml
index 979c2b07..375c1dcc 100644
--- a/crates/benilla-app/assets/ui/ScriptLogFrame.xml
+++ b/crates/benilla-app/assets/ui/ScriptLogFrame.xml
@@ -1,31 +1,24 @@
 <Ui>
     <!--
-        Benilla's script error log. 1.12 has no such window, so every name here carries the
-        `Benilla` prefix (`tests::reference_surface` checks it). It sits beside the stock
-        `ScriptErrors` dialog, which shows one message and keeps none: the dialog interrupts,
-        this window keeps the log.
-        Shaped like the reference's CraftFrame: 13 fixed 16px rows over the stock faux-scroll kit
-        and a detail pane below. It registers in `UIPanelWindows`, which seats it in the left slot
-        and closes it on ESC, and stays out of `UISpecialFrames`, which belongs to addons.
-        The engine's log API: `BenillaGetNumScriptErrors()` returns retained and total-ever
-        counts; `BenillaGetScriptErrorInfo(i)` returns `seq, kind, message, count` (1-based,
-        oldest first, nil past the end); `BenillaClearScriptErrors()`. The window polls it.
+        The script error log, which 1.12 does not have, so every name carries the `Benilla` prefix
+        (`tests::reference_surface`); the stock `ScriptErrors` dialog shows one message, this keeps
+        the log. Shaped like the reference's CraftFrame. It polls the engine:
+        `BenillaGetNumScriptErrors()` is (retained, total-ever), `BenillaGetScriptErrorInfo(i)` is
+        `seq, kind, message, count` (1-based, oldest first, nil past the end).
     -->
     <Script><![CDATA[
-        -- A left-slot window with a pushable above every stock panel's, so a game window opening
-        -- pushes the log aside.
+        -- A pushable above every stock panel's, so a game window opening pushes the log aside.
         UIPanelWindows["BenillaScriptLogFrame"] = { area = "left", pushable = 9, whileDead = 1 }
 
         BENILLA_SCRIPTLOG_ROWS = 13
         BENILLA_SCRIPTLOG_ROW_HEIGHT = 16
-        -- How much of a message a row shows; a wrapped row would break the faux kit's fixed rows.
+        -- A wrapped row would break the faux kit's fixed rows.
         BENILLA_SCRIPTLOG_ROW_CHARS = 52
 
-        -- The selected row's `seq`, not its index: indices shift when the cap evicts.
+        -- A `seq`, not an index: indices shift when the cap evicts.
         BenillaScriptLogSelected = nil
 
-        -- A message's first line, trimmed to a row. `strsub` counts bytes and messages are UTF-8,
-        -- so the cut backs up over continuation bytes (0x80..0xBF) onto a character boundary.
+        -- `strsub` counts bytes, so the cut backs up over UTF-8 continuation bytes (0x80..0xBF).
         function BenillaScriptLog_RowText(message)
             local cut = strfind(message, "\n", 1, 1)
             local head = message
@@ -42,10 +35,8 @@
             return head
         end
 
-        -- Coloured by how much of the addon is broken:
-        --   `load`  red    the addon is not running at all
-        --   `error` amber  code ran and raised; the addon is otherwise up
-        --   `warn`  grey   a call was accepted and quietly did not do what it said
+        -- `load` red (the addon is not running), `error` amber (code raised), `warn` grey (a call
+        -- was accepted and quietly did nothing).
         function BenillaScriptLog_RowColor(kind)
             if kind == "load" then return 1.0, 0.3, 0.3 end
             if kind == "warn" then return 0.65, 0.65, 0.65 end
@@ -55,8 +46,7 @@
         function BenillaScriptLog_Update()
             local shown, total = BenillaGetNumScriptErrors()
 
-            -- `total` counts distinct failures ever recorded, `shown` what the cap kept. The
-            -- summary says "problems" because two of the three kinds are not errors.
+            -- "Problems", because two of the three kinds are not errors.
             local summary
             if total == 0 then
                 summary = "No problems this session."
@@ -97,8 +87,7 @@
                 end
             end
 
-            -- The highlight follows the selected row and hides when it scrolls away, as the
-            -- reference's CraftFrame does.
+            -- Hides when the row scrolls away, as the reference's CraftFrame does.
             local highlight = getglobal("BenillaScriptLogHighlightFrame")
             if selectedRow then
                 highlight:SetPoint("TOPLEFT", selectedRow:GetName(), "TOPLEFT", 0, 0)
@@ -110,8 +99,7 @@
             BenillaScriptLog_UpdateDetail()
         end
 
-        -- The selected message in full, traceback and all; selection is a `seq`, so this walks
-        -- the log rather than indexing it.
+        -- The selected message in full, traceback and all.
         function BenillaScriptLog_UpdateDetail()
             local text = ""
             if BenillaScriptLogSelected then
@@ -130,8 +118,7 @@
             getglobal("BenillaScriptLogDetailText"):SetText(text)
         end
 
-        -- Text rects resolve after Lua runs, so the detail child is re-measured every frame; once
-        -- it settles that is one compare, and OnUpdate fires only while the window is shown.
+        -- Text rects resolve after Lua runs, so the detail child is re-measured every frame.
         function BenillaScriptLogFrame_OnUpdate()
             BenillaScroll_ResizeChild("BenillaScriptLogDetailScroll", { "BenillaScriptLogDetailText" })
         end
@@ -152,7 +139,7 @@
                 "Interface\\Icons\\INV_Misc_Note_01")
         end
 
-        -- Stepping the bar repaints through the list frame's OnVerticalScroll, so no repaint here.
+        -- The list frame's OnVerticalScroll repaints.
         function BenillaScriptLogFrame_OnMouseWheel(delta)
             BenillaFauxScrollFrame_OnMouseWheel(getglobal("BenillaScriptLogListScrollFrame"), delta)
         end
@@ -168,8 +155,7 @@
             end
         end
 
-        -- `/errors clear`: forgets the rows but keeps the numbering, so a number never names two
-        -- failures. It confirms in chat because the window may be closed.
+        -- `/errors clear`: keeps the numbering, so a number never names two failures.
         function BenillaScriptLog_Clear()
             BenillaClearScriptErrors()
             BenillaScriptLogSelected = nil
@@ -180,8 +166,7 @@
         end
     ]]></Script>
 
-    <!-- One list row: the `#N xCount` index column, then the message head, in fixed columns as
-         1.12's lists are. -->
+    <!-- One list row: the `#N xCount` column, then the message head. -->
     <Button name="BenillaScriptLogRowTemplate" virtual="true" hidden="true">
         <Size><AbsDimension x="293" y="16"/></Size>
         <Layers>
@@ -207,19 +192,17 @@
     </Button>
 
     <Frame name="BenillaScriptLogFrame" hidden="true">
-        <!-- 384x512, the standard left-slot panel size. No <Anchors>: ShowUIPanel seats it. -->
+        <!-- The standard left-slot panel size. No <Anchors>: ShowUIPanel seats it. -->
         <Size><AbsDimension x="384" y="512"/></Size>
         <Layers>
             <Layer level="BACKGROUND">
-                <!-- A square item icon: OnLoad masks it with `SetPortraitToTexture`, since `file=`
-                     alone shows its corners through the ring. -->
+                <!-- OnLoad masks the square icon, whose corners would show through the ring. -->
                 <Texture name="BenillaScriptLogFramePortrait" file="Interface\Icons\INV_Misc_Note_01">
                     <Size><AbsDimension x="60" y="60"/></Size>
                     <Anchors><Anchor point="TOPLEFT"><Offset><AbsDimension x="7" y="-6"/></Offset></Anchor></Anchors>
                 </Texture>
             </Layer>
-            <!-- The ClassTrainer quadrants, the one uniform set in the 1.12 art; this window
-                 belongs to no profession. -->
+            <!-- The ClassTrainer quadrants, the one profession-free set in the 1.12 art. -->
             <Layer level="BORDER">
                 <Texture file="Interface\ClassTrainerFrame\UI-ClassTrainer-TopLeft"><Size><AbsDimension x="256" y="256"/></Size><Anchors><Anchor point="TOPLEFT"/></Anchors></Texture>
                 <Texture file="Interface\ClassTrainerFrame\UI-ClassTrainer-TopRight"><Size><AbsDimension x="128" y="256"/></Size><Anchors><Anchor point="TOPRIGHT"/></Anchors></Texture>
@@ -228,7 +211,6 @@
                 <FontString name="BenillaScriptLogTitle" inherits="GameFontNormal" justifyH="CENTER" text="Script Errors">
                     <Anchors><Anchor point="TOP" relativePoint="TOP"><Offset><AbsDimension x="0" y="-17"/></Offset></Anchor></Anchors>
                 </FontString>
-                <!-- The summary line, the only place the dropped-row count shows. -->
                 <FontString name="BenillaScriptLogSummary" inherits="GameFontHighlightSmall" justifyH="LEFT" text="">
                     <Anchors><Anchor point="TOPLEFT" relativePoint="TOPLEFT"><Offset><AbsDimension x="26" y="-76"/></Offset></Anchor></Anchors>
                 </FontString>
@@ -266,19 +248,17 @@
             <Button name="BenillaScriptLogRow12" inherits="BenillaScriptLogRowTemplate"><Anchors><Anchor point="TOPLEFT" relativeTo="BenillaScriptLogRow11" relativePoint="BOTTOMLEFT"/></Anchors></Button>
             <Button name="BenillaScriptLogRow13" inherits="BenillaScriptLogRowTemplate"><Anchors><Anchor point="TOPLEFT" relativeTo="BenillaScriptLogRow12" relativePoint="BOTTOMLEFT"/></Anchors></Button>
 
-            <!-- The faux kit over the 13-row span; only its right-hand Slider renders. -->
+            <!-- Only the faux kit's right-hand Slider renders. -->
             <ScrollFrame name="BenillaScriptLogListScrollFrame" inherits="FauxScrollFrameTemplate">
                 <Size><AbsDimension x="293" y="208"/></Size>
                 <Anchors><Anchor point="TOPLEFT" relativePoint="TOPLEFT"><Offset><AbsDimension x="22" y="-94"/></Offset></Anchor></Anchors>
                             <Scripts>
-                    <!-- The stock kit sets the offset only from here and has no `updateFunc`, so
-                         the repaint is wired here too. -->
+                    <!-- The stock kit has no `updateFunc`, so the repaint is wired here. -->
                     <OnVerticalScroll>FauxScrollFrame_OnVerticalScroll(BENILLA_SCRIPTLOG_ROW_HEIGHT, BenillaScriptLog_Update)</OnVerticalScroll>
                 </Scripts>
 </ScrollFrame>
 
-            <!-- The detail pane, on the real-scroll kit: a message with its `stack traceback:` tail
-                 has variable height. -->
+            <!-- The real-scroll kit: a message with its traceback has variable height. -->
             <ScrollFrame name="BenillaScriptLogDetailScroll">
                 <Size><AbsDimension x="293" y="128"/></Size>
                 <Anchors><Anchor point="TOPLEFT" relativePoint="TOPLEFT"><Offset><AbsDimension x="22" y="-314"/></Offset></Anchor></Anchors>
@@ -325,16 +305,14 @@
         </Frames>
         <Scripts>
             <OnLoad>BenillaScriptLogFrame_OnLoad(self)</OnLoad>
-            <!-- The list's wheel handler is on the window, since a spin bubbles up the parent
-                 chain; the detail pane's own handler wins over its rect. -->
+            <!-- A spin bubbles up the parent chain; the detail pane's own handler wins there. -->
             <OnMouseWheel>BenillaScriptLogFrame_OnMouseWheel(arg1)</OnMouseWheel>
             <OnShow>BenillaScriptLog_Update()</OnShow>
             <OnUpdate>BenillaScriptLogFrame_OnUpdate()</OnUpdate>
         </Scripts>
     </Frame>
-    <!-- Benilla's slash commands in the stock SlashCmdList, which ChatEdit_ParseText walks after
-         its built-ins; each hands its line to SubmitChatInput, where ui_chat::input parses it.
-         This file loads after the stock ChatFrame.xml, which declares the table. -->
+    <!-- Benilla's slash commands, handed to SubmitChatInput (ui_chat::input); loads after the
+         stock ChatFrame.xml, which declares SlashCmdList. -->
     <Script><![CDATA[
         local BENILLA_COMMANDS = {
             { "CHATTEST", "/chattest" },
diff --git a/crates/benilla-app/assets/ui/ScrollTemplates.xml b/crates/benilla-app/assets/ui/ScrollTemplates.xml
index 00a66d3c..0a7cfd07 100644
--- a/crates/benilla-app/assets/ui/ScrollTemplates.xml
+++ b/crates/benilla-app/assets/ui/ScrollTemplates.xml
@@ -1,23 +1,15 @@
 <Ui>
     <!--
-        Benilla's scroll kits, sharing one `Slider` bar, its arrow helpers and an optional trough:
-        a faux-scroll kit that re-binds a fixed set of rows to a moving data offset, and a
-        real-scroll kit that pans and clips a `<ScrollFrame>` child whose height is known only after
-        layout. A real-scroll bar overrides the template's OnValueChanged on its instance, which
-        wins because the loader runs every `<Scripts>` block in order.
-        Faux model: the value is pixels, `[0, (numItems - numToDisplay) * itemHeight]` in steps of
-        `itemHeight`; the parent holds the 0-based top row in `frame.offset` and its repaint in
-        `frame.updateFunc`, set by the owner's OnLoad.
-        Deviation: the faux parent is a plain `<Frame>`, not the reference's ScrollFrame relay,
-        which adds nothing because the reference's `SetVerticalScroll` stores the bar's value as is.
-        `FauxScrollFrameTemplate` and the `FauxScrollFrame_*`, `ScrollFrame_*` and
-        `ScrollingEdit_*` API are the stock `UIPanelTemplates` on the player's chain, which loads
-        after this file, so its declarations win.
+        Benilla's scroll parts: a `Slider` bar with its arrow helpers, an optional trough, and a
+        real-scroll kit that pans a `<ScrollFrame>` child whose height is known only after layout.
+        Faux lists use the stock `FauxScrollFrameTemplate`; this file declares only `Benilla` names.
+        A real-scroll bar overrides the template's OnValueChanged on its instance, which wins
+        because the loader runs every `<Scripts>` block in order.
     -->
     <Script><![CDATA[
-        -- Steps the bar by its valueStep. Deviation: one row on a faux list, where the reference
-        -- bar's arrows step half its height. Soundless: the reference plays UChatScrollButton on
-        -- an arrow click, never on the wheel, so the arrows' OnClick plays it.
+        -- One valueStep per step, where the reference's arrows and wheel move half the bar
+        -- (UIPanelTemplates.xml:137/149, UIPanelTemplates.lua:150-157).
+        -- Soundless: the reference plays UChatScrollButton on an arrow click, never on the wheel.
         function BenillaScrollBar_Step(scrollBar, dir)
             local step = scrollBar:GetValueStep()
             if step <= 0 then step = 1 end
@@ -34,11 +26,10 @@
             if val >= maxV then down:Disable() else down:Enable() end
         end
 
-        -- The faux bar's OnValueChanged: the top row is the value rounded to the nearest row, so
-        -- thumb and rows agree, and `updateFunc` runs only when that row changes, which also ends
-        -- the loop when a repaint re-seats the thumb.
-        -- A ScrollFrame parent also gets the value through SetVerticalScroll, as the reference's
-        -- `UIPanelScrollBarTemplate` routes it (UIPanelTemplates.xml l.156-158).
+        -- The value is pixels in steps of a row; the parent holds the 0-based top row in
+        -- `frame.offset` and its repaint in `frame.updateFunc`, which runs only when that row
+        -- changes, so a repaint that re-seats the thumb ends the loop. A ScrollFrame parent also
+        -- gets SetVerticalScroll, as UIPanelTemplates.xml:156-158 routes it.
         function BenillaFauxScrollBar_OnValueChanged(scrollBar, value)
             local frame = scrollBar:GetParent()
             local step = scrollBar:GetValueStep()
@@ -52,10 +43,8 @@
             if frame.SetVerticalScroll then frame:SetVerticalScroll(value) end
         end
 
-        -- Seats a trough on its bar with the reference's ReputationFrame hang, 8 left, 21 above and
-        -- 20 below (ReputationFrame.xml l.573-599 against UIPanelTemplates.xml l.166-181), which
-        -- puts each art socket on its arrow button. Lazy, because the bar is declared after its
-        -- trough and does not exist at the trough's OnLoad.
+        -- ReputationFrame's hang, 8 left, 21 above, 20 below (ReputationFrame.xml:573-599 against
+        -- UIPanelTemplates.xml:166-181). Lazy: the bar does not exist at the trough's OnLoad.
         function BenillaScrollTrough_Seat(trough, scrollBar)
             if trough.seated then return end
             trough.seated = true
@@ -64,9 +53,7 @@
             trough:SetPoint("BOTTOMRIGHT", scrollBar, "BOTTOMRIGHT", 7, -20)
         end
 
-        -- Shows or hides a bar and its `<barname>Trough` together, seating the trough first; show
-        -- and hide a bar only through here. The trough is opt-in because 1.12 draws trough art per
-        -- window: `UIPanelScrollBarTemplate` carries only the arrows and the knob.
+        -- Show and hide a bar only through here, so its `<barname>Trough` follows.
         function BenillaScrollBar_SetShown(scrollBar, shown)
             local trough = getglobal(scrollBar:GetName() .. "Trough")
             if trough then BenillaScrollTrough_Seat(trough, scrollBar) end
@@ -79,9 +66,7 @@
             end
         end
 
-        -- The same for a stock `FauxScrollFrameTemplate` frame, whose bar is the reference's: seats
-        -- `<frame>ScrollBarTrough` and mirrors the frame's shown state. Call it after
-        -- `FauxScrollFrame_Update`, which shows or hides the frame.
+        -- For a stock `FauxScrollFrameTemplate` frame; call after `FauxScrollFrame_Update`.
         function BenillaScrollTrough_Follow(scrollFrameName)
             local sf = getglobal(scrollFrameName)
             if not sf then return end
@@ -93,30 +78,25 @@
             if sf:IsShown() then trough:Show() else trough:Hide() end
         end
 
-        -- One row per wheel notch (+1 up) on a faux list, called from the owner window's
-        -- OnMouseWheel since the spin bubbles up the parent chain. Benilla-named: the reference has
-        -- no faux wheel function (its `ScrollFrameTemplate_OnMouseWheel` moves half the bar).
+        -- One row per wheel notch (+1 up), from the owner window's OnMouseWheel; the reference's
+        -- `ScrollFrameTemplate_OnMouseWheel` moves half the bar.
         function BenillaFauxScrollFrame_OnMouseWheel(frame, delta)
             local scrollBar = getglobal(frame:GetName() .. "ScrollBar")
             BenillaScrollBar_Step(scrollBar, -delta)
         end
 
         -- ══════════════════════════ The real-scroll kit ══════════════════════════════════════════
-        -- Shaped on the reference `UIPanelScrollFrameTemplate` (UIPanelTemplates.xml l.166-211):
-        -- the bar is a `Slider` child, `$parentBar`, so `bar:GetParent()` is the frame it pans.
+        -- Shaped on UIPanelTemplates.xml:166-211: the bar is the `Slider` child `$parentBar`.
         BENILLA_SCROLL_STEP = 20   -- px per arrow click or wheel notch
         BENILLA_SCROLL_PAD = 20    -- px of room below the child's last element
 
-        -- Pans the frame the bar rides. The loop back through OnVerticalScroll and SyncBar ends in
-        -- one hop: SyncBar writes the value the bar already holds, which Slider:SetValue ignores.
+        -- The loop back through SyncBar ends in one hop: Slider:SetValue ignores an equal value.
         function BenillaScrollBar_OnValueChanged(bar, value)
             bar:GetParent():SetVerticalScroll(value)
             BenillaScrollBar_UpdateArrows(bar)
         end
 
-        -- Fits the bar to the frame's live range, [0, range] px, and hides it when the content fits
-        -- (reference: ScrollFrame_OnScrollRangeChanged). Owners call it from OnScrollRangeChanged
-        -- and OnVerticalScroll.
+        -- Hides the bar when the content fits (reference: ScrollFrame_OnScrollRangeChanged).
         function BenillaScroll_SyncBar(sf)
             local bar = getglobal(sf:GetName() .. "Bar")
             if not bar then return end
@@ -128,8 +108,7 @@
             BenillaScrollBar_SetShown(bar, range > 0)
         end
 
-        -- Pans by `delta` px, clamped here: SetVerticalScroll stores any value, as the reference's
-        -- does; the reference's ScrollFrameTemplate_OnMouseWheel clamps through its bar's range.
+        -- Clamped here: SetVerticalScroll stores any value, as the reference's does.
         function BenillaScroll_Step(sf, delta)
             local target = sf:GetVerticalScroll() + delta
             local range = sf:GetVerticalScrollRange()
@@ -144,7 +123,7 @@
             BenillaScroll_Step(sf, -delta * BENILLA_SCROLL_STEP)
         end
 
-        -- A widget's resolved bottom, or nil if hidden, a blank FontString, or not laid out yet.
+        -- Nil if hidden, a blank FontString, or not laid out yet.
         function BenillaScroll_WidgetBottom(w)
             if not w then return nil end
             if w.IsShown then
@@ -156,13 +135,11 @@
             return w:GetBottom()
         end
 
-        -- Sizes the scroll child to its lowest visible widget plus BENILLA_SCROLL_PAD and updates
-        -- the frame's range. Rects resolve after Lua runs, so owners re-run it from OnUpdate until
-        -- it returns false; it writes only on a real change, since SetHeight invalidates layout.
+        -- Rects resolve after Lua runs, so owners re-run this from OnUpdate; it writes only on a
+        -- real change, since SetHeight invalidates layout.
         function BenillaScroll_ResizeChild(scrollName, widgets)
             local sf = getglobal(scrollName)
-            -- The frame's own child, not a derived name: the reference pairs `<X>ScrollFrame` with
-            -- `<X>ScrollChildFrame`.
+            -- Not a derived name: the reference pairs `<X>ScrollFrame` with `<X>ScrollChildFrame`.
             local child = sf:GetScrollChild()
             if not child then return false end
             local top = child:GetTop()
@@ -182,11 +159,7 @@
         end
     ]]></Script>
 
-    <!--
-        The bar: a 16px `Slider` with step buttons above and below the track, on the stock 1.12
-        scrollbar art cropped to its centred 16px (the `0.25..0.75` TexCoords of the reference's
-        `UIPanelScrollBarButton`).
-    -->
+    <!-- The stock scrollbar art cropped to its centred 16px, as `UIPanelScrollBarButton` does. -->
     <Slider name="BenillaScrollBarTemplate" virtual="true">
         <Size><AbsDimension x="16" y="0"/></Size>
         <Frames>
@@ -219,24 +192,19 @@
     </Slider>
 
     <!--
-        A bar's trough, the recessed channel it rides in; the reference's scroll kit has none.
-        Declare it before its bar, so it draws beneath, named `<barname>Trough` and with no
-        anchors: BenillaScrollTrough_Seat seats it on the bar.
-        `UI-Character-ScrollBar` (64x256) holds two 31-wide channel pieces, the left column
-        (u 0 .. 31/64) capped at the top and the right (u 33/64 .. 1) at the bottom, each with a
-        16-tall socket for its arrow button: rows 4-19 at the top, rows 87-102 at the bottom.
-        Deviation: cut as a three-slice (both socket ends at natural height, the plain channel
-        stretched between) where the reference overlaps two quads, since two quads reach only 362
-        units and a page here is 563 tall.
-        The black fill is the reference's trough backing (ItemTextFrame's 0.8-alpha `Middle`). It
-        is in BACKGROUND and the art in BORDER because the client orders overlapping quads within
-        one layer by texture handle; the bar's buttons (ARTWORK) and knob (OVERLAY) draw above both.
+        A bar's trough, drawn per window in 1.12. Declare it before its bar, named
+        `<barname>Trough`, with no anchors. `UI-Character-ScrollBar` holds two 31-wide pieces,
+        the left capped at the top, the right at the bottom.
+        Deviation: a three-slice where the reference overlaps two quads, since two quads reach
+        only 362 units and a page here is 563 tall.
+        The fill is ItemTextFrame's 0.8-alpha black; fill and art are in separate layers because
+        the client orders overlapping quads within one layer by texture handle.
     -->
     <Frame name="BenillaScrollTroughTemplate" virtual="true" hidden="true">
         <Size><AbsDimension x="31"/></Size>
         <Layers>
             <Layer level="BACKGROUND">
-                <!-- The channel interior: x 6..24 of the 31-wide piece, inset 6 from each edge. -->
+                <!-- The channel interior, inset 6 from each edge of the 31-wide piece. -->
                 <Texture name="$parentFill">
                     <Anchors>
                         <Anchor point="TOPLEFT"><Offset><AbsDimension x="6" y="0"/></Offset></Anchor>
@@ -246,7 +214,7 @@
                 </Texture>
             </Layer>
             <Layer level="BORDER">
-                <!-- Cap + up-arrow socket + crossbar: left column, rows 0..22 (v 0 .. 23/256). -->
+                <!-- Left column, rows 0..22: the cap, the up-arrow socket and a crossbar. -->
                 <Texture name="$parentTop" file="Interface\PaperDollInfoFrame\UI-Character-ScrollBar">
                     <Size><AbsDimension y="23"/></Size>
                     <Anchors>
@@ -255,8 +223,7 @@
                     </Anchors>
                     <TexCoords left="0" right="0.484375" top="0" bottom="0.08984375"/>
                 </Texture>
-                <!-- Crossbar + down-arrow socket + cap: right column, rows 82..107
-                     (v 82/256 .. 108/256), ending on v 0.421875 as ReputationFrame's does. -->
+                <!-- Right column, ending on v 0.421875 as ReputationFrame's does. -->
                 <Texture name="$parentBottom" file="Interface\PaperDollInfoFrame\UI-Character-ScrollBar">
                     <Size><AbsDimension y="26"/></Size>
                     <Anchors>
@@ -265,8 +232,7 @@
                     </Anchors>
                     <TexCoords left="0.515625" right="1.0" top="0.3203125" bottom="0.421875"/>
                 </Texture>
-                <!-- The stretched run between them: left column rows 30..70, plain rails only.
-                     Declared last: an anchor to a later sibling falls back to the parent. -->
+                <!-- Declared last: an anchor to a later sibling falls back to the parent. -->
                 <Texture name="$parentMiddle" file="Interface\PaperDollInfoFrame\UI-Character-ScrollBar">
                     <Anchors>
                         <Anchor point="TOPLEFT" relativeTo="$parentTop" relativePoint="BOTTOMLEFT"/>
diff --git a/crates/benilla-app/assets/ui/SpellBookAdapters.xml b/crates/benilla-app/assets/ui/SpellBookAdapters.xml
index b522c311..67ce0e97 100644
--- a/crates/benilla-app/assets/ui/SpellBookAdapters.xml
+++ b/crates/benilla-app/assets/ui/SpellBookAdapters.xml
@@ -1,13 +1,9 @@
 <Ui>
     <!--
-        Deviation: over the unedited stock SpellBookFrame.xml, the pet
-        page's autocast widgets take the pet bar button's proportions.
-        The `$parentAutoCast` shine (UI-AutoCastButton.mdx) is squared on the button, 37x37 at
-        CENTER (0,0) and scale 1.48, so its rim runs on the viewport edge at the pet button's
-        1.024x and shares the brackets' centre; the reference's is 36x36 at CENTER (1,1), 1.22.
-        The corner brackets are 71.53 rather than 60: the art fills 33/64 of
-        UI-AutoCastableOverlay.blp, and 71.53 = 37 x 58/30 puts them on the button's corners at
-        the pet button's 0.997x. Deleting this file restores the reference's look.
+        Deviation: the pet page's autocast widgets take the pet bar button's proportions, so the
+        shine and the corner brackets sit on the button's edge and share its centre. Stock
+        SpellBookFrame.xml has the shine 36x36 at CENTER (1,1), scale 1.22, the brackets 60; 71.53
+        is 37 x 58/30 (the art fills 33/64 of UI-AutoCastableOverlay.blp).
     -->
     <Script><![CDATA[
         for i = 1, 12 do
diff --git a/crates/benilla-app/assets/ui/benilla.toc b/crates/benilla-app/assets/ui/benilla.toc
index 0fe1a559..9170c73a 100644
--- a/crates/benilla-app/assets/ui/benilla.toc
+++ b/crates/benilla-app/assets/ui/benilla.toc
@@ -1,35 +1,30 @@
-# The built-in interface, parsed like any addon's `.toc`. Entries load in order: a bare filename
-# is ours, from `assets/ui`; a path is the reference's own file, off the player's patch chain.
-# The list loads on entering the world, then third-party addons. Deviation: entry 0, Fonts.xml,
-# loads alone at Startup, because the glue screens share its glyph atlas.
-# A frame built at load resolves `inherits=`, `parent=` and a named `relativeTo=` against names
-# declared above; a missing one only warns (the template is skipped, the parent falls back to the
-# enclosing frame).
-# On a collision a later Lua global or template replaces the earlier one, but a named frame
-# publishes its global only while the name is free.
-# A stock `.xml` that does not `<Script file=>` its own `.lua` needs both rows, `.lua` first
-# (`every_chain_xml_brings_its_own_lua`).
-# Blizzard's LoadOnDemand addons have no row, as in the reference: `ui_script::addons` loads each
-# off the chain on first use, after every template here is registered.
+# The built-in interface, in load order: a bare filename is ours, from `assets/ui`; a path is
+# the reference's own file, off the player's patch chain. Entry 0, Fonts.xml, loads alone into
+# every boot VM, from Startup on; the rest loads on entering the world, then third-party addons.
+# The font objects thus exist before the login screen; the reference loads Fonts.xml with the
+# rest of FrameXML.
+# `inherits=`, `parent=` and a named `relativeTo=` resolve only against names declared above; a
+# missing one only warns (the template is skipped, the parent falls back to the enclosing frame).
+# A later Lua global or template replaces an earlier one; a named frame publishes its global
+# only while the name is free.
+# A stock `.xml` that does not `<Script file=>` its own `.lua` needs both rows, `.lua` first.
+# LoadOnDemand addons have no row, as in the reference; they load off the chain on first use.
 
 ## Interface: 11200
 ## Title: benilla
 
 Interface\FrameXML\Fonts.xml
 
-# Second, not first as in the reference, because entry 0 must be Fonts.xml. The VM already ran it
-# at Startup; this pass makes the manifest complete, and stock files read the strings at load.
+# Second, not first as in the reference, because entry 0 must be Fonts.xml.
 Interface\FrameXML\GlobalStrings.lua
 # `Localize()` runs at load and overwrites GlobalStrings keys, so this follows them.
 Interface\FrameXML\Localization.xml
-# `GetText` and its gender and plural helpers: a Lua global, not an engine binding (the client's
-# `FrameScript_GetText` at `0x703bf0` calls it). UIParent.xml sources this file again.
+# `GetText` is a Lua global, not an engine binding: the client's `0x703bf0` calls it.
 Interface\FrameXML\LocaleProperties.lua
 Interface\FrameXML\BasicControls.xml
 # Before UIParent.xml, whose `LowHealthFrame` has `parent="WorldFrame"`.
 Interface\FrameXML\WorldFrame.xml
 # Above every file that names `parent="UIParent"` or adds a `UIPanelWindows` row at load.
-# `ui_script::manifest` reruns `UIParent_ManageFramePositions` once the whole list has loaded.
 Interface\FrameXML\UIParent.xml
 Interface\FrameXML\ItemButtonTemplate.xml
 # Before GameTooltip.xml and StaticPopup.xml, whose money rows inherit `SmallMoneyFrameTemplate`.
@@ -40,8 +35,7 @@ Interface\FrameXML\MoneyInputFrame.xml
 Interface\FrameXML\GameTooltip.xml
 Interface\FrameXML\UIDropDownMenu.xml
 Interface\FrameXML\UIMenu.xml
-# Before the unit frames: their dropdowns' OnLoad runs `UIDropDownMenu_Initialize`, whose
-# initializer calls `UnitPopup_ShowMenu` at once.
+# Before the unit frames, whose dropdowns' OnLoad reaches `UnitPopup_ShowMenu`.
 Interface\FrameXML\UnitPopup.xml
 Interface\FrameXML\ItemRef.xml
 # The `TextStatusBar` template and verbs, which the unit bars and `MainMenuExpBar` inherit.
@@ -49,8 +43,7 @@ Interface\FrameXML\TextStatusBar.lua
 Interface\FrameXML\TextStatusBar.xml
 # Before PartyFrame.xml, whose rows reach `RefreshBuffs` from their OnLoad.
 Interface\FrameXML\BuffFrame.xml
-# Two function-only kits: the unit windows below call `UnitFrame_Initialize` from their OnLoad,
-# and the player and pet frames `CombatFeedback_Initialize`.
+# Function-only kits the unit windows below call from their OnLoad.
 Interface\FrameXML\UnitFrame.xml
 Interface\FrameXML\CombatFeedback.xml
 Interface\FrameXML\PlayerFrame.xml
@@ -59,43 +52,38 @@ Interface\FrameXML\TargetFrame.xml
 Interface\FrameXML\PetFrame.xml
 # Anchors `relativeTo="TargetFrame"`.
 Interface\FrameXML\ComboFrame.xml
-# Ours: benilla's scroll kits, for our options window and script log.
+# Ours: the scroll parts of our options window and script log.
 ScrollTemplates.xml
 
 Interface\FrameXML\UIPanelTemplates.lua
 
 Interface\FrameXML\UIPanelTemplates.xml
-# The reference's three options windows, loaded hidden so addons find their frames by name;
-# nothing of ours may show them. Deviation: the player opens benilla's own options window,
-# `OptionsFrame.xml` below. The video window's templates (OptionsFrameTemplates.xml) inherit
-# UIPanelTemplates.xml's, and its dropdowns run `UIDropDownMenu_Initialize` at load. It holds the
-# global `OptionsFrame`, so ours is `BenillaOptionsFrame`.
+# The reference's three options windows, loaded hidden so addons find their frames by name.
+# Deviation: the player opens our own options window, `OptionsFrame.xml` below, because 1.12's
+# settings screens are much worse to use; the stock one holds `OptionsFrame`.
 Interface\FrameXML\OptionsFrame.xml
 Interface\FrameXML\SoundOptionsFrame.xml
-# Inherits `OptionsCheckButtonTemplate`; brings CharacterFrameTemplates.xml and declares
-# `UIOptionsFrameCheckButtons`, which MultiActionBars.lua writes at load.
+# Inherits `OptionsCheckButtonTemplate`, and declares `UIOptionsFrameCheckButtons`, which
+# MultiActionBars.lua writes at load.
 Interface\FrameXML\UIOptionsFrame.xml
 # StaticPopup.lua starts `StaticPopupDialogs` empty: a file that adds a dialog at load follows it.
 Interface\FrameXML\StaticPopup.xml
 Interface\FrameXML\CoinPickupFrame.xml
 
-# Ours: the options window's Keybindings page. Before OptionsFrame.xml, whose Keybindings page
-# inherits these templates and calls this script at OnLoad.
+# Ours: the Keybindings page's templates and script, which OptionsFrame.xml uses at load.
 KeyBindingsPage.xml
 
-# Ours: `BenillaOptionsFrame`, the options window the game menu opens. Its rows read
-# `OptionsFrameSliders` and the option globals the stock windows above set at load.
+# Ours: `BenillaOptionsFrame`; its rows read the option globals the stock windows above set.
 OptionsFrame.xml
 
-# Declares `MainMenuBar`, `MainMenuBarArtFrame` and `MainMenuExpBar`, which later files use as a
-# parent or read at load.
+# `MainMenuBar`, `MainMenuBarArtFrame` and `MainMenuExpBar`, which later files read at load.
 Interface\FrameXML\MainMenuBar.xml
 
 Interface\FrameXML\Cooldown.xml
 # `ActionButtonTemplate`, which ActionBarFrame.xml's `ActionBarButtonTemplate` inherits.
 Interface\FrameXML\ActionButtonTemplate.xml
 Interface\FrameXML\ActionBarFrame.xml
-# The four optional bars (action slots 25-72), built on `ActionBarButtonTemplate`.
+# The four optional bars, action slots 25-72.
 Interface\FrameXML\MultiActionBars.xml
 Interface\FrameXML\PetActionBarFrame.xml
 # `UpdateMicroButtons` reads CharacterFrame, SpellBookFrame, QuestLogFrame, GameMenuFrame, the
@@ -119,17 +107,15 @@ Interface\FrameXML\UIErrorsFrame.xml
 # Anchors `relativeTo="UIErrorsFrame"`.
 Interface\FrameXML\RaidWarning.xml
 Interface\FrameXML\ContainerFrame.xml
-# `CharacterFrame` is the parent of every tab page below. PaperDollFrame.xml declares the stat
-# templates PetPaperDollFrame.xml inherits and `PaperDollItemSlotButtonTemplate`, which the bag
-# bar inherits. `CharacterFrame_OnLoad` reads `PlayerFrameHealthBar`, `PlayerFrameManaBar` and
-# `MainMenuExpBar` and calls `PanelTemplates_SetNumTabs`, all declared above.
+# `CharacterFrame` parents every tab page below, and its OnLoad reads `PlayerFrameHealthBar`,
+# `PlayerFrameManaBar` and `MainMenuExpBar`; PaperDollFrame.xml declares templates the pet page
+# and the bag bar inherit.
 Interface\FrameXML\CharacterFrame.xml
 Interface\FrameXML\PaperDollFrame.xml
 Interface\FrameXML\PetPaperDollFrame.xml
 Interface\FrameXML\MainMenuBarBagButtons.xml
 Interface\FrameXML\StackSplitFrame.xml
-# Ours. Deviation: the keyring is an ordinary container (id -2), so its tooltip uses `SetBagItem`;
-# this wraps `ContainerFrameItemButton_OnEnter`, capturing the stock body at load.
+# Ours: wraps the stock bag verbs; the keyring is a container (id -2).
 ContainerFrameAdapters.xml
 Interface\FrameXML\ReputationFrame.xml
 Interface\FrameXML\SkillFrame.xml
@@ -137,8 +123,7 @@ Interface\FrameXML\SkillFrame.xml
 Interface\FrameXML\HonorFrame.xml
 Interface\FrameXML\DressUpFrame.xml
 Interface\FrameXML\SpellBookFrame.xml
-# Ours. Deviation: the spellbook's autocast brackets (71.53, reference 60) and shine (37x37 at
-# scale 1.48) take the pet action button's proportions. Resizes `SpellButton1..12` at load.
+# Ours: the pet page's autocast widgets in the pet action button's proportions.
 SpellBookAdapters.xml
 # RaidFrame.xml names `parent="FriendsFrame"` and MailFrame.xml inherits `FriendsFrameTabTemplate`.
 Interface\FrameXML\FriendsFrame.xml
@@ -163,25 +148,20 @@ Interface\FrameXML\QuestTimerFrame.xml
 Interface\FrameXML\ChatFrame.xml
 Interface\FrameXML\FloatingChatFrame.xml
 
-# `ShapeshiftBar_OnLoad` can show the bar, whose OnShow runs `UIParent_ManageFramePositions`. The
-# pass reads the reputation watch bar, the quest timer and watch frames, the chat frames and more
-# unguarded, so this follows all of them (enforced by
-# `every_load_time_runner_of_the_managed_pass_follows_what_it_reads`).
+# `ShapeshiftBar_OnLoad` can reach `UIParent_ManageFramePositions`, which reads the frames above
+# unguarded.
 Interface\FrameXML\BonusActionBarFrame.xml
 # `WorldStateAlwaysUpFrame`'s OnLoad runs the same pass, which also reads
 # `ShapeshiftBarLeft/Middle/Right`, so this follows BonusActionBarFrame.xml.
 Interface\FrameXML\WorldStateFrame.xml
-# `ClassTrainerListScrollFrameTemplate`, which the on-demand macro, trainer, trade skill and craft
-# addons inherit.
+# `ClassTrainerListScrollFrameTemplate`, which on-demand addons inherit.
 Interface\FrameXML\ClassTrainerFrameTemplates.xml
-# Ours: the `/errors` script error log, which 1.12 lacks, and benilla's slash commands, added to
-# `SlashCmdList` at load.
+# Ours: the `/errors` script error log and our slash commands.
 ScriptLogFrame.xml
 Interface\FrameXML\HelpFrame.xml
 Interface\FrameXML\CinematicFrame.xml
 Interface\FrameXML\TabardFrame.xml
 Interface\FrameXML\TutorialFrame.xml
-# Ours: the ESC game menu. Deviation: its ladder is the 1.15 Era client's. Last: it wraps
-# `ToggleGameMenu`, `IsOptionFrameOpen` and `UpdateMicroButtons`, captured at load, to count
-# `BenillaOptionsFrame`.
+# Ours: the ESC game menu. Last: it wraps `ToggleGameMenu`, `IsOptionFrameOpen` and
+# `UpdateMicroButtons` to count `BenillaOptionsFrame`.
 GameMenuFrame.xml
diff --git a/crates/benilla-app/examples/addon_harness.rs b/crates/benilla-app/examples/addon_harness.rs
index 1d75164c..21f18626 100644
--- a/crates/benilla-app/examples/addon_harness.rs
+++ b/crates/benilla-app/examples/addon_harness.rs
@@ -1,41 +1,22 @@
-//! `addon_harness` — load a folder of addons, one per VM, and print what happened.
+//! `addon_harness`: load a folder of addons, one per VM, and print what happened.
 //!
 //! ```text
-//! cargo run -q -p benilla-app --example addon_harness -- <folder> [--verbose] [--why <substr>] [--deep [n]] [--status <file>] [--diff <file>]
-//!   or: ... -- <folder> --probe <Name> [--eval <lua> | --mouse <x>,<y> | --tick <secs>]...   (one addon, then
-//!       ask its VM — the steps run in the order given, so a read can be taken with the cursor
-//!       parked somewhere the addon cares about)
+//! cargo run -q -p benilla-app --example addon_harness -- <folder> [--verbose] [--why <substr>]
+//!     [--deep [n]] [--status <file>] [--diff <file>]
+//!   or: ... -- <folder> --probe <Name> [--eval <lua> | --mouse <x>,<y> | --tick <secs>]...
+//!     (one addon, then ask its VM; the steps run in the order given)
 //! ```
 //!
-//! The instrument decision 1188 phase 6 asks for: *"which addons work" is a number that can be
-//! re-read on any day*. The mechanics, and what the numbers are and are not worth, are in
-//! [`benilla_app::addon_harness`]'s module doc — read it before quoting anything from here.
-//!
-//! **Expect a long tail and do not chase 100 %** (1188's own instruction). The report is a
-//! distribution, not a pass/fail: a handful of addons will always want features we have not built.
+//! Measures which addons work, as a number that can be re-read any day; what the numbers are
+//! worth is in [`benilla_app::addon_harness`]'s module doc. Expect a long tail: the report is a
+//! distribution, not a pass/fail.
 use benilla_app::addon_harness;
 
-/// How much traceback `--why` prints per addon. Two lines gave the message and mlua's first
-/// frame, which was enough to RANK a row and never enough to FIND one: chasing a `SetTexture`
-/// failure to its call site needed the frames below it, and the addon/file/line only appear there.
+/// How much traceback `--why` prints per addon: the addon, file and line sit below the first frame.
 const WHY_TRACEBACK_LINES: usize = 8;
 
-/// Print a ranked demand table — and **say what was dropped**.
-///
-/// Every one of these lists is a queue, and each was printed as a silent top-N. A silent cut reads
-/// as "that is the whole list", and this arc has one expensive instance of exactly that: the
-/// "a reference frame we do not build" class was swept, found clean, and recorded CLOSED — while
-/// `ShapeshiftBarLeft` sat below the cut with two addons behind it, and stayed there until an
-/// addon's first error named it (1219's class, first regions). The sweep was honest; the list it
-/// swept was not complete and did not say so.
-///
-/// So the tail is now stated: how many rows, and how many addon-mentions, were not shown. The
-/// caller keeps its own `take` — this only refuses to hide the remainder.
-///
-/// `--deep [n]` overrides every caller's `take` (see [`DEEP`]). 1242 made the cut VISIBLE and
-/// rejected raising it — an unreadable report helps nobody. But "visible" only tells a sweep that
-/// rows exist; it still cannot read them, and `--why` opens one name at a time, which is no way to
-/// walk 1930 of them. So the cut stays where it is for the report, and a sweep asks for the rest.
+/// Print a ranked table, stating how many rows and addon-mentions fell below the cut; `--deep [n]`
+/// overrides every caller's `take` (see [`DEEP`]).
 fn ranked(rows: Vec<(String, usize)>, take: usize) {
     let take = DEEP.get().copied().flatten().unwrap_or(take);
     let total = rows.len();
@@ -52,10 +33,8 @@ fn ranked(rows: Vec<(String, usize)>, take: usize) {
     }
 }
 
-/// One of the probe's two error lists, printed with its count — and printed even when EMPTY.
-///
-/// A silent absence and a list nobody asked for read identically, and the whole point of a probe
-/// run is to tell "this addon loaded clean and died in a handler" from "it never loaded at all".
+/// One of the probe's two error lists with its count, printed even when empty, so "loaded clean
+/// and died in a handler" reads apart from "never loaded".
 fn report_lines(label: &str, lines: &[String]) {
     println!("  {label}: {}", lines.len());
     for line in lines {
@@ -65,18 +44,14 @@ fn report_lines(label: &str, lines: &[String]) {
     }
 }
 
-/// The `--deep` override, set once in `main`. `Some(n)` shows `n` rows of EVERY ranked list;
-/// `--deep` with no number means all of them. Absent, each list keeps the `take` its caller chose.
+/// The `--deep` override, set once in `main`: `Some(n)` shows `n` rows of every ranked list,
+/// a bare `--deep` all of them; absent, each list keeps its caller's `take`.
 static DEEP: std::sync::OnceLock<Option<usize>> = std::sync::OnceLock::new();
 
-/// The row's frame names, bounded for the line and **saying so when it bounds**.
-///
-/// `RenderReport::frames` carries every named frame now; the cap that used to live in the
-/// collection (and silently evicted the very names a test asserted on) lives here instead.
+/// The row's frame names, bounded for the line and saying so when it bounds.
 fn render_frames(frames: &[String]) -> String {
     use benilla_app::addon_harness::render::MAX_NAMED_FRAMES;
-    // `--deep` opens THIS bound too. It was added for the ranked tables, but the principle is one
-    // principle: a bounded view is fine, a bounded view you cannot open is not.
+    // `--deep` opens this bound too.
     let cap = DEEP.get().copied().flatten().unwrap_or(MAX_NAMED_FRAMES);
     if frames.len() <= cap {
         return frames.join(",");
@@ -84,19 +59,10 @@ fn render_frames(frames: &[String]) -> String {
     format!("{},+{} more", frames[..cap].join(","), frames.len() - cap)
 }
 
-/// Our `_G` against the captured 1.12 `_G` — decision 1189's diff, re-runnable.
-///
-/// 1189 did this once, by hand, and its finding was that **a superset is not free**: 1.12 addons
-/// branch on presence (`if SomeName then`), so a name we publish that the reference does not have
-/// can route an addon down a path the real client never takes. That makes BOTH directions of this
-/// diff interesting, and the extra-names side the one nothing else in this harness can see — every
-/// other ranking here is demand-driven, so it can only ever report what an addon *asked* for.
-///
-/// The reference side is `reference/1.12-globals.tsv`, generated from a live reference capture.
-/// `lod` rows are the twelve LoadOnDemand `Blizzard_*` addons' names, unioned in by 1200 because a
-/// live dump misses them unless the player opened those windows; they are counted separately rather
-/// than silently folded in, since "absent from us" means something different for a window nobody
-/// opened.
+/// Our `_G` against the captured 1.12 `_G` (`reference/1.12-globals.tsv`). Both directions
+/// matter: 1.12 addons feature-test with `if SomeName then`, so a name we publish that the
+/// reference lacks can send an addon down a path the real client never takes. `lod` rows are the
+/// twelve LoadOnDemand `Blizzard_*` addons' names, counted apart as a live capture misses them.
 fn surface_report(deep: bool, dump_path: Option<String>) {
     let tsv = concat!(
         env!("CARGO_MANIFEST_DIR"),
@@ -120,10 +86,7 @@ fn surface_report(deep: bool, dump_path: Option<String>) {
     let ours: std::collections::BTreeMap<String, String> =
         addon_harness::surface().into_iter().collect();
 
-    // `--surface-dump <file>` writes our raw `_G` as `name<TAB>type`, the same shape the reference
-    // TSV has, so the two can be joined by anything. The printed report answers the questions I
-    // thought to ask; a sweep two sessions from now will have different ones, and re-deriving our
-    // side by scraping a human-readable report is exactly how a measurement quietly goes wrong.
+    // `--surface-dump <file>` writes our raw `_G` as `name<TAB>type`, the reference TSV's shape.
     if let Some(path) = dump_path {
         let body: String = ours
             .iter()
@@ -141,8 +104,7 @@ fn surface_report(deep: bool, dump_path: Option<String>) {
     println!("  reference names : {}", reference.len());
     println!("  ours            : {}", ours.len());
 
-    // Absent from us, by the reference's own type — a function we lack is a different problem from
-    // a string we lack, and `lod` is a third thing again.
+    // Absent from us, by the reference's own type.
     let mut missing_by_kind: std::collections::BTreeMap<&str, Vec<&str>> = Default::default();
     for (name, kind) in &reference {
         if !ours.contains_key(name) {
@@ -157,15 +119,8 @@ fn surface_report(deep: bool, dump_path: Option<String>) {
         println!("    {:<10} {}", kind, names.len());
     }
 
-    // The direction 1189 cared about and nothing else here can see.
-    //
-    // **Split by OUR type, because the total on its own misleads.** Most of these are `table` — the
-    // frame and region names our own FrameXML publishes, which differ from Blizzard's simply
-    // because our XML is our own reimplementation and names its pieces itself. That is not the
-    // hazard 1189 described. The hazard is a **function**: `if SomeApiName then` is how a 1.12
-    // addon feature-tests, and a verb we publish that the client never had can route it down a path
-    // the real client never takes. So the function row is the one to read first, and the one a
-    // future landing should be able to drive to zero.
+    // Published by us and absent from 1.12, split by our type: most are `table`, our FrameXML's
+    // own frame names; a `function` is the hazard, since addons feature-test on it.
     let extra: Vec<(&str, &str)> = ours
         .iter()
         .filter(|(n, _)| !reference.contains_key(n.as_str()))
@@ -187,12 +142,8 @@ fn surface_report(deep: bool, dump_path: Option<String>) {
         };
         println!("    {:<10} {}{}", kind, names.len(), note);
     }
-    // Functions in full even without --deep: it is the row that matters and it has to be readable.
-    //
-    // Split again on the `Benilla` prefix, which is the difference between a name that CAN collide
-    // with an addon's expectations and one that cannot. Nothing in the 1.12 corpus feature-tests
-    // `BenillaPaperDollSlot_OnClick`; our own namespace is safe by construction, and leaving 443 of those
-    // in the list would bury the ones that are not.
+    // Functions in full even without --deep, split on the `Benilla` prefix: no 1.12 addon
+    // feature-tests our own namespace.
     if let Some(fns) = extra_by_kind.get("function") {
         let (ours_ns, unprefixed): (Vec<&&str>, Vec<&&str>) = fns
             .iter()
@@ -246,8 +197,7 @@ fn main() {
     };
     let rest: Vec<String> = args.collect();
 
-    // `--surface` — decision 1189's comparison, made re-runnable. It needs no corpus, so it is
-    // handled before the root is used for anything.
+    // `--surface` needs no corpus, so it is handled before the root is used.
     if root == "--surface" || rest.iter().any(|a| a == "--surface") {
         let dump_path = rest
             .iter()
@@ -259,34 +209,15 @@ fn main() {
     }
 
     let verbose = rest.iter().any(|a| a == "--verbose");
-    // `--why <substring>` — the addons behind one row, with their verbatim errors. The
-    // ranked table collapses quoted names by design (1193); this is the read-back, and two of this
-    // arc's decisions came from doing it by hand (1206, 1210). It matches the normalised row AND
-    // the raw text, so `--why <a row>` and `--why <a name>` both work — the second did not, and
-    // that is what made the whole widget-method class unreadable here.
-    //
-    // It reads back through the **method demand tables** too, which nothing did: every ranking here
-    // is built by scanning, three of them have opened with fiction (1210, 1218, 1227), and the rule
-    // that came out of that is to open the corpus line before quoting a row. Verifying the per-kind
-    // table's own first head cost a temporary debug print and a second corpus run for want of this.
+    // `--why <substring>`: the addons behind one row, with their verbatim errors. Matches the
+    // normalised row and the raw text, and reads back through the method demand tables too.
     let why = rest
         .iter()
         .position(|a| a == "--why")
         .and_then(|i| rest.get(i + 1))
         .cloned();
-    // `--status` writes the per-addon ok/fail roster; `--diff <file>` compares against one.
-    //
-    // **The instrument this survey was missing, and the reason it is missing is instructive.**
-    // Every column here is a TOTAL, so a landing that fixes one addon and breaks another reads as
-    // a clean zero — indistinguishable from a change that did nothing. That happened: the shadow
-    // accessors (`7824c154`) gained FuBar_NavigatorFu and held the column at 107, so something was
-    // lost, and there was no way to ask what. Every "zero delta" recorded in this arc before now
-    // could have been hiding the same swap.
-    // `--status <file>` WRITES the roster, rather than printing it. It printed at first, and the
-    // obvious `--status > roster.txt` then captured the whole report — 53 report lines parsed as
-    // addon rows, because `--diff` splits on the last space and almost anything satisfies that. An
-    // instrument whose output needs a `grep` incantation to be usable is one that will be used
-    // wrong; the file is the artefact, so the tool writes the file.
+    // `--status <file>` writes the per-addon ok/fail roster to a file; `--diff <file>` compares
+    // against one, since a total hides a fix and a break that cancel out.
     let status = rest
         .iter()
         .position(|a| a == "--status")
@@ -306,10 +237,8 @@ fn main() {
     let _ = DEEP.set(deep);
     let root = std::path::PathBuf::from(root);
 
-    // `--together` — the whole folder in ONE VM, the control for the survey's one-VM-per-addon
-    // bound. Not a column and not a headline (see `addon_harness::together`'s header for what it
-    // cannot answer); `--diff <a survey roster>` names the rows the bound is costing, which is
-    // the question it exists for.
+    // `--together`: the whole folder in one VM, the control for the survey's one-VM-per-addon
+    // bound; `--diff <a survey roster>` names the rows the bound costs.
     if rest.iter().any(|a| a == "--together") {
         let rows = addon_harness::together::survey_together(&root);
         if rows.is_empty() {
@@ -335,9 +264,8 @@ fn main() {
             rows.len(),
             rows.len() - raised.len() - wobbly.len()
         );
-        // Named, never folded into either count: Lua hashes a table key by its pointer, so a
-        // registry keyed by objects walks in a different order every process (see the module
-        // doc). A row that raises in some runs and not others is that showing through.
+        // Named apart: Lua hashes a table key by its pointer, so a registry keyed by objects walks
+        // in a different order every process.
         println!(
             "  ORDER-SENSITIVE — raised in some runs, not all ({}):",
             wobbly.len()
@@ -352,8 +280,7 @@ fn main() {
             );
         }
         if let Some(path) = &diff {
-            // The survey's roster, read back: `ok` there and clean here is agreement; `fail`
-            // there and clean here is the bound, priced.
+            // `fail` in the survey and clean here is the bound, priced.
             let prior: std::collections::BTreeMap<String, bool> = std::fs::read_to_string(path)
                 .unwrap_or_default()
                 .lines()
@@ -363,8 +290,7 @@ fn main() {
             let mut freed: Vec<&str> = Vec::new();
             let mut only_together: Vec<&str> = Vec::new();
             for r in &rows {
-                // Only the rows that are the same in every run are compared — an order-sensitive
-                // one belongs to neither list, which is the whole point of naming it separately.
+                // Only rows the same in every run are compared.
                 match (prior.get(&r.name), r.raised_in) {
                     (Some(false), 0) => freed.push(&r.name),
                     (Some(true), n) if n == r.runs => only_together.push(&r.name),
@@ -396,19 +322,14 @@ fn main() {
         return;
     }
 
-    // `--probe <Name> [--eval <lua> ...]` — ONE addon, loaded the way the survey loads it, then
-    // asked. Handled before the survey because it is not one: it prints no column and it is not a
-    // measurement (an eval can mutate the VM), so mixing the two outputs would invite a probe
-    // number into a record. See `addon_harness::probe`'s header for what it is worth and where it
-    // deliberately stops — session start, before the render and use probes touch anything.
+    // `--probe <Name> [--eval <lua> ...]`: one addon, loaded as the survey loads it, then asked.
+    // Not a measurement (an eval can mutate the VM), so it prints no column.
     if let Some(name) = rest
         .iter()
         .position(|a| a == "--probe")
         .and_then(|i| rest.get(i + 1))
     {
-        // `--eval <lua>` and `--mouse <x>,<y>` are ONE ordered list, not two: a read taken
-        // before the cursor arrived and one taken after answer different questions, and which is
-        // which is the order the caller typed.
+        // `--eval`, `--tick` and `--mouse` are one ordered list, run in the order typed.
         let steps: Vec<addon_harness::probe::Step> = rest
             .iter()
             .enumerate()
@@ -467,9 +388,7 @@ fn main() {
         .count();
 
     println!("\n{} addon(s) under {}", reports.len(), root.display());
-    // Which VM the survey ran against. Without an install there is no GlobalStrings.lua, ~5,000
-    // globals are missing, and every number below is worse for a reason that has nothing to do
-    // with the client — say so rather than letting two machines' numbers be compared in silence.
+    // Without an install there is no GlobalStrings.lua and about 5,000 globals are missing.
     println!(
         "  VM: the stock 1.12 FrameXML off the player's chain + a seated session{}\n",
         if addon_harness::seated_with_global_strings() {
@@ -478,10 +397,7 @@ fn main() {
             "  ** no install found: GlobalStrings absent, these numbers are NOT comparable **"
         }
     );
-    // The tree these numbers came from. Two runs are comparable only if this matches: in a dev
-    // build `assets/ui` is read from the SOURCE TREE, so anything else editing the checkout moves
-    // the headline with no rebuild. Quoting a delta across two different digests is how a wrong
-    // attribution got into a decision record (1209).
+    // Two runs compare only at the same digest: a dev build reads `assets/ui` from the source tree.
     println!(
         "  FrameXML digest                    : {}",
         addon_harness::framexml_digest()
@@ -490,11 +406,8 @@ fn main() {
         "  loaded without a single load error : {loaded}/{}",
         reports.len()
     );
-    // **The reconciliation line, printed always** (decision 2155). `loaded` counts what RAISED;
-    // a manifest entry naming a file the package does not contain is not that — the reference logs
-    // `Couldn't open %s` and carries on — and it used to be counted here. Every past record's
-    // figure was the stricter one, so the stricter one is printed beside the honest one rather
-    // than left for a reader to reconstruct: two numbers cannot be silently confused, one can.
+    // `loaded` counts what raised; a manifest entry naming a missing file is not that (the
+    // reference logs `Couldn't open %s` and carries on), so the stricter count prints beside it.
     let strict = reports.iter().filter(|r| r.errors.is_empty()).count();
     println!(
         "      (…{} of those name a file their own package does not contain, which the reference \
@@ -507,11 +420,8 @@ fn main() {
         reports.len()
     );
     println!("  with a dependency not installed    : {blocked}");
-    // The stricter column, and the one that answers what the survey is really asking. Every other
-    // number here is LOAD-time; this one drives the client's own session start
-    // (ADDON_LOADED -> VARIABLES_LOADED -> PLAYER_LOGIN -> PLAYER_ENTERING_WORLD, then a second of
-    // ticks) and reports what the addon's HANDLERS raised. Four decision records in this arc end
-    // with "the headline cannot see this"; this is the number that can.
+    // The session column: drives ADDON_LOADED -> VARIABLES_LOADED -> PLAYER_LOGIN ->
+    // PLAYER_ENTERING_WORLD and a second of ticks, and reports what the handlers raised.
     let survived = reports
         .iter()
         .filter(|r| r.loaded && r.session_errors.is_empty())
@@ -520,9 +430,7 @@ fn main() {
         "  ...and survived a session start    : {survived}/{}",
         reports.len()
     );
-    // The UI-probe column: of those, how many survive having their OVERRIDES actually invoked.
-    // The director found this blind spot by playing the game — an addon that replaces
-    // `ToggleBackpack` and is never called looked identical to one that works.
+    // The UI-probe column: of those, how many survive having their overrides invoked.
     let probed = reports
         .iter()
         .filter(|r| r.loaded && r.session_errors.is_empty() && r.probe_errors.is_empty())
@@ -531,10 +439,8 @@ fn main() {
         "  ...and survived a UI probe         : {probed}/{}",
         reports.len()
     );
-    // **The render column** — the only one here that asks whether anything was DRAWN. Every number
-    // above it asks whether something raised, and the director's Bagnon report raised nothing at
-    // all: a window with a title, a gold line and no bag slots, scoring a clean pass on all four.
-    // `addon_harness::render`'s header is the design and its honest bounds.
+    // The render column, the only one that asks whether anything was drawn; see
+    // `addon_harness::render`'s header.
     let drew = reports
         .iter()
         .filter(|r| r.render.drew() != addon_harness::Drew::Nothing)
@@ -554,9 +460,7 @@ fn main() {
             .count(),
     );
     println!("      of those: {own} drew a window of their own, {overlay} painted onto ours");
-    // The actionable list, and the reason this column exists: an addon that loads clean, survives a
-    // session start AND a UI probe, and still puts nothing on screen. Nothing else here can name
-    // one. Bagnon was on this list.
+    // Addons that load, survive a session start and a UI probe, and still draw nothing.
     let silent: Vec<&str> = reports
         .iter()
         .filter(|r| {
@@ -568,23 +472,8 @@ fn main() {
         .map(|r| r.name.as_str())
         .collect();
     if !silent.is_empty() {
-        // **This list is a QUESTION, not a defect list, and the header used to say otherwise.**
-        //
-        // It read "read this list first", which invites treating every row as a bug. Most are not.
-        // The survey seats a player and an empty world: no buffs, no target, no combat, no cursor
-        // over an item. An addon with nothing to draw in that world draws nothing CORRECTLY — and
-        // that is most of this list. Measured on the vanilla corpus rather than assumed: of 48 rows
-        // checked, 6 ship no XML at all (pure libraries — Ace, LibStub, Stubby, DevTools), and of
-        // the rest the buff bars (CT_BuffMod 29 frames, ElkBuffBar 3, neither hidden at birth) are
-        // waiting on buffs that a fresh login does not have either.
-        //
-        // What the row DOES mean is "nothing here can be ruled out by the other four columns" —
-        // which is worth printing, and is not the same as "broken".
-        //
-        // The instrument change that would sharpen it is a POPULATED session fixture (a buff, a
-        // target, a live cooldown) so that "nothing to draw" and "failed to draw" stop sharing a
-        // row. Named here rather than done, because seating content changes the fixture for all
-        // 218 addons and deserves its own controlled A/B.
+        // A question, not a defect list: the survey seats a player in an empty world, so an addon
+        // with nothing to draw there (a buff bar, a pure library) draws nothing correctly.
         println!(
             "\n  DREW NOTHING, and clean on every other column ({}) — a QUESTION, not a defect\n  \
              list: the seated world has one buff, one target and one running cooldown, so an addon\n  \
@@ -596,14 +485,8 @@ fn main() {
         }
     }
 
-    // **The use column** — the only one here that TOUCHES anything. Every number above it asks
-    // whether something ran or appeared; the director drew the line by hovering Bagnon's freshly
-    // drawn bag slots and getting a wall of `attempt to call global
-    // 'ContainerFrameItemButton_OnEnter'` while all five columns above scored it a pass.
-    //
-    // Printed as THREE numbers, never one, because "nothing raised" and "nothing was touched" are
-    // different answers and a probe that quietly drove zero targets reporting "clean" is this
-    // instrument's own oldest failure mode (`addon_harness::use_probe`'s header).
+    // The use column, the only one that touches anything: three numbers, because "nothing
+    // raised" and "nothing was touched" are different answers (`addon_harness::use_probe`).
     let (survived_use, raised_use, untouched_use) = (
         reports
             .iter()
@@ -635,8 +518,7 @@ fn main() {
          frames each addon painted itself)",
         addon_harness::MAX_USE_TARGETS
     );
-    // The list this column exists to be able to print: an addon whose UI is fully on screen and
-    // falls over the moment anyone uses it.
+    // Addons whose UI is fully on screen and falls over the moment anyone uses it.
     let inert: Vec<String> = reports
         .iter()
         .filter(|r| r.used.verdict() == addon_harness::Used::Raised)
@@ -684,14 +566,8 @@ fn main() {
         }
     }
 
-    // **What was WARNED about, ranked** — the channel that reached nobody until 2135. It is
-    // printed after the error rankings and before the distribution on purpose: these are not
-    // blockers (nothing raised, the addon is running), so they must not outrank a row somebody is
-    // stuck on — but they are the only column that can see an addon quietly getting the wrong
-    // thing, which is the class `render` was added for and reaches later.
-    //
-    // Ranked by how many ADDONS hit each row, not by total occurrences: a warning one addon fires
-    // in an OnUpdate would otherwise bury one that fifty addons hit once.
+    // What was warned about: not blockers, so after the error rankings, ranked by how many addons
+    // hit each row so one noisy OnUpdate does not bury a warning fifty addons hit once.
     let mut warned: std::collections::BTreeMap<String, usize> = Default::default();
     for r in &reports {
         let mut seen: std::collections::BTreeSet<String> = Default::default();
@@ -709,10 +585,7 @@ fn main() {
         println!(
             "\n  what was WARNED about ({addons} addons raised at least one, by addon count):"
         );
-        // Through `ranked`, not a bare `take(12)`: this list is a queue like every other one here,
-        // and a silent cut reads as "that is the whole list" (1242's rule, which this block was
-        // written outside of). It cost a measurement — asking the corpus how many `SetPoint`
-        // targets fail to resolve, the answer sat below the cut and the column read zero.
+        // Through `ranked`, so the cut is stated.
         ranked(rows, 12);
     }
 
@@ -733,11 +606,9 @@ fn main() {
         println!("    {label:>5}  {n:>4}  {}", "#".repeat(n.min(60)));
     }
 
-    // **WHOSE package is incomplete** — printed immediately before the ranked blockers, because it
-    // is the line that stops a session hunting for a client bug that is not one. A `.toc` entry
-    // whose file the addon does not ship is the ADDON's defect, and the reference client's
-    // behaviour there is what ours already does: log `Couldn't open %s` and carry on (`0x6edaa0`).
-    // Nothing is subtracted from the headline — 1213 — so both readings stay available.
+    // Whose package is incomplete: a `.toc` entry whose file the addon does not ship is the
+    // addon's defect, and the reference logs `Couldn't open %s` and carries on (`0x6edaa0`).
+    // Nothing is subtracted from the headline.
     let own: Vec<&addon_harness::AddonReport> = reports
         .iter()
         .filter(|r| !r.absent_own_files.is_empty())
@@ -746,10 +617,7 @@ fn main() {
         .iter()
         .filter(|r| !r.absent_foreign_files.is_empty())
         .collect();
-    // **"the WHOLE reason" is a claim, and it is checked before it is printed.** An addon can be
-    // short a file AND raise somewhere else; saying "this is why it fails" on the strength of
-    // `!loaded` alone would be the same overclaim this column exists to stop. It holds only when
-    // the absent entries account for every load error the addon has.
+    // "The whole reason" holds only when the absent entries account for every load error.
     let sole_cause = |r: &addon_harness::AddonReport| {
         !r.loaded && r.errors.len() == r.absent_own_files.len() + r.absent_foreign_files.len()
     };
@@ -797,63 +665,43 @@ fn main() {
         );
     }
 
-    // What actually STOPPED them — the ranked first error. Read this before the demand list: a
-    // wall 60 addons hit is worth more than a verb 60 addons would like (decision 1193).
+    // What stopped them: the ranked first error.
     println!("\n  what stopped them (addons whose FIRST load error was each):");
     for (err, count) in addon_harness::blockers(&reports).into_iter().take(12) {
         println!("    {count:>4}  {err}");
     }
 
-    // Templates an addon names in `CreateFrame(..., "Template")` that we have never declared
-    // (decision 1203). Its own list because it is invisible to every other number here: an
-    // unresolved template raises no load error, so the addon scores as a pass and paints nothing.
+    // Templates named in `CreateFrame(..., "Template")` that we never declared: an unresolved
+    // template raises no load error, so the addon passes and paints nothing.
     let templates = addon_harness::template_demand(&reports);
     if !templates.is_empty() {
         println!("\n  most-wanted missing TEMPLATES (addons naming each in CreateFrame):");
         ranked(templates, 12);
     }
 
-    // The same question over the OTHER axis, and the one that actually moves the headline: a
-    // template named in an addon's own XML `inherits=`. Unlike the list above this failure is
-    // usually LOUD — the element's `<OnLoad>` fires at load and its first line is normally
-    // `getglobal(this:GetName().."Text")` — which is why transcribing the reference's shared kit
-    // was worth twelve addons while the CreateFrame list predicted none of them. Printed second
-    // and separately because merging the two would hide exactly that difference.
+    // Templates named in an addon's own XML `inherits=`: usually loud, since the element's
+    // `<OnLoad>` fires at load. Kept apart from the list above.
     let inherits = addon_harness::inherits_demand(&reports);
     if !inherits.is_empty() {
         println!("\n  most-wanted missing TEMPLATES (addons naming each in an XML inherits=):");
         ranked(inherits, 12);
     }
 
-    // Frames and tables, ranked separately: a missing function is a Rust verb to write, a missing
-    // frame is FrameXML to transcribe, and the two queues go to different people. The scan was
-    // blind to this whole shape until 2026-08-11 — a window 86 addons reach scored 0.
+    // Frames and tables, ranked separately: a missing function is a Rust verb, a missing frame is
+    // FrameXML.
     let tables = addon_harness::table_demand(&reports);
     if !tables.is_empty() {
         println!("\n  most-wanted missing FRAMES/TABLES (addons indexing each):");
         ranked(tables, 16);
     }
 
-    // **Widget METHODS** — the third queue, and the one this report was blind to while the arc
-    // spent a day building exactly these (GetTexture, SetShadowColor, SetNonSpaceWrap, GetBackdrop
-    // all landed within hours). A method is not a global and not an indexed table, so neither list
-    // above could ever hold one; the only trace a missing method left was an error row reading
-    // `attempt to call method 'X' (a nil value)`, with the name collapsed away by the very
-    // normalisation that makes the row readable.
-    //
-    // Resolved against the live `__index` dispatcher, not a name list — so a whole *kind* left
-    // unwired shows up here as loudly as a verb never written. It over-reports (a scanner cannot
-    // type the receiver of a `:` call); `AddonReport::missing_methods` states exactly how far, and
-    // `--why <name>` now reads any row back by name.
+    // Widget methods: neither a global nor an indexed table, so only these tables see them.
+    // Resolved against the live `__index` dispatcher; it over-reports, since a scanner cannot type
+    // a `:` call's receiver (`AddonReport::missing_methods`).
     let methods = addon_harness::method_demand(&reports);
     if !methods.is_empty() {
-        // The header states BOTH limits, because the list read as a build queue and is not one
-        // (decision 1240). It counts addons that NAME the verb, which is neither "addons blocked
-        // by it" nor "call sites": its top three were once RegisterTabCompletion/IsModule/
-        // IsModuleActive — AceConsole-2.0's and AceAddon-2.0's own methods on their own objects,
-        // one library file replicated into 56 and 38 addons — and its fourth, EnableKeyboard, was
-        // a real absent Frame verb that was blocking none of its 8, every one of which died
-        // earlier and elsewhere.
+        // It counts addons that name the verb, neither addons blocked by it nor call sites: a
+        // library replicated into many addons inflates a row.
         println!("\n  most-wanted missing METHODS — addons that NAME each as obj:Name(), and");
         println!("  no widget answers. NOT a blocker list and NOT a build queue:");
         println!("    · a big number is usually ONE library file replicated (1207/1210), and");
@@ -864,13 +712,9 @@ fn main() {
         ranked(methods, 16);
     }
 
-    // **Per KIND** — the question the table above structurally cannot ask. It resolves a name
-    // against every probe and stops at the first hit, so a verb wired to one class and forgotten on
-    // its sibling comes back present: `MessageFrame:AddMessage` scored zero for as long as it
-    // existed, answered by the ScrollingMessageFrame probe, while three corpus addons had
-    // `UIErrorsFrame:AddMessage` as their FIRST load error (decision 1228). These rows are the
-    // call sites whose receiver the survey could TYPE — from a `CreateFrame("Kind", …)` local, or
-    // from the kind our own arena publishes that name as — asked against that kind alone.
+    // Per kind: rows whose receiver the survey could type, from a `CreateFrame("Kind", …)` local
+    // or our arena's kind for that name, asked against that kind alone, so a verb wired to one
+    // class and missing on its sibling shows.
     let by_kind = addon_harness::kind_method_demand(&reports);
     if !by_kind.is_empty() {
         println!(
@@ -880,11 +724,8 @@ fn main() {
         ranked(by_kind, 16);
     }
 
-    // ...and the residue: a receiver nothing could type, on a name whose answer DEPENDS on the
-    // kind. An upper bound, printed rather than swallowed — resolving these against the whole probe
-    // set and calling them present is the exact blindness above. The length of this table measures
-    // the ATTRIBUTOR, not the widget surface: every receiver shape the scan learns to type moves
-    // rows out of it.
+    // Receivers nothing could type, on a name whose answer depends on the kind: an upper bound
+    // that shrinks as the scan learns to type receivers.
     let ambiguous = addon_harness::ambiguous_method_demand(&reports);
     if !ambiguous.is_empty() {
         println!(
@@ -896,11 +737,8 @@ fn main() {
         ranked(ambiguous, 12);
     }
 
-    // The other half of the same scan, and never merged into it: methods addons call **behind a
-    // feature test**, so nobody is stuck on one. `if sliderFrame.SetTopLevel then` is Dewdrop's,
-    // and `SetTopLevel` is a real 1.12 widget method 60 corpus addons quietly do without. Building
-    // one of these fixes no error and improves N addons' behaviour, which is a different decision
-    // from the list above — so it is a different table.
+    // Methods addons call behind a feature test (`if sliderFrame.SetTopLevel then`): nobody is
+    // stuck on one, so they are a separate table.
     let optional = addon_harness::optional_method_demand(&reports);
     if !optional.is_empty() {
         println!("\n  ...and methods they FEATURE-TEST and work around (not blockers):");
@@ -912,12 +750,8 @@ fn main() {
 
     if let Some(pattern) = &why {
         let hits = addon_harness::blocked_by(&reports, pattern);
-        // "first error" was a lie in two directions and both cost this instrument a whole class:
-        // the match ran against the NORMALISED row only, where every quoted name is already `'X'`,
-        // so `--why GetBackdrop` answered `(none)` while an addon was dying on exactly that; and
-        // it read only the first error, while a session start keeps firing handlers after one dies.
-        // A row with no `#` is the addon's first error — the one the tables above rank — so the
-        // index-less rows still count out to the ranked row exactly.
+        // Matches the raw text as well as the normalised row, over every error, not just the first.
+        // A row with no `#` is the addon's first error, the one the tables above rank.
         println!(
             "\n  errors matching {pattern:?} ({}) — a row without a '#' is the FIRST error, i.e. \
              the one the tables above rank:",
@@ -925,10 +759,8 @@ fn main() {
         );
         for (name, err) in &hits {
             println!("    {name}");
-            // Two lines, not one. The first is the message; the SECOND is mlua's first traceback
-            // frame, and for the row this instrument is most often pointed at that frame is the
-            // whole answer — `in local '(for generator)'` is what tells a generic-for
-            // (decision 1202) apart from any other call of a table value.
+            // The message, then mlua's traceback frames; the first tells a generic-for
+            // (`in local '(for generator)'`) apart from any other call of a table value.
             for line in err.lines().take(WHY_TRACEBACK_LINES) {
                 println!("        {}", line.trim());
             }
@@ -939,10 +771,7 @@ fn main() {
                  normalised row does either)"
             );
         }
-        // ...and the same question of the DEMAND tables, which no read-back reached until now.
-        // Every ranking above is a scan, and this arc has found fiction at the top of three of
-        // them (1210, 1218, 1227); the rule that came out of it is "open the corpus line before
-        // quoting the row", and this is what makes that one command instead of a code edit.
+        // ...and the same question of the method demand tables.
         let rows = addon_harness::method_rows_matching(&reports, pattern);
         println!(
             "\n  method-table rows matching {pattern:?} ({}) — which addons carry the row, and \
@@ -955,11 +784,8 @@ fn main() {
         if rows.is_empty() {
             println!("    (none — no addon's method tables contain that text)");
         }
-        // ...and WHICH ADDONS each demand ranking counted. The rankings print a number per name and
-        // nothing could ask what it was made of, so a row could disagree with the corpus and no
-        // command would say so. It happened: `GetChannelList` ranked 4 while exactly ONE addon's
-        // source names it, and finding that took a hand-rolled grep across a symlinked corpus.
-        // A count you cannot open is a claim, not a measurement.
+        // ...and which addons each demand ranking counted, so a row can be checked against the
+        // corpus.
         for (label, rows) in [
             (
                 "globals",
@@ -997,25 +823,21 @@ fn main() {
                 .map(u32::to_string)
                 .collect::<Vec<_>>()
                 .join(",");
-            // The SESSION column, not just the load one. `loaded` means "no LOAD errors" and
-            // always has (1213); an addon that loads clean and dies in its PLAYER_LOGIN handler
-            // read as a pass here, which is the exact overstatement 1213 measured at four to one.
-            // "does this addon actually work" is the two columns together, so print both.
+            // The session column beside the load one: an addon can load clean and die in its
+            // PLAYER_LOGIN handler.
             let session = match r.session_errors.first() {
                 None if r.loaded => "session=ok".to_string(),
                 None => "session=-".to_string(),
                 Some(e) => format!("session: {}", e.lines().next().unwrap_or(e)),
             };
-            // The render verdict, with the quad count and the frames it was charged to — the row
-            // that turns "this addon is fine" into "this addon is fine AND you can see it".
+            // The render verdict, with the quad count and the frames it was charged to.
             let drew = format!(
                 "drew={}({})",
                 r.render.drew().word(),
                 r.render.own_quads + r.render.overlay_quads
             );
-            // The use verdict, ALWAYS with the target count beside it — a bare `used=ok` would be
-            // unreadable exactly where it matters, because it reads the same whether the probe
-            // drove eight of the addon's frames or none at all.
+            // The use verdict, always with the target count: `used=ok` reads the same whether the
+            // probe drove eight frames or none.
             let used = format!(
                 "used={}({}/{})",
                 r.used.verdict().word(),
@@ -1034,9 +856,8 @@ fn main() {
             );
         }
     }
-    // The per-addon roster: `<name> ok|fail`, sorted, one per line — a shape `--diff` can read back
-    // and a human can eyeball. `ok` is the SESSION column (loaded AND no session error), because
-    // that is the one this arc treats as "works" (1213).
+    // The per-addon roster: `<name> ok|fail`, sorted, one per line. `ok` is the session column
+    // (loaded and no session error).
     let roster: Vec<(String, bool)> = {
         let mut v: Vec<(String, bool)> = reports
             .iter()
@@ -1063,19 +884,9 @@ fn main() {
     if let Some(path) = &diff {
         match std::fs::read_to_string(path) {
             Ok(text) => {
-                // **The digest gate.** `--status` stamps the roster's header with the FrameXML
-                // digest it was taken at, and a delta is only attributable when this run's matches:
-                // in a dev build `assets/ui` is read from the SOURCE TREE, so any *other* session
-                // landing an interface change moves the headline under you with no rebuild of
-                // yours. The stamp was written for this and then never checked, so the check was
-                // the reader's to remember — which is exactly how 1209's wrong attribution reached
-                // a decision record, and it nearly happened again on the run that added this gate
-                // (a rebase pulled in a neighbour's interface change between the baseline and the
-                // measurement).
-                //
-                // So this REFUSES rather than warns. A warning printed beside a `net +0` still
-                // leaves the number sitting there to be quoted; withholding the number is the only
-                // form that cannot be misread.
+                // The digest gate: a delta is attributable only when this run's FrameXML digest
+                // matches the roster's, since a dev build reads `assets/ui` from the source tree.
+                // It refuses rather than warns, so a mismatched number is never printed.
                 let base_digest = text
                     .lines()
                     .find(|l| l.trim_start().starts_with("# per-addon status"))
@@ -1122,8 +933,7 @@ fn main() {
                     gained.len(),
                     lost.len()
                 );
-                // Both lists always print, even when empty. A silent "lost" section would let a
-                // regression read as a clean run, which is the fault this whole mode exists for.
+                // Both lists always print, even when empty.
                 for (label, list) in [("GAINED", &gained), ("LOST", &lost)] {
                     println!("    {label} ({}):", list.len());
                     for n in list.iter() {
diff --git a/crates/benilla-app/src/addon_harness/mod.rs b/crates/benilla-app/src/addon_harness/mod.rs
index 58ae5d98..456055ff 100644
--- a/crates/benilla-app/src/addon_harness/mod.rs
+++ b/crates/benilla-app/src/addon_harness/mod.rs
@@ -1,66 +1,17 @@
-//! **The addon corpus harness** (1188 phase 6) — load every addon in a folder, one at a time, and
-//! report what happened as numbers that can be re-read on any day.
+//! The addon corpus harness: load every addon in a folder, one at a time, and report what each did
+//! as numbers.
 //!
-//! 1188 asks for a harness rather than a one-off, and the reason is in its own closing line:
-//! *"that harness plus phase 0's coverage script are this arc's instruments, and they are what
-//! make the remaining work a list instead of an argument."* `scripts/api-coverage.sh` answers
-//! *what surface do we present*; this answers *what does that surface actually carry*.
+//! Each addon is surveyed in a fresh [`UiScript`] seated with the whole in-game interface (the
+//! stock FrameXML off the player's chain plus the files still ours), so one addon's failure cannot
+//! be charged to another. The 1.12 client loads every addon into one Lua state, so a library
+//! embedded in any addon is global to those after it; here it is not, and an addon relying on a
+//! sibling's copy fails. Every count is therefore a floor
+//! ([`dependency_tests::a_sibling_addons_embedded_library_is_invisible`]).
 //!
-//! ## One VM per addon, deliberately
-//!
-//! Every addon is surveyed in a **fresh** [`UiScript`] with the whole in-game interface loaded
-//! underneath it — the stock 1.12 FrameXML off the player's chain plus the few files still ours
-//! (1751), exactly what a live session seats.
-//! That costs a full UI load per addon and buys the only property that makes the report readable:
-//! one addon's failure cannot be another's. Loading them all into one VM means the first addon to
-//! leave a global in a bad state gets blamed for the next twenty, and the distribution 1188 asks
-//! for stops meaning anything.
-//!
-//! **What one VM per addon costs, stated because it bounds every number here.** The real client
-//! loads every addon into ONE Lua state, so a library embedded in *any* addon's `Libs\` is global
-//! for every addon that loads after it. Here it is not. An addon that ships no libraries and relies
-//! on a sibling's copy — `FuBar_CustomMenuFu` ships one Lua file and calls
-//! `AceLibrary("Tablet-2.0")`, which no addon it can reach provides — fails in this survey and
-//! would work in a real session. **So the headline is a floor, not an estimate**, and a
-//! `Cannot find a library instance of X` row is this limitation before it is a gap of ours. The
-//! isolation is still the right trade (see above: one addon's failure must not be another's); it
-//! is the reporting that has to say so. Pinned by
-//! [`dependency_tests::a_sibling_addons_embedded_library_is_invisible`].
-//!
-//! The FrameXML underneath is not optional either — an addon calls `UIDropDownMenu_Initialize` and
-//! `GameTooltip_SetDefaultAnchor` as readily as it calls `UnitName`, and roughly half of what looks
-//! like "the WoW API" is Lua the client ships (decision 1190: 1,100 engine functions vs 1,075
-//! FrameXML ones). Surveying against a bare VM would report most of FrameXML as missing.
-//!
-//! ## What "missing" means here, and what it does not
-//!
-//! [`AddonReport::missing_globals`] is a **static** read: the names the addon's own source calls
-//! like functions, minus everything the loaded VM has, minus what the addon defines itself. It is
-//! deliberately not a runtime trace, because an addon's API calls overwhelmingly happen in
-//! handlers that only fire in a live session — a load-time trace would report almost nothing and
-//! read as success.
-//!
-//! The cost of that choice, stated rather than hidden: it over-reports. A name reached only on a
-//! path the addon never takes still counts, and a name built at runtime (`getglobal("Unit"..verb)`)
-//! is invisible to it. So the list is a **prioritisation signal**, exactly like
-//! `api-coverage.sh`'s — read the ranked aggregate, not any single row, and never quote it as a
-//! pass rate.
-//!
-//! There are **three** such lists and they rank three different queues, never merged (1207):
-//! [`AddonReport::missing_globals`] is functions to write in Rust, [`AddonReport::missing_tables`]
-//! is FrameXML to transcribe, and [`AddonReport::missing_methods`] is widget bindings. The third
-//! arrived last and had been invisible the longest — a method is not a global, so nothing here
-//! could rank one, and the error row that carried them collapsed the name away.
-//!
-//! The method queue then turned out to be **two** questions, not one (decision 1228):
-//! `missing_methods` asks whether *any* widget answers a name, which is blind to a verb wired to
-//! one class and forgotten on its sibling — `MessageFrame:AddMessage` scored zero on it while three
-//! corpus addons had exactly that call as their first load error.
-//! [`AddonReport::kind_missing_methods`] asks the question the addon asked, by typing the receiver
-//! of the call site; [`AddonReport::ambiguous_methods`] is what the typing could not reach, printed
-//! rather than swallowed.
-//!
-//! ## Running it
+//! The missing-name lists are static reads of the addon's source minus what the VM and the addon
+//! define: they over-report (an untaken branch counts) and miss names built at runtime, so read the
+//! ranked aggregate, never one row. Each ranks its own queue: functions to write, FrameXML to
+//! transcribe, widget methods no kind has, methods the receiver's kind lacks, and untyped calls.
 //!
 //! ```text
 //! cargo run -q -p benilla-app --example addon_harness -- <folder of addons>
@@ -72,24 +23,18 @@ use std::path::{Path, PathBuf};
 use benilla_ui::script::UiScript;
 use benilla_ui::toc::Toc;
 
-/// The read-back — *why is this global nil?* One addon, loaded the way the survey loads it, then
-/// arbitrary Lua evaluated against the VM that is left standing. A debugger, not a column; its
-/// header says what it is worth and where it deliberately stops.
+/// Why a global is nil: one addon loaded as the survey loads it, then Lua evaluated against the VM.
 pub mod probe;
 #[cfg(test)]
 mod probe_tests;
-/// The render column — the one question every column here was blind to: *did this addon put
-/// anything on screen?* Its own module because it is its own concern (and this file is well over
-/// the size budget); its header is the design and the honest bounds.
+/// The render column: did the addon put anything on screen.
 pub mod render;
 #[cfg(test)]
 mod render_tests;
-/// The control for this module's one-VM-per-addon bound — the whole folder in ONE VM, the way a
-/// real client runs it. Its header says what it can and cannot answer.
+/// The control for the one-VM-per-addon bound: the whole folder in one VM, as the 1.12 client runs
+/// it.
 pub mod together;
-/// The use column — *does the thing it drew survive being **touched**?* Its own module for the
-/// same two reasons `render` is; its header is the design, the bounds and the four-deep history
-/// that made it necessary.
+/// The use column: does what the addon drew survive being touched.
 mod use_probe;
 #[cfg(test)]
 mod use_probe_tests;
@@ -100,273 +45,83 @@ use use_probe::measure_use;
 pub use use_probe::{UseReport, Used, MAX_USE_TARGETS};
 
 /// What one addon did.
-///
-/// `Default` is derived so the two error returns in [`survey_one`] and the unit tests can name only
-/// the fields they mean — a report grew from nine fields to fourteen over this arc, and a
-/// positional wall of `Vec::new()`s is where a new column silently gets filled with the wrong one.
 #[derive(Debug, Clone, Default)]
 pub struct AddonReport {
     pub name: String,
-    /// `## Interface`, as written. 1.12 is `11200`; the corpus is full of older values, and we
-    /// deliberately do not refuse them (decision 1191 §6).
+    /// `## Interface`, as written (1.12 is `11200`); older values are not refused.
     pub interface: Vec<u32>,
-    /// **Did anything in its manifest RAISE, fail to parse, or drop a frame?**
-    ///
-    /// Not "did every entry resolve" — that is [`Self::absent_own_files`] and
-    /// [`Self::absent_foreign_files`], and it is a different question because the reference
-    /// answers it differently: a manifest line naming no file is `"Couldn't open %s"` in
-    /// FrameXML.log and the walk carries straight on (`0x6edaa0`). An addon shipping an incomplete
-    /// zip *works* on a real client, so counting it here made the survey say the opposite of the
-    /// truth about 24 addons — FuBar itself among them, on two locale files it does not ship.
-    ///
-    /// **[`Self::errors`] is unchanged and still carries those rows verbatim** (1213), so every
-    /// number in every past record is still readable off it; what changed, deliberately and with
-    /// decision 2155 behind it, is which of them this flag counts. The report prints both.
+    /// No manifest entry raised, failed to parse or dropped a frame. An entry naming no file does
+    /// not count: the 1.12 client logs `Couldn't open %s` and carries on (`0x6edaa0`); its row
+    /// stays in [`Self::errors`].
     pub loaded: bool,
     /// Load errors, verbatim, tagged by file.
     pub errors: Vec<String>,
-    /// **Manifest entries the addon's own package does not contain.** Already counted in
-    /// [`Self::errors`], and deliberately not removed from it — 1213's rule for the fifth time:
-    /// a new question gets a new column, because silently shrinking `errors` would move `loaded`
-    /// and make every number in every past decision record incomparable.
-    ///
-    /// The question it asks that no other column can: **whose fault is this row?** Five of the
-    /// corpus's failures are one addon family shipping a `.toc` that lists files it does not
-    /// contain — `DPSMate_CureDisease.toc` names eight files and the folder holds six, because the
-    /// three `*Received*` ones were split into a sibling addon and the manifest was never updated.
-    /// The client is behaving correctly there (the reference logs `Couldn't open %s` and carries
-    /// on, which is what our loader does), and a headline that cannot say so invites a session to
-    /// go hunting for a bug that is not ours. The director's own AtlasLoot copy is the same shape.
+    /// Manifest entries the addon's own package does not contain, also in [`Self::errors`]: the
+    /// package's fault, since the 1.12 client logs `Couldn't open %s` and carries on, as ours does.
     pub absent_own_files: Vec<String>,
-    /// **Manifest entries resolving OUTSIDE the addon's folder, into one that is not installed** —
-    /// resolved paths, not the raw entry, because the `..` collapse is the interesting half.
-    ///
-    /// A different question from [`Self::absent_own_files`] and kept apart from it: this addon's
-    /// package is fine, it wants a neighbour. The corpus's two are Auctioneer and BeanCounter
-    /// reaching `..\Blizzard_AuctionUI\Blizzard_AuctionUITemplates.xml` — which the real client
-    /// **RESOLVES** (`0x6ede10` collapses the `..`), because there the file layer can see
-    /// `Blizzard_AuctionUI` inside `patch.MPQ`. Ours reads the AddOns directory only, so it
-    /// misses. That one IS ours, and the split is what makes it visible instead of averaging
-    /// with the row above.
+    /// Manifest entries resolving outside the addon's folder, as resolved paths (the `..` collapsed
+    /// as `0x6ede10` does), that neither the AddOns tree nor the patch chain holds: the addon wants
+    /// a neighbour that is not installed.
     pub absent_foreign_files: Vec<String>,
-    /// Names it calls that the VM does not have — see the module doc on what this is worth.
+    /// Names it calls that the VM does not have (see the module doc).
     pub missing_globals: Vec<String>,
     /// Dependencies named in its `.toc` that are not in the folder.
     pub missing_deps: Vec<String>,
-    /// Templates it names in `CreateFrame(kind, name, parent, "Template")` that the VM has never
-    /// declared (decision 1203).
-    ///
-    /// **A blind spot by construction until it was measured.** `CreateFrame`'s fourth argument was
-    /// ignored outright until today; now it is honoured, and the survey's headline did not move at
-    /// all — because an unresolved template produces *no load error*, so `loaded` cannot see it and
-    /// `missing_globals` does not either (a template is not a global). An addon gets a bare frame,
-    /// loads clean, and paints nothing.
-    ///
-    /// Static, like `missing_globals`, and with the same caveat: read the ranked aggregate.
+    /// Templates it names in `CreateFrame(kind, name, parent, "Template")` that the VM never
+    /// declared. An unresolved one raises nothing: the addon gets a bare frame and paints nothing.
     pub missing_templates: Vec<String>,
-    /// Templates it names in an XML `inherits=` that the VM has never declared.
-    ///
-    /// [`Self::missing_templates`]'s twin, added because the first was measuring the wrong axis.
-    /// 1203 built `CreateFrame`'s fourth argument and ranked what it could not resolve; the
-    /// transcription that followed then moved the headline by twelve addons, and **not one of
-    /// those twelve came through `CreateFrame`** — every one failed on an `inherits=` in its own
-    /// XML. The two are ranked separately rather than merged because they behave differently:
-    /// an unresolved `CreateFrame` template is silent (1203 §2), while an unresolved `inherits=`
-    /// is usually loud, because the very next line of the element's `<OnLoad>` is
-    /// `getglobal(this:GetName().."Text")` and the loader fires that `<OnLoad>` immediately.
-    ///
-    /// Same static caveat, plus one of its own: `inherits=` spans two namespaces — a `<FontString
-    /// inherits="GameFontNormal">` names a FONT — so a name registered as either is resolved.
+    /// Templates it names in an XML `inherits=` that the VM never declared. A name registered as a
+    /// template or a font resolves, since `<FontString inherits="GameFontNormal">` names a font.
     pub missing_inherits: Vec<String>,
-    /// Errors raised **after** this addon's own files loaded, while the session start was driven —
-    /// its own `ADDON_LOADED` → `VARIABLES_LOADED` → `PLAYER_LOGIN` → `PLAYER_ENTERING_WORLD`,
-    /// then a few ticks to drain `OnUpdate` and anything scheduled. Every DEPENDENCY's
-    /// `ADDON_LOADED` is already behind this point: each fires beside its own addon's files, where
-    /// `0x51f5ad` fires it ([`load_dependencies`], 2166).
-    ///
-    /// **This is the survey's answer to its own oldest blind spot.** Every number beside it is
-    /// load-time, and this arc has now written the same sentence into four decision records —
-    /// 1203, 1205, 1211 and the state-texture pass all end with *"the headline cannot see this"*,
-    /// because an addon whose file scope runs clean scores as a pass no matter what its handlers
-    /// do. The handlers are where addons actually live: an `OnEvent` that fires on `PLAYER_LOGIN`
-    /// is the single most common shape in the corpus.
-    ///
-    /// Names it INDEXES (`Foo.bar`, `Foo:baz()`) that the VM does not have — frames and tables,
+    /// Names it indexes (`Foo.bar`, `Foo:baz()`) that the VM does not have: frames and tables,
     /// where [`Self::missing_globals`] is functions.
-    ///
-    /// Two lists because the two queues go to different places: a missing function is a verb to
-    /// write in Rust, a missing frame or table is FrameXML to transcribe. And ranking them together
-    /// would mis-rank, which is 1207's lesson.
-    ///
-    /// **The scan was blind to this shape until 2026-08-11.** `ColorPickerFrame` — a window
-    /// **86 corpus addons reach** — scored exactly 0 on the most-wanted list, because the corpus
-    /// spells it `ColorPickerFrame.func` and `ColorPickerFrame:SetColorRGB`, never `ColorPickerFrame(`.
-    /// The same blindness hid `GameTooltip`, `WorldFrame`, `ChatFrame1` and every other FrameXML
-    /// frame global. Third instrument correction of this arc, after 1209 and 1210.
     pub missing_tables: Vec<String>,
-    /// Names it calls as `obj:Name(...)` that **no widget we ship provides** — the widget-method
-    /// class, which nothing else here could see.
-    ///
-    /// [`Self::missing_globals`] is functions and [`Self::missing_tables`] is frames; **a method is
-    /// neither, and never lands in either.** `BuffCheck2/BuffCheck2.lua:448` died on
-    /// `attempt to call method 'GetBackdrop' (a nil value)` while `GetBackdrop` scored exactly zero
-    /// on every ranking this harness printed — and the arc was working precisely this class by hand
-    /// at the time (`GetTexture`, `SetShadowColor`, `SetNonSpaceWrap`, `GetBackdrop` all landed
-    /// within hours of each other). Six corpus addons' FIRST error is this shape today, and the
-    /// ranked row that carries them reads `attempt to call method 'X' (a nil value)`: the name —
-    /// the only part anyone can act on — is exactly what the normalisation deletes.
-    ///
-    /// **Resolved by ASKING THE VM, never by a name list.** One instance of every `CreateFrame`
-    /// kind plus a Texture and a FontString are stood up and each wanted name is looked up through
-    /// the real `__index` dispatcher — the same path the addon's own call takes — so this cannot
-    /// drift from what we actually implement the way a hand-kept list would.
-    ///
-    /// **It resolves against ANY probe, so it is blind to a method on the WRONG kind** (decision
-    /// 1228), and it stays that way **on purpose**: this is the number four decision records quote,
-    /// and redefining it would make every one of them incomparable (1209). A name survives here
-    /// only if *no* widget answers it; a verb we implemented on one class and forgot on its sibling
-    /// resolves and scores zero. This doc once claimed the opposite — that an unwired
-    /// `<MessageFrame>` was exactly what the list would catch, with `AddMessage` topping the
-    /// ranking because of it — and the run underneath it never agreed: `AddMessage` sat at zero all
-    /// along, answered by `ScrollingMessageFrame`, while three addons died on
-    /// `UIErrorsFrame:AddMessage`.
-    ///
-    /// So this list ranks **verbs nobody has**; [`Self::kind_missing_methods`] ranks **kinds nobody
-    /// wired**, by typing the receiver of the call site instead of asking the probe set at large,
-    /// and [`Self::ambiguous_methods`] carries the residue it cannot type. Read all three; they are
-    /// three different jobs, and merging them would lose exactly the distinction that cost this
-    /// instrument a whole class.
-    ///
-    /// **It OVER-reports, deliberately**, and this is the field where that trade bites hardest: a
-    /// scanner cannot know the receiver of a `:` call, so every OO library method whose definition
-    /// is not in the addon's own source counts here too (the whole Ace2/FuBar `self:Foo()` family
-    /// when it is reached through a *dependency* rather than an embedded copy). What is subtracted
-    /// is what can be seen: names the addon's own files bind as `function T:N`, `function T.N`, and
-    /// `T.N = …`, and the same three read off every dependency the VM loaded under it. A method
-    /// bound as `T["N"] = …` cannot be subtracted at all — `strip_lua_noise` blanks the string
-    /// before the scan sees it — and that is stated rather than hidden.
-    ///
-    /// **The residue in the ranking's head is the one-VM limitation, not a gap of ours** — the same
-    /// bound the module doc already puts on `Cannot find a library instance of X`, showing up on a
-    /// new axis. `FuBar:RegisterPlugin` sits at 8 because eight addons call a library they never
-    /// declare, so nothing loads it for them; on the real client a sibling's copy is global. And
-    /// like every list here it counts a name on a branch the addon never takes:
-    /// `instance:RegisterTabCompletion` is 51 addons' copy of one AceConsole line guarded by
-    /// `elseif major == "AceTab-2.0"`, for a library no corpus addon ships. Read the ranked
-    /// aggregate, and read the row's call sites before building it (1214).
+    /// Names it calls as `obj:Name(...)` that no widget kind we ship answers, looked up through one
+    /// probe of every kind's live `__index`; a method on the wrong kind is
+    /// [`Self::kind_missing_methods`]. Over-reports: a `:` receiver is unknown, so a library method
+    /// not defined by the addon or its loaded dependencies counts, and a method bound as
+    /// `T["N"] = …` cannot be subtracted (`strip_lua_noise` blanks the string).
     pub missing_methods: Vec<String>,
-    /// Methods it calls **and feature-tests first** (`if f.SetTopLevel then f:SetTopLevel(1) end`)
-    /// that no widget we ship provides — [`Self::missing_methods`]'s other half, printed beside it
-    /// rather than folded into it.
-    ///
-    /// These are not blockers: the addon has already written the branch it takes without them, so
-    /// counting them in the ranking a session builds from would put a name nobody is stuck on above
-    /// one somebody is. But they are not nothing either — **`SetTopLevel` is a real 1.12 widget
-    /// method 60 corpus addons work around**, and implementing it silently improves every one of
-    /// them. Dropping the class outright is exactly the silent under-report this instrument keeps
-    /// being caught in; it gets its own row instead.
+    /// Methods it calls only after feature-testing them (`if f.SetTopLevel then … end`) that no
+    /// widget we ship provides: not blockers, so kept out of [`Self::missing_methods`].
     pub optional_methods: Vec<String>,
-    /// `Kind:Name (on …)` — a method called on a receiver this survey could **type**, that that
-    /// kind does not answer. [`Self::missing_methods`]'s answer to the bound 1228 recorded.
-    ///
-    /// `missing_methods` asks the probe set *"does ANY widget answer this name"*, and a verb we
-    /// implemented on one class and never wired to its sibling answers yes. That is not a corner
-    /// case: `MessageFrame:AddMessage` scored **zero** on that list for as long as it existed —
-    /// answered by the ScrollingMessageFrame probe — while `EasyCopy`, `QuestHistory` and
-    /// `QuestItem` all had `UIErrorsFrame:AddMessage` as their FIRST load error. This list asks the
-    /// question the addon actually asked: *does the kind it called it on answer it*.
-    ///
-    /// The row says which kinds do answer, because that is the difference between two jobs: `(on no
-    /// kind)` is a verb to write, `(on ScrollingMessageFrame)` is a verb we already wrote and
-    /// forgot to wire.
-    ///
-    /// **Bounded by the attributor, and only the attributor.** A receiver is typed when the file
-    /// binds it from a widget factory (`local f = CreateFrame("MessageFrame", …)`,
-    /// `f:CreateTexture()`) or when it is a **published name** whose kind the live arena knows
-    /// (`UIErrorsFrame` → `MessageFrame`, via [`UiScript::widget_kind`]). `self:Foo()`,
-    /// `this:Foo()`, `a.b:Foo()` and `getglobal(n):Foo()` are not typable and are reported in
-    /// [`Self::ambiguous_methods`] instead of being silently counted as fine.
+    /// `Kind:Name (on …)`: a method called on a receiver of known kind that the kind does not
+    /// answer, naming the kinds that do (`(on no kind)` when none). A receiver is typed when the
+    /// file binds it from a widget factory (`CreateFrame`, `f:CreateTexture()`) or it is a
+    /// published name the arena knows ([`UiScript::widget_kind`]); `self:`, `this:`, `a.b:` and
+    /// `getglobal(n):` receivers go to [`Self::ambiguous_methods`].
     pub kind_missing_methods: Vec<String>,
-    /// `Name (only on …)` — a name the addon calls on a receiver nothing could type, where the
-    /// answer **depends on the kind**: some widgets we ship answer it and some do not.
-    ///
-    /// The row this whole per-kind pass exists to stop swallowing. Before it, such a name resolved
-    /// against the probe set and vanished; now the reader is told the answer is conditional and on
-    /// what. It is an **upper bound on purpose** — the call may well be on one of the kinds that
-    /// does answer — and the honest way to read it is as a measure of how much the *attributor*
-    /// still cannot see: every receiver shape [`scan_receivers`] learns to type moves rows out of
-    /// here and into a real answer.
-    ///
-    /// A name **no** kind answers is not here — it is a plain miss and it is in
-    /// [`Self::missing_methods`].
+    /// `Name (only on …)`: a method called on an untyped receiver that some kinds we ship answer
+    /// and some do not. An upper bound on what [`scan_receivers`] cannot type; a name no kind
+    /// answers is in [`Self::missing_methods`].
     pub ambiguous_methods: Vec<String>,
-    /// Kept **separate from [`Self::loaded`] on purpose.** Folding these in would silently change
-    /// what the headline means and make every number in every past decision record incomparable
-    /// (1209's whole subject). `loaded` still means exactly "no LOAD errors"; this is a second,
-    /// stricter column beside it.
+    /// Errors raised after the addon's own files loaded, while the session start is driven: its
+    /// `ADDON_LOADED`, `VARIABLES_LOADED`, `PLAYER_LOGIN`, `PLAYER_ENTERING_WORLD`, then a few
+    /// ticks of `OnUpdate`. Each dependency's `ADDON_LOADED` already fired beside its own files,
+    /// where `0x51f5ad` fires it ([`load_dependencies`]). Kept apart from [`Self::loaded`], which
+    /// counts load errors.
     pub session_errors: Vec<String>,
-    /// What the addon's own UI OVERRIDES raised when actually invoked — see [`drive_ui_probe`].
-    ///
-    /// A NEW column beside `session_errors`, never folded into it (1213's rule): this asks a
-    /// different question, and redefining an existing number would make every past run
-    /// incomparable.
+    /// What the addon's UI overrides raised when invoked (see [`drive_ui_probe`]).
     pub probe_errors: Vec<String>,
-    /// **Warnings raised while this addon loaded and ran** — the engine's own non-fatal channel
-    /// (decision 2135), which nothing in this survey could see until it had one.
-    ///
-    /// A warning is the class of failure that *does not announce itself*: an `inherits=` argument
-    /// that was not a template name and got dropped, a `SetPoint` whose `relativeTo` did not
-    /// resolve and silently re-anchored, a `SetCVar` on a name nothing registered, a saved
-    /// variable that would not serialise, a loader note about a template of the wrong kind.
-    /// Nothing raises, so `errors`, `session_errors` and `probe_errors` are all blind to it, and
-    /// the addon scores a clean pass while doing the wrong thing. That is exactly the shape
-    /// `render` was added for — and this reaches the cases `render` cannot, because a warning
-    /// usually fires long before anything would have been drawn.
-    ///
-    /// A NEW column, never folded into another (1213's rule, again).
-    ///
-    /// **Read off the retained diagnostic log by `seq`, not off the per-frame drain**, so it
-    /// carries the host's loader warnings (which are recorded with their `<file>` prefix and never
-    /// touch the drain) as well as the engine's. One consequence of the log's dedupe is worth
-    /// stating: a warning whose exact text the FrameXML underneath already produced collapses onto
-    /// that older row and does not appear here. The corpus's warnings name the addon's own frames
-    /// and files, so this is rare rather than theoretical — but it means the column, like every
-    /// other one here, is a floor.
+    /// Warnings raised while the addon loaded and ran: failures that raise nothing, such as a
+    /// dropped `inherits=`, an unresolved `SetPoint` anchor or an unregistered `SetCVar`. Read off
+    /// the retained diagnostic log by `seq`, so loader warnings count too; a warning whose exact
+    /// text the FrameXML underneath already produced dedupes onto that row and is missed.
     pub warnings: Vec<String>,
-    /// **What it actually PUT ON SCREEN** — see [`render`], whose header is the design.
-    ///
-    /// The column every other one here was blind to. `loaded`, `session_errors` and `probe_errors`
-    /// all ask whether something *raised*; the director's Bagnon report raised nothing at all and
-    /// drew nothing either, and scored a clean pass on all three. A new column beside them,
-    /// never folded in — 1213's rule, for the third time.
+    /// What it put on screen (see [`render`]).
     pub render: RenderReport,
-    /// **What happened when the UI it drew was actually USED** — see [`use_probe`], whose header is
-    /// the design and the four-deep history behind it.
-    ///
-    /// [`Self::render`] closed "did anything appear"; this closes "is what appeared alive". The
-    /// director drew the line themselves: Bagnon draws sixteen bag slots and they are dead to the
-    /// touch — hovering one raised `attempt to call global 'ContainerFrameItemButton_OnEnter'` —
-    /// while `render` scored it a full pass, because a frame that paints and does nothing paints
-    /// exactly like one that works.
-    ///
-    /// A new column beside the others, never folded in — 1213's rule, for the fourth time. Read
-    /// [`UseReport::driven`] with every verdict: a clean row that touched nothing is
-    /// [`Used::Untouched`], which is not a pass.
+    /// What happened when the UI it drew was used (see [`use_probe`]). A row that touched nothing
+    /// is [`Used::Untouched`], which is not a pass.
     pub used: UseReport,
 }
 
-/// Survey every addon folder under `root`.
-///
-/// `root` is an AddOns folder — one subfolder per addon, each with a `<Name>.toc`. Anything else
-/// is skipped in silence, exactly as discovery does, because a stray `Backup/` is the common case.
+/// Survey every addon folder under `root`, an AddOns folder; a subfolder without a `<Name>.toc` is
+/// skipped, as discovery skips it.
 pub fn survey(root: &Path) -> Vec<AddonReport> {
     let (names, installed, registry) = corpus(root);
 
-    // Folder → the method names its source DEFINES, memoised across the whole survey.
-    //
-    // A dependency's definitions have to be read once per *folder*, not once per dependent: the
-    // corpus's library folders are declared by dozens of addons each (83 declare `FuBar`), and
-    // re-scanning `FuBar`'s source 83 times is the survey's runtime for nothing.
+    // Folder -> the method names its source defines, memoised: one library folder is a dependency
+    // of dozens of addons.
     let mut defined_methods: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
     names
         .iter()
@@ -374,13 +129,9 @@ pub fn survey(root: &Path) -> Vec<AddonReport> {
         .collect()
 }
 
-/// **The corpus as every VM must see it** — the folders that carry a manifest, the case-folded
-/// installed set dependency resolution consults, and the AddOn registry each VM is seated with.
-///
-/// Its own function because [`probe`] needs the IDENTICAL environment for a single addon, and a
-/// probe built against a registry of one would answer a different question from the row it exists
-/// to explain (see [`probe`]'s header). The installed set is a property of the FOLDER, never of
-/// the selection.
+/// The corpus every VM sees: the folders with a manifest, the case-folded installed set, and the
+/// AddOn registry. [`probe`] needs the identical environment, so the installed set belongs to the
+/// folder, never the selection.
 fn corpus(
     root: &Path,
 ) -> (
@@ -396,30 +147,15 @@ fn corpus(
         .filter_map(|e| e.file_name().to_str().map(str::to_owned))
         .filter(|n| manifest_path(root, n).is_some())
         .collect();
-    // **The live walk's order, not a second opinion.** This used to be a bare `names.sort()`,
-    // a private copy of the ordering `ui_script::addons` decides — so the instrument could
-    // measure a walk the client does not perform. It calls the one definition now, which is what
-    // makes a `--together` row about shared-library provenance mean anything.
+    // The live walk's order, from the one definition `ui_script::addons` uses.
     crate::ui_script::addons::sort_by_directory_order(&mut names);
 
     let installed: BTreeSet<String> = names.iter().map(|n| n.to_ascii_lowercase()).collect();
 
-    // THE ADDON REGISTRY, built once and seated into every VM below.
-    //
-    // Until this existed the survey never called `register_addons` at all, so every VM ran with an
-    // EMPTY registry: `GetNumAddOns()` answered 0 and `GetAddOnInfo(...)` answered nothing, for all
-    // 218. That is a state the real client cannot produce — the same fault as 1193 (dependencies
-    // unloaded) and 1212 (`OptionalDeps` unwalked), and it hid the whole AddOn API from the survey.
-    //
-    // The cost was not theoretical. AceAddon and AceLibrary — the two most replicated files in the
-    // corpus — find their dependencies with `local name, _, _, enabled, loadable =
-    // GetAddOnInfo(major)`, and against an empty registry every one of those took the "nothing is
-    // installed" path. It is also why fixing `GetAddOnInfo`'s slot 4 (`4666b708`) moved the
-    // headline by exactly zero: the instrument could not see the verb at all.
-    //
-    // Every addon is registered ENABLED, which is the survey's own premise — it asks what an addon
-    // does when the player has it on. `loaded` stays false: the flag means "already loaded in this
-    // session", and each VM loads exactly one addon plus its declared dependencies.
+    // The AddOn registry, seated into every VM: without it `GetNumAddOns()` answers 0 and
+    // `GetAddOnInfo` nothing, and AceAddon and AceLibrary find their dependencies through
+    // `GetAddOnInfo`. Every addon is registered enabled; `loaded` stays false, since each VM loads
+    // one addon and its dependencies.
     let registry: Vec<benilla_ui::script::AddOnInfo> = names
         .iter()
         .filter_map(|n| {
@@ -433,23 +169,9 @@ fn corpus(
     (names, installed, registry)
 }
 
-/// The method names one addon folder's source **defines** — `function T:N`, `function T.N`,
-/// `T.N = …` — memoised by folder.
-///
-/// This is the method-side answer to a question `known` already answers for globals. `known` is
-/// read off the VM *after* the dependency chain has run, so a global a dependency defines is
-/// correctly not missing; there is no equivalent read for methods, because a method lives on an
-/// object the survey cannot name, so the source is the only available proxy.
-///
-/// **Skipping this made the first widget-method ranking useless**, and in the most instructive way:
-/// seven of its top eleven rows were `FuBar:RegisterPlugin`, `FuBar:GetNumPanels`,
-/// `FuBar:IsChangingProfile` and their siblings, at 75-78 addons each. Every one is
-/// `function FuBar:<Name>` in the **`FuBar` addon's own source** — a dependency 83 corpus addons
-/// declare, which `load_dependencies` duly loads into their VM. The methods exist at runtime; only
-/// the scanner could not see them, because it read the dependent's folder and stopped. Under them,
-/// at 61 and 60, sat `SetDesaturated` and `SetTopLevel` — two widget methods we genuinely do not
-/// have. That is 1210's lesson a third time: a ranking built by grepping source is worth exactly
-/// what its subtractions are worth.
+/// The method names one addon folder's source defines (`function T:N`, `function T.N`, `T.N = …`),
+/// memoised by folder. A method lives on an object the survey cannot name, so its dependencies'
+/// source stands in for the VM read `known` does for globals.
 fn methods_defined_by<'a>(
     root: &Path,
     folder: &str,
@@ -472,8 +194,8 @@ fn methods_defined_by<'a>(
     &memo[folder]
 }
 
-/// `<root>/<name>/<name>.toc`, matched case-insensitively — a real 1.12 addon may ship
-/// `MyAddon/myaddon.toc`, and on a case-sensitive filesystem an exact probe would not find it.
+/// `<root>/<name>/<name>.toc`, matched case-insensitively: a 1.12 addon may ship
+/// `MyAddon/myaddon.toc`.
 fn manifest_path(root: &Path, name: &str) -> Option<PathBuf> {
     let want = format!("{name}.toc");
     std::fs::read_dir(root.join(name))
@@ -487,10 +209,8 @@ fn manifest_path(root: &Path, name: &str) -> Option<PathBuf> {
         .map(|e| e.path())
 }
 
-/// The per-addon VM-instruction bound (see its use in [`survey_one`]) — the ONE number, shared
-/// with the live client's world-entry arming (decision 1306) so the corpus measurement behind it
-/// (heaviest legitimate addon 4M, 214 of 218 under 1M) cannot drift apart from the bound players
-/// actually run under.
+/// The per-addon VM-instruction bound, shared with the live client's world-entry arming (the
+/// heaviest corpus addon runs 4M, 214 of 218 under 1M).
 const ADDON_INSTRUCTION_BUDGET: u64 = crate::ui_script::addons::LOAD_INSTRUCTION_BUDGET;
 
 fn survey_one(
@@ -507,9 +227,7 @@ fn survey_one(
             ..Default::default()
         };
     };
-    // Decoded, not `read_to_string`'d: five of the corpus's 218 manifests are cp1252 and would
-    // otherwise parse as an empty `.toc` — an addon with no files and no dependencies, which reads
-    // as a clean pass (decision 1193).
+    // Decoded, not `read_to_string`: some manifests are cp1252 and would parse as an empty `.toc`.
     let toc = Toc::parse(&benilla_ui::source::decode(
         &std::fs::read(&toc_path).unwrap_or_default(),
     ));
@@ -520,7 +238,7 @@ fn survey_one(
         .map(str::to_owned)
         .collect();
 
-    // A VM with our whole interface under it — see the module doc on why per-addon and why loaded.
+    // A VM with our whole interface under it (see the module doc).
     let mut script = match UiScript::new() {
         Ok(s) => s,
         Err(e) => {
@@ -533,40 +251,19 @@ fn survey_one(
             }
         }
     };
-    // **A time bound, so one non-terminating addon cannot take the whole survey with it.**
-    //
-    // 1247 met the failure this exists for: `date("*t")` returned a string where Lua returns a
-    // table, so an addon's `while` never ended and the 218-addon run simply stopped finishing —
-    // no roster to diff, no column to compare, no error row to read, and the cause found by
-    // bisecting the corpus BY HAND. A wrong number is recoverable; an instrument that does not
-    // return is not.
-    //
-    // The budget is MEASURED, not guessed. Across the corpus at the time of writing, 214 of 218
-    // addons execute fewer than 1M VM instructions in a whole survey (the counter's resolution);
-    // the heaviest legitimate one is Enchantrix at 4M, then FuBar_CTRaid and BigWigs at 1M. So
-    // this is ~50x the heaviest real addon — far enough out that a fixture growing new seats
-    // cannot drift into it, and near enough that a runaway reports in about a second.
+    // A time bound, so one non-terminating addon cannot stall the survey: about 50x the heaviest
+    // corpus addon (Enchantrix, 4M instructions), so a runaway reports in about a second.
     script.set_instruction_budget(ADDON_INSTRUCTION_BUDGET);
     script.set_screen_size(1024.0, 768.0);
-    // Before anything runs: the AddOn API must answer for the whole installed set, not for nothing.
-    // The **saved-variable** roots are `None` — a survey must never read or write the director's
-    // real ones (the same reason `drive_session_start` is not `finish_ui_load`, 1213 §4). The
-    // ADDONS root is not one of those and is passed in full (decision 2102): without it every
-    // `LoadAddOn("<a folder addon>")` answered `MISSING`, which is a state the real client cannot
-    // produce and is exactly the 1193/1212 fault one level up — `/msbt`'s
-    // `UIParentLoadAddOn("MikScrollingBattleTextOptions")` is the shape it hides.
+    // The AddOn API answers for the whole installed set before anything runs. The saved-variable
+    // roots are `None`, so a survey never reads or writes a player's; the AddOns root is passed, so
+    // `LoadAddOn("<folder addon>")` does not answer `MISSING`.
     script.register_addons(registry.to_vec(), Some(root.to_path_buf()), None, None);
     seat_a_session(&mut script);
     let _ = crate::ui_script::load_default_ui(&script);
-    // The addon's DEPENDENCIES, first and recursively — `AddOn_Load 0x51f240`'s own first two
-    // steps (1191 §2, byte-verified). Surveying an addon without them is surveying a state the
-    // real client never presents: `FuBar_Aspect` declares `## Dependencies: Ace, FuBar` and opens
-    // with `ace:LoadTranslation(...)`, so in isolation it fails on a global its dependency was
-    // always going to define. Fifteen corpus addons failed that way, on us rather than on
-    // themselves.
-    //
-    // Loaded BEFORE `globals_of` below, so a name a dependency provides does not also count as a
-    // missing global — the same double-count the FrameXML-underneath decision avoided.
+    // The addon's dependencies, first and recursively, as `AddOn_Load` (`0x51f240`) does in its
+    // first two steps. Loaded before `globals_of` below, so a name a dependency provides is not
+    // missing.
     let mut dep_loads: Vec<LoadedDep> = Vec::new();
     load_dependencies(
         &mut script,
@@ -578,43 +275,31 @@ fn survey_one(
     );
     let dep_order: Vec<String> = dep_loads.into_iter().map(|d| d.name).collect();
     let known = globals_of(&script);
-    // The METHODS the dependency chain defines, gathered from the same folders whose files were
-    // just loaded above. `known` covers their globals because the VM actually ran them; a method
-    // has no such read (it lives on an object the survey cannot name), so its source stands in.
+    // The methods the dependency chain defines, read from its source (a method has no VM read).
     let dep_methods: BTreeSet<String> = dep_order
         .iter()
         .flat_map(|d| methods_defined_by(root, d, defined_methods).clone())
         .collect();
 
-    // THE RENDER BASELINE — every widget that exists before this addon has run a single line.
-    // Everything that appears after it was created by this addon (or by a handler of its own that
-    // it installed), which is what makes the render column an attribution rather than a guess.
-    // Taken here, after the dependency chain, so a library's frames are not charged to its
-    // consumer — the same rule `load_dependencies` applies to errors.
+    // The render baseline: every widget that exists before this addon runs, taken after the
+    // dependency chain so a library's frames are not charged to its consumer.
     let baseline = RenderBaseline::of(&script);
-    // THE WARNING MARK, taken at the same seam and for the same reason: everything the FrameXML
-    // underneath and this addon's dependency chain warned about is already behind us, so what
-    // follows is this addon's (decision 2135). `seq` is monotonic and never reused, which is what
-    // makes a high-water mark a valid cut of a log that also evicts and dedupes.
+    // The warning mark, taken at the same seam: `seq` is monotonic and never reused, so a
+    // high-water mark is a valid cut of a log that evicts and dedupes.
     let warn_mark = script.diagnostics().last().map_or(0, |d| d.seq);
 
     let files = load_addon_files(&script, root, name, &toc);
-    // The registry has to agree with the VM about what has loaded: the live walk stamps each
-    // addon at `0x51f5ad`'s position (`ui_script::addons`'s `mark_addon_loaded`, just before
-    // `ADDON_LOADED`), and without it here `IsAddOnLoaded` answered nil for an addon whose files
-    // had just run — and a LoadOnDemand dependent of it got `DEP_NOT_DEMAND_LOADED` rather than
-    // loading (decision 2102). The dependency chain stamped itself as it loaded, each one beside
-    // its own `ADDON_LOADED` (`load_dependencies`, 2166); only the surveyed addon is left.
+    // The live walk stamps each addon as loaded just before its `ADDON_LOADED` (`0x51f5ad`);
+    // without it `IsAddOnLoaded` answers nil and a LoadOnDemand dependent gets
+    // `DEP_NOT_DEMAND_LOADED`. The dependencies stamped themselves in `load_dependencies`.
     script.mark_addon_loaded(name);
     let wants = missing_calls(root, name, &toc, &known, &dep_methods);
-    // AFTER the addon's files: a template it declares in its OWN XML is registered by then, so it
-    // is not missing. The check asks the VM's live registry, not a name list.
+    // After the addon's files, so a template its own XML declares is registered.
     let missing_templates = missing_templates(&script, root, name, &toc);
     let missing_inherits = missing_inherits(&script, root, name, &toc);
     let session_errors = drive_session_start(&mut script, name, installed);
     let probe_errors = drive_ui_probe(&mut script);
-    // Everything filed since the mark, warnings only — the errors have their own columns and are
-    // retained under their own kinds.
+    // Warnings only; errors have their own columns.
     let warnings: Vec<String> = script
         .diagnostics()
         .into_iter()
@@ -629,28 +314,15 @@ fn survey_one(
             }
         })
         .collect();
-    // AFTER the UI probe and BEFORE the method oracle, and both halves of that are load-bearing.
-    // After, because the probe leaves the addon fully driven — and this pass re-OPENS what the
-    // probe's second toggle closed, which is why it is a separate probe rather than a read at the
-    // end of that one. Before, because `unresolved_widget_methods` stands up one frame of every
-    // kind: measuring after it would charge sixteen widgets of the harness's own to the addon and
-    // score every single row as having drawn.
+    // After the UI probe, because it reopens what the probe's second toggle closed; before the
+    // method oracle, whose probe widgets would otherwise count as this addon's drawing.
     let (render, painted) = measure_render(&mut script, &baseline);
-    // ...and then USE what it drew. Same seam, same two reasons: after every other column so no
-    // number beside it can be perturbed by input this probe invented, and before the method oracle
-    // so the sixteen widgets that pass stands up can never become an addon's input targets.
-    //
-    // It consumes `render`'s own attribution rather than re-deriving it — "which pixels are this
-    // addon's" is one question with one answer, and two instruments computing it separately is how
-    // they start disagreeing about the same addon.
+    // Then use what it drew: after every other column so the input it invents perturbs none, before
+    // the oracle so its widgets never become targets. It reuses `render`'s attribution.
     let used = measure_use(&mut script, &baseline, &painted);
-    // LAST, and the ordering is deliberate: standing up the probe widgets writes frames and one
-    // global into the VM, and this is the only point at which no addon code will ever observe
-    // them. Every other number above is therefore provably unperturbed by this list existing —
-    // which is what an instrument addition has to be able to claim (1225's measurement rule).
-    //
-    // ONE oracle call for both question sets and for the per-kind pass: it stood the whole probe
-    // set up twice for the same answer before, and the per-kind pass would have made that three.
+    // Last: the oracle writes probe frames and a global into the VM, and no addon code runs after
+    // this, so every number above is unperturbed by it. One oracle call serves both question sets
+    // and the per-kind pass.
     let asked: BTreeSet<String> = wants
         .wanted_methods
         .union(&wants.tested_methods)
@@ -659,9 +331,8 @@ fn survey_one(
     let oracle = widget_method_kinds(&script, &asked);
     let missing_methods = unresolved_from(&oracle, &wants.wanted_methods);
     let optional_methods = unresolved_from(&oracle, &wants.tested_methods);
-    // The receiver-typed half. It reads `widget_kind` off the same VM, which is the point: the kind
-    // an addon's call actually lands on is the kind OUR object graph publishes, not the one the
-    // reference documents.
+    // The receiver-typed half, read off the same VM: the kind a call lands on is the kind our
+    // object graph publishes.
     let (kind_missing_methods, ambiguous_methods) = per_kind_rows(&script, &oracle, &wants);
 
     AddonReport {
@@ -688,38 +359,15 @@ fn survey_one(
     }
 }
 
-/// **Which widget KINDS answer each wanted name** — the oracle every method table here is read off.
-/// `None` means the oracle could not run at all.
-///
-/// **It asks the live `__index` dispatcher, one probe per widget kind, rather than consulting a
-/// list of names.** The method tables live in the Lua registry behind a Rust `__index` and are not
-/// enumerable from Lua at all, so the alternative was a hand-kept mirror of every
-/// `REG_*_METHODS` table — a list that would go stale the first time a kind was added and would
-/// then report a whole widget class as missing, or (worse) as present. Standing up one of each
-/// kind and indexing it is the *same path the addon's own call takes*, which is the only oracle
-/// that cannot disagree with what we ship.
-///
-/// **The answer is kept PER KIND, and that is the change decision 1228 asked for.** It used to be
-/// collapsed to "did anything answer", which is why `MessageFrame:AddMessage` was unfindable while
-/// three addons died on it: the ScrollingMessageFrame probe answered the name, so the name was not
-/// missing, so there was no row anywhere in this report.
-///
-/// A kind `CreateFrame` refuses is skipped rather than fatal (`pcall`), so this survives a kind
-/// being renamed. But **an oracle that finds no probes at all reports everything as missing**, not
-/// nothing: a silent empty answer would read as "this addon calls no method we lack", which is the
-/// one thing this instrument exists to stop being invisible. `None` is how that travels; every
-/// reader of it ([`unresolved_from`], [`per_kind_rows`]) turns it into the loudest answer it can.
-/// Pinned by `the_method_oracle_fails_loudly_when_it_cannot_probe` and
-/// `the_per_kind_census_fails_loudly_when_it_cannot_probe`.
-///
-/// One call per addon serves all three tables. It used to be two (`wanted`, then `tested`), which
-/// stood the whole probe set up twice for the same answer.
+/// Which widget kinds answer each wanted name, asked of the live `__index` dispatcher through one
+/// probe per kind (the method tables are not enumerable from Lua). A kind `CreateFrame` refuses is
+/// skipped. `None` means no probe could be made, and every reader of it reports the whole wanted
+/// set as missing rather than nothing.
 fn widget_method_kinds(script: &UiScript, wanted: &BTreeSet<String>) -> Option<MethodOracle> {
     if wanted.is_empty() {
         return Some(MethodOracle::default());
     }
-    // Safe to interpolate unquoted: these names came out of the scanner's identifier reader, so
-    // they are letters, digits and underscores — a quote or a backslash cannot be in one.
+    // Safe to interpolate unquoted: the scanner's identifiers hold only letters, digits and `_`.
     let names = wanted
         .iter()
         .map(|n| format!("\"{n}\""))
@@ -790,23 +438,16 @@ fn widget_method_kinds(script: &UiScript, wanted: &BTreeSet<String>) -> Option<M
     Some(oracle)
 }
 
-/// What the live `__index` dispatcher answered, per kind — [`widget_method_kinds`]'s result.
+/// What the live `__index` dispatcher answered, per kind.
 #[derive(Default)]
 struct MethodOracle {
-    /// The kinds that actually stood up, in probe order. Carried explicitly so "how many kinds are
-    /// there" never has to be inferred from the answers.
+    /// The kinds that stood up, in probe order.
     probes: Vec<String>,
-    /// Wanted name → the kinds that answer it (empty = no widget we ship has it).
+    /// Wanted name -> the kinds that answer it (empty: no widget we ship has it).
     answered: BTreeMap<String, Vec<String>>,
 }
 
-/// The names in `wanted` that **no** kind answers — [`AddonReport::missing_methods`]'s rule,
-/// unchanged since 1227 so its numbers stay comparable (1209).
-///
-/// "Found nothing" must stay distinguishable from "ran nothing": an oracle that could not run
-/// reports the whole wanted set, which is loud and wrong in the direction that gets noticed, rather
-/// than empty and wrong in the direction that does not. A name the oracle somehow did not answer
-/// for falls the same way.
+/// The names in `wanted` that no kind answers; an oracle that could not run reports all of them.
 fn unresolved_from(oracle: &Option<MethodOracle>, wanted: &BTreeSet<String>) -> Vec<String> {
     let Some(oracle) = oracle else {
         return wanted.iter().cloned().collect();
@@ -818,30 +459,16 @@ fn unresolved_from(oracle: &Option<MethodOracle>, wanted: &BTreeSet<String>) ->
         .collect()
 }
 
-/// The two per-kind lists: what the addon calls **on a kind that cannot answer it**, and what it
-/// calls on a receiver nothing could type where the answer *depends* on the kind.
-///
-/// This is 1228's bound, closed as far as a static scan honestly can — and the residue is printed
-/// rather than swallowed. Three outcomes for a wanted name:
+/// The two per-kind lists, one verdict per wanted name:
 ///
 /// | the call site | the verdict |
 /// |---|---|
-/// | receiver typed, the kind answers | silent — this is the ordinary case |
-/// | receiver typed, the kind does not | `Kind:Name` — a real blocker, whoever else answers it |
-/// | receiver untypable, some kinds answer and some do not | `Name (only on …)` — an upper bound |
+/// | receiver typed, the kind answers | silent |
+/// | receiver typed, the kind does not | `Kind:Name`, a blocker whoever else answers it |
+/// | receiver untypable, some kinds answer and some do not | `Name (only on …)`, an upper bound |
 ///
-/// **It over-reports and never under-reports, deliberately.** The ambiguous list counts a name once
-/// per addon that calls it on *any* untypable receiver, which is a call that might be perfectly
-/// fine — `self:SetTexture()` inside a texture wrapper class is not a bug. The alternative is to
-/// swallow it as present because *something* answers it, which is precisely how `AddMessage` scored
-/// zero for a fortnight while three addons died on it. Its size is therefore a reading of the
-/// **attributor's** reach, not of ours: every shape [`scan_receivers`] learns to type moves rows out
-/// of it.
-///
-/// The blocking/feature-tested split is honoured here as it is above (a guarded call is not a
-/// blocker), and so is the definition subtraction — `f.Update = function … f:Update()` on a frame
-/// the addon made is the corpus's most common idiom, and its receiver is genuinely a widget, so
-/// without the subtraction every one of those would be a `Frame:Update` row.
+/// Feature-tested calls are not blockers, and names the addon defines itself are subtracted
+/// (`f.Update = function … f:Update()` on its own frame is the common idiom).
 fn per_kind_rows(
     script: &UiScript,
     oracle: &Option<MethodOracle>,
@@ -855,14 +482,14 @@ fn per_kind_rows(
             .unwrap_or(&empty)
             .as_slice()
     };
-    // Every typed call site, as `name → the kinds it was called on`.
+    // Every typed call site, as `name -> the kinds it was called on`.
     let mut typed: BTreeMap<&str, BTreeSet<&str>> = BTreeMap::new();
     for (kind, name) in &wants.kind_calls {
         if wants.wanted_methods.contains(name) {
             typed.entry(name).or_default().insert(kind);
         }
     }
-    // ...plus the published names, resolved against the live arena rather than guessed.
+    // ...plus the published names, resolved against the live arena.
     let mut untyped_by_name: BTreeSet<&str> = BTreeSet::new();
     for (receiver, name) in &wants.global_calls {
         if !wants.wanted_methods.contains(name) {
@@ -872,8 +499,7 @@ fn per_kind_rows(
             Some(kind) => {
                 typed.entry(name).or_default().insert(kind);
             }
-            // Nothing publishes that name, so the receiver is a runtime value this scan cannot
-            // follow — the same standing as `self:Foo()`.
+            // Nothing publishes that name, so the receiver is a runtime value, like `self:Foo()`.
             None => {
                 untyped_by_name.insert(name);
             }
@@ -890,10 +516,8 @@ fn per_kind_rows(
         }
     }
 
-    // A name is ambiguous only if it has an UNTYPED call site in this addon (a name every one of
-    // whose call sites was typed has already been answered above) and the answer actually depends
-    // on the kind. A name no kind answers is not ambiguous — it is missing, and it is already in
-    // `missing_methods`.
+    // Ambiguous only with an untyped call site in this addon and an answer that depends on the
+    // kind; a name no kind answers is already in `missing_methods`.
     let probes: &[String] = oracle.as_ref().map_or(&[], |o| o.probes.as_slice());
     let mut ambiguous: Vec<String> = Vec::new();
     for name in wants
@@ -910,11 +534,8 @@ fn per_kind_rows(
     (kind_missing, ambiguous)
 }
 
-/// `(on ScrollingMessageFrame)` / `(on no kind)` — who *does* answer a name the called kind does not.
-///
-/// The distinction is the whole point of the row: "on no kind" is a verb to write, "on
-/// ScrollingMessageFrame" is a verb we already wrote and forgot to wire to its sibling, and those
-/// are different jobs.
+/// `(on ScrollingMessageFrame)` / `(on no kind)`: the kinds that do answer a name the called kind
+/// does not. "On no kind" is a verb to write; a named kind is a verb to wire to its sibling.
 fn elsewhere(have: &[String]) -> String {
     match have.len() {
         0 => "on no kind".to_string(),
@@ -923,14 +544,12 @@ fn elsewhere(have: &[String]) -> String {
     }
 }
 
-/// `(only on Texture)` / `(missing on Texture, FontString)` — whichever side of the split is
-/// shorter, so a reader can triage the row at a glance. Deterministic, because it is part of a
-/// ranking key.
+/// `(only on Texture)` / `(missing on Texture, FontString)`, whichever side is shorter;
+/// deterministic, since it is part of a ranking key.
 fn only_on(have: &[String], probes: &[String]) -> String {
     if have.len() * 2 <= probes.len() {
-        // Never truncated, unlike the other side: the length of this list IS the row's rank
-        // ([`ambiguous_method_demand`] counts its separators), and it is bounded by construction —
-        // this branch only runs when at most half the kinds answer.
+        // Never truncated: its length is the row's rank ([`ambiguous_method_demand`] counts its
+        // separators), bounded because at most half the kinds answer here.
         format!("only on {}", have.join(", "))
     } else {
         let lack: Vec<&str> = probes
@@ -945,61 +564,24 @@ fn only_on(have: &[String], probes: &[String]) -> String {
     }
 }
 
-/// Drive the client's own session-start sequence over a loaded addon and report what its HANDLERS
-/// raised — the errors no other number here can see.
+/// Drive the session-start sequence over a loaded addon and report what its handlers raised.
 ///
-/// The order is the reference's, byte-verified inside `UI_Init 0x48fbf0` and already pinned by
-/// `ui_script::addons`' own test: every addon's `ADDON_LOADED`, then `VARIABLES_LOADED`, then
-/// `PLAYER_LOGIN`; `PLAYER_ENTERING_WORLD` follows in the cascade. Then a few ticks, because a
-/// great deal of addon code runs from `OnUpdate` or from something scheduled on the first one.
-///
-/// **Only the surveyed addon's `ADDON_LOADED` is fired here** (2166). The client fires each one
-/// inside that addon's own `AddOn_Load` (`0x51f5ad`), not in a batch afterwards, so every
-/// dependency's event has already happened in [`load_dependencies`] — before the surveyed addon's
-/// first line ran, which is what the real client presents to it.
-///
-/// **Deliberately not `ui_script::finish_ui_load`**, which is the production path: that also runs
-/// `load_saved_variables`, which reads the machine's real `BENILLA_HOME`. A survey must not depend
-/// on — or write to — the director's own saved variables, so the events are fired directly.
-///
-/// **Ten ticks of 0.1 s, and the bound is the point.** An addon with a busy `OnUpdate` would
-/// otherwise run for as long as we let it, and 218 VMs multiply whatever that is. One simulated
-/// second reaches the common `ScheduleEvent(..., 0)`/`(..., 0.05)` shapes and Ace's own one-second
-/// `AceEvent_FullyInitialized` timer; it does not reach a ten-second self-heal, and that
-/// under-report is stated rather than hidden.
+/// The order is the 1.12 client's (`UI_Init`, `0x48fbf0`): `ADDON_LOADED`, `VARIABLES_LOADED`,
+/// `PLAYER_LOGIN`, with `PLAYER_ENTERING_WORLD` in the cascade, then ten ticks of 0.1 s for
+/// `OnUpdate` and first-tick timers (Ace's one-second `AceEvent_FullyInitialized` included; a
+/// longer timer is not reached). Only the surveyed addon's `ADDON_LOADED` fires here: each
+/// dependency's fired in [`load_dependencies`], inside its own `AddOn_Load` (`0x51f5ad`). Not
+/// `ui_script::finish_ui_load`, which would read the real saved variables.
 fn drive_session_start(
     script: &mut UiScript,
     name: &str,
     installed: &BTreeSet<String>,
 ) -> Vec<String> {
-    // **The dependencies' `ADDON_LOADED`s are already behind us** — each fired beside its own
-    // addon's files, at `0x51f5ad`'s position, inside `load_dependencies` (2166). What is left of
-    // the client's session start is the SURVEYED addon's own event and the three that follow it
-    // once every addon has loaded: `VARIABLES_LOADED`, `PLAYER_LOGIN`, `PLAYER_ENTERING_WORLD`.
-    //
-    // A dependency's initialiser is almost always gated on its own name arriving in `arg1`:
-    //
-    //     -- Atlas.lua:326
-    //     if (event == "ADDON_LOADED" and arg1 == "Atlas") then Atlas_Init(); end
-    //
-    // `Atlas_Init` is what assigns `AtlasOptions` (l.199). Firing only the SURVEYED addon's name
-    // meant that guard never passed for a dependency, so `FuBar_AtlasFu` met an Atlas that had
-    // loaded its files and never initialised — and died at `AtlasButton.lua:30` on a nil
-    // `AtlasOptions`, a fault the survey then recorded against FuBar_AtlasFu. That was fixed by
-    // firing every dependency's event here; 2166 moved each one to where the client fires it.
-    //
-    // **Attribution is by the RAISING CHUNK, not by which event window the raise fell in**
-    // (decision 1226 — recorded when this was still window-based, fixed since). The window proxy
-    // broke on the shape it was written for: AceAddon drains its ENTIRE `nextAddon` queue on any
-    // `ADDON_LOADED` it sees (`AceAddon-2.0.lua:104-105`) and calls each consumer's
-    // `OnInitialize` there (`:230`). So the SURVEYED addon's own code can run inside a
-    // DEPENDENCY's window, and a mark that only covered its own window charged those raises to
-    // nobody — the whole FuBar/Ace family was silently OVER-reported as surviving.
-    //
-    // The mark opens BEFORE the surveyed addon's own event for exactly that reason, and the
-    // dependency exemption is applied afterwards by asking WHOSE FILE raised. Chunk names have
-    // been truthful since 1217 (`@Interface\AddOns\<Folder>\<File>`), which is what makes the
-    // honest key available at all.
+    // Errors are attributed by the raising chunk, not the event window: AceAddon runs every queued
+    // consumer's `OnInitialize` on any `ADDON_LOADED` it sees (`AceAddon-2.0.lua:104-105`, `:230`),
+    // so the surveyed addon's code can run inside a dependency's event. The mark opens before the
+    // surveyed addon's event, and a raise in another addon's file is exempted afterwards by its
+    // chunk name (`@Interface\AddOns\<Folder>\<File>`).
     let before = script.errors().len();
     script.fire_event(
         "ADDON_LOADED",
@@ -1018,33 +600,14 @@ fn drive_session_start(
         .collect()
 }
 
-/// Does this raise belong to **another installed addon's** file rather than the surveyed addon's?
+/// Does this raise belong to another installed addon's file? A library that fails is its own row;
+/// charging its consumers would count one fault once per addon that embeds it.
 ///
-/// The rule `load_dependencies` already states for load errors, enforceable for session errors
-/// since 1226: *a library that fails is its own row; blaming its consumers would count one fault
-/// once per addon that embeds it.* Only the FIRST line is consulted — that is the raise site; the
-/// frames below it are the call path, and a consumer calling into a library that then raises is
-/// still the library's fault, exactly as it is at load time.
-///
-/// **The exemption was "a DECLARED DEPENDENCY's file" and that was too narrow** (decision 2107).
-/// Once the harness's VMs got a real AddOns root, `LoadAddOn` began doing what it does in a real
-/// session, and the corpus's largest family drives it deliberately: `FuBar.lua:1034`'s
-/// `LoadLoadOnDemandPlugins` demand-loads **every** installed `FuBar_*` plugin the moment any one
-/// of them seats. So surveying `FuBar_MoneyFu` runs fifty *siblings*' file scope, and
-/// `FuBar_BattlegroundFu`'s embedded `Glory-2.0` raises `Glory-2.0 requires Deformat-2.0` —
-/// a library `FuBar_BattlegroundFu` does not ship and that a dozen of its siblings do, which is
-/// this module's own stated one-VM-per-addon limitation and not a gap of ours. It is not
-/// `FuBar_MoneyFu`'s row either: it is `FuBar_BattlegroundFu`'s, where the survey already counts it
-/// once. **49 of the corpus's 219 addons were failing on somebody else's file.**
-///
-/// A demand-loaded sibling is the same category as a declared dependency — code the surveyed addon
-/// did not write — so the test is now "an installed addon that is not this one", which subsumes
-/// `deps` (every dependency is installed) and adds the siblings.
-///
-/// **Conservative on purpose, unchanged.** A chunk that names no addon folder at all — our own
-/// FrameXML, an `[string "Frame:OnEvent"]` handler — is KEPT, because the surveyed addon is what
-/// drove it. And the surveyed addon's own folder is tested FIRST, so a raise inside its own
-/// `Libs\Ace\…` is never handed to an installed addon that happens to be called `Ace`.
+/// Only the first line, the raise site, is consulted. Any installed addon counts, not only declared
+/// dependencies: `LoadAddOn` runs siblings' file scope (FuBar demand-loads every installed
+/// `FuBar_*` plugin, `FuBar.lua:1034`). A chunk naming no addon folder (our FrameXML, an
+/// `[string "Frame:OnEvent"]` handler) is kept, and the surveyed addon's own folder is tested
+/// first, so its own `Libs\Ace\…` is never handed to an addon named `Ace`.
 fn raised_inside_another_addons_own_file(
     err: &str,
     name: &str,
@@ -1059,8 +622,8 @@ fn raised_inside_another_addons_own_file(
             || line.starts_with(&format!("{folder}\\"))
     };
     let mine = name.to_ascii_lowercase();
-    // The surveyed addon's own folder always wins, even when another addon's name is a substring
-    // of a path inside it.
+    // The surveyed addon's own folder wins, even when another addon's name is a substring of a path
+    // in it.
     if owns(&first, &mine) {
         return false;
     }
@@ -1070,25 +633,11 @@ fn raised_inside_another_addons_own_file(
     raised_inside_a_demand_load(err, &mine)
 }
 
-/// The raise site names **no file at all** — did it happen inside a `LoadAddOn` this addon made?
-///
-/// An inline `<OnEvent>`/`<OnLoad>` body is compiled under the FRAME's name
-/// (`[string "AuctioneerFrame:OnEvent"]`), not the file's, so the folder test above cannot see
-/// whose code it is — and 1226's conservative half then KEEPS it, charged to whoever drove it.
-/// That is right for a handler the surveyed addon's own events reached, and wrong for one reached
-/// through a demand load, which is somebody else's addon loading its own frames.
-///
-/// The traceback says which. `Stubby.lua:581`'s `inspectAddOn` calls `LoadAddOn` on every addon it
-/// finds, Auctioneer's `AuctioneerFrame:OnEvent` raises inside that call, and the frame between
-/// them is `[C]: in function 'LoadAddOn'`. So: walk the traceback from the raise site down, and if
-/// a `LoadAddOn` frame comes **before** any frame naming the surveyed addon's own folder, the code
-/// that raised belongs to the addon being loaded. It cost six addons their row — Stubby and the
-/// five that pull it in — for one raise in Auctioneer, which has its own row already.
-///
-/// **The false negative, stated:** the surveyed addon's OWN inline handler, fired by an event that
-/// happened to be dispatched inside a demand load it made, is exempted too. That is the same
-/// direction the dependency exemption has always erred in, and the alternative — charging every
-/// addon that calls `LoadAddOn` for its neighbours' code — is what this replaces.
+/// The raise site names no file: did it happen inside a `LoadAddOn` this addon made? An inline
+/// `<OnEvent>` body is compiled under the frame's name (`[string "AuctioneerFrame:OnEvent"]`), so
+/// the traceback is walked from the raise site down, and a `LoadAddOn` frame before any frame in
+/// the surveyed addon's folder makes it the loaded addon's raise. The surveyed addon's own inline
+/// handler fired inside such a load is exempted too.
 fn raised_inside_a_demand_load(err: &str, mine: &str) -> bool {
     for line in err.lines().skip(1).map(str::to_ascii_lowercase) {
         if line.contains(&format!("\\{mine}\\")) || line.contains(&format!("{mine}/")) {
@@ -1101,16 +650,8 @@ fn raised_inside_a_demand_load(err: &str, mine: &str) -> bool {
     false
 }
 
-/// Invoke the reference's own UI entry points, so an addon's OVERRIDES actually execute.
-///
-/// **The blind spot this closes was found by the director, not by any number here.** They installed
-/// Bagnon, saw it listed in the AddOns window, and still got the stock bags: it had replaced
-/// `ToggleBackpack` and nothing in the client ever called that name. Every column in this survey
-/// said the addon was fine, because the survey loads addons and fires events and **never clicks
-/// anything**. An override that is installed and never invoked is indistinguishable here from one
-/// that works.
-///
-/// So this drives a small set of entry points that real corpus addons are known to replace:
+/// Invoke the stock UI entry points corpus addons replace, so their overrides execute: the survey
+/// otherwise never clicks anything, and an override never invoked looks like one that works.
 ///
 /// | entry point | who replaces it |
 /// |---|---|
@@ -1118,17 +659,11 @@ fn raised_inside_a_demand_load(err: &str, mine: &str) -> bool {
 /// | `UnitFrame_OnEnter`/`OnLeave` | TipBuddy (`TipBuddy.lua:2770`) |
 /// | `ActionButton_Update` | zBar, zBarEx, CT_BarMod |
 ///
-/// **Bounded on purpose, like the ten ticks above.** These three families are the ones with a
-/// measured corpus hooker; driving the whole UI would be a different program, and an unbounded
-/// probe over 218 VMs is how a survey stops finishing. Each call is guarded on the global existing
-/// and wrapped so a raise is RECORDED rather than aborting the probe — the error is the finding.
-///
-/// What it still cannot see: whether the override produced the right *result*. It proves the body
-/// ran, not that the bags look right. That remains the director's eye.
+/// Each call is guarded on the global existing and wrapped so a raise is recorded. It proves the
+/// body ran, not that its result is right.
 fn drive_ui_probe(script: &mut UiScript) -> Vec<String> {
     let before = script.errors().len();
-    // `this` is set explicitly for the `this`-shaped entry points, because the reference's contract
-    // reads it and an addon's replacement will too.
+    // `this` is set for the `this`-shaped entry points, which read it.
     let _ = script.run(
         r#"
         -- The pcall CAPTURES the error; it does not discard it. Written the obvious way first
@@ -1180,7 +715,7 @@ fn drive_ui_probe(script: &mut UiScript) -> Vec<String> {
     "#,
     );
     let mut out = script.errors().split_off(before);
-    // The captured raises, in the order they happened.
+    // The captured raises, in order.
     if let Ok(n) = script.eval::<i64>("return table.getn(BENILLA_PROBE_ERRORS)") {
         for i in 1..=n {
             if let Ok(e) = script.eval::<String>(&format!("return BENILLA_PROBE_ERRORS[{i}]")) {
@@ -1193,21 +728,11 @@ fn drive_ui_probe(script: &mut UiScript) -> Vec<String> {
 
 /// Load an addon's declared dependencies into the VM, depth-first, each at most once.
 ///
-/// The reference's own order (`AddOn_Load 0x51f240`, 1191 §2): **OptionalDeps first, failures
-/// ignored; RequiredDeps next, a failure aborts the dependent's load; then its own files.** Both
-/// halves are walked, in that order; the harness does not reproduce the *abort*, only the **state**
-/// a dependent's file scope actually meets, and it reports a missing required dependency separately
-/// ([`AddonReport::missing_deps`]) while an absent optional one is silent, as the client's is.
-///
-/// This doc claimed the same thing from 1193 onward while the code read `dependencies()` only —
-/// the third doc-vs-code lie this arc has found in its own instruments (the others: a module doc
-/// claiming it printed which mode a run was in, and a comment claiming the leading-capital filter
-/// covered Lua locals). **A sentence describing behaviour is a claim, and an unverified claim in a
-/// comment is worse than none, because it stops the next reader checking.**
-///
-/// Errors inside a dependency are **not** attributed to the dependent. A library that fails is its
-/// own row in this survey; blaming its consumers would count one fault N times, which is the
-/// mistake the one-VM-per-addon rule exists to prevent.
+/// The 1.12 client's order (`AddOn_Load`, `0x51f240`): optional dependencies first, failures
+/// ignored; required ones next, a failure aborting the dependent; then its own files. The abort is
+/// not reproduced, only the state the dependent's file scope meets; a missing required dependency
+/// is reported ([`AddonReport::missing_deps`]), an absent optional one is silent. Errors inside a
+/// dependency are its own row, never the dependent's.
 fn load_dependencies(
     script: &mut UiScript,
     root: &Path,
@@ -1216,14 +741,8 @@ fn load_dependencies(
     seen: &mut BTreeSet<String>,
     loaded: &mut Vec<LoadedDep>,
 ) {
-    // OPTIONAL first, then required — the reference's own order, and the half this walk was
-    // missing. The doc above has claimed since 1193 that the two are "folded together"; only
-    // `dependencies()` was ever read, so `## OptionalDeps: FuBar, Ace2` did nothing and the survey
-    // met a state the real client never produces. That is the exact bug `load_dependencies` exists
-    // to prevent, in the half nobody checked. **130 corpus addons declare optional deps**, and it
-    // is how the whole FuBar family gets AceLibrary: `FuBar_BagFu`'s `.toc` lists
-    // `FuBarPlugin-2.0.lua` BEFORE `AceLibrary.lua`, and FuBarPlugin raises
-    // "FuBarPlugin-2.0 requires AceLibrary." unless the `Ace2` addon loaded first.
+    // Optional first, then required: `FuBar_BagFu` lists `FuBarPlugin-2.0.lua` before
+    // `AceLibrary.lua`, and FuBarPlugin raises unless the optional `Ace2` loaded first.
     let deps: Vec<&str> = toc
         .optional_dependencies()
         .into_iter()
@@ -1242,25 +761,12 @@ fn load_dependencies(
         };
         load_dependencies(script, root, &dep_toc, installed, seen, loaded);
         let files = load_addon_files(script, root, dep, &dep_toc);
-        // **`ADDON_LOADED` fires HERE, at the reference's own position** — not later, with every
-        // other one, which is what this harness did until 2166. `AddOn_Load 0x51f240` emits, per
-        // addon: its dependencies → its own `.toc` files (`0x51f3fa`) → `Bindings.xml` → the two
-        // SavedVariables chunks → **`ADDON_LOADED` (event 429) at `0x51f5ad`** — and only then
-        // returns to load the next addon. So a dependency's event lands BEFORE its dependent's
-        // first line runs, and the loaded flag is set before the event (`[rec+0x18]=1` at
-        // `0x51f313`, the loop preamble) so a handler asking `IsAddOnLoaded` gets the truth.
-        //
-        // Deferring them all to `drive_session_start` put the corpus's largest family in a state
-        // the client never produces. AceAddon-2.0 drains its **whole** `nextAddon` queue on the
-        // first `ADDON_LOADED` it sees, whoever it names (`AceAddon-2.0.lua:104-105`), and calls
-        // each consumer's `OnInitialize` there (`:230`) — so with the events deferred, every Ace2
-        // addon in the VM initialised under its FIRST DEPENDENCY's name, after every file in the
-        // chain had already run. ~87 corpus addons are Ace2.
-        //
-        // Fired OUTSIDE the surveyed addon's error mark, deliberately and for the same reason the
-        // dependency's load errors are: a library that raises in its own initialiser is its own
-        // row in this survey, where it is the surveyed addon and this same event fires inside the
-        // mark. Charging it here would count one fault once per addon that embeds the library.
+        // `ADDON_LOADED` fires here, at the 1.12 client's position: `AddOn_Load` (`0x51f240`) runs
+        // an addon's dependencies, its `.toc` files (`0x51f3fa`), `Bindings.xml`, the two
+        // SavedVariables chunks, then `ADDON_LOADED` (event 429, `0x51f5ad`), before the next
+        // addon. The loaded flag is set first (`[rec+0x18]=1` at `0x51f313`), so a handler's
+        // `IsAddOnLoaded` is true. Fired outside the surveyed addon's error mark: a library raising
+        // in its initialiser is its own row.
         script.mark_addon_loaded(dep);
         script.fire_event(
             "ADDON_LOADED",
@@ -1273,12 +779,8 @@ fn load_dependencies(
     }
 }
 
-/// One dependency the walk pulled in, and what its own files did.
-///
-/// The name alone was enough while every consumer only wanted the load ORDER. The shared-VM
-/// control ([`together`]) wants the failures too, and it cannot recover them any other way: a
-/// library folder loads exactly once in that VM, under whichever dependent reached it first, so
-/// it never gets a turn of its own to be measured in.
+/// One dependency the walk pulled in, and what its own files did; [`together`] needs the failures,
+/// since a library loads once in its shared VM, under whichever dependent reached it first.
 struct LoadedDep {
     name: String,
     files: FileLoad,
@@ -1286,40 +788,18 @@ struct LoadedDep {
 
 /// Template names the addon passes to `CreateFrame` that the VM cannot resolve.
 ///
-/// Scanned rather than traced, for `missing_globals`' reason: the calls overwhelmingly happen in
-/// handlers a load-time survey never fires. It is not comment-stripped: a `CreateFrame` inside a
-/// comment counts, and that over-report is the cheaper error of the two.
-///
-/// **A string literal in the fourth argument, OR a local bound to one in the same file.** The
-/// literal-only form was the honest under-report this doc used to name — and then a decision was
-/// made on the number it produced. `Interface\FrameXML\ItemButtonTemplate.xml` declined to build
-/// `ItemButtonTemplate` citing "the harness's template demand ranks it at zero on both axes"; the
-/// zero was real, and pfUI wanted `ContainerFrameItemButtonTemplate` (which inherits it) the whole
-/// time, through
-///
-/// ```lua
-/// local tpl = "ContainerFrameItemButtonTemplate"
-/// if bag == -1 then tpl = "BankItemButtonGenericTemplate" end
-/// CreateFrame("Button", "pfBag" .. bag .. "item" .. slot, pfUI.bags[bag], tpl)
-/// ```
-///
-/// The instrument was not lying — it said what it could not see, right here. But a bound that is
-/// stated at the function and forgotten at the call site is only half a guard, so the cheap half
-/// of the gap is closed: one pass collects `x = "literal"` bindings per file, and a bare
-/// identifier in the fourth argument resolves through it.
-///
-/// Still invisible, and still stated: a name built by concatenation, one passed in as a function
-/// argument, one read from a table, and one bound in another file. Those are real and this does
-/// not pretend otherwise — what it fixes is the single commonest shape, measured.
+/// Scanned, not traced (the calls run in handlers a load-time survey never fires) and not
+/// comment-stripped (a commented call counts). The fourth argument resolves as a string literal or
+/// an identifier bound to one in the same file (`local tpl = "ContainerFrameItemButtonTemplate"`);
+/// a concatenated name, a function argument, a table read or a binding in another file is not seen.
 fn missing_templates(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> Vec<String> {
     let mut wanted: BTreeSet<String> = BTreeSet::new();
     for path in source_files(root, name, toc) {
         let Some(text) = read_text(root, &path) else {
             continue;
         };
-        // `ident = "literal"` bindings in this file, for the fourth-argument lookup below. A name
-        // rebound to several literals keeps ALL of them (pfUI's `tpl` is two), because the census
-        // asks "could this call want that template", and both branches genuinely can.
+        // `ident = "literal"` bindings in this file; a name bound to several literals keeps all of
+        // them.
         let mut bound: BTreeMap<&str, Vec<&str>> = BTreeMap::new();
         for (i, _) in text.match_indices('=') {
             // Not `==`, `~=`, `<=`, `>=`.
@@ -1342,18 +822,9 @@ fn missing_templates(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> V
                 continue;
             };
             let lit = &rhs[1..end + 1];
-            // **Disqualify on an OPERATOR, not on a terminator.** The defect this closes is a
-            // fragment: `local built = "A" .. "B"` binding `built` to `"A"` — a name nobody asked
-            // for entering the demand ranking, which is not an under-report but the fiction this
-            // table has opened with three times (1210/1218/1227).
-            //
-            // Written first as "the tail must be a statement end", which is the wrong shape: Lua's
-            // terminators are open-ended (`end`, `then`, `else`, `until`, …) and chasing that list
-            // is endless — `tpl = "X" end` was missed for exactly that reason. What actually makes
-            // a literal part of a larger expression is a binary operator after it, and on a STRING
-            // in Lua that is `..` almost exclusively. So the test names the operators and lets
-            // everything else through, which also keeps this scanner's standing posture: over-
-            // report rather than under-report, the cheaper error of the two.
+            // Disqualified on a binary operator after the literal (on a Lua string, almost only
+            // `..`), so `local built = "A" .. "B"` binds nothing while any statement end still lets
+            // it through.
             let tail = rhs[end + 2..].trim_start_matches([' ', '\t']);
             let part_of_expression = tail.starts_with("..")
                 || tail.starts_with(['+', '-', '*', '/', '%', '^', '<', '>'])
@@ -1372,15 +843,9 @@ fn missing_templates(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> V
             let Some(close) = rest[open..].find(')') else {
                 continue;
             };
-            // Split the ARGUMENT LIST at depth 0 only. A plain `split(',')` cuts inside nested
-            // calls and strings, and it produced a phantom: AceGUI's
-            //
-            //     CreateFrame("ScrollFrame", format("%s@%s@%s", Type, "ScrollFrame", …), backdrop, …)
-            //
-            // has its 4th comma-separated chunk INSIDE `format(...)`, so the census reported a
-            // missing template literally named `ScrollFrame` — which is a frame KIND, not a
-            // template, and named nothing that was ever missing. One of four rows in that table was
-            // fiction (1210/1218/1227, the fourth time a ranking here has opened with one).
+            // Split the argument list at depth 0 only: a plain split cuts inside a nested call such
+            // as AceGUI's
+            // `CreateFrame("ScrollFrame", format("%s@%s@%s", Type, "ScrollFrame", …), …)`.
             let args = &rest[open + 1..open + close];
             let mut depth = 0i32;
             let mut quote: Option<char> = None;
@@ -1405,9 +870,8 @@ fn missing_templates(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> V
                 continue;
             };
             let f = fourth.trim();
-            // A quoted literal, either quote style, taken WHOLE. This used to split the literal on
-            // commas, on the belief that the fourth argument is a list; it is not — 1.12 looks up
-            // the string it was handed, once.
+            // A quoted literal, either quote style, taken whole: 1.12 looks up the string it was
+            // handed, once.
             let lit = f
                 .strip_prefix('"')
                 .and_then(|s| s.strip_suffix('"'))
@@ -1415,7 +879,7 @@ fn missing_templates(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> V
             if let Some(lit) = lit.filter(|s| !s.is_empty()) {
                 wanted.insert(lit.to_string());
             } else if let Some(lits) = bound.get(f) {
-                // A bare identifier bound to a literal in this file — pfUI's `tpl`.
+                // A bare identifier bound to a literal in this file.
                 wanted.extend(lits.iter().map(|s| (*s).to_string()));
             }
         }
@@ -1426,19 +890,10 @@ fn missing_templates(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> V
         .collect()
 }
 
-/// Template names the addon names in an XML `inherits=` that the VM cannot resolve.
-///
-/// [`missing_templates`]'s twin over the *other* way a template is asked for, and the one that
-/// turned out to carry the weight (see [`AddonReport::missing_inherits`]). Same discipline as
-/// every scanner here: a plain attribute read, not comment-stripped, over the addon's XML only.
-///
-/// Two deliberate rules, both of which the CreateFrame scanner does not need:
-///
-/// - **A name registered as a FONT resolves.** `inherits=` is one attribute over two namespaces,
-///   and `<FontString inherits="GameFontNormal">` is the single most common use of it in any
-///   corpus. Asking only the template registry would bury the real answer under font names.
-/// - **`virtual="true"` elements the addon declares itself are already in the registry**, because
-///   this runs after its files have loaded — the same ordering `missing_templates` relies on.
+/// Template names the addon names in an XML `inherits=` that the VM cannot resolve, read as a plain
+/// attribute over the addon's XML only. A name registered as a font resolves (`inherits=` spans
+/// both namespaces), and templates the addon declares itself are already registered, since this
+/// runs after its files load.
 fn missing_inherits(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> Vec<String> {
     let mut wanted: BTreeSet<String> = BTreeSet::new();
     for path in source_files(root, name, toc) {
@@ -1457,10 +912,8 @@ fn missing_inherits(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> Ve
             let Some(end) = rest[1..].find(quote) else {
                 continue;
             };
-            // ONE name, verbatim — the attribute value is what the loader looks up, commas and
-            // spaces included. Splitting here made the census ask about names the loader never
-            // asks for: a comma list would be reported as two missing templates when the real
-            // lookup misses once, on the whole string.
+            // One name, verbatim: the loader looks up the whole attribute value, commas and spaces
+            // included.
             wanted.extend(
                 [rest[1..1 + end].to_string()]
                     .into_iter()
@@ -1474,9 +927,8 @@ fn missing_inherits(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> Ve
         .collect()
 }
 
-/// Every source file an addon reaches — its manifest entries plus the `<Script file=>`/`<Include>`
-/// tree hanging off them. An addon's real Lua often hangs off its XML rather than its `.toc`, the
-/// same trap the 1.12 corpus set in decision 1190.
+/// Every source file an addon reaches: its manifest entries plus the `<Script file=>`/`<Include>`
+/// tree hanging off them, where much of an addon's Lua lives.
 fn source_files(root: &Path, name: &str, toc: &Toc) -> Vec<String> {
     let base = addon_base(name);
     let mut pending: Vec<String> = toc
@@ -1501,32 +953,17 @@ fn source_files(root: &Path, name: &str, toc: &Toc) -> Vec<String> {
     out
 }
 
-/// The FrameXML digest of the interface this survey loaded (`crate::ui_script::framexml_digest`).
-///
-/// **Print it beside every number.** A survey run is only comparable to another survey run that
-/// loaded the same interface, and in a dev build the manifest and the files still ours are read
-/// from the source tree — so an edit by anything sharing the checkout moves the headline with no
-/// rebuild and no announcement. A chain entry contributes its name only (its bytes are the
-/// player's install), so migrating a window changes the digest and playing does not.
+/// The FrameXML digest of the interface this survey loaded; print it beside every number. In a dev
+/// build the manifest and our files are read from the source tree, so an edit moves the headline
+/// without a rebuild. A chain entry contributes its name only, so migrating a window changes the
+/// digest and the player's install does not.
 pub fn framexml_digest() -> String {
     crate::ui_script::framexml_digest()
 }
 
-/// Every name our VM publishes into `_G`, with its Lua type — **no addons loaded**.
-///
-/// The other half of decision 1189's diff. 1189 established that the authoritative 1.12 surface is
-/// already captured (the running client's in-world `_G`, 19,572 entries, vendored here as
-/// `reference/1.12-globals.tsv`) and compared our table against it *once*, by hand. Nothing has
-/// re-run it since, so the comparison has been drifting ever since — which is the failure mode this
-/// project keeps writing records about: a measurement taken once and then cited as though it were
-/// current.
-///
-/// Deliberately addon-free. The question is what OUR interface publishes, and an addon's own globals
-/// would inflate both directions of the diff with names that belong to nobody but that addon.
-///
-/// The dump runs in Lua rather than reaching into the registry from Rust, because `_G` is the thing
-/// an addon actually sees — the same reasoning that made the reference side a live capture instead
-/// of the binary's registration table.
+/// Every name our VM publishes into `_G`, with its Lua type, with no addons loaded: our side of the
+/// diff against the 1.12 client's in-world `_G` (`reference/1.12-globals.tsv`). Dumped in Lua,
+/// since `_G` is what an addon sees.
 pub fn surface() -> Vec<(String, String)> {
     let Ok(mut script) = UiScript::new() else {
         return Vec::new();
@@ -1558,22 +995,14 @@ pub fn surface() -> Vec<(String, String)> {
         .collect()
 }
 
-/// The real `GlobalStrings.lua`, read once off the install's patch chain.
-///
-/// **~5,000 globals the surveyed VM would otherwise not have**, and the difference between an
-/// instrument that models a session and one that models a blank slate. `FACTION_ALLIANCE`,
-/// `PLAYER_OF_REALM`, `LEVEL`, every `ERR_*` — an addon reads them at file scope constantly, and
-/// AceDB-2.0 alone builds its per-realm key out of `FACTION_ALLIANCE` before anything else runs.
-///
-/// Read once per process rather than per addon: it is a megabyte of Lua and the survey stands up
-/// 218 VMs. `None` when there is no install, in which case the survey still runs and the numbers
-/// are simply worse — and this says which mode a run was in, so two numbers taken on different
-/// machines are never quietly compared.
+/// Whether the survey is seated with the real `GlobalStrings.lua` off the install's patch chain
+/// (about 5,000 globals such as `FACTION_ALLIANCE` and every `ERR_*`, read at file scope). Without
+/// an install the survey still runs on a worse VM, and this says which mode a run was in.
 pub fn seated_with_global_strings() -> bool {
     global_strings().is_some()
 }
 
-/// The real `GlobalStrings.lua`, or `None` with no install to read it from.
+/// The real `GlobalStrings.lua`, read once per process, or `None` with no install.
 fn global_strings() -> Option<&'static str> {
     use std::sync::OnceLock;
     static SRC: OnceLock<Option<String>> = OnceLock::new();
@@ -1588,45 +1017,23 @@ fn global_strings() -> Option<&'static str> {
     .as_deref()
 }
 
-/// Put a **player and a realm** in the VM before the addon loads (decision 1195).
+/// Put a player and a realm in the VM before the addon loads: the 1.12 client runs `AddOn_Load`
+/// from `UI_Init`, after the world is entered, so an addon's file scope always sees a real
+/// character (AceDB-2.0 opens with
+/// `string.format(PLAYER_OF_REALM, UnitName("player"), GetRealmName())`).
 ///
-/// Not decoration, and not optimism: the reference runs `AddOn_Load` from inside `UI_Init`, which
-/// is *after* the world is entered, so an addon's file scope always sees a real character. A bare
-/// VM answers `UnitName("player")` with nil, and the corpus's single most common opening line is
-///
-/// ```lua
-/// local charID = string.format(PLAYER_OF_REALM, UnitName("player"), GetRealmName())
-/// ```
-///
-/// — AceDB-2.0's, embedded in a large slice of the ecosystem. Without a seated session that is 24
-/// addons failing on a condition that cannot occur in a real client, which would make the harness
-/// pessimistic in exactly the way §4 of 1193 caught it being optimistic. The numbers are only
-/// worth quoting if the VM is shaped like the session an addon will actually meet.
-///
-/// Deliberately minimal — a name, a realm, a level, a class — because everything beyond that is
-/// state an addon reads *in handlers*, which this survey never fires.
+/// Every seat below is a state an in-world character is always in, kept minimal and ordinary: a VM
+/// answering nil or zero there would fail addons on a state the 1.12 client cannot be in.
 fn seat_a_session(script: &mut UiScript) {
-    // The reference boots FrameXML with this file FIRST; so does our app. Before the survey did,
-    // an addon's `FACTION_ALLIANCE` was nil and the failure looked like our bug.
+    // The 1.12 client boots FrameXML with this file first; so does our app.
     if let Some(src) = global_strings() {
         let _ = script.run(src);
     }
-    // The shipped CVar table, before the realm below writes into it — the survey never registered
-    // any, so `GetCVar` answered nil for every name the client actually ships. Same class as the
-    // empty addon registry: a state the real client cannot be in.
+    // The shipped CVar table, before the realm below writes into it.
     script.register_cvars(crate::cvars::registered_pairs());
-    // **A session runs on a DISPLAY, and until 2177 this one ran on none.** The host pushes the
-    // offered resolutions and the live one (`crate::video::publish_display_modes`); a VM with no
-    // window behind it gets an empty list, `GetScreenResolutions()` returns nothing and
-    // `GetCurrentResolution()` answers 0 — a state the real client cannot be in, and exactly the
-    // 1193/1212 fault this whole function exists to close. `CT_Viewport` is what found it: it
-    // reads its own screen size as `arg[GetCurrentResolution()]` at load and then indexes
-    // `CT_Viewport.screenRes` from an event handler, so an empty list turned "the verb is missing"
-    // into a nil-index two lines later — a moved symptom that would have read as a gap of ours.
-    //
-    // One mode, and it is the one this survey already tells the interface it is running at
-    // (`set_screen_size(1024, 768)` above): a display that offers exactly what the client is using.
-    // Anything richer would be numbers invented for an instrument.
+    // A display: `GetScreenResolutions()` empty and `GetCurrentResolution()` 0 is no state the 1.12
+    // client can be in (`CT_Viewport` indexes its screen size by it at load). One mode, the
+    // `set_screen_size(1024, 768)` the interface is already told.
     script.set_screen_resolutions(
         vec![benilla_ui::script::ScreenResolution {
             width: 1024,
@@ -1637,8 +1044,7 @@ fn seat_a_session(script: &mut UiScript) {
             height: 768,
         }),
     );
-    // What this run's device offers, as `crate::cvars` pushes it in the app — same values, because
-    // six of the seven are properties of this client rather than of the adapter.
+    // What this run's device offers, as `crate::cvars` pushes it in the app.
     script.set_video_caps(benilla_ui::script::VideoCaps {
         anisotropic: true,
         pixel_shaders: true,
@@ -1649,13 +1055,7 @@ fn seat_a_session(script: &mut UiScript) {
         hardware_cursor: true,
     });
     script.set_realm_name("Harness");
-    // THE BIND POINT. `GetBindLocation()` answered `""` in every VM, and a logged-in character with
-    // no hearth location is not a state one is in — the server sends `SMSG_BINDPOINTUPDATE` at
-    // login, before any addon runs. Same argument as the purse and the nil faction group.
-    //
-    // Three corpus addons read it, in three separate files (FuBar_TransporterFu, Necrosis,
-    // _LazyPig), and one of them CONCATENATES the result — so an empty seat is the difference
-    // between exercising their path and not.
+    // The bind point: the server sends `SMSG_BINDPOINTUPDATE` at login, before any addon runs.
     script.set_bind_location("Stormwind City");
     script.set_unit(
         "player",
@@ -1674,34 +1074,20 @@ fn seat_a_session(script: &mut UiScript) {
             class_file: Some("WARRIOR".into()),
             sex: 2,
             is_player: true,
-            // `UnitFactionGroup("player")` — nil here is not "no faction", it is a state a real
-            // player character cannot be in. AceDB-2.0 builds its per-realm key as
-            // `realm .. " - " .. faction` at file scope, so a nil faction is 24 addons stopping on
-            // `attempt to concatenate local 'faction'`. Every playable race has a side.
+            // `UnitFactionGroup("player")`: every playable race has a side, and AceDB-2.0
+            // concatenates it into its per-realm key at file scope.
             faction_group: Some("Alliance".into()),
-            // `0x5efe00`'s team digit for Human (race 1) — the rank-title key's second `%d`.
-            // Seated beside the faction group because they are different questions
-            // (`ui_unit::race_pvp_team`), not because they agree here.
+            // `0x5efe00`'s team digit for Human (race 1), the rank-title key's second `%d`.
             pvp_team: crate::ui_unit::race_pvp_team(1),
             ..Default::default()
         }),
     );
 
-    // ── A POPULATED world, not merely an inhabited one ──────────────────────────────────────
+    // ── A populated world ──
     //
-    // The columns above answer "did it raise"; the render column answers "did it draw". Until
-    // now the survey seated a player into an EMPTY world — no buffs, no target, no live
-    // cooldown — so a buff bar, a target frame or a cooldown-text addon drew nothing and landed
-    // in the drew-nothing list beside the pure libraries. `CT_BuffMod` declares 29 frames with
-    // none hidden at birth and `ElkBuffBar` 3: neither was failing to build, both had nothing to
-    // put in them.
-    //
-    // That made "nothing to draw" and "failed to draw" share a row, and the second is the one
-    // worth finding. Seating content separates them — and, more usefully, exposes the addons
-    // that only fail WHEN there is something to draw, which no empty-world column can reach.
-    //
-    // Deliberately minimal and deliberately ordinary: one buff, one target, one occupied action
-    // with a running cooldown. Not a stress fixture — a Tuesday.
+    // One buff, one target and one action with a running cooldown, so an addon that only draws when
+    // there is content (a buff bar, a target frame, cooldown text) is separated from one that
+    // failed.
     script.set_auras(
         "player",
         Some(vec![benilla_ui::script::AuraState {
@@ -1744,38 +1130,17 @@ fn seat_a_session(script: &mut UiScript) {
         1,
         Some(benilla_ui::script::ActionState {
             usable: true,
-            // (startTime ms, duration ms, enable) — a cooldown with time left on it, which is
-            // what a cooldown-text addon (OmniCC, CooldownCount) needs before it draws anything.
+            // (startTime ms, duration ms, enable): a cooldown with time left, which cooldown-text
+            // addons need.
             cooldown: Some((1, 30_000, true)),
             ..Default::default()
         }),
     );
-    // A SPELLBOOK. A level-60 warrior with an empty one is a state no real character is in — the
-    // same argument this fixture already makes for a nil `UnitFactionGroup` and an empty CVar
-    // table, and it costs an addon the same way: `TheoryCraftEngine.lua:306` is
-    // `name, texture, offset, numSpells = GetSpellTabInfo(1)` then `for i=1, numSpells`, so an
-    // empty book is `'for' limit must be a number` and the addon dies at session start. The verb
-    // was never the problem — `GetSpellTabInfo` already returns all four values — the FIXTURE was.
-    //
-    // Deliberately modest, and the reason is 1209's: a fixture that seats everything stops
-    // resembling a session anyone has, and every row it lights up is one nobody can attribute. Two
-    // tabs and four spells is a Tuesday. `Attack` is slot 1 because it is on every warrior's, and
-    // three corpus addons look for exactly that name.
-    // THE QUEST LOG. `GetNumQuestLogEntries()` answered `0, 0`, so every quest addon's walk ran
-    // zero times — the same shape as the 0-copper purse below and the empty spellbook: not a bug
-    // anywhere, just a path nothing ever entered. Five corpus addons walk this API (AtlasQuest,
-    // EQL3, FuBar_QuestsFu, QuestHistory, QuestItem).
-    //
-    // A HEADER AND TWO QUESTS, and each piece is here to be a shape the API distinguishes rather
-    // than to be plausible scenery:
-    //  · a zone HEADER row, because `GetQuestLogTitle`'s `isHeader` is a different row kind and an
-    //    addon that indexes rows without checking it walks straight into one;
-    //  · an IN-PROGRESS quest with two objectives, one finished and one not — so a leaderboard walk
-    //    sees both states, and `%d/%d` progress is mid-way rather than 0 or complete;
-    //  · a COMPLETE quest (`complete = 1`), the other end of `isComplete`'s 1/-1/nil.
-    // Not seated: a FAILED quest (-1) and a TIMED one. Both are real states, and both are states a
-    // character is only briefly in — 1209's rule that a row nobody can attribute is worth less than
-    // one nobody lit applies to fixtures too.
+    // A spellbook (seated below) and a quest log. An empty book fails `TheoryCraftEngine.lua:306`
+    // (`for i=1, numSpells` off `GetSpellTabInfo(1)`); two tabs, four spells, `Attack` in slot 1.
+    // The quest log is a zone header row (`isHeader`), an in-progress quest with one objective done
+    // and one not, and a complete one (`complete = 1`); failed (-1) and timed quests are not
+    // seated.
     {
         use benilla_ui::script::{QuestLogEntryView, QuestLogObjectiveView, QuestLogState};
         let objective = |text: &str, cur: u32, req: u32| QuestLogObjectiveView {
@@ -1815,28 +1180,12 @@ fn seat_a_session(script: &mut UiScript) {
         });
     }
 
-    // THE PURSE. `GetMoney()` answered **0 copper** for every addon in every VM — and a level-60
-    // with literally no money is not a state a character is in; it is the same "state the real
-    // client cannot be in" the nil `UnitFactionGroup` below is seated for. Money addons are a whole
-    // genre in this corpus (Accountant, the CT_* expense trackers, every auction and vendor addon),
-    // and they all compute with this number.
-    //
-    // **12_345_678 copper — 1234g 56s 78c — and the digits are the point.** A round figure is what
-    // a fixture reaches for and it is exactly the value that hides bugs: any of `gold`, `silver`
-    // and `copper` being zero lets a broken coin-format or a `mod`/`floor` slip read as correct.
-    // All three non-zero means a formatter that drops a field, or divides in the wrong order, has
-    // nowhere to hide. Non-zero also matters on its own: an addon that guards `if GetMoney() > 0`
-    // never ran its body here.
+    // The purse: 12_345_678 copper (1234g 56s 78c), every denomination non-zero, so a coin
+    // formatter that drops a field or divides in the wrong order shows it.
     script.set_money(12_345_678);
 
-    // EQUIPPED GEAR. Every `GetInventoryItem*("player", slot)` answered the empty shape, and a
-    // level-60 with no equipment at all is a state no character reaches — the same argument the
-    // spellbook and the backpack landed on.
-    //
-    // Three slots, not nineteen: head, chest and main hand. A fully-geared doll would be a state a
-    // real session presents, but it would also light up every path at once, and 1209's rule is
-    // that a row nobody can attribute is worth less than one nobody lit. Three is enough for an
-    // addon that WALKS the slots to reach real items, empty ones, and the ammo slot's absence.
+    // Equipped gear: head, chest and main hand, enough for a slot walk to meet items, empty slots
+    // and no ammo.
     {
         let mut slots: benilla_ui::script::InventorySlots = Default::default();
         slots[1] = Some(equip_slot(12640, "Lionheart Helm"));
@@ -1844,15 +1193,8 @@ fn seat_a_session(script: &mut UiScript) {
         slots[16] = Some(equip_slot(871, "Flurry Axe"));
         script.set_inventory_slots(slots);
     }
-    // THE BACKPACK. `GetContainerNumSlots(0)` answered 0 — and a character with no backpack has
-    // never existed: bag 0 is 16 slots from level 1, before a single bag is bought. Same argument
-    // as the spellbook above and the nil `UnitFactionGroup` below it, and the same expectation:
-    // seating a state every character is in should LOSE rows, because a path nothing walked is a
-    // path nothing tested.
-    //
-    // Backpack only, and deliberately: bags 1..4 are equipped bags, which a fresh character does
-    // NOT have, so seating them would manufacture a state rather than expose one. Two items in
-    // sixteen slots — the rest empty, which is itself a shape bag addons must handle.
+    // The backpack: bag 0 is 16 slots from level 1. Bags 1..4 are equipped bags, which a fresh
+    // character does not have, so they are not seated.
     {
         let mut slots = std::collections::HashMap::new();
         slots.insert(1, bag_slot(6948, "Hearthstone", 1));
@@ -1889,57 +1231,26 @@ fn seat_a_session(script: &mut UiScript) {
         ],
     });
 
-    // ── THE TWO LOGIN-SCOPED CATALOGUES (2167) ─────────────────────────────────────────────
+    // ── The login-scoped catalogues ──
     //
-    // Both of these are answered by the client with **no session behind them at all** — they are
-    // DBC reads, live from the moment the VM exists — so a VM that answers them empty is in a
-    // state the reference cannot be in, exactly like the nil faction group and the empty CVar
-    // table above. Both are read off the PLAYER'S OWN CHAIN, never shipped: we seat the
-    // structure, the install supplies the words (`ui_auction`'s own rule).
-    //
-    // **The auction class tree.** `GetAuctionItemClasses()` is `ItemClass.dbc` in the browse
-    // menu's order (1971), and the stock `AuctionFrameBrowse_OnLoad` reads it at the addon's
-    // LOAD. `Auctioneer`'s `AucCore.lua:105` is
-    //
-    //     local classes = pack(GetAuctionItemClasses());
-    //     local bidBasedCategories = {[classes[1]]=true, ..., [classes[10]]=true}
-    //
-    // — ten subscripts into a list that answered nothing, so `AucCore.lua:106` died on
-    // `table index is nil` and took `BeanCounter`, `Informant`, `Enchantrix` and `FonzAppraiser`
-    // with it. Five corpus addons read the tree; four of them at file scope.
-    // **The `SMSG_ADDON_INFO` reply, hiding nothing** (2175) — the same class of state correction
-    // as the two catalogues below and the empty spellbook above. The Lua index space
-    // (`GetNumAddOns`, and the index form of every AddOn verb) is built only when the server
-    // answers, and a surveyed VM is an IN-WORLD VM: the reference cannot be in the world without
-    // having had that reply. A survey that left it unanswered would measure a client whose
-    // `GetNumAddOns()` is 0, which is what AceAddon and AceLibrary scan.
-    //
-    // Empty, not the twelve: the corpus registry holds no `## Secure:` addon, so a real server
-    // would have nothing to hide here.
+    // Answered from DBCs with no session behind them, off the player's own chain. The
+    // `SMSG_ADDON_INFO` reply is seated empty: the Lua index space (`GetNumAddOns`, the index form
+    // of every AddOn verb) is built only when the server answers, which an in-world client always
+    // had, and no corpus addon is `## Secure:`. The auction class tree (`ItemClass.dbc` in the
+    // browse menu's order) is read at file scope, as by `Auctioneer`'s `AucCore.lua:105`.
     script.note_addon_info_reply(&[]);
     script.set_auction_item_classes(auction_item_classes());
 
-    // **The talent tree.** `GetTalentInfo(tab, i)` answers off `Talent.dbc` × `TalentTab.dbc`;
-    // ten corpus addons read it, and `KLHThreatMeter` reads it by POSITION at file scope
-    // (`KTM_Data.lua:376`, `_, _, _, _, rank = GetTalentInfo(info[1], info[2])`) and then does
-    // `-rank` arithmetic on the answer (`KTM_My.lua:721`). An unseated tree is nil, not zero.
-    //
-    // **Zero ranks, the full unspent pool** — a character who has just reached 60 and not spent a
-    // point. Deliberately, and for 1209's reason: a specific build would put arbitrary constants
-    // into every threat and damage calculation in the corpus, and a row nobody can attribute is
-    // worse than a row that is merely quiet. Rank 0 is a NUMBER, which is the whole difference
-    // this seat makes. 51 points is `level - 9` at 60, and the class is the seated warrior's.
+    // The talent tree (`Talent.dbc` x `TalentTab.dbc`), read by position at file scope
+    // (`KTM_Data.lua:376`). Zero ranks and the full pool, a fresh 60 (51 points, `level - 9`), so a
+    // rank is a number rather than nil.
     if let Some(state) = talent_snapshot(script) {
         script.set_talents(state);
     }
 }
 
-/// The reference's own auction browse tree, read once off the player's chain.
-///
-/// The same builder the live client feeds from (`ui_auction::categories`) over the same two DBCs,
-/// so the survey cannot drift from the window: a second copy of the ten-class set would be a
-/// second thing to keep right. Empty with no install, in which case the survey simply measures a
-/// worse VM and says so through [`seated_with_global_strings`].
+/// The 1.12 auction browse tree, read once off the player's chain by the builder the live client
+/// uses (`ui_auction::categories`); empty with no install.
 fn auction_item_classes() -> Vec<benilla_ui::script::AuctionCategory> {
     use std::sync::OnceLock;
     static TREE: OnceLock<Vec<benilla_ui::script::AuctionCategory>> = OnceLock::new();
@@ -1961,12 +1272,9 @@ fn auction_item_classes() -> Vec<benilla_ui::script::AuctionCategory> {
     .clone()
 }
 
-/// The seated character's talent pages, built by the live client's own `build_pages`.
-///
-/// The catalogues are read once per process (they are two DBC loads plus `Spell.dbc`, and the
-/// survey stands up 219 VMs); the PAGES are built per VM, because the red requirement lines are
-/// filled from that VM's own `GlobalStrings.lua` — the same rule the live feed follows (2045).
-/// `None` with no install.
+/// The seated character's talent pages, built by the live client's `build_pages`. The DBCs are read
+/// once per process; the pages are built per VM, since the requirement lines come from that VM's
+/// `GlobalStrings.lua`. `None` with no install.
 fn talent_snapshot(script: &UiScript) -> Option<benilla_ui::script::TalentUiState> {
     use std::sync::OnceLock;
     #[allow(clippy::type_complexity)]
@@ -1993,8 +1301,7 @@ fn talent_snapshot(script: &UiScript) -> Option<benilla_ui::script::TalentUiStat
             .ok()
             .filter(|t| !t.is_empty())
     };
-    // Human (`ChrRaces.dbc` 1) warrior (`ChrClasses.dbc` 1) — the character `seat_a_session`
-    // seats above, so the pages are the ones that character's talent window would show.
+    // Human (`ChrRaces.dbc` 1) warrior (`ChrClasses.dbc` 1), the character `seat_a_session` seats.
     Some(crate::ui_talent::build_pages(
         talents,
         &BTreeSet::new(),
@@ -2006,7 +1313,7 @@ fn talent_snapshot(script: &UiScript) -> Option<benilla_ui::script::TalentUiStat
     ))
 }
 
-/// One seated equipment slot — full durability, so no alert region lights up.
+/// One seated equipment slot, at full durability.
 fn equip_slot(item_id: u32, name: &str) -> benilla_ui::script::InvSlotView {
     benilla_ui::script::InvSlotView {
         item_id,
@@ -2014,10 +1321,8 @@ fn equip_slot(item_id: u32, name: &str) -> benilla_ui::script::InvSlotView {
         count: 1,
         quality: 2,
         name: Some(name.to_string()),
-        // FULL durability on purpose. The setter recomputes the eleven alert statuses and fires
-        // UPDATE_INVENTORY_ALERTS, so a worn item would light DurabilityFrame's regions — a
-        // VISIBLE change, and this fixture's job is to present a plausible session, not to drive
-        // the alert law. Undamaged gear is the ordinary case anyway.
+        // Full durability: the setter fires `UPDATE_INVENTORY_ALERTS`, and a worn item would light
+        // DurabilityFrame.
         durability: Some((100, 100)),
         link: Some(format!("|cff1eff00|Hitem:{item_id}:0:0:0|h[{name}]|h|r")),
         ..Default::default()
@@ -2036,7 +1341,7 @@ fn bag_slot(item_id: u32, name: &str, count: u32) -> benilla_ui::script::Contain
     }
 }
 
-/// One seated spellbook slot — the fields a book reader actually reads, defaulted otherwise.
+/// One seated spellbook slot: the fields a book reader reads, defaulted otherwise.
 fn spell_slot(spell_id: u32, name: &str, rank: Option<&str>) -> benilla_ui::script::SpellSlotView {
     benilla_ui::script::SpellSlotView {
         spell_id,
@@ -2060,40 +1365,32 @@ fn globals_of(script: &UiScript) -> BTreeSet<String> {
         .collect()
 }
 
-/// What a manifest entry that does not resolve actually is — see [`AddonReport::absent_own_files`].
+/// What a manifest entry that does not resolve is (see [`AddonReport::absent_own_files`]).
 #[derive(Debug, Default)]
 pub struct AbsentFiles {
-    /// Entries under the addon's **own** folder that the package does not contain.
+    /// Entries under the addon's own folder that the package does not contain.
     pub own: Vec<String>,
-    /// Entries resolving **outside** it, into a folder that is not installed.
+    /// Entries resolving outside it, into a folder that is not installed.
     pub foreign: Vec<String>,
 }
 
-/// What one addon's manifest did: every load failure verbatim, which of them were files that
-/// simply are not there, and whether anything actually **raised**.
+/// What one addon's manifest did: every load failure, which were absent files, and whether anything
+/// raised.
 struct FileLoad {
-    /// Every load failure, in order, unchanged in content and meaning (1213: `errors` is never
-    /// quietly shrunk — every past record's number is still readable off this list).
+    /// Every load failure, in order, unchanged.
     errors: Vec<String>,
-    /// The subset of [`Self::errors`] that is a named file the provider does not have, split by
-    /// whose package is incomplete.
+    /// The subset of [`Self::errors`] that names a file the provider does not have, split by whose
+    /// package is incomplete.
     absent: AbsentFiles,
-    /// **Did anything raise, fail to parse, or drop a frame** — the question
-    /// [`AddonReport::loaded`] asks (decision 2155).
-    ///
-    /// It is `false` for an addon whose only failures are absent files, because on the reference
-    /// that addon *loads*: `0x6edaa0` logs `"Couldn't open %s"` and returns null, and the walk
-    /// carries on to the next manifest entry with nothing raised (the same rule 2107 unified for
-    /// the two loaders that reach it from Lua). Until this existed the survey scored 24 corpus
-    /// addons as not surviving a session start on nothing but a locale file their own zip omits,
-    /// FuBar and 22 of its plugins among them.
+    /// Anything raised, failed to parse or dropped a frame ([`AddonReport::loaded`]). False when
+    /// the only failures are absent files: `0x6edaa0` logs `"Couldn't open %s"`, returns null, and
+    /// the walk carries on.
     raised: bool,
 }
 
-/// Run the addon's manifest through the same two arms the real loader uses — `.lua` as a chunk,
-/// anything else as FrameXML — in the client's **install-relative** path space (decision 2155:
-/// `Interface/AddOns/<Folder>`, exactly what `ui_script::addons::Addon::prefix` hands its own
-/// loader, so a chunk name here and a chunk name in a live session are the same string).
+/// Run the addon's manifest through the loader's two arms, `.lua` as a chunk and anything else as
+/// FrameXML, in the install-relative path space (`Interface/AddOns/<Folder>`, as
+/// `ui_script::addons::Addon::prefix`), so chunk names match a live session's.
 fn load_addon_files(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> FileLoad {
     let provider = |req: &str| -> Option<Vec<u8>> { read_under(root, req) };
     let base = addon_base(name);
@@ -2104,11 +1401,9 @@ fn load_addon_files(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> Fi
         let path = benilla_ui::loader::join_ref(&base, file);
         let Some(bytes) = read_under(root, &path) else {
             errors.push(format!("{file}: not found"));
-            // WHOSE package is incomplete. `join_ref` has already collapsed the `..`s the way the
-            // client does (`0x6ede10`), so the resolved path is what the real file layer would be
-            // handed — and an entry that still points inside the addon's own folder is the addon
-            // shipping a manifest it does not satisfy, while one pointing out of it wants a
-            // neighbour that is not installed.
+            // Whose package is incomplete: `join_ref` has collapsed the `..`s as the 1.12 client
+            // does (`0x6ede10`), so a path still inside the addon's folder is its own manifest
+            // unsatisfied, and one outside it wants a neighbour.
             let own = path
                 .strip_prefix(base.as_str())
                 .is_some_and(|rest| rest.starts_with('/'));
@@ -2120,11 +1415,9 @@ fn load_addon_files(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> Fi
             continue;
         };
         if is_lua(file) {
-            // Named as the client names it, so the survey sees what a player would: an addon
-            // that PARSES a traceback for its own folder (the whole FuBar family) needs the real
-            // `Interface\AddOns\<Folder>\<File>` shape, not mlua's Rust-caller default. Built
-            // from the RESOLVED path, like the loader's own `<Script file=>` naming — one rule,
-            // so the two doors into a VM cannot disagree about what a file is called (2155).
+            // Named as the 1.12 client names it (`@Interface\AddOns\<Folder>\<File>`, from the
+            // resolved path, as the loader names `<Script file=>`): the FuBar family parses
+            // tracebacks for its own folder.
             if let Err(e) = script.run_chunk_named(&bytes, &format!("@{}", path.replace('/', "\\")))
             {
                 errors.push(format!("{file}: {e}"));
@@ -2135,16 +1428,13 @@ fn load_addon_files(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> Fi
         match benilla_ui::framexml::parse(&benilla_ui::source::decode(&bytes)) {
             Ok(doc) => {
                 let report = benilla_ui::loader::load_in(script, &doc, &path, &provider);
-                // Retained with the file prefix so the survey's `warnings` column can see them
-                // (2135); they were dropped with the report before that, which is why an
-                // unresolved `inherits=` scored as a clean load.
+                // Retained with the file prefix, so the `warnings` column sees them.
                 for w in report.warnings {
                     script.report_warning(&format!("{file}: {w}"));
                 }
-                // A file the DOCUMENT named and the provider does not have — the `.toc` arm's rule
-                // one level down (decision 2155). Recorded as absent, under the same own/foreign
-                // split, and never as something that raised: the reference logs `Couldn't open %s`
-                // for an `<Include>` and `Error loading %s` for a `<Script file=>`, and carries on.
+                // A file the document named that the provider lacks: recorded as absent, own or
+                // foreign, never as raised; the 1.12 client logs `Couldn't open %s` for an
+                // `<Include>` and `Error loading %s` for a `<Script file=>`, and carries on.
                 for m in report.missing_files {
                     let own = m
                         .split_once("no provider hit for \"")
@@ -2185,45 +1475,25 @@ fn is_lua(entry: &str) -> bool {
         .is_some_and(|(_, ext)| ext.eq_ignore_ascii_case("lua"))
 }
 
-/// One addon file, read **through the client's own reader** — the loose AddOns tree, then the
-/// player's patch chain ([`crate::ui_script::addons::read_addon_file`], decision 2155).
-///
-/// It delegates rather than re-implementing, and that is the whole point of it still existing as a
-/// name: this was a private copy of the loader's `read_under`, and a copy of a resolution rule is
-/// a copy that drifts. It had already drifted — the client resolves `..\Blizzard_AuctionUI\…`
-/// and `..\..\FrameXML\…` off the chain and this could not, so the survey reported two addon
-/// families as broken packages when the miss was the instrument's.
-///
-/// **Bytes, like the loader's** (decision 1193). Until then this function carried a private
-/// lossy-UTF-8 + BOM-strip of its own, so the harness could survey files the *client* refused to
-/// load — an instrument reporting on a world its host could not reach, which is the wrong way
-/// round. The client reads bytes now, so the harness can simply read bytes too, and the one place
-/// that still needs text ([`read_text`]) says so.
+/// One addon file as bytes, through the client's own reader: the loose AddOns tree, then the
+/// player's patch chain ([`crate::ui_script::addons::read_addon_file`]).
 fn read_under(root: &Path, rel: &str) -> Option<Vec<u8>> {
     crate::ui_script::addons::read_addon_file(root, rel)
 }
 
-/// Where one addon's files sit in the install's path space — `Interface/AddOns/<Folder>`.
-///
-/// The survey's copy of [`crate::ui_script::addons::Addon::prefix`], and it must stay its copy:
-/// every path this module builds is handed to the same reader and named by the same rule, so a
-/// divergence here is a survey measuring a client nobody runs.
+/// Where one addon's files sit in the install's path space, `Interface/AddOns/<Folder>`; must match
+/// [`crate::ui_script::addons::Addon::prefix`].
 fn addon_base(name: &str) -> String {
     format!("Interface/AddOns/{name}")
 }
 
-/// [`read_under`] for the **source scanner**, which greps text rather than running it.
+/// [`read_under`] as text, for the source scanner.
 fn read_text(root: &Path, rel: &str) -> Option<String> {
     read_under(root, rel).map(|b| benilla_ui::source::decode(&b).into_owned())
 }
 
-/// Names the addon calls like functions that the VM does not have.
-///
-/// Two subtractions matter and both are easy to get wrong: the addon's **own** definitions (a
-/// helper it declares and calls is not a missing API), and Lua's **locals** — `local Foo = function`
-/// then `Foo()`. The leading-capital filter alone does not cover the second, because a local can be
-/// capitalised, and for a long time this list's top five rows were exactly that mistake (see
-/// [`scan_lua`]'s assignment pass). Both `local function Foo` and `local Foo = …` are credited now.
+/// Names the addon calls like functions that the VM does not have, minus its own definitions and
+/// its locals (`local function Foo` and `local Foo = …`, capitalised or not).
 fn missing_calls(
     root: &Path,
     name: &str,
@@ -2253,20 +1523,15 @@ fn missing_calls(
             .filter(|n| !known.contains(n) && !defined.contains(n))
             .collect()
     };
-    // The METHOD candidates are returned raw rather than resolved here: `known` is a set of
-    // globals and a method is not one, so the only honest oracle is the VM itself
-    // ([`widget_method_kinds`]). Subtracted here is the half a *scanner* can answer — the
-    // names this addon's own source binds as fields on its own tables.
-    // Split, not filtered away: a name the addon feature-tests is not a blocker, but losing it
-    // entirely would be the silent under-report this instrument keeps getting caught in — 60
-    // corpus addons guard `SetTopLevel`, which is a real widget method we do not have.
+    // Method candidates stay raw: `known` holds globals, so only the VM ([`widget_method_kinds`])
+    // can answer a method. Subtracted here are the names the addon or its dependencies define; the
+    // feature-tested ones are split off, not dropped.
     let (wanted_methods, tested_methods): (BTreeSet<String>, BTreeSet<String>) = methods
         .into_iter()
         .filter(|n| !defined_methods.contains(n) && !dep_methods.contains(n))
         .partition(|n| !tested_fields.contains(n));
-    // Kept as separate lists, not one, for 1207's reason: shapes ranked together mis-rank. A
-    // missing FUNCTION is a verb to write in Rust; a missing FRAME or TABLE is FrameXML to
-    // transcribe; a missing METHOD is a widget binding — three queues, three places.
+    // Three queues: a missing function is a verb to write, a missing frame or table is FrameXML to
+    // transcribe, a missing method is a widget binding.
     Wants {
         missing_globals: absent(called),
         missing_tables: absent(indexed),
@@ -2278,17 +1543,13 @@ fn missing_calls(
     }
 }
 
-/// What one addon's source scan wants — [`missing_calls`]' result.
-///
-/// A struct rather than the tuple this was: the per-kind census took it from four members to seven,
-/// and four of those are `BTreeSet<String>`-shaped, which is how the wrong one gets passed at a
-/// call site and nobody sees it. Same reasoning as [`Scan`]'s own.
+/// What one addon's source scan wants.
 struct Wants {
     missing_globals: Vec<String>,
     missing_tables: Vec<String>,
-    /// Method names the addon calls and does not define — the census's question set.
+    /// Method names the addon calls and does not define: the census's question set.
     wanted_methods: BTreeSet<String>,
-    /// ...and the half it feature-tests first, which is not a blocker.
+    /// ...and those it feature-tests first, which are not blockers.
     tested_methods: BTreeSet<String>,
     kind_calls: BTreeSet<(String, String)>,
     global_calls: BTreeSet<(String, String)>,
@@ -2307,12 +1568,8 @@ fn refs_in_xml(text: &str) -> Vec<String> {
     out
 }
 
-/// Blank out `<!-- … -->`, preserving line structure — run over an XML file **before**
-/// [`strip_lua_noise`], which cannot see them.
-///
-/// An unterminated `<!--` swallows the rest of the file, which is what a real XML parser does with
-/// it too: the document is malformed and there is no honest way to guess where the comment meant
-/// to stop.
+/// Blank out `<!-- … -->`, keeping newlines; run over an XML file before [`strip_lua_noise`], which
+/// cannot see them. An unterminated `<!--` swallows the rest of the file, as an XML parser does.
 fn strip_xml_comments(text: &str) -> String {
     let mut out = String::with_capacity(text.len());
     let mut rest = text;
@@ -2321,7 +1578,7 @@ fn strip_xml_comments(text: &str) -> String {
         let after = &rest[open + 4..];
         match after.find("-->") {
             Some(close) => {
-                // Keep the newlines so anything reporting a line still reports a real one.
+                // Keep the newlines so a reported line is still a real one.
                 out.extend(after[..close].chars().filter(|c| *c == '\n'));
                 rest = &after[close + 3..];
             }
@@ -2335,27 +1592,15 @@ fn strip_xml_comments(text: &str) -> String {
     out
 }
 
-/// Blank out Lua comments and string literals, preserving line structure.
-///
-/// **This is not tidying — it is the difference between a signal and a list of names.** Without
-/// it the ranked demand is topped by `Author`, `Iriel`, `Tekkub` and `Knight`: words inside
-/// `-- credits` comments and `"..."` messages that happen to sit before a `(`. Measured on the
-/// vanilla corpus, stripping removes over a thousand phantom call targets, and every one of the
-/// top four was one.
+/// Blank out Lua comments and string literals, keeping newlines, so words in credits comments and
+/// messages are not read as call targets.
 fn strip_lua_noise(text: &str) -> String {
     strip_lua(text, false)
 }
 
-/// [`strip_lua_noise`] with the string **contents kept** — comments still go.
-///
-/// Exactly one question needs this, and it is the one the per-kind census is built on: the widget
-/// kind in `CreateFrame("MessageFrame", …)` lives *inside* a string literal, which the ordinary
-/// stripper blanks before anything can read it. Reading the raw file instead would count a
-/// commented-out `CreateFrame` — the mistake 1218 is about, where five words of GPL boilerplate
-/// topped a ranking — so the comments go and only the literals stay.
-///
-/// It is never used for the *call-site* scan ([`scan_lua`], [`attribute_calls`]): a name inside a
-/// string would read as an identifier there, which is the same fault the other way round.
+/// [`strip_lua_noise`] with string contents kept, comments still gone: the kind in
+/// `CreateFrame("MessageFrame", …)` is inside a literal. Never used for the call-site scan
+/// ([`scan_lua`], [`attribute_calls`]), where a name inside a string would read as an identifier.
 fn strip_lua_comments_only(text: &str) -> String {
     strip_lua(text, true)
 }
@@ -2429,14 +1674,9 @@ fn strip_lua(text: &str, keep_strings: bool) -> String {
     out
 }
 
-/// [`scan_lua`] over one source file, stripped according to what kind of file it is.
-///
-/// An XML file is scanned as Lua on purpose — its `<Script>` CDATA and its `<OnLoad>` handler
-/// bodies ARE Lua, and skipping the file would lose them. But `strip_lua_noise` only knows `--` and
-/// `[[ ]]`, so an `<!-- … -->` header survived it whole. XML attribute values happen to be blanked
-/// already (they are `"…"`, which the Lua string rule eats) and tag names are never followed by
-/// `(`/`.`/`:` — the comment was the entire hole, and it was enough to put five license-boilerplate
-/// words at the top of the frames/tables ranking (decision 1218).
+/// [`scan_lua`] over one source file. An XML file is scanned as Lua (its `<Script>` and handler
+/// bodies are Lua) after its `<!-- … -->` comments are blanked; its attribute values are `"…"`,
+/// which the Lua string rule blanks.
 fn scan_source(path: &str, text: &str, scan: &mut Scan) {
     let text: std::borrow::Cow<'_, str> = if is_lua(path) {
         std::borrow::Cow::Borrowed(text)
@@ -2444,17 +1684,13 @@ fn scan_source(path: &str, text: &str, scan: &mut Scan) {
         std::borrow::Cow::Owned(strip_xml_comments(text))
     };
     scan_lua(&text, scan);
-    // The receiver pass is per FILE, never per addon: a `local f = CreateFrame("MessageFrame")` in
-    // one file says nothing about an `f` in the next, and pretending otherwise is how an
-    // attribution becomes fiction.
+    // The receiver pass is per file: a `local f` in one file says nothing about an `f` in the next.
     scan_receivers(&text, scan);
 }
 
-/// Every kind `CreateFrame` accepts, in `frame_kind_from_str`'s own spelling — the probe set of the
-/// widget-method census, and the vocabulary [`UiScript::widget_kind`] answers in.
-///
-/// A kind that is refused is simply skipped by the oracle, so this list going stale narrows the
-/// probe set rather than producing a wrong answer.
+/// Every kind `CreateFrame` accepts, in `frame_kind_from_str`'s spelling: the census's probe set
+/// and the vocabulary [`UiScript::widget_kind`] answers in. A refused kind is skipped by the
+/// oracle.
 const PROBE_FRAME_KINDS: &[&str] = &[
     "Frame",
     "Button",
@@ -2474,44 +1710,25 @@ const PROBE_FRAME_KINDS: &[&str] = &[
     "Minimap",
 ];
 
-/// **Type the receiver of a `:` call where the file says what it is** — the whole basis of the
-/// per-kind census.
+/// Type the receiver of a `:` call where the file says what it is, for the per-kind census. Two
+/// shapes are typed:
 ///
-/// The census's oracle used to ask "does *any* widget answer this name", and decision 1228 is the
-/// record of what that cost: `MessageFrame:AddMessage` scored **zero** for as long as it existed,
-/// because the ScrollingMessageFrame probe answered the name, while three corpus addons had
-/// `UIErrorsFrame:AddMessage` as their first load error. A verb wired to one class and forgotten on
-/// its sibling is exactly the shape an ANY-kind answer cannot see. The only fix is to ask the
-/// question per kind, and that needs a receiver type.
+/// - a local or plain global bound from a widget factory (`local f = CreateFrame("Frame")`,
+///   `f:CreateTexture()`, `f:CreateFontString()`);
+/// - a published name, resolved later by [`UiScript::widget_kind`] against our own object graph,
+///   which is where the addon's call really lands.
 ///
-/// A static scan cannot type an arbitrary expression, so this types the two shapes that carry the
-/// corpus and says nothing about the rest:
-///
-/// - a **local (or plain global) bound from a widget factory** — `local f = CreateFrame("Frame")`,
-///   `local t = f:CreateTexture()`, `local fs = f:CreateFontString()`;
-/// - a **published name**, resolved later against the live arena by [`UiScript::widget_kind`] —
-///   `UIErrorsFrame:AddMessage(…)` is a MessageFrame call because our `UIErrorsFrame` *is* one.
-///   That is deliberately our object graph, not the reference's: if we declared it a plain
-///   `<Frame>`, the addon's call really would land on a plain Frame, and the census should say so.
-///
-/// Everything else — `self:Foo()`, `this:Foo()`, `a.b:Foo()`, `getglobal(n):Foo()` — is left
-/// **untyped on purpose** and reported as such ([`AddonReport::ambiguous_methods`]), because
-/// swallowing it as "some kind has it, so fine" is the exact blindness this is here to end.
+/// `self:Foo()`, `this:Foo()`, `a.b:Foo()` and `getglobal(n):Foo()` stay untyped and are reported
+/// ([`AddonReport::ambiguous_methods`]).
 fn scan_receivers(text: &str, scan: &mut Scan) {
-    // Pass 1 needs the string literal inside `CreateFrame("MessageFrame")`, which the ordinary
-    // stripper blanks; pass 2 must NOT see identifiers inside strings. Two texts, one file.
+    // Pass 1 needs the literal inside `CreateFrame("MessageFrame")`, which the ordinary stripper
+    // blanks; pass 2 must not see identifiers inside strings.
     let typed = local_widget_kinds(&strip_lua_comments_only(text));
     attribute_calls(&strip_lua_noise(text), &typed, scan);
 }
 
-/// Identifiers this file binds to a widget of a known kind — `Some(kind)`, or `None` for a name the
-/// file also binds to something else (and therefore cannot be typed).
-///
-/// **Every binding of a name must agree, and a name that is ever a loop variable or a function
-/// parameter is out.** Without that, one `local frame = CreateFrame("Frame")` at file top types
-/// every `frame:Method()` in the file — including the `frame` that is a *parameter* of a helper
-/// three functions down, holding whatever the caller passed. That is how an attribution pass
-/// invents rows, and the corpus is full of exactly that naming.
+/// Identifiers this file binds to a widget of a known kind: `Some(kind)`, or `None` for a name
+/// whose bindings disagree or that is ever a loop variable or function parameter.
 fn local_widget_kinds(text: &str) -> BTreeMap<String, Option<&'static str>> {
     let mut out: BTreeMap<String, Option<&'static str>> = BTreeMap::new();
     let mut bind = |name: &str, kind: Option<&'static str>| match out.get(name) {
@@ -2530,16 +1747,13 @@ fn local_widget_kinds(text: &str) -> BTreeMap<String, Option<&'static str>> {
         let lhs = line[..eq].trim();
         let lhs = lhs.strip_prefix("local ").unwrap_or(lhs).trim();
         if !is_ident(lhs) {
-            continue; // a comma list, a dotted field, an index — not a name we can follow
+            continue; // a comma list, a dotted field or an index: not a name we can follow
         }
         bind(lhs, widget_kind_of_expression(&line[eq + 1..]));
     }
-    // The POISON pass, over the whole file rather than line by line: every name that is ever a
-    // `for` variable or a function parameter is struck out, wherever it was bound. Without it one
-    // `local frame = CreateFrame("Frame")` at file top types every `frame:Method()` below —
-    // including the `frame` that is a *parameter* of a helper three functions down, holding
-    // whatever its caller passed. An untyped name costs a row in the ambiguous table; a wrongly
-    // typed one is fiction in the ranking, which is the error this whole arc keeps paying for.
+    // Over the whole file: a name ever bound by `for` or as a function parameter is untyped
+    // wherever it is bound, so a file-top `local frame = CreateFrame("Frame")` does not type a
+    // helper's `frame`.
     for name in binder_names(text) {
         bind(&name, None);
     }
@@ -2580,7 +1794,7 @@ fn binder_names(text: &str) -> BTreeSet<String> {
     };
     for i in 0..b.len() {
         if word_at(i, "for") {
-            // `for i = 1, n do` and `for k, v in pairs(t) do` — the header ends at the `=`/`in`.
+            // `for i = 1, n do` and `for k, v in pairs(t) do`: the header ends at the `=`/`in`.
             let rest: String = b[i + 3..].iter().take(200).collect();
             let head = rest
                 .find(" in ")
@@ -2601,14 +1815,11 @@ fn binder_names(text: &str) -> BTreeSet<String> {
     out
 }
 
-/// The widget kind a right-hand side **provably** produces, or `None`.
-///
-/// Only the factory calls, and only with a literal kind: `CreateFrame(kind, …)` with a variable
-/// first argument is exactly as untypable as `getglobal(n)` and is treated the same.
+/// The widget kind a right-hand side provably produces: a factory call with a literal kind, never
+/// `CreateFrame(kind, …)` with a variable first argument.
 fn widget_kind_of_expression(rhs: &str) -> Option<&'static str> {
-    // This is the ONE pass that reads un-blanked string literals, so it is also the one pass that
-    // has to check it is not standing *inside* one: `local x = "CreateFrame('Button')"` types
-    // nothing. An odd number of quotes before the match is the cheap, deterministic test.
+    // The one pass that reads string literals, so a match inside one (`"CreateFrame('Button')"`)
+    // types nothing; an odd count of quotes before the match is the test.
     let outside_string =
         |i: usize| rhs[..i].chars().filter(|c| *c == '"' || *c == '\'').count() % 2 == 0;
     if let Some(i) = rhs
@@ -2616,7 +1827,7 @@ fn widget_kind_of_expression(rhs: &str) -> Option<&'static str> {
         .find(|(i, _)| outside_string(*i))
     {
         let i = i.0;
-        // Not `lib.CreateFrame(...)` — a qualified call is some other function of the same name.
+        // Not `lib.CreateFrame(...)`: a qualified call is another function of the same name.
         let qualified = rhs[..i].trim_end().ends_with(['.', ':']);
         let after = &rhs[i + "CreateFrame".len()..];
         if !qualified && after.trim_start().starts_with('(') {
@@ -2630,9 +1841,7 @@ fn widget_kind_of_expression(rhs: &str) -> Option<&'static str> {
         }
         return None;
     }
-    // The two region leaves have factories of their own, and they are worth typing: a region method
-    // called on a region is the single biggest source of "present on some kinds only" noise, and
-    // every one of these moves a row OUT of the ambiguous table by answering it properly.
+    // The two region leaves have factories of their own.
     for (call, kind) in [
         (":CreateTexture", "Texture"),
         (":CreateFontString", "FontString"),
@@ -2660,7 +1869,7 @@ fn attribute_calls(text: &str, typed: &BTreeMap<String, Option<&'static str>>, s
             i += 1;
             continue;
         }
-        // The METHOD name, right of the colon.
+        // The method name, right of the colon.
         let mut m = i + 1;
         while m < src.len() && src[m] == ' ' {
             m += 1;
@@ -2674,8 +1883,7 @@ fn attribute_calls(text: &str, typed: &BTreeMap<String, Option<&'static str>>, s
         while p < src.len() && src[p] == ' ' {
             p += 1;
         }
-        // Same guards as `scan_lua`'s method arm, so the two lists cannot disagree about what a
-        // method call is: it must be called, and it must be capitalised.
+        // Same guards as `scan_lua`'s method arm: called, and capitalised.
         if name.is_empty()
             || p >= src.len()
             || src[p] != '('
@@ -2684,8 +1892,8 @@ fn attribute_calls(text: &str, typed: &BTreeMap<String, Option<&'static str>>, s
             i += 1;
             continue;
         }
-        // The RECEIVER, left of the colon: a bare identifier and nothing else. `a.b:C()`,
-        // `getglobal(n):C()` and `t[1]:C()` are all real corpus shapes and none of them is typable.
+        // The receiver, left of the colon: a bare identifier only; `a.b:C()`, `getglobal(n):C()`
+        // and `t[1]:C()` are not typable.
         let mut r = i;
         while r > 0 && src[r - 1] == ' ' {
             r -= 1;
@@ -2704,14 +1912,12 @@ fn attribute_calls(text: &str, typed: &BTreeMap<String, Option<&'static str>>, s
                 Some(Some(kind)) => {
                     scan.kind_calls.insert(((*kind).to_string(), name));
                 }
-                // The file demonstrably rebinds this name, so it is untypable HERE — and it must
-                // not fall through to the published-name lookup either, or a local called `Minimap`
-                // would be answered by the global of that name.
+                // The file rebinds this name, so it is untypable here and must not fall through to
+                // the published-name lookup (a local called `Minimap` is not the global).
                 Some(None) => {
                     scan.loose_methods.insert(name);
                 }
-                // The receiver might still be a PUBLISHED widget — but only the live arena knows,
-                // so the name travels to Rust rather than being guessed here.
+                // Possibly a published widget; only the live arena knows.
                 None => {
                     scan.global_calls.insert((receiver, name));
                 }
@@ -2722,40 +1928,30 @@ fn attribute_calls(text: &str, typed: &BTreeMap<String, Option<&'static str>>, s
 }
 
 /// What one pass of [`scan_lua`] found.
-///
-/// **A struct rather than a row of `&mut BTreeSet` out-parameters**, which is what this was: the
-/// scan grew a fourth and fifth set when the widget-method class was made rankable, and five
-/// positionally-identical sets in one signature is how the wrong one gets passed and nobody sees it
-/// — the exact class of silent instrument fault this arc keeps writing records about.
 #[derive(Default)]
 struct Scan {
-    /// `Foo(` — API-shaped call sites. Missing ones become [`AddonReport::missing_globals`].
+    /// `Foo(`: API-shaped call sites, for [`AddonReport::missing_globals`].
     called: BTreeSet<String>,
-    /// `Foo.bar` / `Foo:baz` — names the addon *indexes*. → [`AddonReport::missing_tables`].
+    /// `Foo.bar` / `Foo:baz`: names the addon indexes, for [`AddonReport::missing_tables`].
     indexed: BTreeSet<String>,
-    /// `obj:Name(` — method calls, receiver unknowable. → [`AddonReport::missing_methods`].
+    /// `obj:Name(`: method calls, receiver unknown, for [`AddonReport::missing_methods`].
     methods: BTreeSet<String>,
     /// Globals the addon binds itself, in any of the shapes below.
     defined: BTreeSet<String>,
-    /// FIELDS the addon binds itself — `function T:N`, `function T.N`, `T.N = …`. These are the
-    /// method definitions a scanner *can* see, and subtracting them is what keeps an embedded OO
-    /// library's own `self:Foo()` calls out of the widget-method ranking.
+    /// Fields the addon binds itself (`function T:N`, `function T.N`, `T.N = …`): subtracting them
+    /// keeps an embedded library's own `self:Foo()` calls out of the widget-method ranking.
     defined_methods: BTreeSet<String>,
-    /// Fields the addon READS without calling — `if self.OnMouseUp then`. A feature-tested method
-    /// is one the addon has already written a fallback for, so it is not a blocker; see the arm
-    /// that fills this for the two library idioms that made the rule necessary.
+    /// Fields the addon reads without calling (`if self.OnMouseUp then`): feature tests, not
+    /// blockers.
     tested_fields: BTreeSet<String>,
-    /// `(kind, method)` — call sites [`scan_receivers`] could TYPE from the file itself, because
-    /// the receiver was bound by a widget factory: `local f = CreateFrame("MessageFrame")` then
-    /// `f:AddMessage(…)`. → [`AddonReport::kind_missing_methods`].
+    /// `(kind, method)`: call sites [`scan_receivers`] typed from a widget-factory binding in the
+    /// file, for [`AddonReport::kind_missing_methods`].
     kind_calls: BTreeSet<(String, String)>,
-    /// `(receiver name, method)` — the receiver is a bare identifier the file does not bind, so it
-    /// may be a **published** widget. Only the live arena can say ([`UiScript::widget_kind`]), so
-    /// the pair travels to Rust unresolved.
+    /// `(receiver name, method)`: a bare receiver the file does not bind, possibly a published
+    /// widget ([`UiScript::widget_kind`]), resolved later.
     global_calls: BTreeSet<(String, String)>,
-    /// Methods called on a receiver nothing can type — `self:Foo()`, `a.b:Foo()`,
-    /// `getglobal(n):Foo()`. The size of this set is the honest measure of how much the per-kind
-    /// census is *guessing about*, and it is why [`AddonReport::ambiguous_methods`] exists.
+    /// Methods called on a receiver nothing can type (`self:Foo()`, `a.b:Foo()`,
+    /// `getglobal(n):Foo()`), for [`AddonReport::ambiguous_methods`].
     loose_methods: BTreeSet<String>,
 }
 
@@ -2782,8 +1978,7 @@ fn scan_lua(text: &str, scan: &mut Scan) {
     let mut i = 0;
     while i < bytes.len() {
         if bytes[i].is_alphabetic() || bytes[i] == '_' {
-            // A qualified name (`self.foo`, `string.format`) is not a global call site — skip the
-            // whole chain, except the `C_Thing.Verb` shape which IS one.
+            // A qualified name (`self.foo`, `string.format`) is not a global call site.
             let prev = if i > 0 { bytes[i - 1] } else { '\0' };
             let qualified = prev == '.' || prev == ':';
             let (word, next) = ident(i);
@@ -2795,63 +1990,29 @@ fn scan_lua(text: &str, scan: &mut Scan) {
             if !qualified && j < bytes.len() && bytes[j] == '(' && capitalised {
                 called.insert(word.clone());
             }
-            // **`obj:Name(` — the widget-method class**, and the third thing an addon can want
-            // that we might not have. It is neither a global nor an indexed table, so neither arm
-            // above can see it, and until this existed the only trace a missing method left was a
-            // ranked error row reading `attempt to call method 'X' (a nil value)` — with the name
-            // collapsed away by the normalisation.
-            //
-            // The receiver is deliberately ignored: a static scan cannot type `obj`. The same
-            // leading-capital guard as the other two arms is the only filter, and it is doing the
-            // same work — every widget method in the 1.12 surface is capitalised, while an
-            // addon's private `obj:doThing()` helpers usually are not.
+            // `obj:Name(`: a widget method. The receiver is ignored (a static scan cannot type it);
+            // the leading capital is the filter, since every 1.12 widget method is capitalised.
             if prev == ':' && j < bytes.len() && bytes[j] == '(' && capitalised {
                 methods.insert(word.clone());
             }
             if prev == '.' {
                 let assigned = bytes.get(j) == Some(&'=') && bytes.get(j + 1) != Some(&'=');
                 if assigned {
-                    // `T.Name = …` — a field the addon binds on a table it already has. `f.Update
-                    // = function` is the corpus's other way of writing a method, and without
-                    // crediting it every subsequent `f:Update()` would read as a widget binding we
-                    // lack.
+                    // `T.Name = …`: a field the addon binds, the corpus's other way of writing a
+                    // method (`f.Update = function`).
                     defined_methods.insert(word.clone());
                 } else if bytes.get(j) != Some(&'(') {
-                    // **A field the source READS rather than calls is a feature test, and a
-                    // feature-tested method is by definition not a blocker** — the addon has
-                    // already written the branch it takes when the method is absent.
-                    //
-                    // This is not a heuristic dressed as a rule; it is the corpus's dominant idiom,
-                    // verbatim, in the two libraries that between them owned ten of this ranking's
-                    // top sixteen rows:
-                    //
-                    //     if type(self.OnMouseUp) == "function" then self:OnMouseUp(arg1) end
-                    //         -- FuBarPlugin-2.0.lua:768
-                    //     elseif type(self) == "table" and self.CompareTo then
-                    //         return self:CompareTo(other) == 0
-                    //         -- AceOO-2.0.lua:353
-                    //
-                    // Neither `OnMouseUp` nor `CompareTo` is defined anywhere in the corpus: they
-                    // are optional callbacks a *plugin author* may supply, dispatched by hand.
-                    // They are not widget methods, they are not missing, and no amount of
-                    // definition-scanning could ever have subtracted them — the definition does not
-                    // exist. What does exist, one line up, is the addon saying it can live without.
-                    //
-                    // A dotted CALL (`MyLib.Helper()`) is neither read nor test and lands in
-                    // neither set: it is a plain function call through a table, already the
-                    // `indexed` arm's business.
+                    // A field read rather than called is a feature test, and a feature-tested
+                    // method is not a blocker: the addon has its branch for when it is absent
+                    // (`FuBarPlugin-2.0.lua:768`,
+                    // `if type(self.OnMouseUp) == "function" then self:OnMouseUp(arg1) end`). A
+                    // dotted call is neither.
                     tested_fields.insert(word.clone());
                 }
             }
-            // **A name the addon INDEXES is a surface it expects too**, and this scan was blind to
-            // every one of them. `ColorPickerFrame.func = …`, `GameTooltip:AddLine(…)`,
-            // `ChatFrame1:AddMessage(…)` — a FRAME or a TABLE global, never followed by `(`, so the
-            // call arm above cannot see it. A window **86 corpus addons reach** scored exactly 0 on
-            // the most-wanted list until this arm existed, and the same blindness hid every other
-            // FrameXML frame global.
-            //
-            // Same two guards as the call arm (unqualified, capitalised) and the same `defined`
-            // subtraction, so an addon's own `MyAddon = {}` namespace stays its own.
+            // A name the addon indexes (`ColorPickerFrame.func = …`, `GameTooltip:AddLine(…)`): a
+            // frame or table global it expects. Same guards and `defined` subtraction as the call
+            // arm.
             if !qualified && j < bytes.len() && (bytes[j] == '.' || bytes[j] == ':') && capitalised
             {
                 indexed.insert(word.clone());
@@ -2864,11 +2025,8 @@ fn scan_lua(text: &str, scan: &mut Scan) {
                 if k < bytes.len() && (bytes[k].is_alphabetic() || bytes[k] == '_') {
                     let (fname, mut end) = ident(k);
                     defined.insert(fname);
-                    // `function T:N(`, `function T.N(`, `function A.B.C:D(` — every name after the
-                    // first is a FIELD bound on a table the addon already has, not a global. This
-                    // is how an addon and every embedded Ace/FuBar library declares its methods,
-                    // and it is the single biggest subtraction keeping the widget-method ranking
-                    // from being a list of `AceEvent-2.0`'s verbs.
+                    // `function T:N(`, `function T.N(`, `function A.B.C:D(`: every name after the
+                    // first is a field on a table the addon has, not a global.
                     while end < bytes.len() && (bytes[end] == '.' || bytes[end] == ':') {
                         let (part, next_end) = ident(end + 1);
                         if part.is_empty() {
@@ -2884,24 +2042,10 @@ fn scan_lua(text: &str, scan: &mut Scan) {
         }
         i += 1;
     }
-    // Assignments — `Foo = …`, the other way an addon defines a global it later calls, AND
-    // `local Foo = …`, which is not a global at all and is the reason this scan exists in the
-    // shape it does.
-    //
-    // **The local arm is a correction, and it was worth five wrong rows at the top of `demand`.**
-    // The doc above claims locals are handled by only counting leading-capital names; they are
-    // not, because a local can be capitalised. `local CheckShow = function(self, panelId)` in
-    // `FuBarPlugin-2.0.lua` is called four lines later as `CheckShow(...)`, and the scanner read
-    // that as a missing API in **74 addons** — the corpus's most-wanted global, ahead of anything
-    // real. `DropDownList1_Show`, `WorldFrame_OnMouseDown`, `WorldFrame_OnMouseUp` (60 each) and
-    // `ColorPickerOkayButton_OnClick` (51) are the same `local X = <expr>` shape in Dewdrop-2.0
-    // and AceConsole-2.0. Five rows, 305 addon-mentions, all phantom; the first true row was
-    // `SendAddonMessage` at 24.
-    //
-    // **The trade, stated:** `defined` is addon-wide while a `local` is file-scoped, so an addon
-    // that shadows a real API name in one file now suppresses that name in all of them. That is an
-    // under-report, which is the error this instrument's module doc already chooses to prefer —
-    // and it is bounded by the addon, where the over-report was unbounded.
+    // Assignments: `Foo = …` defines a global, and `local Foo = …` a local, which the capital
+    // filter alone does not exclude (`local CheckShow = function` in `FuBarPlugin-2.0.lua`).
+    // `defined` is addon-wide while a local is file-scoped, so a shadowed API name is hidden
+    // addon-wide: an under-report bounded by the addon.
     for line in text.lines() {
         let t = line.trim_start();
         let body = t.strip_prefix("local ").unwrap_or(t);
@@ -2915,12 +2059,9 @@ fn scan_lua(text: &str, scan: &mut Scan) {
             {
                 continue;
             }
-            // **A self-localisation is not a definition.** `local GetTime = GetTime` — and its
-            // `local a, b = a, b` and `local X = X or {}` cousins — binds the local from the
-            // GLOBAL of the same name, so the global really is demanded and hiding it is exactly
-            // the under-report this pass was supposed to avoid. **143 corpus sites, 41 distinct
-            // names**, and the shape is the performance idiom every library writes at file top, so
-            // it is concentrated on precisely the APIs an addon uses most.
+            // A self-localisation is not a definition: `local GetTime = GetTime` (and
+            // `local a, b = a, b`, `local X = X or {}`) binds the local from the global, which is
+            // therefore demanded.
             if rhs
                 .split(|c: char| !c.is_alphanumeric() && c != '_')
                 .any(|tok| tok == name)
@@ -2932,20 +2073,13 @@ fn scan_lua(text: &str, scan: &mut Scan) {
     }
 }
 
-/// The aggregate 1188 asks for: how many addons want each missing name, most-wanted first.
-///
-/// **This is the number phase 5 is prioritised by** — one addon wanting a verb is a curiosity,
-/// forty wanting it is the next thing to build.
+/// How many addons want each missing global, most-wanted first.
 pub fn demand(reports: &[AddonReport]) -> Vec<(String, usize)> {
     rank(reports, |r| &r.missing_globals)
 }
 
-/// **How many ADDONS want each name**, most-wanted first, ties broken alphabetically — the one
-/// shape every ranking here has, factored out when the fifth arrived.
-///
-/// The unit is deliberately the addon, never the call site: a library file replicated across sixty
-/// folders would otherwise decide the whole ranking by itself (1207), and the queue this feeds is
-/// "how many players notice if we build it", which counts addons.
+/// How many addons want each name, most-wanted first, ties alphabetical. The unit is the addon,
+/// never the call site, so a library replicated across sixty folders does not decide the ranking.
 fn rank(
     reports: &[AddonReport],
     pick: impl Fn(&AddonReport) -> &Vec<String>,
@@ -2964,83 +2098,45 @@ fn rank(
     out
 }
 
-/// [`demand`]'s twin for **templates** (decision 1203) — how many addons name each template we
-/// have never declared, most-wanted first.
-///
-/// The list `CreateFrame`'s fourth argument working made measurable: honouring it moved the
-/// headline by exactly zero, because an unresolved template was never a load error in the first
-/// place. This is what actually stands between an addon and a painted window.
+/// [`demand`] over templates: how many addons name each template we never declared.
 pub fn template_demand(reports: &[AddonReport]) -> Vec<(String, usize)> {
     rank(reports, |r| &r.missing_templates)
 }
 
-/// [`demand`] over [`AddonReport::missing_tables`] — the frames and tables an addon indexes and we
-/// do not have. Its own list because a missing frame is FrameXML to transcribe, not a Rust verb.
+/// [`demand`] over [`AddonReport::missing_tables`]: frames and tables to transcribe.
 pub fn table_demand(reports: &[AddonReport]) -> Vec<(String, usize)> {
     rank(reports, |r| &r.missing_tables)
 }
 
-/// [`demand`] over [`AddonReport::missing_methods`] — **the widget-method queue**, and the axis
-/// this survey was blind to while the arc spent a day building exactly these.
-///
-/// Its own list for the same reason as the other three (1207): the three queues go to different
-/// places. A missing global is a Rust verb to write; a missing frame is FrameXML to transcribe; a
-/// missing method is a widget **binding** — and sometimes not a verb at all but a whole *kind* left
-/// unwired, which is what the head of this list said the first time it was run.
-///
-/// Read [`AddonReport::missing_methods`] before quoting a row: this one over-reports by
-/// construction and the doc there says exactly how far.
+/// [`demand`] over [`AddonReport::missing_methods`]: the widget-method queue. It over-reports; see
+/// that field.
 pub fn method_demand(reports: &[AddonReport]) -> Vec<(String, usize)> {
     rank(reports, |r| &r.missing_methods)
 }
 
-/// [`method_demand`] over [`AddonReport::optional_methods`] — the methods addons **work around**.
-///
-/// Ranked apart from the blocking list on purpose, and never merged into it: nobody is stuck on
-/// these, so mixing them in would rank a name nobody needs above one somebody does. Read as
-/// "implementing this improves N addons silently", not as "N addons are broken".
+/// [`method_demand`] over [`AddonReport::optional_methods`]: methods addons work around, read as
+/// "implementing this improves N addons", not "N addons are broken".
 pub fn optional_method_demand(reports: &[AddonReport]) -> Vec<(String, usize)> {
     rank(reports, |r| &r.optional_methods)
 }
 
-/// [`demand`] over [`AddonReport::kind_missing_methods`] — **the per-kind widget-method queue**,
-/// and the one row shape this whole survey was structurally unable to print until it existed.
-///
-/// Read it before [`method_demand`], not after: a row here names a kind an addon's call actually
-/// lands on, so it is a blocker whether or not some *other* widget answers the same verb. The
-/// `(on …)` tail says which job it is — `(on no kind)` is a verb to write, `(on
-/// ScrollingMessageFrame)` is a verb we already wrote and forgot to wire to its sibling, which is
-/// the `MessageFrame:AddMessage` shape decision 1228 is about.
+/// [`demand`] over [`AddonReport::kind_missing_methods`]: the per-kind widget-method queue, each
+/// row a blocker whatever other kind answers the verb. `(on no kind)` is a verb to write; a named
+/// kind is a verb to wire to its sibling.
 pub fn kind_method_demand(reports: &[AddonReport]) -> Vec<(String, usize)> {
     rank(reports, |r| &r.kind_missing_methods)
 }
 
-/// [`demand`] over [`AddonReport::ambiguous_methods`] — the names whose answer **depends on the
-/// kind** at a call site nothing could type.
+/// [`demand`] over [`AddonReport::ambiguous_methods`]: names whose answer depends on the kind at an
+/// untyped call site, an upper bound.
 ///
-/// An **upper bound**, and it says so in every row: the receiver may well be one of the kinds that
-/// answers. It is printed anyway because the alternative — resolving it against the whole probe set
-/// and calling it present — is exactly how `AddMessage` scored zero while three addons died on it.
-/// Its length is a reading of the *attributor's* reach, not of ours.
-///
-/// **NARROWEST first, then by demand** — the only table here that is not ranked by count alone, and
-/// the ordering is the row's whole usefulness rather than a preference.
-///
-/// Measured on the corpus, demand order puts `StopMovingOrSizing` (122 addons, absent only on the
-/// two region leaves) at the top: an untyped receiver being a Texture *there* is not a thing anyone
-/// writes, so the row is noise by construction — and with 139 rows and a printed head, noise at the
-/// top is the same as hiding the rest. The fewer kinds answer a name, the likelier an untyped
-/// receiver is one of the kinds that does not, and two-kind rows are literally the
-/// `MessageFrame:AddMessage` shape (`AddMessage` is answered by exactly the two message frames).
-/// So the key is the size of the answering set, ascending, then demand.
-///
-/// Nothing is filtered — the wide rows follow in their own demand order, and the printed header
-/// says which half is which.
+/// Ranked narrowest first, then by demand: the fewer kinds answer a name, the likelier an untyped
+/// receiver is one that does not (`AddMessage` is answered by the two message frames only), while a
+/// name absent only on the region leaves (`StopMovingOrSizing`) is noise. Nothing is filtered.
 pub fn ambiguous_method_demand(reports: &[AddonReport]) -> Vec<(String, usize)> {
     let mut rows = rank(reports, |r| &r.ambiguous_methods);
-    // The row TEXT is the sort key, so the ordering and the printed row can never disagree about
-    // how narrow a name is: `only on` is [`only_on`]'s own word for "at most half the kinds", and
-    // that branch never truncates its list, so counting separators recovers the set size exactly.
+    // The row text is the sort key: `only on` is [`only_on`]'s untruncated branch, so counting
+    // separators recovers the set size exactly.
     rows.sort_by_key(|(row, count)| {
         let narrow = row.contains("(only on ");
         (
@@ -3052,24 +2148,14 @@ pub fn ambiguous_method_demand(reports: &[AddonReport]) -> Vec<(String, usize)>
     rows
 }
 
-/// [`template_demand`] over [`AddonReport::missing_inherits`] — the same ranking, the other axis.
+/// [`template_demand`] over [`AddonReport::missing_inherits`].
 pub fn inherits_demand(reports: &[AddonReport]) -> Vec<(String, usize)> {
     rank(reports, |r| &r.missing_inherits)
 }
 
-/// The **first** error of every addon that failed to load, normalised and ranked (decision 1193).
-///
-/// [`demand`]'s twin, and the more useful of the two for a while. `demand` answers *what would an
-/// addon like to call*; this answers **what actually stopped it**, and those are different
-/// questions with different top entries. The first error is the load-bearing one because a chunk
-/// stops at its first raise: everything after it in that file never ran, so ranking all errors
-/// would count the same root cause once per victim.
-///
-/// Normalisation is deliberately crude and deliberately stated: quoted names (`'setn'`,
-/// `'GetMouseFocus'`) collapse to `'X'`, source positions are dropped, and the `<file>: ` prefix
-/// goes. That turns 60 different-looking lines into one row reading `runtime error: 'X' is
-/// obsolete`, which is what made the Lua 5.0/5.1 dialect gap visible at all — before this the
-/// only view was per-addon, where it read as sixty unrelated failures.
+/// The first error of every addon that failed to load, normalised and ranked: a chunk stops at its
+/// first raise, so later errors would count one cause once per victim. Normalisation collapses
+/// quoted names to `'X'`, drops source positions and the `<file>: ` prefix.
 pub fn blockers(reports: &[AddonReport]) -> Vec<(String, usize)> {
     let mut counts: BTreeMap<String, usize> = BTreeMap::new();
     for r in reports.iter().filter(|r| !r.loaded) {
@@ -3082,53 +2168,19 @@ pub fn blockers(reports: &[AddonReport]) -> Vec<(String, usize)> {
     out
 }
 
-/// The addons **behind** one [`blockers`] row, with their verbatim first errors.
+/// The addons behind one [`blockers`] row, with their verbatim errors.
 ///
-/// The ranked table collapses every quoted name to `'X'` on purpose (1193) — that collapse is what
-/// made the Lua-dialect gap readable as one wall instead of sixty. The cost is that reading back
-/// *through* it has been a manual grep every time, and twice this arc that manual step was where
-/// the finding actually was: decision **1206** came from noticing that eleven of fifteen
-/// `bad argument #1 to 'X' (table expected, got nil)` rows were one missing table, and **1210** came
-/// from asking which addons were behind a 74-count row (none: it was a Lua local).
-///
-/// `pattern` is a plain substring match against **the normalised row *or* the raw error text**, and
-/// it is checked against **every** error, not only the ranked one.
-///
-/// **Both halves are corrections, and the first one is why this read-back was blind to an entire
-/// class.** It used to match the normalised row alone — and step 2 of [`normalise_error`] replaces
-/// every quoted name with `'X'`. So the one substring a reader would ever type was the one
-/// substring the matcher deleted before comparing. `--why GetBackdrop` answered `(none)` while
-/// `BuffCheck2/BuffCheck2.lua:448` was dying on `attempt to call method 'GetBackdrop' (a nil
-/// value)`; `--why AddMessage` answered `(none)` with three addons behind it. The instrument even
-/// printed *"matched against the NORMALISED row"* underneath, which reads as an explanation and is
-/// exactly why nobody chased it (1212: a comment that says why a known problem is already handled
-/// is the dangerous kind).
-///
-/// This is not a widget-method bug. **No name of any kind was findable** — not `setn`, not
-/// `SendAddonMessage`, not a file path. The method class is simply the one that is *only* ever
-/// identified by its quoted name, so it is where the hole became impossible to miss.
-///
-/// The second half: a chunk stops at its first raise, but a session start does not — an addon's
-/// handlers keep firing after one of them dies, so the error naming the method can be the fourth in
-/// the list. Searching only the first is the same blindness one level down.
-///
-/// **The ranked correspondence is preserved, which is what makes the read-back trustworthy.** A hit
-/// on the error the tables actually counted (a failed addon's first LOAD error; a loaded addon's
-/// first SESSION error) is labelled `[load]`/`[session]` with no index — so counting the
-/// index-less rows reproduces the ranked row's count exactly. Anything else is `[load #3]`,
-/// `[session #2]`: real, findable, and visibly not part of that count.
+/// `pattern` is a substring matched against the raw error text or its normalised row (which turns
+/// every quoted name into `'X'`), over every error, not only the ranked one. A hit on the error the
+/// tables counted (a failed addon's first load error, a loaded addon's first session error) is
+/// labelled `[load]`/`[session]` with no index, so the index-less rows reproduce the ranked count;
+/// any other is `[load #3]`, `[session #2]`.
 pub fn blocked_by(reports: &[AddonReport], pattern: &str) -> Vec<(String, String)> {
     let mut out = Vec::new();
     for r in reports {
-        // A failed addon is ranked through its LOAD error; one that loaded clean is ranked through
-        // what its handlers raised at session start. Both lists are searched for every addon,
-        // because a reader asking "which addons?" means whichever table they were looking at — and
-        // because an addon that failed to load still runs a session start.
-        //
-        // The USE column is searched too, and its first error IS ranked (its table counts every
-        // addon's first, with no `loaded` filter) — without this, `--why` could not read back the
-        // one column whose rows a human most wants the text of. The UI probe ranks nothing, so its
-        // rows are always indexed.
+        // A failed addon ranks through its load error, a clean one through its first session error;
+        // both lists are searched either way. The use column's first error is ranked too (its table
+        // has no `loaded` filter); the UI probe ranks nothing, so its rows always carry an index.
         let ranked_kind = if r.loaded { "session" } else { "load" };
         for (list, kind) in [
             (&r.errors, "load"),
@@ -3153,31 +2205,8 @@ pub fn blocked_by(reports: &[AddonReport], pattern: &str) -> Vec<(String, String
     out
 }
 
-/// The addons behind one **method-table** row — [`blocked_by`]'s twin for the rankings that are
-/// built by scanning rather than by catching an error.
-///
-/// `blocked_by` reads back through error text; nothing read back through a demand row, and the cost
-/// of that was paid immediately: verifying the per-kind table's own top row (`EditBox:SetFontObject`,
-/// 63 addons) meant patching a debug print into the example and re-running the corpus, because
-/// there was no way to ask *which* 63. "Read the line before ranking" (1207, 1210, 1214, 1227 — four
-/// records in one arc, three of which found fiction at the top of a ranking) is the standing rule
-/// here, and a rule whose only tool is a temporary code edit gets skipped.
-///
-/// A plain substring match against the row as printed, over all four method tables, each hit
-/// labelled with the table it came from — so `--why "EditBox:SetFontObject"` names the addons and
-/// `--why SetFontObject` finds every table that mentions it.
-/// Which addons carry `pattern` in one of the three demand lists — the read-back those rankings
-/// never had.
-///
-/// Every ranked table above is a **count**, and until this existed nothing could ask which addons a
-/// count was made of. That is not a theoretical gap: `GetChannelList` ranked 4 while exactly one
-/// corpus addon's source names it, and establishing that took a hand-rolled grep across a corpus
-/// whose entries are symlinks (so `grep -r` silently reads none of them). A number you cannot open
-/// is a claim rather than a measurement — the same lesson `--why`'s error read-back learned in
-/// 1210/1218/1227, applied to the other three tables.
-///
-/// Matched case-insensitively on a substring, exactly like the error read-back, so a half-remembered
-/// name still finds its row.
+/// Which addons carry `pattern` in one demand list, matched case-insensitively on a substring: the
+/// read-back behind a ranked count.
 pub fn wanters(
     reports: &[AddonReport],
     pattern: &str,
@@ -3195,6 +2224,9 @@ pub fn wanters(
     out
 }
 
+/// The addons behind one method-table row: a case-sensitive substring match against the row as
+/// printed, over all four method tables, each hit labelled with its table, so
+/// `--why "EditBox:SetFontObject"` names the addons and `--why SetFontObject` finds every table.
 pub fn method_rows_matching(reports: &[AddonReport], pattern: &str) -> Vec<(String, String)> {
     let mut out = Vec::new();
     for r in reports {
@@ -3212,14 +2244,12 @@ pub fn method_rows_matching(reports: &[AddonReport], pattern: &str) -> Vec<(Stri
     out
 }
 
-/// [`normalise_error`], public so the report can rank SESSION-start errors with the same collapse
-/// the load-time table uses — one wall must read as one row on both sides of the load boundary.
+/// [`normalise_error`], public so session-start errors rank with the load-time collapse.
 pub fn normalise(raw: &str) -> String {
     normalise_error(raw)
 }
 
-/// The byte index of the next `'` that actually OPENS a quote — one with a non-alphanumeric on at
-/// least one side. See [`normalise_error`] step 2.
+/// The byte index of the next `'` that opens a quote: one without a letter or digit on both sides.
 fn quote_open(s: &str) -> Option<usize> {
     let b = s.as_bytes();
     let mut from = 0usize;
@@ -3236,26 +2266,18 @@ fn quote_open(s: &str) -> Option<usize> {
 }
 
 /// One load error with everything addon-specific removed, so two addons hitting the same wall
-/// produce the same string. See [`blockers`] for why the crudeness is the point.
+/// produce the same string.
 fn normalise_error(raw: &str) -> String {
-    // 1 · Keep from the LAST `error: ` on, which drops every `<file>: <Script file="…">: ` prefix
-    //     without having to know their shapes — and cut mlua's `stack traceback:` tail, which is
-    //     per-addon detail that would split one wall into a dozen rows.
+    // 1 · From the last `error: ` on, which drops every `<file>: <Script file="…">: ` prefix, and
+    //     without mlua's `stack traceback:` tail.
     let core = raw.rfind("error: ").map_or(raw, |i| &raw[i..]);
     let core = core
         .split_once("stack traceback:")
         .map_or(core, |(head, _)| head)
         .trim();
 
-    // 2 · Every quoted name becomes `'X'` — the name is what varies between two addons that hit
-    //     the same wall, and it is already ranked by `demand`. Both quote kinds, because mlua
-    //     writes a chunk name as `[string "MyFrame:OnLoad"]`.
-    //
-    //     **An APOSTROPHE INSIDE A WORD is not a quote.** The reference's own diagnostics are
-    //     written in English — `Couldn't find region named '%s'`, `Couldn't find relative frame:
-    //     %s` — and the `'` in `Couldn't` opened a quote that then swallowed the rest of the line,
-    //     so the row read `Couldn'X'` and named nothing. Letters on both sides is the whole test:
-    //     a real opening quote is preceded by a space, a bracket or the line start.
+    // 2 · Every quoted name becomes `'X'`; both quote kinds, since mlua writes a chunk name as
+    //     `[string "MyFrame:OnLoad"]`. An apostrophe inside a word (`Couldn't`) is not a quote.
     let squashed = core.replace('"', "'");
     let mut collapsed = String::with_capacity(squashed.len());
     let mut rest = squashed.as_str();
@@ -3272,7 +2294,7 @@ fn normalise_error(raw: &str) -> String {
     }
     collapsed.push_str(rest);
 
-    // 3 · Source positions carry no information once the name is gone.
+    // 3 · Source positions carry nothing once the name is gone.
     collapsed
         .split_whitespace()
         .filter(|t| !is_position(t))
@@ -3280,10 +2302,7 @@ fn normalise_error(raw: &str) -> String {
         .join(" ")
 }
 
-/// Is this whitespace-separated token a source position rather than words?
-///
-/// `crates/benilla-ui/src/script/mod.rs:406:305:`, `[string "X"]:2:`, `MyAddon.lua:12:` — all of
-/// them a `<where>:<line>[:<col>]:` tail, which is the only shape mlua emits.
+/// Is this token a source position (`<where>:<line>[:<col>]:`, the only shape mlua emits)?
 fn is_position(tok: &str) -> bool {
     if tok == "[string" {
         return true; // the opening half of mlua's `[string "…"]:N:` chunk name
@@ -3294,7 +2313,7 @@ fn is_position(tok: &str) -> bool {
     if last.is_empty() || !last.chars().all(|c| c.is_ascii_digit()) {
         return false;
     }
-    // `<where>:<line>` is enough; a third field just means a column was included.
+    // `<where>:<line>` is enough; a third field is a column.
     tail.next().is_some()
 }
 
@@ -3302,9 +2321,7 @@ fn is_position(tok: &str) -> bool {
 mod tests {
     use super::*;
 
-    /// Two addons hitting one wall must produce **one** row — that collapse is the whole value of
-    /// [`blockers`], and it is what made the Lua-dialect gap readable as `61` rather than as sixty
-    /// unrelated-looking lines (decision 1193).
+    /// Two addons hitting one wall produce one row.
     #[test]
     fn one_wall_is_one_row_however_it_was_reported() {
         let same = [
@@ -3320,14 +2337,8 @@ mod tests {
         );
     }
 
-    /// **A raise in a DEMAND-LOADED SIBLING is that sibling's row, not the surveyed addon's**
-    /// (decision 2107) — the FuBar shape, verbatim from the corpus.
-    ///
-    /// `FuBar.lua:1034`'s `LoadLoadOnDemandPlugins` demand-loads every installed `FuBar_*` the
-    /// moment any one of them seats, so surveying `FuBar_MoneyFu` runs `FuBar_BattlegroundFu`'s
-    /// file scope. Its embedded `Glory-2.0` wants a `Deformat-2.0` a dozen of its siblings ship and
-    /// it does not — this module's one-VM-per-addon limitation, and `FuBar_BattlegroundFu`'s own
-    /// row, where the survey counts it once. It cost 49 addons their session-start row.
+    /// A raise in a demand-loaded sibling's file (FuBar loads every installed `FuBar_*`,
+    /// `FuBar.lua:1034`) is that sibling's row, not the surveyed addon's.
     #[test]
     fn a_raise_in_another_installed_addons_file_is_that_addons_row() {
         let installed: BTreeSet<String> = ["fubar", "fubar_moneyfu", "fubar_battlegroundfu", "ace"]
@@ -3341,22 +2352,22 @@ mod tests {
             raised_inside_another_addons_own_file(sibling, "FuBar_MoneyFu", &installed),
             "a sibling's own file is the sibling's row"
         );
-        // The surveyed addon's OWN file is always its own row — including a library it embeds
-        // whose folder name is itself an installed addon.
+        // The surveyed addon's own file is its own row, even a library whose folder name is an
+        // installed addon.
         let mine = "runtime error: Interface\\AddOns\\FuBar_MoneyFu\\Libs\\Ace\\Ace.lua:8: boom";
         assert!(!raised_inside_another_addons_own_file(
             mine,
             "FuBar_MoneyFu",
             &installed
         ));
-        // A chunk naming no addon folder at all is KEPT — the surveyed addon drove it.
+        // A chunk naming no addon folder is kept: the surveyed addon drove it.
         let ours = "runtime error: [string \"Frame:OnEvent\"]:2: attempt to index a nil value";
         assert!(!raised_inside_another_addons_own_file(
             ours,
             "FuBar_MoneyFu",
             &installed
         ));
-        // A folder that is not installed is not somebody else's row either.
+        // A folder that is not installed is not another addon's row.
         let stranger = "runtime error: Interface\\AddOns\\NotInstalled\\x.lua:1: boom";
         assert!(!raised_inside_another_addons_own_file(
             stranger,
@@ -3365,13 +2376,8 @@ mod tests {
         ));
     }
 
-    /// **A raise inside a `LoadAddOn` the surveyed addon made is the LOADED addon's row** — even
-    /// when the raise site names no file at all (decision 2107).
-    ///
-    /// An inline `<OnEvent>` body is compiled under the frame's name, so the folder test is blind
-    /// to it. `Stubby.lua:581` demand-loads every addon it finds; Auctioneer's
-    /// `AuctioneerFrame:OnEvent` raises inside that call. Six addons — Stubby and the five that
-    /// pull it in — were failing on that one raise, which Auctioneer's own row already carries.
+    /// A raise inside a `LoadAddOn` the surveyed addon made is the loaded addon's row, even when
+    /// the raise site names no file (`Stubby.lua:581` loading Auctioneer).
     #[test]
     fn a_raise_inside_a_demand_load_belongs_to_the_addon_being_loaded() {
         let installed: BTreeSet<String> = ["stubby", "auctioneer", "enchantrix"]
@@ -3394,7 +2400,7 @@ mod tests {
             raised_inside_another_addons_own_file(through_loadaddon, "Enchantrix", &installed),
             "…and the same for an addon that only pulled Stubby in"
         );
-        // The surveyed addon's OWN frame ABOVE the boundary keeps the raise: it drove it itself.
+        // The surveyed addon's own frame above the boundary keeps the raise.
         let ours_first = "runtime error: [string \"StubbyFrame:OnEvent\"]:2: boom\n\
              stack traceback:\n\
              \tInterface\\AddOns\\Stubby\\Stubby.lua:12: in function 'Stubby.Thing'\n\
@@ -3402,7 +2408,7 @@ mod tests {
         assert!(!raised_inside_another_addons_own_file(
             ours_first, "Stubby", &installed
         ));
-        // No LoadAddOn anywhere: 1226's conservative KEEP is untouched.
+        // No `LoadAddOn` anywhere: the raise is kept.
         let plain = "runtime error: [string \"StubbyFrame:OnEvent\"]:2: boom\n\
              stack traceback:\n\
              \t[C]: in ?";
@@ -3422,16 +2428,7 @@ mod tests {
         );
     }
 
-    /// **An XML license header is not a list of frames**, and for a while it was the top of one.
-    ///
-    /// `.xml` files are scanned as Lua deliberately — `<Script>` CDATA and `<OnLoad>` bodies are
-    /// Lua and skipping the file loses them. But `strip_lua_noise` only knows `--` and `[[ ]]`, so
-    /// a GPL header in an `<!-- … -->` came through whole, and `PURPOSE.  See the` reads exactly
-    /// like a table index. Five of the frames/tables ranking's top rows were this boilerplate
-    /// (decision 1218).
-    ///
-    /// The other half of the claim matters as much: the Lua INSIDE the file must survive, or the
-    /// fix trades a wrong ranking for a blind one.
+    /// An XML comment is not scanned, and the Lua inside the file still is.
     #[test]
     fn an_xml_comment_is_not_scanned_but_the_script_body_is() {
         let xml = "<Ui>\n\
@@ -3460,10 +2457,7 @@ mod tests {
             "the script body must still be scanned: {:?}",
             s.called
         );
-        // ...and the METHOD arm obeys the same stripper. `See the` in that header is a capitalised
-        // word after a word — harmless — but `GameTooltip:AddLine(` inside the CDATA is the shape
-        // the method scan lives on, so both halves are asserted on the same file (1218's rule: a
-        // noise fix that goes blind is worse than the noise).
+        // The method arm obeys the same stripper.
         assert!(
             s.methods.contains("AddLine"),
             "the script body's method call must be scanned: {:?}",
@@ -3471,8 +2465,7 @@ mod tests {
         );
     }
 
-    /// An unterminated `<!--` takes the rest of the file, exactly as a real XML parser does — the
-    /// document is malformed and guessing where the comment meant to stop would invent structure.
+    /// An unterminated `<!--` takes the rest of the file, as an XML parser does.
     #[test]
     fn an_unterminated_xml_comment_swallows_the_rest() {
         let out = strip_xml_comments("Kept.Alpha\n<!-- Dropped.Beta\nDropped.Gamma\n");
@@ -3481,18 +2474,11 @@ mod tests {
             !out.contains("Beta") && !out.contains("Gamma"),
             "got: {out:?}"
         );
-        // Line structure survives, so anything counting lines still counts real ones.
+        // Line structure survives.
         assert_eq!(out.matches('\n').count(), 3);
     }
 
-    /// **A capitalised Lua local is not a missing API**, and for a long time this instrument said
-    /// it was — loudly, at the top of its own most-wanted list.
-    ///
-    /// The shape is `FuBarPlugin-2.0.lua`'s, verbatim: a `local` bound to a function expression and
-    /// called a few lines down. `local function Foo` was already credited; `local Foo = function`
-    /// was not, and the leading-capital filter that was supposed to cover it cannot, because
-    /// nothing stops a local from being capitalised. Five rows and 305 addon-mentions of the
-    /// vanilla corpus's `demand` table were this.
+    /// A capitalised Lua local is not a missing API (`FuBarPlugin-2.0.lua`'s `local X = function`).
     #[test]
     fn a_capitalised_local_is_not_a_missing_global() {
         let mut s = Scan::default();
@@ -3521,13 +2507,7 @@ mod tests {
         );
     }
 
-    /// ...**but a self-localisation is not a definition.** `local GetTime = GetTime` is the
-    /// performance idiom every library writes at file top, and it binds the local from the GLOBAL,
-    /// so the global is still demanded. 143 corpus sites over 41 names — concentrated, by its
-    /// nature, on the APIs an addon leans on hardest.
-    ///
-    /// This is a correction to the fix one commit up: crediting every `local X =` line hid exactly
-    /// the names most worth ranking.
+    /// ...but a self-localisation (`local GetTime = GetTime`) still demands the global.
     #[test]
     fn localising_a_global_still_demands_it() {
         let mut s = Scan::default();
@@ -3554,8 +2534,7 @@ mod tests {
         );
     }
 
-    /// A "not found" has no `error: ` marker and must survive whole — it is a *different* wall
-    /// (a missing file) and collapsing it into the runtime errors would hide it.
+    /// A "not found" has no `error: ` marker and survives whole: a missing file is its own wall.
     #[test]
     fn a_missing_file_stays_its_own_row() {
         assert_eq!(
@@ -3564,8 +2543,7 @@ mod tests {
         );
     }
 
-    /// Only the FIRST error counts, and only from addons that failed — a chunk stops at its first
-    /// raise, so everything after it is a consequence rather than a cause.
+    /// Only the first error of a failed addon counts.
     #[test]
     fn only_the_first_error_of_a_failed_addon_is_counted() {
         let report = |name: &str, loaded: bool, errors: Vec<String>| AddonReport {
@@ -3598,13 +2576,7 @@ mod tests {
 mod dependency_tests {
     use super::*;
 
-    /// **A dependency is loaded before its dependent** — `AddOn_Load 0x51f240`'s own first step,
-    /// and the difference between surveying a real session and surveying a state that cannot occur.
-    ///
-    /// The corpus case this is drawn from: `FuBar_Aspect` declares `## Dependencies: Ace, FuBar`
-    /// and its very first line is `ace:LoadTranslation("FuBar_Aspect")`. Surveyed alone it fails
-    /// on a global its dependency was always going to define — fifteen addons failed that way, on
-    /// us rather than on themselves.
+    /// A dependency is loaded before its dependent, depth-first, as `AddOn_Load` (`0x51f240`) does.
     #[test]
     fn a_dependency_runs_before_the_addon_that_declares_it() {
         let tmp = std::env::temp_dir().join(format!("benilla-harness-deps-{}", std::process::id()));
@@ -3615,8 +2587,8 @@ mod dependency_tests {
             std::fs::write(dir.join(format!("{name}.toc")), toc).unwrap();
             std::fs::write(dir.join(file), body).unwrap();
         };
-        // A library, a middle layer that depends on it, and a leaf that depends on the middle —
-        // so the walk has to be depth-first, not one level.
+        // A library, a middle layer on it and a leaf on the middle, so the walk must be
+        // depth-first.
         write(
             "Lib",
             "## Interface: 11200\nlib.lua\n",
@@ -3645,7 +2617,7 @@ mod dependency_tests {
         );
         assert!(leaf.missing_deps.is_empty());
 
-        // ...and an addon whose dependency is NOT installed still reports it, unchanged.
+        // ...and a dependency that is not installed is still reported.
         write(
             "Orphan",
             "## Interface: 11200\n## Dependencies: Nowhere\norphan.lua\n",
@@ -3659,15 +2631,8 @@ mod dependency_tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
-    /// **A frame is a surface too**, and the scan could not see one until this arm existed.
-    ///
-    /// The corpus spells the colour picker `ColorPickerFrame.func` and
-    /// `ColorPickerFrame:SetColorRGB` — never `ColorPickerFrame(` — so a window **86 addons reach**
-    /// scored exactly 0 on the most-wanted list. Same blindness for `GameTooltip`, `WorldFrame`,
-    /// `ChatFrame1` and every other FrameXML frame global.
-    ///
-    /// The two lists stay separate (1207): a missing function is a Rust verb, a missing frame is
-    /// FrameXML to transcribe.
+    /// An indexed frame (`ColorPickerFrame.func`, `ColorPickerFrame:SetColorRGB`) is a missing
+    /// surface, not a missing function.
     #[test]
     fn an_indexed_frame_is_a_missing_surface_not_a_missing_function() {
         let mut s = Scan::default();
@@ -3700,8 +2665,8 @@ mod dependency_tests {
             vec!["UnitName"],
             "and the lists do not bleed into each other"
         );
-        // `ColorPickerFrame.func = function` is a FIELD the file binds, so `func` is credited as a
-        // definition — while `SetColorRGB` and `AddLine`, which it only calls, are demanded.
+        // `ColorPickerFrame.func = function` binds a field, so `func` is credited; `SetColorRGB`
+        // and `AddLine` are only called, so they are demanded.
         assert_eq!(
             s.methods.iter().map(String::as_str).collect::<Vec<_>>(),
             vec!["AddLine", "SetColorRGB"],
@@ -3714,19 +2679,8 @@ mod dependency_tests {
         );
     }
 
-    /// `blocked_by` matches the row **as printed** *and* the raw error text — and the second half
-    /// is a correction to what this test used to assert.
-    ///
-    /// It pinned `blocked_by(&reports, "tinsert").is_empty()` as *correct*, on the reasoning that
-    /// "the quoted name is already `'X'` in the row the reader is holding". That reasoning describes
-    /// the mechanism accurately and draws the wrong conclusion from it: the normalisation exists so
-    /// sixty lines rank as one **row**, not so a reader is forbidden from searching by **name**.
-    /// Searching by name is in fact the only thing anyone ever does with this — and it silently
-    /// returned nothing every time. `--why GetBackdrop` said `(none)` while an addon was dying on
-    /// `attempt to call method 'GetBackdrop' (a nil value)`.
-    ///
-    /// A test can encode a bug as an invariant, and this one did, which is why the assertion below
-    /// is inverted rather than deleted.
+    /// `blocked_by` matches the row as printed and the raw error text, so a quoted name the
+    /// normalisation collapsed is findable.
     #[test]
     fn blocked_by_reads_back_by_row_and_by_name() {
         let report = |name: &str, loaded: bool, first: &str| AddonReport {
@@ -3755,15 +2709,13 @@ mod dependency_tests {
         ];
         let wall = blocked_by(&reports, "table expected");
         let hits: Vec<&str> = wall.iter().map(|(n, _)| n.as_str()).collect();
-        // The `[load]`/`[session]` tag is part of the row (c91cd11a: "the label says which") —
-        // both of these failed to LOAD, so both read back through the load table.
+        // Both failed to load, so both read back through the load table.
         assert_eq!(
             hits,
             vec!["A [load]", "B [load]"],
             "two different verbs, one wall"
         );
-        // The half that was inverted: the NAME the normalisation collapsed is findable again, and
-        // finds exactly the addon that used it — not the whole wall.
+        // The collapsed name finds exactly the addon that used it.
         let by_name: Vec<String> = blocked_by(&reports, "tinsert")
             .into_iter()
             .map(|(n, _)| n)
@@ -3773,21 +2725,12 @@ mod dependency_tests {
             vec!["A [load]"],
             "a quoted name is what a reader types, and it must reach the addon behind it"
         );
-        // ...and the verbatim error comes back, which is the reason to run it at all.
+        // ...and the verbatim error comes back.
         assert!(wall[0].1.contains("tinsert"));
     }
 
-    /// **A later error is findable, and says so** — the second half of the read-back's blindness.
-    ///
-    /// A chunk stops at its first raise, but a session start does not: handlers keep firing, so the
-    /// error naming the method can be the third in the list. Searching only the first is the same
-    /// hole one level down.
-    ///
-    /// The labelling is the load-bearing part. A hit on the error the tables actually **ranked**
-    /// carries no index, so counting index-less rows reproduces the ranked row's count exactly; a
-    /// later one is `#N` and visibly outside that count. Without that, making the search complete
-    /// would have made the read-back disagree with the table above it, and a reader would have no
-    /// way to tell which was wrong.
+    /// A later error is found and labelled `#N`, outside the ranked count; the ranked one carries
+    /// no index.
     #[test]
     fn a_later_error_is_found_and_labelled_as_not_the_ranked_one() {
         let reports = [AddonReport {
@@ -3822,14 +2765,8 @@ mod dependency_tests {
         );
     }
 
-    /// **A clean load is not a working addon**, and this is the column that can tell the
-    /// difference — the survey's answer to the blind spot four decision records end on.
-    ///
-    /// Three addons, one shape each: one that raises only from its `PLAYER_LOGIN` handler, one that
-    /// raises only from `OnUpdate` (so it needs a tick, not just an event), and one that is clean
-    /// throughout. All three must report `loaded == true`, because **`loaded` still means exactly
-    /// "no LOAD errors"** — changing that would make every number in every past decision record
-    /// incomparable, which is 1209's whole subject.
+    /// A clean load is not a working addon: a raise from a `PLAYER_LOGIN` handler or from
+    /// `OnUpdate` lands in `session_errors`, and `loaded` still counts load errors only.
     #[test]
     fn a_clean_load_is_not_a_working_addon() {
         let tmp =
@@ -3890,45 +2827,9 @@ mod dependency_tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
-    /// **A library another addon embeds is invisible here, and that is the isolation's price.**
-    ///
-    /// The real client loads everything into one Lua state; this harness stands up one VM per
-    /// addon so a failure cannot be attributed to the wrong party (the module doc's first
-    /// section). The cost is exactly this: an addon that ships no libraries and leans on a
-    /// sibling's copy fails here and would work in a real session.
-    ///
-    /// Drawn from `FuBar_CustomMenuFu`, which ships one Lua file, declares
-    /// `## OptionalDeps: Ace2, FuBar`, and calls `AceLibrary("Tablet-2.0")` — a library neither
-    /// installed addon provides. Five corpus addons sit behind that row, and none of them is a gap
-    /// of ours.
-    /// **Every addon in the VM gets its own `ADDON_LOADED`, with its OWN name in `arg1`.**
-    ///
-    /// The survey fired exactly one, carrying the SURVEYED addon's folder. A dependency's
-    /// initialiser is almost always gated on its own name — `Atlas.lua:326` is
-    /// `if (event == "ADDON_LOADED" and arg1 == "Atlas") then Atlas_Init(); end`, and `Atlas_Init`
-    /// is what assigns `AtlasOptions` (l.199) — so a dependency loaded its files and never
-    /// initialised. `FuBar_AtlasFu` then died at `AtlasButton.lua:30` on a nil `AtlasOptions`, and
-    /// the survey recorded that against FuBar_AtlasFu. **The state was one the real client never
-    /// produces**, and it cost 11 addons of the session-start column.
-    ///
-    /// The second assertion is the half that keeps the rule this module already states: a
-    /// dependency's OWN handler raising is the dependency's row, never its consumers'. Those
-    /// events fire outside the error-capture window, so one library's fault cannot be counted once
-    /// per addon that embeds it.
-    /// **A consumer's OWN code raising inside a DEPENDENCY's window is the consumer's row.**
-    ///
-    /// 1226's finding, now enforced. `AceAddon-2.0.lua:104-105` drains its entire `nextAddon` queue
-    /// on ANY `ADDON_LOADED` it sees and calls each consumer's `OnInitialize` there (`:230`). So
-    /// the surveyed addon's own file runs inside a dependency's window — and while attribution was
-    /// by window, those raises were charged to nobody and the whole FuBar/Ace family read as
-    /// surviving when it was not.
-    ///
-    /// Attribution is by the raising CHUNK now, which 1217 made truthful. The fixture is AceAddon's
-    /// shape reduced: the library drains a queue on the first ADDON_LOADED it sees, whoever it
-    /// names, and the consumer's callback raises from the consumer's own file.
-    ///
-    /// The second half is the half that must not regress: the LIBRARY's own raise, in the same
-    /// window, still belongs to the library.
+    /// A consumer's own code raising inside a dependency's `ADDON_LOADED` is the consumer's row:
+    /// AceAddon runs queued consumers' `OnInitialize` on any `ADDON_LOADED` it sees
+    /// (`AceAddon-2.0.lua:104-105`, `:230`). Attribution is by the raising chunk.
     #[test]
     fn a_consumers_raise_inside_a_dependency_window_is_the_consumers_row() {
         let tmp =
@@ -3940,7 +2841,8 @@ mod dependency_tests {
             std::fs::write(dir.join(format!("{name}.toc")), toc).unwrap();
             std::fs::write(dir.join(file), body).unwrap();
         };
-        // AceAddon's shape: drain every queued consumer on the FIRST ADDON_LOADED, whoever it names.
+        // AceAddon's shape: drain every queued consumer on the first `ADDON_LOADED`, whoever it
+        // names.
         write(
             "QueueLib",
             "## Interface: 11200\nlib.lua\n",
@@ -3954,7 +2856,7 @@ mod dependency_tests {
              end\n\
              end)\n",
         );
-        // The consumer queues a callback that raises from ITS OWN file.
+        // The consumer queues a callback that raises from its own file.
         write(
             "QueueUser",
             "## Interface: 11200\n## Dependencies: QueueLib\nuse.lua\n",
@@ -3977,6 +2879,9 @@ mod dependency_tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
+    /// Every addon in the VM gets its own `ADDON_LOADED`, its own name in `arg1`: a dependency's
+    /// initialiser is gated on it (`Atlas.lua:326`). A dependency's own handler raising is the
+    /// dependency's row, never its consumers', since those events fire outside the error mark.
     #[test]
     fn each_loaded_addon_gets_its_own_addon_loaded_event() {
         let tmp = std::env::temp_dir().join(format!(
@@ -3990,7 +2895,8 @@ mod dependency_tests {
             std::fs::write(dir.join(format!("{name}.toc")), toc).unwrap();
             std::fs::write(dir.join(file), body).unwrap();
         };
-        // Atlas's shape, reduced: a library that initialises ONLY on its own ADDON_LOADED.
+        // Atlas's shape (`Atlas.lua:326`): a library that initialises only on its own
+        // `ADDON_LOADED`.
         write(
             "TheLib",
             "## Interface: 11200\nlib.lua\n",
@@ -4001,7 +2907,7 @@ mod dependency_tests {
              if event == \"ADDON_LOADED\" and arg1 == \"TheLib\" then TheLibOptions = {} end\n\
              end)\n",
         );
-        // The consumer reads the library's initialised state on a LATER event, as Atlas's button does.
+        // The consumer reads the library's initialised state on a later event.
         write(
             "TheUser",
             "## Interface: 11200\n## Dependencies: TheLib\nuse.lua\n",
@@ -4010,7 +2916,7 @@ mod dependency_tests {
              TheUserFrame:RegisterEvent(\"PLAYER_LOGIN\")\n\
              TheUserFrame:SetScript(\"OnEvent\", function() local _ = TheLibOptions.anything end)\n",
         );
-        // A library whose own handler blows up — its consumers must not wear it.
+        // A library whose own handler raises: its row, not its consumers'.
         write(
             "BadLib",
             "## Interface: 11200\nbad.lua\n",
@@ -4053,23 +2959,11 @@ mod dependency_tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
-    /// **A dependency's `ADDON_LOADED` lands before the dependent's FIRST LINE runs** (2166).
-    ///
-    /// The reference emits, per addon: its dependencies → its own `.toc` files (`0x51f3fa`) →
-    /// `Bindings.xml` → the SavedVariables chunks → **`ADDON_LOADED` at `0x51f5ad`** — and only
-    /// then moves to the next addon. So by the time a dependent's file scope runs, every
-    /// dependency has already had its own event.
-    ///
-    /// This harness deferred all of them to `drive_session_start` instead, which is a state the
-    /// client never produces and which no earlier test could see: the one above reads the
-    /// dependency's state from a `PLAYER_LOGIN` handler, and that passes either way. **The
-    /// discriminating read is at FILE SCOPE**, and it is the corpus's own shape — `KTMAutoHider`'s
-    /// `<OnLoad>` calls into `KLHThreatMeter`'s GUI, which is nil until KLHThreatMeter's own
-    /// `ADDON_LOADED` builds it.
-    ///
-    /// The control below is what stops this test passing for the wrong reason: `EagerLib` must
-    /// initialise **on its own event and nowhere else**, so a consumer that sees it has genuinely
-    /// received the event and not merely run a file.
+    /// A dependency's `ADDON_LOADED` lands before the dependent's first line runs: the 1.12 client
+    /// emits per addon its dependencies, its `.toc` files (`0x51f3fa`), `Bindings.xml`, the
+    /// SavedVariables chunks, then `ADDON_LOADED` (`0x51f5ad`). The read is at file scope (as
+    /// `KTMAutoHider`'s `<OnLoad>` reads `KLHThreatMeter`'s GUI), and `EagerLib` initialises on its
+    /// own event only.
     #[test]
     fn a_dependencys_addon_loaded_precedes_the_dependents_file_scope() {
         let tmp =
@@ -4091,7 +2985,7 @@ mod dependency_tests {
              if event == \"ADDON_LOADED\" and arg1 == \"EagerLib\" then EagerLibReady = {} end\n\
              end)\n",
         );
-        // The consumer reads it AT FILE SCOPE — no handler, no later event.
+        // The consumer reads it at file scope.
         write(
             "EagerUser",
             "## Interface: 11200\n## Dependencies: EagerLib\nuse.lua\n",
@@ -4112,7 +3006,7 @@ mod dependency_tests {
             "...and the row is clean end to end: {:?}",
             of("EagerUser").session_errors
         );
-        // The control: EagerLib's own row still gets its own event, and nothing raised there.
+        // The control: `EagerLib`'s own row gets its own event and raises nothing.
         assert!(
             of("EagerLib").loaded && of("EagerLib").session_errors.is_empty(),
             "the library's own row is unaffected: {:?}",
@@ -4122,44 +3016,9 @@ mod dependency_tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
-    /// **A manifest entry with no file is split by WHOSE package is short** — the column that
-    /// stops a session hunting for a client bug that is not one.
-    ///
-    /// Both rows below are load failures and stay load failures: nothing is subtracted from
-    /// `loaded` or from `errors` (1213's rule, for the fifth time). What the split adds is the
-    /// attribution, and the two cases genuinely differ:
-    ///
-    /// - **`own`** — the addon ships a `.toc` listing a file it does not contain. Five corpus rows
-    ///   are this, all one family: `DPSMate_CureDisease.toc` names eight files and the folder
-    ///   holds six, because the three `*Received*` ones were split into a sibling addon and the
-    ///   manifest was never updated. Our loader is behaving correctly (the reference logs
-    ///   `Couldn't open %s` at `0x6edaa0` and carries on).
-    /// - **`foreign`** — the entry escapes the addon's folder with `..`, which the client supports
-    ///   and `join_ref` reproduces, into a folder that is not installed. The corpus's two are
-    ///   Auctioneer and BeanCounter reaching `..\Blizzard_AuctionUI\...`, which the real client
-    ///   **RESOLVES** (`0x6ede10` collapses the `..`) because its file layer can see that folder
-    ///   inside `patch.MPQ`. That one IS ours.
-    ///
-    /// The assertion that matters is that the two never merge: a single "files not found" count
-    /// would average a broken package with a real client gap and read as one number.
-    /// **A template named through a local resolves; the shapes that still cannot are asserted too.**
-    ///
-    /// The literal-only scan was an honest under-report — stated at `missing_templates` — and a
-    /// decision was then made on the number it produced:
-    /// `Interface\FrameXML\ItemButtonTemplate.xml` declined to build `ItemButtonTemplate` citing a
-    /// demand of zero "on both axes". The zero was real and the demand was not: pfUI binds `local
-    /// tpl = "ContainerFrameItemButtonTemplate"` and passes the variable, so the one addon that wanted it was invisible to the ranking.
-    ///
-    /// Both halves are asserted, because a scanner that quietly widened would be the worse fix:
-    /// the shape it now sees, AND the shapes it still does not, so the next decision quoting this
-    /// number can read its bound from a test rather than from a comment.
-    ///
-    /// **The exact-set form earned itself immediately.** Written first as a few absence checks it
-    /// PASSED, while the collector was binding `built` to `"Unseen"` out of
-    /// `local built = "Unseen" .. "ByConcat"` — a fragment entering the demand ranking as a
-    /// template name nobody asked for. That is not an under-report, it is the fiction this table
-    /// has opened with three times before (1210/1218/1227). Hence the whole-right-hand-side rule
-    /// in `missing_templates`, and hence asserting the set rather than sampling it.
+    /// A template named through a local resolves, and the census's bound is asserted as an exact
+    /// set: a concatenated name, a table field and a parameter stay invisible (a fragment of
+    /// `"Unseen" .. "ByConcat"` must not enter).
     #[test]
     fn the_template_census_resolves_a_local_and_says_what_it_still_cannot_see() {
         let tmp = std::env::temp_dir().join(format!("benilla-harness-tpl-{}", std::process::id()));
@@ -4167,7 +3026,7 @@ mod dependency_tests {
         let dir = tmp.join("TplUser");
         std::fs::create_dir_all(&dir).unwrap();
         std::fs::write(dir.join("TplUser.toc"), "## Interface: 11200\nuse.lua\n").unwrap();
-        // Every shape in one file. Only the first three are meant to be seen.
+        // Every shape in one file; only the first three are seen.
         std::fs::write(
             dir.join("use.lua"),
             r#"
@@ -4193,16 +3052,12 @@ mod dependency_tests {
         for want in ["SeenViaLocal", "SeenViaRebind", "SeenAsLiteral"] {
             assert!(got.contains(want), "{want} must be seen — got {got:?}");
         }
-        // A name rebound to two literals keeps BOTH: the census asks "could this call want that
-        // template", and each branch genuinely can.
+        // A name rebound to two literals keeps both.
         assert!(
             got.contains("SeenViaLocal") && got.contains("SeenViaRebind"),
             "a rebound local keeps every literal it was bound to"
         );
-        // **The stated bound, asserted as an EXACT set** so it cannot rot into a claim of
-        // completeness. The file also asks for a concatenated name, a table field
-        // (`cfg.template`) and a parameter (`passed`); none may appear, and pinning the whole set
-        // rather than a few absences is what makes a future widening announce itself here.
+        // The bound as an exact set, so a future widening shows here.
         let want: BTreeSet<&str> = ["SeenViaLocal", "SeenViaRebind", "SeenAsLiteral"]
             .into_iter()
             .collect();
@@ -4215,6 +3070,10 @@ mod dependency_tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
+    /// A manifest entry with no file is split by whose package is short: `own`, a `.toc` listing a
+    /// file its folder lacks (the 1.12 client logs `Couldn't open %s` at `0x6edaa0` and carries
+    /// on), or `foreign`, a `..` entry (collapsed as `0x6ede10` does) into a folder not installed.
+    /// The two never merge.
     #[test]
     fn an_absent_manifest_entry_is_attributed_to_whose_package_is_short() {
         let tmp =
@@ -4228,13 +3087,13 @@ mod dependency_tests {
                 std::fs::write(dir.join(f), body).unwrap();
             }
         };
-        // Ships one of the two files its own manifest lists — DPSMate_CureDisease's exact shape.
+        // Ships one of the two files its own manifest lists.
         write(
             "ShortPackage",
             "## Interface: 11200\nhere.lua\ngone.lua\n",
             &[("here.lua", "ShortPackageRan = 1\n")],
         );
-        // Reaches a neighbour that is not installed — Auctioneer's exact shape, `..` and all.
+        // Reaches a neighbour that is not installed, through `..`.
         write(
             "WantsNeighbour",
             "## Interface: 11200\nown.lua\n..\\NotInstalled\\templates.xml\n",
@@ -4271,12 +3130,8 @@ mod dependency_tests {
             wants.absent_own_files
         );
 
-        // **NOTHING is subtracted from `errors`** (1213) — both rows are still there, verbatim, so
-        // every figure any past record quoted is still readable off this list. What changed in
-        // 2155 is which of them `loaded` counts: on the reference these addons LOAD, because
-        // `0x6edaa0` logs `Couldn't open %s` and the walk carries on with nothing raised. Both
-        // halves are asserted together, because either one alone is a rule that has already been
-        // got wrong in both directions.
+        // Nothing is subtracted from `errors`, and both addons count as loaded: `0x6edaa0` logs
+        // `Couldn't open %s` and the walk carries on with nothing raised.
         for r in [short, wants] {
             assert!(
                 r.loaded,
@@ -4290,7 +3145,7 @@ mod dependency_tests {
                 r.errors
             );
         }
-        // ...and the file that DID exist ran, because a missing entry does not abort the manifest.
+        // ...and the file that exists ran: a missing entry does not abort the manifest.
         assert!(
             !short.errors.iter().any(|e| e.contains("here.lua")),
             "the surviving file loads: {:?}",
@@ -4300,6 +3155,9 @@ mod dependency_tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
+    /// A library another addon embeds is invisible here, the price of one VM per addon: an addon
+    /// leaning on a sibling's copy (`FuBar_CustomMenuFu` calls `AceLibrary("Tablet-2.0")`) fails
+    /// here and works on the 1.12 client, which shares one Lua state.
     #[test]
     fn a_sibling_addons_embedded_library_is_invisible() {
         let tmp =
@@ -4311,8 +3169,8 @@ mod dependency_tests {
             std::fs::write(dir.join(format!("{name}.toc")), toc).unwrap();
             std::fs::write(dir.join(file), body).unwrap();
         };
-        // One addon embeds a library. Another uses it, and declares no relationship at all —
-        // which on the real client is fine, because they share a Lua state.
+        // One addon embeds a library; another uses it with no declared relationship, which works on
+        // the 1.12 client because they share a Lua state.
         write(
             "Embedder",
             "## Interface: 11200\nembedded.lua\n",
@@ -4345,16 +3203,8 @@ mod dependency_tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
-    /// **An OPTIONAL dependency loads too, and first** — `AddOn_Load`'s own order (1191 §2).
-    ///
-    /// Drawn from the shape that exposed it: `FuBar_BagFu` declares `## OptionalDeps: FuBar, Ace2`
-    /// and then lists `FuBarPlugin-2.0.lua` in its manifest BEFORE `AceLibrary.lua`. That only
-    /// works because the `Ace2` addon went first and left `AceLibrary` global; surveyed without it,
-    /// FuBarPlugin raises "requires AceLibrary" and the addon dies on a state the real client never
-    /// produces. Ten corpus addons sat behind that row.
-    ///
-    /// Also asserts the half that must NOT change: an optional dependency that is not installed is
-    /// skipped in silence and never appears in `missing_deps`, which is the required-only list.
+    /// An optional dependency loads first (`AddOn_Load`'s order; `FuBar_BagFu` needs `Ace2` first),
+    /// and an uninstalled one is silent: `missing_deps` is required-only.
     #[test]
     fn an_optional_dependency_loads_first_and_a_missing_one_is_silent() {
         let tmp =
@@ -4366,7 +3216,7 @@ mod dependency_tests {
             std::fs::write(dir.join(format!("{name}.toc")), toc).unwrap();
             std::fs::write(dir.join(file), body).unwrap();
         };
-        // The library addon, and a dependent whose OWN file order needs it to have gone first.
+        // The library, and a dependent whose own file order needs it to have gone first.
         write(
             "TheLib",
             "## Interface: 11200\nlib.lua\n",
@@ -4396,12 +3246,8 @@ mod dependency_tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
-    /// **The `inherits=` census sees the axis `template_demand` cannot**, and its two exclusions
-    /// hold: a FONT name is not a missing template, and neither is a virtual the addon declares
-    /// itself.
-    ///
-    /// Written from the shape that produced the finding — twelve corpus addons whose whole failure
-    /// was an `inherits=` in their own XML, none of which appeared in the `CreateFrame` ranking.
+    /// The `inherits=` census counts a missing template, and neither a font name nor a virtual the
+    /// addon declares itself.
     #[test]
     fn the_inherits_census_counts_templates_and_not_fonts() {
         benilla_formats::wow_data_or_skip!();
@@ -4445,36 +3291,19 @@ mod dependency_tests {
 
         let _ = std::fs::remove_dir_all(&tmp);
     }
-    /// **The widget-method census finds a method that does not exist** — the can-it-fail proof, and
-    /// the reason this test is written against `survey` rather than against the scanner.
-    ///
-    /// A census that returns an empty list is indistinguishable from one that never ran, and this
-    /// instrument has already shipped once in the second state (`drive_ui_probe`'s own comment).
-    /// So the fixture calls an **invented** method that no widget can ever provide, and it must
-    /// come back — while four shapes that are *not* gaps must not:
+    /// The widget-method census finds an invented method no widget provides, and none of these:
     ///
     /// | called | why it must not appear |
     /// |---|---|
-    /// | `f:SetWidth` | a frame method we ship — if this appeared, the oracle answered "everything" |
-    /// | `f:CreateTexture` | ditto, and it is what produces the region probe |
-    /// | `t:SetTexCoord` | a **region** method: reachable only from the Texture probe, never a frame |
-    /// | `Probe:OwnMethod` | the addon declares it — `function T:N` |
-    /// | `f:Hooked` | the addon declares it the other way — `T.N = function` |
-    /// | `MethodicalLib:LibOnly` | a **dependency** declares it, and the VM loaded that dependency |
-    /// | `f:OptionalHook` | the addon **feature-tests** it one line up, so it is not a blocker |
+    /// | `f:SetWidth` | a frame method we ship |
+    /// | `f:CreateTexture` | a frame method we ship; it makes the region probe |
+    /// | `t:SetTexCoord` | a region method, reachable only from the Texture probe |
+    /// | `Probe:OwnMethod` | the addon declares it (`function T:N`) |
+    /// | `f:Hooked` | the addon declares it (`T.N = function`) |
+    /// | `MethodicalLib:LibOnly` | a loaded dependency declares it |
+    /// | `f:OptionalHook` | feature-tested one line up, so not a blocker |
     ///
-    /// Both failure directions are therefore pinned by one assertion pair: a silent-empty oracle
-    /// loses `NoSuchWidgetMethod`, a blanket-report oracle gains `SetWidth`.
-    ///
-    /// The last two rows are the ones that were learned from the corpus rather than reasoned out,
-    /// and each was worth most of a screen of fiction:
-    ///
-    /// - without the dependency subtraction the top seven rows were `FuBar:RegisterPlugin` and its
-    ///   siblings at 75-78 addons each — every one `function FuBar:<Name>` in a dependency 83
-    ///   corpus addons declare and the VM duly loads;
-    /// - without the feature-test subtraction the next ten were FuBarPlugin's optional callbacks
-    ///   (`OnMouseUp`, `OnReceiveDrag`) and AceOO's duck-typed operators (`CompareTo`, `Equals`,
-    ///   `Divide`), none of which is *defined* anywhere in the corpus at all.
+    /// A silent-empty oracle loses `NoSuchWidgetMethod`; a blanket-report one gains `SetWidth`.
     #[test]
     fn the_method_census_finds_a_method_no_widget_provides() {
         let tmp =
@@ -4499,10 +3328,8 @@ mod dependency_tests {
             "## Interface: 11200\n## Dependencies: MethodicalLib\na.lua\n",
         )
         .unwrap();
-        // Wrapped in a function that is never called: the census is STATIC, so it sees these
-        // whether or not the path runs — which is the whole reason it is a scan and not a trace
-        // (the module doc's first section). Keeping it unrun also keeps `loaded` clean, so a
-        // failure here can only be the census's.
+        // Inside a function never called: the census is static, and an unrun body keeps `loaded`
+        // clean.
         std::fs::write(
             dir.join("a.lua"),
             "local f = CreateFrame(\"Frame\")\n\
@@ -4530,15 +3357,13 @@ mod dependency_tests {
             vec!["NoSuchWidgetMethod".to_string()],
             "the invented method must be found and nothing else may be"
         );
-        // The feature-tested one is not a blocker — and it is not lost either. Dropping the class
-        // outright would have taken `SetTopLevel` (60 corpus addons, a real widget method) with it.
+        // The feature-tested one is its own row, not lost.
         assert_eq!(
             r.optional_methods,
             vec!["OptionalHook".to_string()],
             "a guarded call is its own row, never a silent omission"
         );
-        // ...and it reaches the ranking a session actually reads. The library's own row is empty:
-        // it calls nothing.
+        // ...and it reaches the ranking; the library calls nothing.
         assert_eq!(
             method_demand(&reports),
             vec![("NoSuchWidgetMethod".to_string(), 1)]
@@ -4547,29 +3372,19 @@ mod dependency_tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
-    /// **The per-kind census, end to end over a real addon folder** — the can-it-fail proof for the
-    /// whole path, not just the oracle.
-    ///
-    /// The fixture is 1228's own case, both ways round, so a pass here cannot be a pass by
-    /// accident:
+    /// The per-kind census end to end over a real addon folder:
     ///
     /// | the call | what must happen |
     /// |---|---|
-    /// | `smf:SetInsertMode()` on a `CreateFrame("ScrollingMessageFrame")` local | a row — the verb is real, the sibling has it, this kind does not |
-    /// | `mf:SetInsertMode()` on a `CreateFrame("MessageFrame")` local | **no** row — the control that stops "report everything" passing |
-    /// | `UIParent:AddMessage()` | a row via the PUBLISHED-name path: `UIParent` is a plain Frame in our arena |
-    /// | `UIErrorsFrame:AddMessage()` | **no** row — ours really is a `<MessageFrame>` (1228) |
-    /// | `self:SetInsertMode()` | not a row, an AMBIGUOUS one: nothing can type `self` |
+    /// | `smf:SetInsertMode()`, a ScrollingMessageFrame local | a row: this kind lacks it |
+    /// | `mf:SetInsertMode()`, a MessageFrame local | no row: the control |
+    /// | `UIParent:AddMessage()` | a row via the published name: a plain Frame |
+    /// | `UIErrorsFrame:AddMessage()` | no row: ours is a `<MessageFrame>` |
+    /// | `self:SetInsertMode()` | an ambiguous row: `self` is untyped |
     ///
-    /// And the two blindness guards this arc keeps paying for, both written so they can only pass
-    /// for the right reason: `ghost` is typed **only** inside a `--` comment and `faker` **only**
-    /// inside a string literal, both as `Button` — a kind nothing else in the fixture uses — so a
-    /// stripper that leaked would mint a `Button:AddMessage` row that is impossible otherwise
-    /// (1218: five words of GPL boilerplate once topped a ranking, and this pass is the first here
-    /// that reads un-blanked string literals at all).
-    ///
-    /// `missing_methods` must stay **empty** throughout: every name here is one some widget answers,
-    /// which is exactly why the old table could not see any of it.
+    /// `ghost` is typed only inside a `--` comment and `faker` only inside a string, both as
+    /// `Button`, so a leaking stripper would mint an otherwise impossible `Button:AddMessage` row.
+    /// `missing_methods` stays empty: some widget answers every name here.
     #[test]
     fn the_per_kind_census_finds_a_verb_wired_to_the_wrong_kind() {
         benilla_formats::wow_data_or_skip!();
@@ -4579,8 +3394,7 @@ mod dependency_tests {
         let dir = tmp.join("PerKind");
         std::fs::create_dir_all(&dir).unwrap();
         std::fs::write(dir.join("PerKind.toc"), "## Interface: 11200\na.lua\n").unwrap();
-        // Never executed, like the census fixture above: the scan is static, and an unrun body
-        // keeps `loaded` clean so a failure here can only be the census's.
+        // Never executed: the scan is static, and an unrun body keeps `loaded` clean.
         std::fs::write(
             dir.join("a.lua"),
             "local smf = CreateFrame(\"ScrollingMessageFrame\")\n\
@@ -4617,8 +3431,7 @@ mod dependency_tests {
             "the typed call sites, and only the ones whose kind cannot answer — no Button row, so \
              neither the comment nor the string literal was read as code"
         );
-        // `self`, `ghost` and `faker` are all untypable, so the NAME is reported as conditional
-        // rather than swallowed as present.
+        // `self`, `ghost` and `faker` are untyped, so the name is reported as conditional.
         assert_eq!(
             r.ambiguous_methods,
             vec![
@@ -4627,7 +3440,7 @@ mod dependency_tests {
             ],
             "an untypable receiver is a stated unknown, never a silent pass"
         );
-        // ...and it reaches the rankings a session reads.
+        // ...and it reaches the rankings.
         assert_eq!(
             kind_method_demand(&reports),
             vec![
@@ -4645,13 +3458,8 @@ mod dependency_tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
-    /// **A name the file rebinds cannot be typed at all** — the rule that stops the attributor
-    /// inventing rows, which is the failure mode every demand ranking in this arc has already had.
-    ///
-    /// One `local frame = CreateFrame("MessageFrame")` at file top would otherwise type every
-    /// `frame:Method()` below it, including the `frame` that is a **parameter** of a helper, or a
-    /// `for` variable, holding whatever the caller passed. Three shapes, one assertion: the typed
-    /// receiver keeps its kind, and each rebound one loses it.
+    /// A name the file rebinds (shadowed, a `for` variable, a parameter) is not typed; the one
+    /// bound once keeps its kind.
     #[test]
     fn a_rebound_name_is_not_typed() {
         let kinds = local_widget_kinds(
@@ -4682,21 +3490,13 @@ mod dependency_tests {
         script
     }
 
-    /// **The session fixture is LIVE**, asserted through the same Lua surface an addon sees.
-    ///
-    /// A fixture that silently fails to seat reads EXACTLY like a fixture that exposed nothing —
-    /// both are "net +0" — and this arc has already been fooled once by a measurement that
-    /// returned an empty answer for a tooling reason (1242's note on `grep`). The backpack seat
-    /// produced no corpus delta at all; this is what makes that a finding rather than a
-    /// possibility.
-    ///
-    /// It is also a guard: delete a seat and this fails, instead of the columns quietly shifting
-    /// and the next A/B attributing the move to whatever landed beside it.
+    /// The seated session is visible through the Lua surface an addon sees, so a seat that silently
+    /// fails to take is caught.
     #[test]
     fn the_seated_session_is_visible_from_lua() {
         let s = seated_vm();
 
-        // The backpack — 16 slots from level 1, two of them filled. Exposed nothing, verifiably.
+        // The backpack: 16 slots, two filled.
         assert_eq!(s.eval::<i64>("return GetContainerNumSlots(0)").unwrap(), 16);
         assert_eq!(
             s.eval::<String>("return GetBagName(0)").unwrap(),
@@ -4708,13 +3508,11 @@ mod dependency_tests {
             12,
             "the Linen Cloth stack"
         );
-        // Bags 1..4 are deliberately NOT seated: a fresh character has no equipped bags, and
-        // seating them would manufacture a state rather than expose one.
+        // Bags 1..4 are not seated.
         assert_eq!(s.eval::<i64>("return GetContainerNumSlots(1)").unwrap(), 0);
 
-        // The quest log — asserted through the API an addon actually walks, not the state struct.
-        // `GetNumQuestLogEntries` returns (rows, quests): THREE rows but TWO quests, because the
-        // header is a row and not a quest. An addon that conflates the two indexes off the end.
+        // The quest log through the API an addon walks: `GetNumQuestLogEntries` returns (rows,
+        // quests), three rows but two quests, since the header is a row.
         assert_eq!(
             s.eval::<(i64, i64)>("return GetNumQuestLogEntries()")
                 .unwrap(),
@@ -4741,8 +3539,7 @@ mod dependency_tests {
                 .unwrap(),
             1
         );
-        // A leaderboard walk sees a finished objective AND an unfinished one — the pair a
-        // one-objective fixture cannot show.
+        // A leaderboard walk sees one finished objective and one not.
         s.run("SelectQuestLogEntry(2)").unwrap();
         assert_eq!(
             s.eval::<i64>("return GetNumQuestLeaderBoards()").unwrap(),
@@ -4757,16 +3554,13 @@ mod dependency_tests {
             "one objective outstanding, one done"
         );
 
-        // The bind point — a plain string, and the reason it is seated is that an addon
-        // CONCATENATES it (`Necrosis.lua:1089`), where an empty answer reads as no hearth at all.
+        // The bind point, a string an addon concatenates (`Necrosis.lua:1089`).
         assert_eq!(
             s.eval::<String>("return GetBindLocation()").unwrap(),
             "Stormwind City"
         );
 
-        // The purse — and asserted as its three coin fields, not as one number, because that is the
-        // whole reason the value is 1234g 56s 78c rather than something round. A seat that reads
-        // back as 12345678 but breaks down wrong is the bug this shape exists to catch.
+        // The purse, asserted as its three coin fields.
         assert_eq!(s.eval::<i64>("return GetMoney()").unwrap(), 12_345_678);
         assert_eq!(
             s.eval::<(i64, i64, i64)>(
@@ -4777,7 +3571,7 @@ mod dependency_tests {
             "gold/silver/copper are each non-zero, so no field can be dropped unnoticed"
         );
 
-        // Equipped gear — head, chest, main hand, with the rest empty. Also exposed nothing.
+        // Equipped gear: head, chest, main hand, the rest empty.
         assert_eq!(
             s.eval::<String>(r#"return GetInventoryItemTexture("player", 16)"#)
                 .unwrap(),
@@ -4794,19 +3588,18 @@ mod dependency_tests {
                 .unwrap(),
             2
         );
-        // An EMPTY slot still answers the absent shape — the case an addon walking 1..19 hits most.
+        // An empty slot answers the absent shape.
         assert!(s
             .eval::<bool>(r#"return GetInventoryItemLink("player", 10) == nil"#)
             .unwrap());
-        // The slot ids come from the same table `GetInventorySlotInfo` serves, so a walk that
-        // resolves names to ids lands on the seated items rather than past them.
+        // The slot ids match `GetInventorySlotInfo`'s table.
         assert_eq!(
             s.eval::<i64>(r#"return GetInventorySlotInfo("MainHandSlot")"#)
                 .unwrap(),
             16
         );
 
-        // The spellbook, as the positive control — this seat DID move the columns (+2).
+        // The spellbook.
         assert_eq!(
             s.eval::<String>(r#"return GetSpellName(1, "spell")"#)
                 .unwrap(),
@@ -4824,15 +3617,8 @@ mod dependency_tests {
         names.iter().map(|n| (*n).to_string()).collect()
     }
 
-    /// **An oracle that cannot probe reports EVERYTHING missing, never nothing.**
-    ///
-    /// [`widget_method_kinds`] asks the live `__index` dispatcher, so it depends on
-    /// `CreateFrame` still being callable — and an addon is perfectly free to replace it. The
-    /// failure has to land in the direction that gets noticed: a blanket over-report is loud and
-    /// obviously wrong, while a silent empty answer reads as "this addon calls no method we lack",
-    /// which is the exact sentence this whole census exists to stop being invisible.
-    ///
-    /// The first assertion is what stops the fix being trivially satisfied by always over-reporting.
+    /// An oracle that cannot probe (an addon may replace `CreateFrame`) reports every wanted name
+    /// missing, never nothing; the first assertion is the live control.
     #[test]
     fn the_method_oracle_fails_loudly_when_it_cannot_probe() {
         let script = seated_vm();
@@ -4853,13 +3639,8 @@ mod dependency_tests {
         );
     }
 
-    /// **The PER-KIND pass fails loudly too** — the same rule one level down, and it needs its own
-    /// test because the per-kind pass has a second way to answer nothing: no *attributed* call
-    /// sites.
-    ///
-    /// With the oracle dead, every typed call site is reported against its kind and the ambiguous
-    /// table is empty (a name whose answer we cannot compute is not "conditional", it is unknown,
-    /// and it is already in the loudest bucket — `missing_methods`).
+    /// The per-kind pass fails loudly too: with the oracle dead, every typed call site is reported
+    /// against its kind, and the ambiguous table is empty (an unknown answer is not conditional).
     #[test]
     fn the_per_kind_census_fails_loudly_when_it_cannot_probe() {
         let script = seated_vm();
@@ -4889,7 +3670,7 @@ mod dependency_tests {
             "...and the untypable one is reported as conditional, with the kind named"
         );
 
-        // Now break it. `None` is the oracle saying it could not run.
+        // Now break it: `None` is the oracle saying it could not run.
         let (missing, ambiguous) = per_kind_rows(&script, &None, &wants);
         assert_eq!(
             missing,
@@ -4902,24 +3683,9 @@ mod dependency_tests {
         );
     }
 
-    /// **A method on a sibling kind is invisible to the ANY-kind oracle, and the PER-KIND pass
-    /// finds it** — decision 1228's bound, and the fix for it, asserted together.
-    ///
-    /// 1228 landed this test to pin a bound it deliberately left open: the census resolved a name
-    /// against every probe and stopped at the first `function`, so a name survived only if *no*
-    /// widget answered it. `MessageFrame:AddMessage` therefore scored zero for as long as it
-    /// existed — the ScrollingMessageFrame probe answered it — while `EasyCopy`, `QuestHistory`
-    /// and `QuestItem` all died on `UIErrorsFrame:AddMessage`.
-    ///
-    /// Both halves are still true, and both are asserted here, because they are now *different
-    /// tables*: `missing_methods` still answers ANY-kind and still cannot see this (its numbers
-    /// have to stay comparable — 1209), while `kind_missing_methods` asks the kind the addon
-    /// actually called it on. `SetInsertMode` is the probe: a MessageFrame binding and only a
-    /// MessageFrame binding (1228 §3's table), so a ScrollingMessageFrame calling it is exactly the
-    /// shape that used to be unfindable.
-    ///
-    /// The control below it is what stops the pass being satisfied by reporting everything: the
-    /// same verb on the kind that *does* answer it produces no row at all.
+    /// A method on a sibling kind is invisible to the any-kind table and found per kind:
+    /// `SetInsertMode` is a MessageFrame binding only, so a ScrollingMessageFrame call to it is a
+    /// row, and the same call on a MessageFrame is none.
     #[test]
     fn a_method_on_a_sibling_kind_is_invisible_to_any_and_found_per_kind() {
         let script = seated_vm();
@@ -4961,13 +3727,9 @@ mod dependency_tests {
         );
     }
 
-    /// **The receiver of a published name is typed off the LIVE ARENA**, which is what lets the
-    /// census see `UIErrorsFrame:AddMessage` as a MessageFrame call at all.
-    ///
-    /// Both directions are pinned, because the attribution is only worth what its source is worth:
-    /// our `UIErrorsFrame` really is a `<MessageFrame>` (1228 converted it), `UIParent` is a plain
-    /// `<Frame>`, `GameTooltipTextLeft1` is a **region** — and a name nothing publishes is `None`
-    /// rather than a guess.
+    /// A published name's kind is read off the live arena: our `UIErrorsFrame` is a
+    /// `<MessageFrame>`, `UIParent` a plain `<Frame>`, `GameTooltipTextLeft1` a region, and an
+    /// unpublished name `None`.
     #[test]
     fn a_published_name_carries_its_kind() {
         benilla_formats::wow_data_or_skip!();
@@ -4987,18 +3749,10 @@ mod dependency_tests {
         assert_eq!(script.widget_kind("NoSuchFrameAnywhere"), None);
     }
 
-    /// **The seated session answers the two login-scoped catalogues** (2167) — the auction browse
-    /// tree and the player's talent pages.
-    ///
-    /// Both are DBC reads the client answers with no session behind them, so an empty answer is a
-    /// state the reference cannot be in — and both were read AT FILE SCOPE by corpus addons that
-    /// then did arithmetic or subscripting on the answer. `Auctioneer` subscripts `classes[10]`
-    /// (`AucCore.lua:106`) and `KLHThreatMeter` negates `GetTalentInfo`'s rank
-    /// (`KTM_My.lua:721`); nil is what both were getting.
-    ///
-    /// The subscript and the arithmetic are what this asserts, not a count: the ten-class set and
-    /// the warrior's three pages come off the player's own DBCs, and pinning their contents here
-    /// would be pinning the install rather than the seat.
+    /// The seated session answers the login-scoped catalogues at file scope: `Auctioneer`
+    /// subscripts `classes[10]` (`AucCore.lua:106`) and `KLHThreatMeter` negates a talent rank
+    /// (`KTM_My.lua:721`). The contents come off the player's DBCs, so the reads are asserted, not
+    /// the data.
     #[test]
     fn the_seated_session_answers_the_login_scoped_catalogues() {
         if benilla_formats::wow_data().is_none() {
@@ -5009,7 +3763,7 @@ mod dependency_tests {
         script.set_screen_size(1024.0, 768.0);
         seat_a_session(&mut script);
 
-        // Auctioneer's own line, reduced: ten subscripts into the packed return.
+        // Auctioneer's line, reduced: ten subscripts into the packed return.
         assert_eq!(
             script
                 .eval::<i64>(
@@ -5021,7 +3775,7 @@ mod dependency_tests {
             Some(10),
             "the browse tree is the reference's ten auctionable classes"
         );
-        // KLHThreatMeter's own line, reduced: a positional read and arithmetic on the rank.
+        // KLHThreatMeter's line, reduced: a positional read and arithmetic on the rank.
         assert_eq!(
             script
                 .eval::<i64>("local _, _, _, _, rank = GetTalentInfo(3, 13) return -rank")
@@ -5037,13 +3791,8 @@ mod dependency_tests {
         );
     }
 
-    /// **The UI probe actually INVOKES an addon's override**, which is the only thing that makes it
-    /// different from every other column here.
-    ///
-    /// Earned two ways rather than trusted: a hook is installed the way Bagnon installs one, the
-    /// probe is driven, and the hook's own counter is read back. A probe that silently found no
-    /// entry point would report a clean run forever and be worse than not having it — which is
-    /// exactly the failure mode the corpus's first run looked like (zero addons failing it).
+    /// The UI probe invokes an addon's override: a hook installed as Bagnon installs one is
+    /// counted.
     #[test]
     fn the_ui_probe_reaches_an_addon_override() {
         let mut script = UiScript::new().unwrap();
@@ -5051,7 +3800,7 @@ mod dependency_tests {
         seat_a_session(&mut script);
         let _ = crate::ui_script::load_default_ui(&script);
 
-        // Bagnon's idiom, on the verb Bagnon actually replaces.
+        // Bagnon's idiom, on the verb Bagnon replaces.
         script
             .run("BENILLA_PROBE_HITS = 0 ToggleBackpack = function() BENILLA_PROBE_HITS = BENILLA_PROBE_HITS + 1 end")
             .unwrap();
@@ -5065,7 +3814,7 @@ mod dependency_tests {
         );
     }
 
-    /// And it RECORDS a raise rather than swallowing it — the error is the finding.
+    /// And it records a raise rather than swallowing it.
     #[test]
     fn the_ui_probe_records_what_an_override_raises() {
         let mut script = UiScript::new().unwrap();
@@ -5083,16 +3832,8 @@ mod dependency_tests {
         );
     }
 
-    /// **The HOVER arm reaches an addon's tooltip hook, and reports what it raises.**
-    ///
-    /// Nothing else in the probe puts a tooltip on screen, so an addon that hooks `GameTooltip`'s
-    /// `OnShow` or scrapes its line regions was invisible to this column — the gap decision 1220
-    /// named after fixing a raise squarely inside it.
-    ///
-    /// The assertion is deliberately the RAISE, not the call count. When the hover arm landed the
-    /// column did not move at all, and "found nothing" has to be distinguishable from "ran
-    /// nothing" — this instrument has already shipped once in the second state
-    /// (see `drive_ui_probe`'s own comment), and a probe that cannot fail is not a probe.
+    /// The hover arm shows the tooltip, so a hook on `GameTooltip`'s `OnShow` runs and its raise is
+    /// recorded.
     #[test]
     fn the_ui_probe_hovers_and_records_what_a_tooltip_hook_raises() {
         benilla_formats::wow_data_or_skip!();
@@ -5100,7 +3841,7 @@ mod dependency_tests {
         script.set_screen_size(1024.0, 768.0);
         seat_a_session(&mut script);
         let _ = crate::ui_script::load_default_ui(&script);
-        // The corpus shape: hook the tooltip's own OnShow, which only runs if something shows it.
+        // The corpus shape: hook the tooltip's own OnShow, which runs only if something shows it.
         script
             .run(
                 "GameTooltip:SetScript(\"OnShow\", function() error(\"tooltip hook blew up\") end)",
@@ -5114,30 +3855,9 @@ mod dependency_tests {
         );
     }
 
-    /// ...and the hover arm raises NOTHING on a clean VM with no addon loaded.
-    ///
-    /// Without this, a probe arm that is simply broken would charge its own failure to all 218
-    /// addons — the mis-attribution 1209 exists about, arriving through the instrument instead of
-    /// through a claim.
-    ///
-    /// **"Silent" has to mean "ran and said nothing", never "had nothing to run"** — the same
-    /// distinction the hover-arm test above is built around ("found nothing" vs "ran nothing"),
-    /// and decision 1751 put this test one step from the wrong side of it: `ToggleBackpack`, the
-    /// probe's first and most-hooked entry point, is defined in the reference's own
-    /// `ContainerFrame.lua` now, which `load_default_ui` reads off the PLAYER'S INSTALL. On a
-    /// machine without one the global is simply absent, `drive_ui_probe`'s `try` guard skips it,
-    /// and an empty error list would mean the probe drove nothing at all. So the entry points are
-    /// asserted to EXIST before the silence is asserted, and the test gates on client data like
-    /// every other reader of the chain.
-    ///
-    /// What is deliberately NOT asserted here is `load_default_ui`'s own failure list, and the
-    /// reason is a policy rather than a symptom: it is a different measurement from this one, and
-    /// pinning it here would make the probe's gate hostage to whatever else the chain is mid-way
-    /// through. (The concrete case that prompted the note has since gone with its file: our
-    /// `UnitFrames.xml` had `TargetFrame`'s OnLoad reach a `BenillaTargetAuras_Update` that indexed
-    /// `TargetofTargetFrame` ~1150 lines before the frame was declared, so a seated TARGET raised
-    /// at load. `TargetFrame.xml` is the reference's own now, 1751, and neither the caller nor the
-    /// ordering survives.)
+    /// ...and the probe raises nothing on a clean VM with no addon loaded, having driven every
+    /// entry point: `ToggleBackpack` comes from the stock `ContainerFrame.lua:67` off the player's
+    /// install, so the entry points are asserted to exist first and the test needs client data.
     #[test]
     fn the_ui_probe_is_silent_on_a_clean_vm() {
         let _data = benilla_formats::wow_data_or_skip!();
@@ -5145,9 +3865,8 @@ mod dependency_tests {
         script.set_screen_size(1024.0, 768.0);
         seat_a_session(&mut script);
         let _ = crate::ui_script::load_default_ui(&script);
-        // The probe's entry points are here to be driven. Each is `try`-guarded inside
-        // `drive_ui_probe`, so a missing one is silent — which would make the assertion below
-        // pass by having done nothing.
+        // Each entry point is `try`-guarded in `drive_ui_probe`, so a missing one would pass
+        // silently.
         for entry in [
             "ToggleBackpack",
             "UnitFrame_OnEnter",
diff --git a/crates/benilla-app/src/addon_harness/probe.rs b/crates/benilla-app/src/addon_harness/probe.rs
index 6844cee8..6fb9dd62 100644
--- a/crates/benilla-app/src/addon_harness/probe.rs
+++ b/crates/benilla-app/src/addon_harness/probe.rs
@@ -1,35 +1,10 @@
-//! **The read-back column — ask the VM instead of guessing at it.**
+//! The read-back probe: load one addon as the survey does, drive the session start, then run
+//! the caller's Lua, cursor moves and ticks against the VM left standing.
 //!
-//! [`super::survey`] answers *how many* addons work and *what row* each one died on. It cannot
-//! answer the next question, which is the one every fix actually turns on: **why is this
-//! particular global nil?** The report's `--why` opens the error text; nothing opened the *state*
-//! the error was raised against.
-//!
-//! So this loads **one** addon exactly the way the survey loads it, drives the same session start,
-//! and then evaluates Lua of the caller's choosing against the VM that is left standing.
-//!
-//! ## Two properties it has to have, and both are about not lying
-//!
-//! **The environment is the corpus's, never the selection's.** The registry every VM is seated
-//! with, and the case-folded installed set dependency resolution consults, are built from the
-//! *whole folder* — exactly as [`super::survey`] builds them — so probing `KLHThreatMeter` out of
-//! a 219-addon root produces the same VM its row in the full run had. Building a registry of one
-//! would quietly answer a different question: `GetAddOnInfo` is how AceAddon and AceLibrary find
-//! their dependencies, and against a registry of one they take the "nothing is installed" path
-//! (the fault [`super::survey`]'s registry comment records at corpus scale).
-//!
-//! **It stops at session start, before the render and use probes.** Those two drive input into the
-//! addon's own frames — hover, click, drag — and standing up the method oracle writes sixteen
-//! widgets and a global into the VM. A read taken after them answers "what is true once the
-//! harness has finished poking it", which is not the state a player is in and not the state an
-//! error was raised in. `ADDON_LOADED` → `VARIABLES_LOADED` → `PLAYER_LOGIN` →
-//! `PLAYER_ENTERING_WORLD` + the ticks is the moment this reads, and it is the moment the session
-//! column's errors come from.
-//!
-//! ## What it is worth
-//!
-//! It is a **debugger, not a measurement**. An eval can mutate the VM, so nothing here prints a
-//! column and no number from a probe run belongs in a record — quote [`super::survey`] for that.
+//! The registry and installed set are built from the whole folder, as the survey builds them:
+//! against a registry of one, AceAddon and AceLibrary find no dependencies. It reads the state
+//! after `PLAYER_ENTERING_WORLD` and the ticks, before the render and use probes touch the VM.
+//! An eval can mutate the VM, so a probe is a debugger; the survey is the measurement.
 
 use std::collections::BTreeSet;
 use std::path::Path;
@@ -41,21 +16,17 @@ use benilla_ui::toc::Toc;
 #[derive(Debug, Clone, Default)]
 pub struct ProbeOutcome {
     pub name: String,
-    /// Load-time failures, verbatim — the same list [`super::AddonReport::errors`] carries.
+    /// Load-time failures, verbatim, as [`super::AddonReport::errors`] carries them.
     pub load_errors: Vec<String>,
     /// What its handlers raised while the session start was driven.
     pub session_errors: Vec<String>,
-    /// `(chunk, answer)` per `--eval`, in the order asked. An answer is `= <value>` or
-    /// `ERROR: <message>`; the chunk that raises does not stop the ones after it.
+    /// `(chunk, answer)` per step in order; an answer is `= <value>` or `ERROR: <message>`, and a
+    /// raise does not stop the steps after it.
     pub answers: Vec<(String, String)>,
 }
 
-/// Wrap a caller's chunk so a raise comes back as a value instead of killing the probe.
-///
-/// **`pcall` + `tostring`, and only the FIRST result.** Multi-return would need `table.getn` or
-/// `select`, and this VM is deliberately 5.0-shaped (decisions 1194/1215) — a probe that depended
-/// on which of those the dialect layer publishes would be an instrument with a dialect bug in it.
-/// A caller that wants more concatenates its own string, which is what `..` is for.
+/// Wrap a chunk in `pcall` + `tostring` so a raise comes back as a value; only the first result
+/// is returned, so the wrapper needs nothing beyond Lua 5.0.
 fn wrapped(chunk: &str) -> String {
     format!(
         "local __ok, __v = pcall(function() {chunk} end)\n\
@@ -63,37 +34,23 @@ fn wrapped(chunk: &str) -> String {
     )
 }
 
-/// One step of a probe run, in the order the caller asked for it.
-///
-/// A probe used to be a list of chunks alone, which cannot ask the question half of this corpus
-/// is about: an addon's map, bar and tooltip behaviour is **hover-driven**, and the state a read
-/// finds with the cursor parked off-screen is not the state a player is in. Cartographer's world
-/// map is the case that forced this — its area label is hidden at every zone change and shown
-/// again only by `WorldMapButton`'s `OnEnter`, so `WorldMapFrameAreaLabel:IsShown()` reads `nil`
-/// in a cursor-less VM whether the hover works or not. Interleaving the move with the reads is
-/// what tells those two apart.
+/// One step of a probe run. Much addon state is hover-driven, so moves interleave with reads.
 #[derive(Debug, Clone)]
 pub enum Step {
     /// Lua to evaluate against the VM as it stands.
     Eval(String),
     /// Move the cursor to `(x, y)` in UI units (y-up from the bottom-left), firing the real
-    /// `OnLeave`/`OnEnter` pair exactly as [`UiScript::mouse_move`] does for the app.
+    /// `OnLeave`/`OnEnter` pair as [`UiScript::mouse_move`] does for the app.
     Mouse(f32, f32),
-    /// Advance the engine one frame of `secs` — the `OnUpdate` pump. An addon that hooks a
-    /// FrameXML `OnUpdate` (Cartographer secure-hooks `WorldMapButton_OnUpdate`) raises there and
-    /// nowhere else, so a probe that never ticks reports it clean. The answer is what the tick
-    /// raised, or `no errors`.
+    /// Advance one `OnUpdate` frame of `secs`; the answer is what the tick raised, or `no errors`.
     Tick(f32),
 }
 
 /// Load `name` out of `root` the way the survey does, drive the session start, then run each
-/// [`Step`] against the VM that is left.
-///
-/// `None` when the folder has no manifest — the same refusal [`super::survey`] makes by filtering.
+/// [`Step`] against the VM that is left; `None` when the folder has no manifest.
 pub fn probe(root: &Path, name: &str, steps: &[Step]) -> Option<ProbeOutcome> {
     let toc_path = super::manifest_path(root, name)?;
-    // Decoded, not `read_to_string`'d, for the reason `survey_one` states: a cp1252 manifest read
-    // as UTF-8 parses as an EMPTY toc, and an addon with no files reads as a clean pass.
+    // Decoded: a cp1252 manifest read as UTF-8 parses as an empty toc and a false clean pass.
     let toc = Toc::parse(&benilla_ui::source::decode(
         &std::fs::read(&toc_path).unwrap_or_default(),
     ));
@@ -112,10 +69,8 @@ pub fn probe(root: &Path, name: &str, steps: &[Step]) -> Option<ProbeOutcome> {
     };
     script.set_instruction_budget(super::ADDON_INSTRUCTION_BUDGET);
     script.set_screen_size(1024.0, 768.0);
-    // `None` **saved-variable** roots: a probe must never read or write the director's real ones,
-    // for the same reason the survey does not call `finish_ui_load` (1213 §4). The AddOns root is
-    // passed, exactly as [`super::survey_one`] passes it — a probe VM that answers `MISSING` to
-    // every `LoadAddOn` is not the VM the row came from (decision 2102).
+    // No saved-variable roots, so a probe never touches a player's saved variables; the AddOns
+    // root is passed as the survey passes it, so `LoadAddOn` resolves.
     script.register_addons(registry, Some(root.to_path_buf()), None, None);
     super::seat_a_session(&mut script);
     let _ = crate::ui_script::load_default_ui(&script);
@@ -131,9 +86,8 @@ pub fn probe(root: &Path, name: &str, steps: &[Step]) -> Option<ProbeOutcome> {
     );
 
     let load_errors = super::load_addon_files(&script, root, name, &toc).errors;
-    // Same stamp the survey applies, for the same reason: the registry must agree with the VM
-    // about what is loaded, or `IsAddOnLoaded` and every dependency verdict answer for a session
-    // that does not exist. The chain stamped itself as it loaded (2166); this is the surveyed one.
+    // The registry must agree with the VM, or `IsAddOnLoaded` answers for another session; the
+    // dependency chain stamped itself as it loaded.
     script.mark_addon_loaded(name);
     let session_errors = super::drive_session_start(&mut script, name, &installed);
 
@@ -143,9 +97,7 @@ pub fn probe(root: &Path, name: &str, steps: &[Step]) -> Option<ProbeOutcome> {
             Step::Eval(chunk) => {
                 let answer = script
                     .eval::<String>(&wrapped(chunk))
-                    // A raise HERE is the wrapper failing to compile the caller's chunk — a syntax
-                    // error in what they typed — not the chunk raising, which `pcall` already
-                    // caught.
+                    // Only a syntax error in the chunk reaches here; `pcall` caught any raise.
                     .unwrap_or_else(|e| format!("SYNTAX: {e}"));
                 (chunk.clone(), answer)
             }
@@ -163,8 +115,8 @@ pub fn probe(root: &Path, name: &str, steps: &[Step]) -> Option<ProbeOutcome> {
                 )
             }
             Step::Mouse(x, y) => {
-                // `resolve` first: the hit-test reads resolved rects, and a frame the addon
-                // created or moved since the last resolve has none (`pointer`'s module doc).
+                // Resolve first: the hit-test reads resolved rects, which a new or moved frame
+                // lacks until then.
                 script.resolve();
                 script.mouse_move(*x, *y);
                 let focus = script
diff --git a/crates/benilla-app/src/addon_harness/probe_tests.rs b/crates/benilla-app/src/addon_harness/probe_tests.rs
index 040a5af9..da073966 100644
--- a/crates/benilla-app/src/addon_harness/probe_tests.rs
+++ b/crates/benilla-app/src/addon_harness/probe_tests.rs
@@ -1,8 +1,4 @@
-//! **The probe's can-it-fail proof**, plus the one property that makes its answers worth
-//! anything: the VM it reads is the corpus's, not the selection's.
-//!
-//! A debugger that quietly answers a different question from the report it exists to explain is
-//! worse than no debugger, because every conclusion drawn from it looks sourced.
+//! Tests for the read-back probe: it reads after the session start, in the corpus's VM.
 
 use std::path::{Path, PathBuf};
 
@@ -46,14 +42,8 @@ impl Drop for Fixtures {
     }
 }
 
-/// **The probe reads AFTER the session start, and a raise is a value, not a stop.**
-///
-/// Three claims in one addon. A global written at file scope is readable (the load ran); a global
-/// written only from a `PLAYER_LOGIN` handler is readable too (**the session start ran** — this is
-/// the claim that separates this from a bare load, and the moment the session column's own errors
-/// come from); and an eval that raises comes back tagged `ERROR:` **without stopping the eval after
-/// it**, because a debugging session that dies on its own first typo is a debugging session spent
-/// re-running the command.
+/// A file-scope global and a `PLAYER_LOGIN` global are both readable, and a raise comes back as
+/// `ERROR:` without stopping the next eval.
 #[test]
 fn the_probe_reads_the_vm_after_the_session_start() {
     let fx = Fixtures::new("after");
@@ -98,13 +88,7 @@ fn the_probe_reads_the_vm_after_the_session_start() {
     );
 }
 
-/// **The environment is the whole folder's, never the probed addon's.**
-///
-/// `GetAddOnInfo` is how AceAddon and AceLibrary — the two most replicated files in the corpus —
-/// find their dependencies, so a probe built against a registry of one would send half the
-/// ecosystem down its "nothing is installed" path and answer a different question from the survey
-/// row it was opened to explain. The sibling here is never surveyed and never loaded; it must
-/// still be *installed*.
+/// The registry is the whole folder's: a sibling that is never loaded is still installed.
 #[test]
 fn the_probe_sees_the_whole_folder_installed() {
     let fx = Fixtures::new("registry");
@@ -131,16 +115,14 @@ fn the_probe_sees_the_whole_folder_installed() {
         out.answers[1].1, "= 2",
         "the registry is the folder's, not the selection's"
     );
-    // ...and installed is not loaded: one addon per VM is the survey's own isolation rule, and a
-    // probe that silently ran the neighbours would attribute their globals to the addon in hand.
+    // Installed is not loaded: one addon per VM, as in the survey.
     assert_eq!(
         out.answers[2].1, "= nil",
         "an installed sibling must NOT have been run"
     );
 }
 
-/// A folder with no manifest is `None`, not an empty outcome — the same refusal the survey makes
-/// by filtering, said out loud so the caller can tell "no such addon" from "that addon is silent".
+/// A folder with no manifest is `None`, not an empty outcome.
 #[test]
 fn a_folder_without_a_manifest_is_refused() {
     let fx = Fixtures::new("nomanifest");
diff --git a/crates/benilla-app/src/addon_harness/render.rs b/crates/benilla-app/src/addon_harness/render.rs
index 58a5b178..28c9efbf 100644
--- a/crates/benilla-app/src/addon_harness/render.rs
+++ b/crates/benilla-app/src/addon_harness/render.rs
@@ -1,48 +1,14 @@
-//! **The render column — "did this addon put anything on screen?"**
+//! The render column: which painting quads come from widgets the addon created.
 //!
-//! Every other column in [`super`] is load- or event-based: they ask whether something *raised*.
-//! None of them could ask whether anything was **drawn**, and that gap is not theoretical — the
-//! director installed Bagnon, opened their bags, and saw a title and a gold line with **no bag
-//! slots at all**, while the survey scored it `loaded, missing=0, session=ok, probe=ok`. The cause
-//! raised nothing anywhere (`crate::ui_script::bagnon_render_tests` is the reproduction), so no
-//! error-shaped instrument could ever have found it.
+//! [`RenderBaseline::of`] snapshots every live draw target before the addon runs, and anything
+//! new afterwards is the addon's, anonymous frames included; handles are generational, so a
+//! reused slot is never taken for a survivor. [`Drew`] splits a window of the addon's own from an
+//! overlay on an existing one.
 //!
-//! ## The oracle: a handle diff, not a name and not a total
-//!
-//! [`RenderBaseline::of`] snapshots every live draw target *before* the addon runs a line; anything
-//! new afterwards was created by the addon. Both obvious alternatives are wrong, and wrong in ways
-//! this arc has already been bitten by:
-//!
-//! - **A with/without quad-count diff** reads zero for an addon that *replaces* rather than adds.
-//!   Bagnon takes the bags over: our own `BenillaBagFrame` stops drawing as Bagnon starts, and the
-//!   total barely moves whether Bagnon painted sixteen slots or none. (Measured: 16 either way, in
-//!   the first draft of the reproduction test.)
-//! - **A name-prefix match** cannot see an anonymous frame, and `!OmniCC`'s entire visible output
-//!   hangs off `CreateFrame("Frame", nil, cooldown:GetParent())` — no name at all.
-//!
-//! Handles are generational, so a destroyed-and-reused slot can never be mistaken for a survivor.
-//!
-//! ## Three answers, because the interesting one is the middle
-//!
-//! [`Drew`] separates an addon that built **its own window** from one that **painted over ours**,
-//! and that split is usually the most useful thing here: it points straight at the cause. The two
-//! addons the director has verified by eye land on opposite sides of it — `!OmniCC` works and is
-//! an [`Drew::Overlay`], Bagnon has to build its own slot buttons and was a [`Drew::Nothing`] — and
-//! a check that could only see one of the two shapes would have scored the working addon zero.
-//!
-//! ## What it over- and under-reports, stated rather than hidden
-//!
-//! - **Over-reports**: any quad from a new widget counts, including one drawn off-screen or under
-//!   another window. "Something reached the render list" is not "the player can see it"; the
-//!   director's eye is still the judge of that (`docs/METHOD.md` §7). Over-reporting is the deliberate
-//!   direction — a silent under-report is the failure mode this whole column exists to end.
-//! - **Under-reports** in one known shape: an addon that changes an *existing* widget in place —
-//!   `SetTexture` on one of our regions, `SetBackdrop` on one of our frames — creates no new
-//!   handle and scores [`Drew::Nothing`]. Catching that needs a per-quad content diff, which is a
-//!   different instrument; it is named here so nobody reads a `nothing` row as proof.
-//! - **The world is minimal**, exactly as [`super::drive_session_start`] says: no real bank, no
-//!   real raid, no real quests. An addon whose window only opens on state we do not simulate draws
-//!   nothing here and would draw in play.
+//! It over-reports: a quad off-screen or under another window counts. It under-reports an addon
+//! that only changes an existing widget in place (`SetTexture`, `SetBackdrop`), which makes no new
+//! handle. The session world is minimal, so a window that opens only on unsimulated state (a
+//! bank, a raid) draws nothing here.
 
 use std::collections::{BTreeSet, HashSet};
 
@@ -51,7 +17,7 @@ use benilla_ui::order::ZTarget;
 use benilla_ui::script::{QuadContent, UiScript};
 use benilla_ui::widget::FrameHandle;
 
-/// Every widget that existed before an addon ran — the set the render probe diffs against.
+/// Every widget that existed before an addon ran, the set the render probe diffs against.
 pub(super) struct RenderBaseline {
     targets: HashSet<ZTarget>,
     frames: HashSet<FrameHandle>,
@@ -71,45 +37,33 @@ impl RenderBaseline {
         Self { targets, frames }
     }
 
-    /// Did this frame exist before the addon ran a line?
-    ///
-    /// The one question [`super::use_probe`] asks of the baseline: a pointer event is only the
-    /// addon's to be judged by when the frame that captures it is one the addon itself created.
+    /// Whether `frame` existed before the addon ran; [`super::use_probe`] judges only pointer
+    /// events captured by frames the addon created.
     pub(super) fn is_pre_existing(&self, frame: FrameHandle) -> bool {
         self.frames.contains(&frame)
     }
 }
 
-/// One place on screen the addon **painted** — a candidate for [`super::use_probe`] to point at.
-///
-/// Emitted by the same walk that attributes the render column, and that is deliberate: "which
-/// pixels are this addon's" is one question with one answer, and computing it twice is how two
-/// instruments start disagreeing about the same addon.
+/// One place the addon painted, for [`super::use_probe`] to point at; emitted by the same walk
+/// that attributes the render column, so the two never disagree.
 pub(super) struct Painted {
-    /// The frame the quad was charged to. Only used to **dedupe** candidates — sixteen quads on
-    /// one button should not spend sixteen hit-tests — never to decide what gets driven; the
-    /// hit-test does that, because the frame that owns a painted region is often not the frame
-    /// that would actually eat a click on it.
+    /// The frame the quad was charged to, used only to dedupe candidates: the hit-test decides
+    /// which frame a click reaches.
     pub(super) owner: FrameHandle,
-    /// The centre of the painted rect: where a player's cursor would be to be "on" this pixel.
+    /// The centre of the painted rect.
     pub(super) point: (f32, f32),
 }
 
-/// What an addon put on screen.
-///
-/// Ordered by how much of the screen the addon owns, so a `>` comparison reads the way it looks.
+/// What an addon put on screen, ordered by how much of the screen it owns.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord)]
 pub enum Drew {
-    /// Not one painting quad came from anything this addon created. Bagnon's row before the fix,
-    /// and the answer this column was built to be able to give.
+    /// No painting quad came from anything the addon created.
     #[default]
     Nothing,
-    /// It painted, but only from widgets hanging off frames that already existed — an overlay on
-    /// somebody else's window. `!OmniCC`'s countdown text is the reference case: an anonymous
-    /// `Frame` + `FontString` parented to one of our action buttons' cooldowns.
+    /// Painted only from widgets hung off pre-existing frames, such as `!OmniCC`'s anonymous
+    /// countdown text on an action button's cooldown.
     Overlay,
-    /// It painted from a window of its own — a frame tree rooted outside everything that existed
-    /// before it. Bagnon's inventory window, once it works.
+    /// Painted from a frame tree of its own, rooted outside everything pre-existing.
     Own,
 }
 
@@ -131,12 +85,8 @@ pub struct RenderReport {
     pub own_quads: usize,
     /// Painting quads from widgets the addon hung off a frame that already existed.
     pub overlay_quads: usize,
-    /// **Every** distinct named frame, not a sample — [`MAX_NAMED_FRAMES`] bounds only what is
-    /// PRINTED, because a caller that asks "did it draw an item slot?" cannot answer that from a
-    /// truncated list, and one of ours silently could not.
-    ///
-    /// The distinct named frames those quads were charged to, nearest-named-ancestor per quad, so
-    /// a `nothing`/`own` row can be read back to a place in the addon's own code. Capped, sorted.
+    /// Every distinct named frame the quads were charged to (nearest named ancestor), sorted and
+    /// uncapped: [`MAX_NAMED_FRAMES`] bounds only the print.
     pub frames: Vec<String>,
 }
 
@@ -150,64 +100,23 @@ impl RenderReport {
     }
 }
 
-/// How many named frames a row PRINTS. Enough to name the window; not enough to be a dump.
-///
-/// **This bounds the display, not the collection, and that distinction is the whole of 1242.** It
-/// used to stop the `named` set filling at 6 — so a row kept the first six names *encountered* and
-/// then rendered them through a `BTreeSet`, i.e. sorted. The output therefore read as an
-/// alphabetical list of what an addon drew while actually being an arbitrary six of N, and nothing
-/// said so.
-///
-/// That is not hypothetical damage. `render_tests`'
-/// `the_directors_two_verified_addons_come_out_on_opposite_sides` asserts Bagnon draws frames named
-/// `BagnonItem*` — the director's original complaint. It passed only because `BagnonItem1` happened
-/// to be among the first six quads attributed. Seating the player's PURSE in the session fixture
-/// added `BagnonMoneyFrameSilverButton` to the same window, which took the sixth slot, evicted
-/// `BagnonItem1`, and made the test assert — correctly, against the data it was given — that Bagnon
-/// draws no item slots at all. The addon had not changed.
-///
-/// So the set now collects everything and the cap applies where the constraint actually is: the
-/// printed line. 1242's rule, in the second instrument to break it.
+/// How many named frames a row prints. It bounds the display, never the collection: a set capped
+/// while filling keeps an arbitrary few that then print sorted, as if complete.
 pub const MAX_NAMED_FRAMES: usize = 6;
 
-/// Drive the entry points that make a UI **visible**, then attribute every painting quad.
+/// Open the entry points that make a UI visible, tick, then attribute every painting quad.
 ///
-/// **This is a different probe from [`super::drive_ui_probe`], not a duplicate of it**, and the
-/// difference is the whole point: that one *toggles* — open then close — because what it measures
-/// is whether an override raises on both paths. A render read after it sees a closed window. This
-/// one only ever **opens**, and leaves everything up, because what it measures is what is on the
-/// screen at the end.
-///
-/// The entry points are chosen because a corpus addon is measured to replace or hook each:
-///
-/// | driven | why |
-/// |---|---|
-/// | `OpenBackpack()` | Bagnon replaces it — and with an *open*, not a toggle, unlike its `ToggleBackpack`/`OpenAllBags` |
-/// | `CooldownFrame_SetTimer` on a real button | `!OmniCC` hooks exactly this global; its text exists only while a cooldown runs |
-/// | `ActionButton_Update` | zBar, zBarEx, CT_BarMod |
-/// | a shown `GameTooltip` | the hover class (decision 1220) — left SHOWN, where the UI probe hides it |
-///
-/// Then ten ticks, because a great deal of addon painting happens on the first `OnUpdate` —
-/// OmniCC's countdown text is written there and nowhere else, so a probe that never ticked would
-/// score our one director-verified working addon as blank.
-///
-/// Returns the report **and the places the addon painted**, in painter order, for
-/// [`super::use_probe`] to point at. Nothing else in the survey knows which pixels are the addon's,
-/// and it should stay that way: one attribution, one answer.
+/// Unlike [`super::drive_ui_probe`], which toggles open then closed, this only opens and leaves
+/// everything up. It opens the backpack, updates action button 1 and starts its cooldown, and
+/// shows the tooltip, the entry points corpus addons replace or hook; then ten ticks, since much
+/// addon painting happens in the first `OnUpdate`. Returns the report and the places the addon
+/// painted, in painter order, for [`super::use_probe`].
 pub(super) fn measure_render(
     script: &mut UiScript,
     baseline: &RenderBaseline,
 ) -> (RenderReport, Vec<Painted>) {
-    // A REAL ACTION on slot 1, with a real icon and a running cooldown.
-    //
-    // Not decoration — without it this column scored `!OmniCC` as blank, and `!OmniCC` is on the
-    // director's screen. Its `OnUpdate` writes the countdown only `if floor(remain + 0.5) > 0 and
-    // this.icon:IsVisible()`, and on an empty bar `ActionButton1Icon` is hidden, so the text frame
-    // is created, shown, and never given a single character. An empty action bar is a state a
-    // level-60 session does not present; `seat_a_session`'s argument, one slot wide.
-    //
-    // Seated HERE rather than in `seat_a_session` on purpose (1225's rule): this runs after every
-    // other column has been read, so no number beside this one can be perturbed by it.
+    // A real action with an icon on slot 1: cooldown-count addons write text only while the
+    // button's icon is visible. Seated here, after every other column is read, so it perturbs none.
     script.set_action(
         1,
         Some(benilla_ui::script::ActionSlot {
@@ -225,11 +134,8 @@ pub(super) fn measure_render(
             ..Default::default()
         }),
     );
-    // A REAL BACKPACK, for the same reason. `GetContainerNumSlots(0)` answers 16 for every
-    // character in the game; in a VM where it answers 0 a bag addon correctly draws a window with
-    // no slots in it — which is *exactly* the picture this column was built to be able to catch,
-    // so leaving it unseated would make the column blind to its own founding case. Sixteen empty
-    // slots, no items: an addon that paints a slot paints it whether or not something is in it.
+    // A 16-slot empty backpack, as every character has: with 0 slots a bag addon draws a window
+    // with no slots, the very failure this column catches.
     script.set_container(
         0,
         Some(benilla_ui::script::ContainerState {
@@ -238,9 +144,8 @@ pub(super) fn measure_render(
             slots: std::collections::HashMap::new(),
         }),
     );
-    // Guarded on each global being a FUNCTION and each raise swallowed: a raise here is
-    // `probe_errors`' column to report, and letting one abort the run would silently zero every
-    // measurement after it (the mis-attribution 1209 was written about).
+    // Each global is called only if it is a function and each raise is swallowed: raises are the
+    // `probe_errors` column's, and one here must not zero the measurements after it.
     let _ = script.run(
         r#"
         local function try(fn) if type(fn) == "function" then pcall(fn) end end
@@ -277,20 +182,17 @@ pub(super) fn measure_render(
     let mut named: BTreeSet<String> = BTreeSet::new();
     let mut painted: Vec<Painted> = Vec::new();
     for quad in script.extract() {
-        // A frame's own slot paints NOTHING (`ui_script::extract`'s converter drops it outright);
-        // a Backdrop, Texture, Text, Minimap or Cooldown is pixels. Counting the frame slot would
-        // score every addon that merely *creates* a frame as having drawn, which is the exact
-        // false pass this column exists to stop.
+        // A frame's own slot paints nothing; counting it would score every addon that merely
+        // creates a frame as having drawn.
         if matches!(quad.content, QuadContent::Frame) {
             continue;
         }
-        // Under-constrained widgets never reach the screen either. Bound here rather than merely
-        // tested, because the rect is also WHERE the addon painted — the point `use_probe` aims at.
+        // Under-constrained widgets never reach the screen; the rect is where `use_probe` aims.
         let Some(rect) = quad.rect else {
             continue;
         };
         if baseline.targets.contains(&quad.target) {
-            continue; // ours, drawing as it always did
+            continue; // pre-existing, not the addon's
         }
         let Some(owner) = script.target_frame(quad.target) else {
             continue;
@@ -300,9 +202,7 @@ pub(super) fn measure_render(
         } else {
             report.own_quads += 1;
         }
-        // The same quad, kept as a place to point at. An off-screen or zero-area one simply
-        // hit-tests to nothing later, which is the honest answer for it — no filtering here, or
-        // the two columns would disagree about which pixels are the addon's.
+        // Unfiltered: an off-screen quad hit-tests to nothing later.
         painted.push(Painted {
             owner,
             point: centre(rect),
@@ -315,33 +215,19 @@ pub(super) fn measure_render(
     (report, painted)
 }
 
-/// The middle of a rect, in the y-up UI space `resolve`/`extract`/`hit_test` all share.
+/// The middle of a rect, in the y-up UI space `resolve`, `extract` and `hit_test` share.
 fn centre(r: Rect) -> (f32, f32) {
     ((r.left + r.right) * 0.5, (r.bottom + r.top) * 0.5)
 }
 
-/// Does this new frame hang off one of **our widgets**, rather than off the screen?
-///
-/// The overlay/own split, and it needs more care than "did it reach a pre-existing frame", because
-/// *everything* does: `UIParent` is where every window in the game is parented, ours and theirs
-/// alike, so that test calls every addon an overlay (it did — this function's first draft failed
-/// its own fixture). The seam is one step further in: walk to the nearest ancestor that existed
-/// before the addon ran, and ask whether **it** is a top-level frame.
-///
-/// - nearest pre-existing ancestor is top-level (`UIParent`, `WorldFrame`, the screen root) → the
-///   addon put a window on the screen. Bagnon.
-/// - nearest pre-existing ancestor is *nested* inside one of our windows → the addon decorated
-///   something of ours. `!OmniCC`'s anonymous text frame, whose parent is an action button's
-///   cooldown.
-/// - no pre-existing ancestor at all (a detached tree) → its own, by the same reading.
-///
-/// The walk is bounded by the tree's own depth.
+/// Whether the nearest pre-existing ancestor of `frame` is nested inside a window (an overlay)
+/// rather than top-level (the addon's own window). Every window hangs off `UIParent`, so merely
+/// reaching a pre-existing frame proves nothing; a detached tree is the addon's own.
 fn hangs_off_one_of_ours(script: &UiScript, baseline: &RenderBaseline, frame: FrameHandle) -> bool {
     let mut cursor = Some(frame);
     while let Some(fh) = cursor {
         if baseline.frames.contains(&fh) {
-            // `UIParent` and friends carry no parent of their own — reaching one of those means
-            // the addon reached the *screen*, which is not somebody else's window.
+            // A pre-existing frame with no parent is the screen root, not another window.
             return script.frame_parent(fh).is_some();
         }
         cursor = script.frame_parent(fh);
diff --git a/crates/benilla-app/src/addon_harness/render_tests.rs b/crates/benilla-app/src/addon_harness/render_tests.rs
index 3467ec7f..7a639b3a 100644
--- a/crates/benilla-app/src/addon_harness/render_tests.rs
+++ b/crates/benilla-app/src/addon_harness/render_tests.rs
@@ -1,22 +1,5 @@
-//! **The render column's can-it-fail proof.**
-//!
-//! A probe that cannot fail is not a probe, and this arc has shipped two that could not: the UI
-//! probe swallowed every raise it was built to report (`the_ui_probe_records_what_an_override_raises`
-//! is that scar), and the method oracle answered "nothing missing" when it could not run at all.
-//! So this file pins **both directions**, twice over.
-//!
-//! **Synthetically**, on three fixture addons written to be unambiguous — one that paints a
-//! texture, one that hangs a FontString off a frame it did not create, and one that creates a
-//! shown frame with nothing paintable on it. The third is the sharp one: a frame's own draw slot
-//! emits a quad and paints **nothing** (`ui_script::extract`'s converter drops it), so an
-//! implementation that counted quads instead of *painting* quads would score it as drawing and
-//! every `nothing` row in the corpus would be a lie.
-//!
-//! **And against reality**, on the two addons the director has verified with their own eyes:
-//! `!OmniCC`'s countdown numbers are on their screen, and Bagnon's bag slots were not. Two real
-//! addons with known, opposite, human-checked outcomes is a better oracle than any fixture — it is
-//! the check that would have caught this class months ago — so
-//! [`the_directors_two_verified_addons_come_out_on_opposite_sides`] is the one to read first.
+//! Tests for the render column, in both directions: synthetic fixtures that paint a window, an
+//! overlay or nothing, and two real corpus addons with known opposite outcomes.
 
 use std::path::{Path, PathBuf};
 
@@ -61,8 +44,8 @@ impl Drop for Fixtures {
     }
 }
 
-/// **The proof, in both directions.** An addon that paints must register; one that does not must
-/// not — and "creates a frame" is not "paints".
+/// An addon that paints registers, one that does not stays `nothing`, and creating a frame is not
+/// painting.
 #[test]
 fn the_render_column_can_fail() {
     benilla_formats::wow_data_or_skip!();
@@ -80,7 +63,7 @@ fn the_render_column_can_fail() {
         f:Show()
     "#,
     );
-    // Paints, but onto one of OUR frames — no window of its own anywhere.
+    // Paints, but only onto a pre-existing frame.
     fx.addon(
         "PaintsOnOurs",
         r#"
@@ -91,9 +74,7 @@ fn the_render_column_can_fail() {
         fs:Show()
     "#,
     );
-    // Draws NOTHING — but is far from inert: it creates a frame, shows it, and that frame emits a
-    // `QuadContent::Frame` entry. Nothing paints from it. This is the fixture that fails a naive
-    // implementation.
+    // Creates and shows a frame, whose own `QuadContent::Frame` slot paints nothing.
     fx.addon(
         "DrawsNothing",
         r#"
@@ -113,8 +94,7 @@ fn the_render_column_can_fail() {
             .unwrap_or_else(|| panic!("{name} was not surveyed"))
     };
 
-    // Every fixture must actually have RUN — otherwise "drew nothing" would be measuring a load
-    // failure, which is the confusion this column exists to end.
+    // Each fixture must load, or "drew nothing" would measure a load failure.
     for name in ["PaintsAWindow", "PaintsOnOurs", "DrawsNothing"] {
         assert!(
             drew(name).loaded,
@@ -158,26 +138,14 @@ fn the_render_column_can_fail() {
     );
 }
 
-/// **The oracle: two real addons, opposite director-verified outcomes.**
-///
-/// `!OmniCC` puts cooldown countdown numbers on the director's screen — it works, and it works by
-/// creating an **anonymous** frame parented to one of our cooldowns, so any check built on name
-/// prefixes or on "did it create a top-level window" scores it zero. Bagnon has to build its own
-/// item-slot buttons, and the director saw none of them.
-///
-/// The two are surveyed together in one throwaway root — copies are not made, the corpus folders
-/// are surveyed where they lie — and the column must place them on opposite sides:
-/// `!OmniCC` an [`Drew::Overlay`], Bagnon a window of its [`Drew::Own`].
-///
-/// If this test ever disagrees with the director's eyes, **the test is wrong**.
+/// `!OmniCC` paints through an anonymous frame parented to an existing cooldown, an overlay;
+/// Bagnon builds its own window of item-slot buttons.
 #[test]
 fn the_directors_two_verified_addons_come_out_on_opposite_sides() {
     benilla_formats::wow_data_or_skip!();
-    // The one resolver, and a skip the gate can refuse (`benilla_formats::install`).
+    // A skip the gate can refuse (`benilla_formats::install`).
     let corpus = benilla_formats::addon_corpus_or_skip!();
-    // A root holding just these four, SYMLINKED rather than copied. Surveying the whole corpus
-    // here would put a minute onto `cargo test --workspace` for four rows — the full sweep is the
-    // `addon_harness` example's job, not a unit test's.
+    // Symlinked into a small root: the full corpus sweep is the `addon_harness` example's job.
     let fx = Fixtures::new("oracle");
     for name in ["!OmniCC", "Bagnon", "Bagnon_Core", "Bagnon_Forever"] {
         std::os::unix::fs::symlink(corpus.join(name), fx.root().join(name)).unwrap();
@@ -190,8 +158,7 @@ fn the_directors_two_verified_addons_come_out_on_opposite_sides() {
             .unwrap_or_else(|| panic!("{name} is not in the corpus"))
     };
 
-    // The POSITIVE control. A render check that scores this one blank is broken, whatever else it
-    // gets right — the director sees its numbers.
+    // The positive control.
     assert_eq!(
         row("!OmniCC").render.drew(),
         Drew::Overlay,
@@ -199,8 +166,6 @@ fn the_directors_two_verified_addons_come_out_on_opposite_sides() {
          parented to a cooldown of ours, which is precisely what a name-based check cannot see"
     );
 
-    // The case that started this. Bagnon builds its own window; before the two fixes it built
-    // nothing at all and every other column called it fine.
     assert_eq!(
         row("Bagnon").render.drew(),
         Drew::Own,
diff --git a/crates/benilla-app/src/addon_harness/together.rs b/crates/benilla-app/src/addon_harness/together.rs
index 4b45dfd5..bb8112cd 100644
--- a/crates/benilla-app/src/addon_harness/together.rs
+++ b/crates/benilla-app/src/addon_harness/together.rs
@@ -1,55 +1,20 @@
-//! **The control for the one-VM-per-addon bound** — the whole folder in ONE VM, the way a real
-//! client runs it.
+//! The control for the survey's one-VM-per-addon bound: the whole folder in one VM, as a real
+//! client runs it, walked in load order with each `ADDON_LOADED` at its own position, then one
+//! session start. Rows differ from the survey's where an addon relies on a library a neighbour
+//! ships.
 //!
-//! The survey next door loads each addon into a VM of its own, with only its declared dependencies
-//! underneath, and says so in its own header: *the headline is a floor, not an estimate*. That
-//! bound is real and it is the largest single category left in the corpus's failures — a package
-//! that does not ship `Tablet-2.0` and simply expects the library to be there, because in a folder
-//! of 219 addons seventy of its neighbours ship a copy and Ace2's registry is one global table.
+//! It cannot attribute render or use results, and cannot tell clean from never reached;
+//! attribution is by the raising chunk alone.
 //!
-//! **A bound that is stated and never measured is an excuse.** This is the measurement: one Lua
-//! state, every addon in the folder walked in load order, dependencies first, each addon's
-//! `ADDON_LOADED` at its own position — then the session start, once, for everybody. What comes
-//! back is *which addons raise inside their own files when their neighbours are present*, and the
-//! difference between that list and the survey's is exactly the size of the bound.
+//! A shared VM is not reproducible: Lua hashes a table key by its pointer, so `pairs()` over an
+//! object-keyed registry (every Ace2 library's) walks in a different order per process under
+//! ASLR, as the reference's Lua does. So the walk runs [`DEFAULT_RUNS`] times in fresh VMs and
+//! each row reports how many runs raised: every run is a real failure, some is order-sensitive.
 //!
-//! ## What this is NOT
-//!
-//! Not a replacement for the survey and not a headline. It cannot attribute a *render* or a *use*
-//! result (every addon's frames are in one world), it cannot tell "clean" from "never reached",
-//! and one addon's runaway is everybody's. Attribution here is by the RAISING CHUNK and nothing
-//! else — the same rule the survey applies to session errors, and the only one available when 219
-//! addons share a state.
-//!
-//! ## It is run N times, and the reason is the whole finding
-//!
-//! **A big shared VM is not reproducible, and that is a property of Lua rather than a defect of
-//! ours.** Lua 5.1 hashes a **table key by its POINTER** (`hashpointer`), so `pairs()` over a
-//! registry keyed by objects — which is what every Ace2 library's registry is — walks in a
-//! different order on every process, because ASLR moves the addresses. Measured directly rather
-//! than deduced: twelve fresh tables as keys in one table, iterated, gave `3,7,11,1,…` then
-//! `12,5,9,2,…` then `11,1,4,8,…` on three consecutive runs of the same binary.
-//!
-//! The reference's Lua does exactly the same thing, so this is a fact about the sessions we are
-//! modelling and not something to fix. What it means for an INSTRUMENT is that a single run's
-//! number cannot be quoted: three consecutive runs here disagreed by one addon and swapped three
-//! rows. So the walk runs [`DEFAULT_RUNS`] times in fresh VMs and the verdict is per row:
-//!
-//!   - **raised in EVERY run** — a real failure with the neighbours present;
-//!   - **raised in SOME** — order-sensitive, named as such and never folded into either count;
-//!   - **clean in every run** — clean.
-//!
-//! The per-addon survey next door has been stable run to run (three rosters, byte-identical), and
-//! the reason is scale rather than luck: one addon and its declared dependencies rarely build a
-//! pointer-keyed registry big enough for the order to change an outcome. "Rarely" is not "never",
-//! which is worth knowing about every `--diff` this arc has read as exact.
-//!
-//! **LoadOnDemand is ignored on purpose.** 62 of the corpus's manifests carry `## LoadOnDemand: 1`
-//! and the boot walk skips every one (`0x51f600` loads only records whose LoadOnDemand byte is 0),
-//! but the corpus's own addons then demand-load them: `FuBar.lua:1034`'s `LoadLoadOnDemandPlugins`
-//! pulls in every installed `FuBar_*` the moment any one of them seats, and Auctioneer's stub does
-//! the same for its family. A run that honoured the flag would answer for a session five minutes
-//! shorter than the one anybody plays.
+//! `## LoadOnDemand: 1` is ignored: the reference's boot walk skips those (`0x51f600` loads only
+//! records whose LoadOnDemand byte is 0), but corpus addons demand-load them at once (FuBar's
+//! `LoadLoadOnDemandPlugins`, Auctioneer's stub), so honouring the flag would model a shorter
+//! session than anyone plays.
 
 use std::collections::BTreeSet;
 use std::path::Path;
@@ -61,17 +26,15 @@ use super::{
 };
 use benilla_ui::toc::Toc;
 
-/// How many times [`survey_together`] repeats the walk before it reports — see the module doc on
-/// why one run is not quotable. Three is the smallest number that can tell "always" from
-/// "sometimes"; each run is about twenty-five seconds.
+/// How many fresh-VM runs [`survey_together`] makes: three is the fewest that tell "always" from
+/// "sometimes".
 pub const DEFAULT_RUNS: usize = 3;
 
 /// One addon's verdict in the shared VM.
 pub struct TogetherRow {
     pub name: String,
-    /// Raises whose first stack frame is inside **this** addon's own folder, load-time and
-    /// session-time together — the shared VM cannot separate the two windows per addon. From the
-    /// FIRST run that produced any, so the text is a real traceback and not a merge of several.
+    /// Raises whose first stack frame is in this addon's folder, load and session together, from
+    /// the first run that produced any, so the text is one real traceback.
     pub errors: Vec<String>,
     /// How many of the [`runs`](Self::runs) raised at all.
     pub raised_in: usize,
@@ -79,18 +42,18 @@ pub struct TogetherRow {
 }
 
 impl TogetherRow {
-    /// Raised in every run — a failure the neighbours do not fix.
+    /// Raised in every run: a failure the neighbours do not fix.
     pub fn always_raises(&self) -> bool {
         self.raised_in == self.runs
     }
-    /// Raised in some runs and not others — the pointer-hash order showing through (module doc).
+    /// Raised in some runs and not others: the pointer-hash order showing through.
     pub fn order_sensitive(&self) -> bool {
         self.raised_in > 0 && self.raised_in < self.runs
     }
 }
 
-/// Load every addon under `root` into one VM and drive the session start — [`DEFAULT_RUNS`] times,
-/// in a fresh VM each time, because one run's answer is not reproducible (module doc).
+/// Load every addon under `root` into one VM and drive the session start, [`DEFAULT_RUNS`] times
+/// in fresh VMs.
 pub fn survey_together(root: &Path) -> Vec<TogetherRow> {
     let mut merged: Vec<TogetherRow> = Vec::new();
     for run in 0..DEFAULT_RUNS {
@@ -123,7 +86,7 @@ pub fn survey_together(root: &Path) -> Vec<TogetherRow> {
     merged
 }
 
-/// One walk, one VM — the measurement [`survey_together`] repeats.
+/// One walk in one VM.
 fn survey_together_once(root: &Path) -> Vec<(String, Vec<String>)> {
     let (names, installed, registry) = corpus(root);
     let Ok(mut script) = UiScript::new() else {
@@ -134,12 +97,10 @@ fn survey_together_once(root: &Path) -> Vec<(String, Vec<String>)> {
     super::seat_a_session(&mut script);
     let _ = crate::ui_script::load_default_ui(&script);
 
-    // `seen` spans the WHOLE walk, not one addon: a library folder declared by eighty dependents
-    // loads once, which is the property that makes this a session rather than eighty of them.
+    // `seen` spans the whole walk: a library declared by many dependents loads once.
     let mut seen: BTreeSet<String> = BTreeSet::new();
-    // `(folder, its own load failures)` — kept beside the walk rather than read back out of the
-    // VM, because the diagnostics log caps at 256 distinct rows and evicts, and 219 addons
-    // overflow it. The survey has the same rule for the same reason.
+    // `(folder, its load failures)`, kept beside the walk: the VM's diagnostics log caps at 256
+    // distinct rows and evicts.
     let mut load_errors: Vec<(String, Vec<String>)> = Vec::new();
     for name in &names {
         let Some(toc) = manifest_path(root, name)
@@ -149,17 +110,14 @@ fn survey_together_once(root: &Path) -> Vec<(String, Vec<String>)> {
             continue;
         };
         if !seen.insert(name.to_ascii_lowercase()) {
-            continue; // already pulled in as somebody's dependency
+            continue; // already loaded as a dependency
         }
-        // Re-armed PER ADDON, exactly as the live walk re-arms it (1306): without the reset one
-        // runaway spends the whole allowance and every addon after it fails for somebody else's
-        // loop.
+        // Re-armed per addon, as the live walk does, so one runaway does not starve the rest.
         script.set_instruction_budget(ADDON_INSTRUCTION_BUDGET);
         let mut pulled: Vec<LoadedDep> = Vec::new();
         load_dependencies(&mut script, root, &toc, &installed, &mut seen, &mut pulled);
-        // **A dependency's load failures are collected HERE and nowhere else.** In this VM a
-        // library folder loads exactly once, under whichever dependent reached it first, so it
-        // never gets a turn of its own in the loop below — and its failures would simply vanish.
+        // A dependency's load failures are collected only here: it loads once, under the first
+        // dependent to reach it, and never gets a turn of its own.
         for dep in pulled {
             load_errors.push((dep.name, dep.files.errors));
         }
@@ -179,14 +137,12 @@ fn survey_together_once(root: &Path) -> Vec<(String, Vec<String>)> {
         script.tick(0.1);
     }
 
-    // Attribution by the raising chunk. `\<Folder>\` rather than a prefix match, because Lua
-    // truncates a long chunk name from the LEFT (`...Ons\FuBar_DakSmak\Libs\…`) and the prefix is
-    // the half it eats.
+    // Attribution by the raising chunk, matched as `\<Folder>\` rather than a prefix: Lua
+    // truncates a long chunk name from the left (`...Ons\FuBar_DakSmak\Libs\…`).
     let mut rows: Vec<(String, Vec<String>)> =
         names.iter().map(|n| (n.clone(), Vec::new())).collect();
-    // The LOAD half first, already attributed by whose manifest was being walked — the survey's
-    // own `loaded` rule applies unchanged: a named file the package does not contain is not a
-    // raise (2155), so it is not counted here either.
+    // Load failures first, attributed by whose manifest was walked; a missing named file is not a
+    // raise, as in the survey.
     for (folder, errs) in load_errors {
         let Some(row) = rows.iter_mut().find(|r| r.0 == folder) else {
             continue;
@@ -216,8 +172,8 @@ fn survey_together_once(root: &Path) -> Vec<(String, Vec<String>)> {
     rows
 }
 
-/// A load failure that is only *a file the package does not contain* — the reference logs
-/// `Couldn't open %s` and carries on (2155), so it is not a raise here either.
+/// A load failure that is only a file the package does not contain: the reference logs
+/// `Couldn't open %s` and carries on.
 fn is_absent_file(err: &str) -> bool {
     err.ends_with(": not found")
         || err.contains("no provider hit for")
@@ -228,11 +184,7 @@ fn is_absent_file(err: &str) -> bool {
 mod tests {
     use super::*;
 
-    /// **The control answers the question it exists for**: an addon whose package is short a
-    /// library its neighbour ships fails ALONE and is clean TOGETHER.
-    ///
-    /// Both halves are asserted, because either one alone would pass for the wrong reason — a
-    /// control that finds everything clean is worthless, and so is one that finds nothing.
+    /// An addon short a library its neighbour ships fails alone and is clean together.
     #[test]
     fn a_library_a_neighbour_ships_is_there_in_the_shared_vm() {
         let tmp =
@@ -244,16 +196,15 @@ mod tests {
             std::fs::write(dir.join(format!("{name}.toc")), toc).unwrap();
             std::fs::write(dir.join(file), body).unwrap();
         };
-        // Loads FIRST (`A` before `Z` under the walk's NTFS collation) and puts the library in
-        // the one global state, exactly as any of the seventy corpus packages that ship a copy of
-        // `Tablet-2.0` does.
+        // Loads first (`A` before `Z` under the walk's NTFS collation) and puts the library in the
+        // global state, as corpus packages that ship `Tablet-2.0` do.
         write(
             "AlphaShipsIt",
             "## Interface: 11200\nlib.lua\n",
             "lib.lua",
             "SharedLibrary = { greet = function() return 1 end }\n",
         );
-        // Declares no dependency on it and does not ship it — the corpus's own shape.
+        // Declares no dependency on it and does not ship it.
         write(
             "ZuluWantsIt",
             "## Interface: 11200\nuse.lua\n",
@@ -287,7 +238,7 @@ mod tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
-    /// ...and a raise is still ATTRIBUTED, rather than the shared VM turning everything green.
+    /// A raise in the shared VM is still attributed to its folder.
     #[test]
     fn a_raise_in_the_shared_vm_lands_on_the_folder_that_raised() {
         let tmp = std::env::temp_dir().join(format!(
diff --git a/crates/benilla-app/src/addon_harness/use_probe.rs b/crates/benilla-app/src/addon_harness/use_probe.rs
index 8f7e1f5d..92f0a304 100644
--- a/crates/benilla-app/src/addon_harness/use_probe.rs
+++ b/crates/benilla-app/src/addon_harness/use_probe.rs
@@ -1,63 +1,17 @@
-//! **The use column — "does it survive being USED?"**
+//! The use column: drive real pointer input (hover, left and right click, drag) at the frames the
+//! addon itself painted, through [`UiScript::mouse_move`] and [`UiScript::mouse_button`] as the
+//! app does, and report what raised. An addon can load, run its handlers and draw, yet raise the
+//! moment it is hovered.
 //!
-//! ## Why there is a fifth column, and why it is the fourth of its kind
+//! A row that drove nothing is [`Used::Untouched`], never a pass; [`UseReport::driven`] prints
+//! beside every verdict.
 //!
-//! This survey has now been wrong at four successive depths, and a human found every one of them by
-//! **playing**, never a number here:
+//! Targets come from [`super::render`]'s attribution, hit-tested, and a target is kept only when
+//! the frame that captures the point is one the addon created: driving a pre-existing frame would
+//! charge its raise to whichever addon is in the VM. So an addon that only hooks existing frames
+//! (`PlayerFrame:SetScript("OnEnter", …)`) reads `untouched` here.
 //!
-//! 1. `loaded` measured *"the addon's files ran"*. Bagnon scored perfect and did nothing.
-//! 2. [`super::drive_session_start`] measured *"the handlers ran"* (1213). Same result.
-//! 3. [`super::drive_ui_probe`] measured *"the override body ran"*. Same result.
-//! 4. [`super::render`] measured *"something was drawn"* (1230). Bagnon now draws sixteen bag
-//!    slots — and the director hovered them and got a wall of
-//!    `attempt to call global 'ContainerFrameItemButton_OnEnter' (a nil value)`.
-//!
-//! Every one of those columns asks whether something **ran or appeared**. None of them **touches**
-//! anything. So an addon whose UI is fully drawn and completely inert scores full marks on all
-//! four, which is exactly what Bagnon did on the morning this was written.
-//!
-//! This column drives real pointer input — hover, left click, right click, drag — at the frames the
-//! addon **itself painted**, through the same [`UiScript::mouse_move`]/[`UiScript::mouse_button`]
-//! entry points the app feeds from the host window, and reports what raised.
-//!
-//! ## "Nothing raised" and "nothing was touched" are different answers
-//!
-//! [`Used::Untouched`] exists because the failure this instrument is most likely to repeat is its
-//! own history: the UI probe once shipped with a `pcall` that swallowed every raise and reported a
-//! spotless corpus forever. A probe that drove **zero** targets and printed "clean" would be that
-//! bug with a different mechanism, so a row that touched nothing says so in the verdict itself and
-//! is counted separately in the report. [`UseReport::driven`] is printed beside every verdict for
-//! the same reason: a clean row with `driven = 0` is not evidence of anything.
-//!
-//! `!OmniCC` — director-verified working — is precisely that shape, and it is the reason the
-//! distinction is not academic. Its entire visible output is a `FontString` on an **anonymous,
-//! mouse-disabled** `Frame` parented to a cooldown; there is nothing on it a pointer can reach, and
-//! there is nothing wrong with it either. `untouched`, not `raised`.
-//!
-//! ## What gets driven: the addon's own frames, and only those
-//!
-//! The target list is [`super::render`]'s own attribution — the quads that addon painted — turned
-//! into points and hit-tested. **A candidate is kept only when the frame that captures the point is
-//! one the addon created**; when one of ours is on top, or the painted region belongs to a
-//! mouse-disabled frame and our window underneath eats the click, the candidate is dropped rather
-//! than driven.
-//!
-//! That rule is the whole attribution argument. Driving one of *our* frames and charging what it
-//! raises to whichever addon happens to be in the VM is the mis-attribution decision 1209 was
-//! written about, and it would smear a single FrameXML bug across two hundred rows.
-//!
-//! The cost of the rule, stated: **an addon that only hooks our frames is invisible here.** A
-//! `PlayerFrame:SetScript("OnEnter", …)` replacement is a real corpus shape, and this column scores
-//! it `untouched`. Reaching it needs a script-table diff rather than a handle diff — a different
-//! instrument, named here so nobody reads an `untouched` row as proof of anything.
-//!
-//! ## What a raise here means, and what it does not
-//!
-//! It means **a player doing that would see that error**. It does *not* say whose fault it is: the
-//! wall the director hit is our missing `ContainerFrameItemButton_OnEnter`, reached through
-//! Bagnon's slot button. That is the same open question 1213 §4 and 1204 §4 left about every other
-//! column, and it is deliberately not answered here — "hovering this addon's UI raises" is the
-//! finding, whoever owes the fix.
+//! A raise means a player doing that would see the error; it does not say whose code is at fault.
 
 use std::collections::HashSet;
 
@@ -66,45 +20,25 @@ use benilla_ui::widget::FrameHandle;
 
 use super::render::{Painted, RenderBaseline};
 
-/// How many distinct frames one addon gets driven. **The bound, and what it drops.**
-///
-/// 218 VMs times this times the seven pointer events below is the whole cost of the column, and
-/// each event pays a full [`UiScript::hit_test`] (a traversal + sort of the arena). Eight is what a
-/// window's worth of interactive surface looks like — Bagnon's sixteen slots are sixteen instances
-/// of one button template, so the ninth tells you nothing the first did not — and it holds the
-/// column's share of the survey to seconds rather than minutes.
-///
-/// What it drops: the 9th..Nth distinct target, in painter order (so the earliest-drawn survive).
-/// An addon whose only broken widget is the twelfth thing it painted reads clean here. Stated
-/// rather than hidden, and the number is a constant precisely so raising it is one edit.
+/// How many distinct frames one addon gets driven; each event pays a full hit-test. Targets past
+/// it, in painter order, are dropped, so a broken ninth widget reads clean.
 pub const MAX_USE_TARGETS: usize = 8;
 
-/// How far the drag gesture travels. Must exceed `cursor::DRAG_START_THRESHOLD` (4 px, strict `>`)
-/// or `OnDragStart` never fires and the "drag" is silently two clicks; small enough that it stays
-/// inside a 16-px item slot, or the release lands on a different frame and `OnReceiveDrag` goes
-/// somewhere else.
+/// How far the drag travels: past `cursor::DRAG_START_THRESHOLD` (4 px, strict `>`) so
+/// `OnDragStart` fires, and inside a 16 px item slot so the release lands on the same frame.
 const DRAG_PX: f32 = 5.0;
 
-/// Where the cursor is parked at the end, to fire the last `OnLeave`.
-///
-/// Off-screen by a mile: [`UiScript::hit_test`] answers `None` there whatever the addon built, so
-/// the final hover boundary is guaranteed to be crossed. A hover half-driven — `OnEnter` fired and
-/// `OnLeave` never — is the shape that leaves a tooltip up forever in play, and it is a real corpus
-/// bug class, so the probe always closes the pair.
+/// Where the cursor is parked at the end, off-screen so the last `OnLeave` always fires.
 const PARKED: (f32, f32) = (-10_000.0, -10_000.0);
 
-/// What happened when the addon's own UI was used.
-///
-/// Deliberately **not** ordered: there is no honest ranking between "it raised" and "there was
-/// nothing to touch", and deriving one would invite a `>` comparison that quietly asserts it.
+/// What happened when the addon's own UI was used; unordered, since "raised" and "nothing to
+/// touch" do not rank.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub enum Used {
-    /// **Nothing was touched** — the addon painted nothing a pointer can reach, so this row is not
-    /// a pass and not a failure. The verdict exists so a probe that drove zero targets can never
-    /// be read as one that drove some and found nothing (see the module doc).
+    /// The addon painted nothing a pointer can reach: neither a pass nor a failure.
     #[default]
     Untouched,
-    /// Driven, and it raised. The director's Bagnon: sixteen slots on screen, dead to the touch.
+    /// Driven, and it raised.
     Raised,
     /// Driven, and nothing raised.
     Survived,
@@ -124,15 +58,12 @@ impl Used {
 /// What one addon's UI did when it was used.
 #[derive(Debug, Clone, Default)]
 pub struct UseReport {
-    /// Frames actually driven — **the number that makes a clean row mean anything**. Zero here and
-    /// an empty [`Self::errors`] is [`Used::Untouched`], not a pass.
+    /// Frames actually driven; zero is [`Used::Untouched`], not a pass.
     pub driven: usize,
-    /// Distinct frames of the addon's own that answered a hit-test, **before** [`MAX_USE_TARGETS`].
-    /// Greater than [`Self::driven`] means the cap dropped some; printed so the bound is visible in
-    /// the data rather than only in this comment.
+    /// Distinct addon frames that answered a hit-test, before [`MAX_USE_TARGETS`]; more than
+    /// [`Self::driven`] means the cap dropped some.
     pub touchable: usize,
-    /// The names of the frames driven (anonymous ones omitted), so a row can be read back to a
-    /// place in the addon's own code. Capped by [`MAX_USE_TARGETS`] already.
+    /// The names of the frames driven, anonymous ones omitted.
     pub frames: Vec<String>,
     /// Errors raised by the input, verbatim, in the order they happened.
     pub errors: Vec<String>,
@@ -150,42 +81,25 @@ impl UseReport {
 
 /// Drive hover, both clicks and a drag at everything the addon drew, and report what raised.
 ///
-/// **Runs after every other column has been read and before the method oracle**, for the two
-/// reasons 1225 and 1230 already established: after, so no number beside it can be perturbed by
-/// input this probe invented; before, because the oracle stands up one widget of every kind and
-/// those sixteen frames of the harness's own must never become an addon's input targets.
-///
-/// `painted` is [`super::render`]'s attribution, not a fresh walk — see [`Painted`].
+/// Runs after every other column is read, so its input perturbs none of them, and before the
+/// method oracle, whose widgets must never become input targets. `painted` is
+/// [`super::render`]'s attribution, not a fresh walk.
 pub(super) fn measure_use(
     script: &mut UiScript,
     baseline: &RenderBaseline,
     painted: &[Painted],
 ) -> UseReport {
     let mut report = UseReport::default();
-    // PUT THE TOOLTIP AWAY FIRST, before a single hit-test.
-    //
-    // `measure_render` deliberately leaves `GameTooltip` **shown** — it is measuring what is on
-    // screen at the end, and a tooltip is on screen. But it is one of OURS, it lives in the
-    // TOOLTIP strata (above everything), and it is therefore topmost over whatever it covers: any
-    // addon frame underneath would hit-test to the tooltip, be dropped by the attribution rule
-    // below as "one of ours", and leave the addon reading `untouched` for a reason that has
-    // nothing to do with the addon. That is this column's own founding failure — a probe that
-    // silently drove nothing and reported clean — so it is closed here rather than left to luck.
-    //
-    // Hiding it is also the faithful state: in play the tooltip trails the cursor, it is never the
-    // thing under it. Done BEFORE the error baseline below, so an `OnHide` hook's raise is not
-    // charged to input this probe has not driven yet.
+    // Hide the tooltip `measure_render` left shown first: in the TOOLTIP strata it would capture
+    // every hit-test beneath it, as in play it never does. Done before the error baseline, so an
+    // `OnHide` hook's raise is not charged to input.
     let _ = script.run(
         r#"
         if GameTooltip and type(GameTooltip.Hide) == "function" then pcall(function() GameTooltip:Hide() end) end
     "#,
     );
-    // The addon's painted quads, resolved to the frames a cursor over them would actually hit.
-    //
-    // Two dedupes, and they answer different questions. `owners` bounds the WORK: an icon, its
-    // border, its count text and its highlight are four quads on one button, and hit-testing each
-    // is four traversals for one answer. `hits` bounds the TARGETS: two different buttons can
-    // stack, and driving the same captured frame twice would double-count a raise.
+    // Painted quads resolved to the frames a cursor over them would hit. `owners` dedupes the
+    // work (many quads on one button), `hits` the targets (a frame driven twice double-counts).
     script.resolve();
     let mut owners: HashSet<FrameHandle> = HashSet::new();
     let mut hits: HashSet<FrameHandle> = HashSet::new();
@@ -197,9 +111,7 @@ pub(super) fn measure_use(
         let Some(hit) = script.hit_test_frame(p.point.0, p.point.1) else {
             continue; // painted, but nothing there takes the mouse
         };
-        // THE ATTRIBUTION RULE. One of ours captured the point — our window on top, or the
-        // addon's own region sitting on a mouse-disabled frame with ours underneath. Driving it
-        // would charge our handler's raise to this addon, in all 218 VMs (1209).
+        // A pre-existing frame captured the point: its raise is not this addon's.
         if baseline.is_pre_existing(hit) {
             continue;
         }
@@ -216,64 +128,37 @@ pub(super) fn measure_use(
         .filter_map(|(fh, _)| script.frame_name(*fh))
         .collect();
 
-    // The engine collects handler raises itself (`UiScript::push_error`), so there is nothing to
-    // swallow here and nothing to remember to re-read: a `split_off` of the tail is the whole
-    // capture. This is deliberately NOT the `pcall`-and-collect shape `drive_ui_probe` needs —
-    // that one calls Lua globals directly, this one goes through the real input path.
+    // The engine collects handler raises itself (`UiScript::push_error`); the tail is the capture.
     let before = script.errors().len();
     for (_, (x, y)) in &targets {
         drive_one(script, *x, *y);
     }
-    // Close the hover pair on the last target (see [`PARKED`]).
+    // Close the hover pair on the last target.
     script.mouse_move(PARKED.0, PARKED.1);
     report.errors = script.errors().split_off(before);
     report
 }
 
-/// One target, four gestures: **hover · left click · right click · drag**.
+/// One target, four gestures through the real input path: hover, left click, right click, drag.
 ///
-/// Every one of them is what it says. `mouse_move` fires the real `OnEnter`/`OnLeave` pair on a
-/// hover-boundary crossing; `mouse_button` runs the real press/release path — `OnMouseDown`,
-/// `OnMouseUp`, the `RegisterForClicks` adjudication that decides whether `OnClick` fires at all
-/// and with which button, the double-click detector, and the drag trio. None of it is simulated:
-/// this is the same code the host window's events reach.
-///
-/// A [`UiScript::resolve`] between gestures because a handler is free to move, show or build
-/// things, and the next hit-test must see what it did. It is tier-1 gated (nothing touched the
-/// layout ⇒ immediate return), so the quiet case is free.
-///
-/// **The drag is honest, with one stated degradation.** On a frame that called `RegisterForDrag`
-/// the press → move → release below is the real gesture: `OnDragStart` past the 4-px threshold,
-/// then `OnDragStop` on the source and `OnReceiveDrag` on whatever the release hit. On a frame
-/// that did not, the same three events are simply a second click — and because the probe does not
-/// tick, that second click lands inside the 300-ms window and fires `OnDoubleClick` where the
-/// widget has one. Both are inputs a player produces; neither is invented.
-///
-/// **Two of these four lines overlap, and the falsification run found it rather than the design —
-/// so it is written down here before somebody "simplifies" one of them away.** Deleting the hover
-/// move alone does *not* stop `OnEnter` firing (the drag's move crosses the same boundary), and
-/// deleting the left click alone does *not* stop `OnClick` firing (the degenerate drag above *is*
-/// a left click). Only removing **every** cursor move, or **every** left-button transition, turns
-/// the matching fixture red — which is what `use_probe_tests` actually pins. The overlap is not
-/// waste: the ORDER is the player's (you hover a thing before you click it), and a handler that
-/// only breaks on the second click is a real bug class.
+/// A [`UiScript::resolve`] follows each, since a handler may move, show or build frames. On a
+/// frame without `RegisterForDrag` the drag is a second click inside the 300 ms window, so it
+/// fires `OnDoubleClick`. The gestures overlap (the drag's move also hovers, its press also
+/// clicks); the order is a player's, hover before click, and the tests pin the removal of every
+/// move or every left-button transition.
 fn drive_one(script: &mut UiScript, x: f32, y: f32) {
-    // HOVER. The single most common thing a player does to a bag slot, and the gesture the
-    // director's error wall came from.
+    // Hover.
     script.mouse_move(x, y);
     script.resolve();
-    // LEFT CLICK — press and release on the same frame, which is what `wants_click` requires
-    // before `OnClick` fires at all.
+    // Left click: press and release on the same frame, as `wants_click` requires.
     script.mouse_button(x, y, "LeftButton", true);
     script.mouse_button(x, y, "LeftButton", false);
     script.resolve();
-    // RIGHT CLICK. Not a duplicate of the left one: the default registration is
-    // `{"LeftButtonUp"}`, so a right click reaches `OnClick` only on a widget that asked for it —
-    // which every container slot in the game does, because right-click is how you use an item.
+    // Right click: reaches `OnClick` only where the widget registered it, as container slots do.
     script.mouse_button(x, y, "RightButton", true);
     script.mouse_button(x, y, "RightButton", false);
     script.resolve();
-    // DRAG.
+    // Drag.
     script.mouse_button(x, y, "LeftButton", true);
     script.mouse_move(x + DRAG_PX, y);
     script.mouse_button(x + DRAG_PX, y, "LeftButton", false);
diff --git a/crates/benilla-app/src/addon_harness/use_probe_tests.rs b/crates/benilla-app/src/addon_harness/use_probe_tests.rs
index 825f3b0e..db756f47 100644
--- a/crates/benilla-app/src/addon_harness/use_probe_tests.rs
+++ b/crates/benilla-app/src/addon_harness/use_probe_tests.rs
@@ -1,54 +1,15 @@
-//! **The use column's can-it-fail proof, in both directions and per gesture.**
-//!
-//! This arc has shipped two instruments that could not fail — the UI probe swallowed every raise it
-//! was built to report, and the method oracle answered "nothing missing" when it could not run at
-//! all — so a new column arrives with its falsifier or it does not arrive.
-//!
-//! Two directions, and both are load-bearing:
-//!
-//! - **It must report.** Four fixtures, one per gesture, each drawing one button and raising from
-//!   exactly one handler: `OnEnter`, `OnClick` on the left, `OnClick` on the right (registered for
-//!   `RightButtonUp` only, so a left click cannot reach it), and `OnDragStart`. A column that
-//!   drove only clicks passes three of these and fails one, which is the point of splitting them.
-//! - **It must stay quiet.** A fixture that draws the *same* button with **no handlers at all**
-//!   must come out [`Used::Survived`] with `driven ≥ 1` and zero errors — the shape that proves the
-//!   errors above came from the addons and not from the probe.
-//!
-//! ...and one more, which is the distinction the whole column is built around: a fixture that
-//! **paints but takes no mouse** must come out [`Used::Untouched`] with `driven == 0`, never
-//! `Survived`. "Nothing raised" and "nothing was touched" are different answers, and an instrument
-//! that cannot tell them apart is the one that reported a spotless corpus for a month.
-//!
-//! Then the real oracle: the director's two verified addons. `!OmniCC` works and must not be
-//! reported broken; Bagnon's slots are the reason this file exists and must at minimum be
-//! **reachable** — whether they still raise is the parallel handler fix's to change, so the
-//! durable assertion is that the probe can get its hands on them at all.
-//!
-//! ## What the falsification run actually established (2026-08-11)
-//!
-//! Each was applied to `use_probe`, run, and reverted — a can-it-fail claim is worth what it was
-//! measured at, not what it was asserted at:
-//!
-//! | change to the probe | this file |
-//! |---|---|
-//! | right-click press/release removed | RED — `RaisesOnRightClick` reads `Survived`, `driven=1` |
-//! | drag presses and releases in place (no 4-px move) | RED — `RaisesOnDrag` |
-//! | every `mouse_move` removed | RED — `RaisesOnEnter` |
-//! | every left-button transition removed | RED — `RaisesOnLeftClick` |
-//! | `Untouched` folded into `Survived` | RED — `PaintsButTakesNoMouse` |
-//!
-//! And the two **negative** results, which are the useful ones: removing only the hover move
-//! leaves this file GREEN (the drag's own move crosses the same hover boundary), and removing only
-//! the explicit left click leaves it GREEN (the drag press/release *is* a left click on a frame
-//! that never registered for drag). So what these fixtures pin is the gesture, not the line —
-//! stated in `drive_one` too, where somebody would otherwise delete an "obviously redundant" call.
+//! Tests for the use column: one fixture per gesture that raises from exactly one handler, a
+//! silent button that must survive with `driven >= 1`, a painted mouse-disabled frame that must be
+//! `untouched`, and two real corpus addons that must be reachable. The fixtures pin each gesture,
+//! not each line: removing only the hover move or only the explicit left click stays green, since
+//! the drag also hovers and clicks.
 
 use std::path::{Path, PathBuf};
 
 use super::{survey, Used};
 
-/// One throwaway AddOns root, cleaned up on drop even if a test panics. (The twin of
-/// `render_tests::Fixtures`; kept local so the two files' fixtures cannot collide in `temp_dir`.)
+/// One throwaway AddOns root, cleaned up on drop even if a test panics; its own temp prefix keeps
+/// it apart from `render_tests`'.
 struct Fixtures(PathBuf);
 
 impl Fixtures {
@@ -88,11 +49,8 @@ impl Drop for Fixtures {
 }
 
 /// A 64×64 painted Button at the centre of the screen, plus whatever `extra` wires onto it.
-///
-/// Painted, because an unpainted frame never reaches the target list at all — the use column takes
-/// its aim from the render column's attribution, so every fixture here has to draw first. Centred,
-/// because the corners of the default UI are full of our own windows and a fixture underneath one
-/// of them would be dropped by the attribution rule for a reason the test is not about.
+/// Painted, since the use column aims at the render column's quads; centred, clear of the default
+/// UI's windows.
 fn painted_button(extra: &str) -> String {
     format!(
         r#"
@@ -108,12 +66,11 @@ fn painted_button(extra: &str) -> String {
     )
 }
 
-/// **The proof: every gesture is really driven, and silence is really silence.**
+/// Every gesture is driven, silence stays silent, and nothing touched is not a pass.
 #[test]
 fn the_use_column_can_fail() {
     let fx = Fixtures::new("cannotfail");
-    // One fixture per gesture. Each raises from exactly ONE handler, so a probe that skips that
-    // gesture reports this addon clean and the assertion below catches it by name.
+    // One fixture per gesture, each raising from exactly one handler.
     fx.addon(
         "RaisesOnEnter",
         &painted_button(r#"f:SetScript("OnEnter", function() error("USEFIXTURE_ENTER") end)"#),
@@ -122,10 +79,8 @@ fn the_use_column_can_fail() {
         "RaisesOnLeftClick",
         &painted_button(r#"f:SetScript("OnClick", function() error("USEFIXTURE_LEFTCLICK") end)"#),
     );
-    // Registered for the RIGHT button ONLY — the default set is `{"LeftButtonUp"}`, so this
-    // handler is unreachable by any amount of left-clicking. It is the fixture that separates
-    // "the probe clicks" from "the probe clicks with both buttons", which matters because
-    // right-click is how every container slot in the game is used.
+    // Registered for `RightButtonUp` only (the default is `{"LeftButtonUp"}`), so no left click
+    // reaches it.
     fx.addon(
         "RaisesOnRightClick",
         &painted_button(
@@ -135,8 +90,7 @@ fn the_use_column_can_fail() {
         "#,
         ),
     );
-    // `OnDragStart` fires only past the 4-px threshold, so this one also proves the probe's drag
-    // actually MOVES rather than pressing and releasing in place.
+    // `OnDragStart` fires only past the 4 px threshold, so the drag must actually move.
     fx.addon(
         "RaisesOnDrag",
         &painted_button(
@@ -146,12 +100,9 @@ fn the_use_column_can_fail() {
         "#,
         ),
     );
-    // THE OTHER DIRECTION. The same painted, mouse-taking button with nothing wired to it at all:
-    // driven, and silent. Without this row the four above prove only that the probe can produce
-    // errors, not that the errors came from the addons.
+    // The same button with no handlers: driven and silent, so the errors above are the addons'.
     fx.addon("SilentButTouchable", &painted_button(""));
-    // ...and the distinction the column exists for. It paints exactly as much as the others and
-    // takes no mouse, so nothing of the addon's answers a hit-test: `untouched`, never `ok`.
+    // Paints but takes no mouse: `untouched`, never `ok`.
     fx.addon(
         "PaintsButTakesNoMouse",
         r#"
@@ -174,8 +125,7 @@ fn the_use_column_can_fail() {
             .unwrap_or_else(|| panic!("{name} was not surveyed"))
     };
 
-    // Every fixture must have LOADED and DRAWN, or a `driven = 0` below would be measuring a load
-    // failure or a blank window rather than the thing under test.
+    // Each fixture must load and draw, or `driven = 0` would measure something else.
     for name in [
         "RaisesOnEnter",
         "RaisesOnLeftClick",
@@ -197,7 +147,7 @@ fn the_use_column_can_fail() {
         );
     }
 
-    // ── It reports, per gesture ────────────────────────────────────────────────────────────────
+    // ── It reports, per gesture ──
     for (name, marker) in [
         ("RaisesOnEnter", "USEFIXTURE_ENTER"),
         ("RaisesOnLeftClick", "USEFIXTURE_LEFTCLICK"),
@@ -220,7 +170,7 @@ fn the_use_column_can_fail() {
         );
     }
 
-    // ── ...and it stays quiet when there is nothing to report ──────────────────────────────────
+    // ── It stays quiet when nothing raises ──
     let quiet = row("SilentButTouchable");
     assert_eq!(
         quiet.used.verdict(),
@@ -234,7 +184,7 @@ fn the_use_column_can_fail() {
          whole column is about"
     );
 
-    // ── ...and it never calls "nothing was touched" a pass ─────────────────────────────────────
+    // ── Nothing touched is not a pass ──
     let untouched = row("PaintsButTakesNoMouse");
     assert_eq!(
         untouched.used.verdict(),
@@ -248,22 +198,13 @@ fn the_use_column_can_fail() {
     );
 }
 
-/// **The real oracle: the director's two verified addons.**
-///
-/// - `!OmniCC` **works** — its countdown numbers are on their screen. It must not be reported as
-///   broken. It is also the reference [`Used::Untouched`]: its whole visible output is a
-///   `FontString` on an anonymous, mouse-disabled `Frame`, so there is nothing on it to click and
-///   nothing wrong with it either. If this column ever calls it `raised`, the column is wrong.
-/// - **Bagnon** is why this file exists: sixteen bag slots drawn and dead to the touch. The
-///   assertion here is the durable half — the probe can **reach** them (`driven ≥ 1`, on a
-///   `BagnonItem*` frame). Whether they still raise is the parallel handler fix's to change, so
-///   asserting `Raised` would turn somebody else's fix into this file's failure; what must never
-///   regress is the probe's ability to get its hands on the slots at all, because a column that
-///   silently stops touching them is exactly how this instrument has been wrong four times.
+/// `!OmniCC` is never `raised`: its output is a `FontString` on an anonymous mouse-disabled frame,
+/// so it is `untouched`. Bagnon's item slots must be reachable (`driven >= 1` on a `BagnonItem*`
+/// frame); whether they raise is not asserted here.
 #[test]
 fn the_directors_two_verified_addons_are_reachable_and_omnicc_is_not_broken() {
     benilla_formats::wow_data_or_skip!();
-    // The one resolver, and a skip the gate can refuse (`benilla_formats::install`).
+    // A skip the gate can refuse (`benilla_formats::install`).
     let corpus = benilla_formats::addon_corpus_or_skip!();
     let fx = Fixtures::new("oracle");
     for name in ["!OmniCC", "Bagnon", "Bagnon_Core", "Bagnon_Forever"] {
diff --git a/crates/benilla-app/src/area.rs b/crates/benilla-app/src/area.rs
index f599708b..2f49d4f6 100644
--- a/crates/benilla-app/src/area.rs
+++ b/crates/benilla-app/src/area.rs
@@ -1,62 +1,33 @@
-//! The player's area identity, published to the UI — the real 1.12 `ZONE_CHANGED` event family
-//! and the zone-text host globals behind `GetZoneText`/`GetSubZoneText`/`GetRealZoneText`/
-//! `GetMinimapZoneText`/`GetZonePVPInfo` (decision 0287; corrected to the bytes by its fold-back
-//! record).
+//! The player's area identity for the UI: the `ZONE_CHANGED` event family and the host globals
+//! behind `GetZoneText`, `GetSubZoneText`, `GetRealZoneText`, `GetMinimapZoneText` and
+//! `GetZonePVPInfo`, all fired from the one updater `0x494780`.
 //!
-//! The model (`0x494780` is the one updater all three zone events fire from, on the per-update
-//! area resolve):
+//! - A zone id change fires `ZONE_CHANGED_NEW_AREA` alone; else a text change fires
+//!   `ZONE_CHANGED_INDOORS` or `ZONE_CHANGED` by the indoor bit. The first world-enter is a zone
+//!   id change from the zeroed cache.
+//! - The zone is the leaf's single-hop parent (AreaTable field 2, itself when 0).
+//! - The indoor bit is the faces-only down-ray (`0x6a87f0`): the surface below is a WMO face whose
+//!   group lacks MOGP `0x8` EXTERIOR.
+//! - Indoor naming (`0x67e670`): while indoors in the same group the whole updater is skipped
+//!   (`[0x868608]`, `[0x86860c]`). On a change, the whole-WMO row (`0x69d830`) overrides the zone
+//!   slot and nulls the subzone when its name is non-empty and differs from the subzone; an
+//!   unnamed row resolves through its `AreaTableID`, a missing row never overrides. Then the
+//!   group's own row (`0x69d8f0`) refills the subzone. Both are exact-key lookups.
+//! - `GetRealZoneText` reads the zone name before the indoor override.
+//! - `GetMinimapZoneText` is subzone-else-zone (`0xb4da28`), with its own `MINIMAP_ZONE_CHANGED`
+//!   (`0x494970`).
 //!
-//! - The client caches `(zoneId, zoneText, subzoneText)` and compares per update: **zone id
-//!   changed → `ZONE_CHANGED_NEW_AREA` fires alone**; else **either text changed →
-//!   `ZONE_CHANGED_INDOORS`** when the resolver's indoor bit is set, else **`ZONE_CHANGED`**.
-//!   Mutually exclusive; the first world-enter is a zone-id change from the zeroed cache.
-//! - **Indoors, the zone-text slot takes the WMO interior's name and the subzone slot nulls**
-//!   (`0x67e670`) — entering a named inn splashes the inn's name. `GetRealZoneText` reads the
-//!   pre-override (WMO-immune) zone name; `GetMinimapZoneText` reads subzone-else-zone
-//!   (`0xb4da28`, its own change event `MINIMAP_ZONE_CHANGED` from `0x494970`).
-//! - The "zone" is the leaf's **single-hop parent** (AreaTable field 2; itself when 0) — equal
-//!   to the defensive `top_zone` walk on 5875 data (chains are 1–2 deep), which the world map
-//!   keeps using.
-//! - `GetZonePVPInfo` (`0x48d540`): `isArena` = the **leaf** row's Flags bit `0x80` (the FFA-pit
-//!   flag); ownership = the **zone** row's FactionGroupMask vs the player template's
-//!   friend-then-enemy group masks → "friendly"/"hostile", else **"contested" — never nil for an
-//!   ownerless zone** (nil is structural failure only); `factionName` = FactionGroup.dbc's
-//!   localized Name for the zone's mask bit; pvpType is never "arena"; realm type never enters.
-//! - **The indoor bit** is the player's faces-only down-ray verdict
-//!   ([`benilla_world::wmo_portal::CurrentAreaInterior`] — the CGLight node's `+0x90` bit 0, set
-//!   by `0x6a87f0`): indoors ⇔ the nearest surface below is a WMO face whose group lacks MOGP
-//!   `0x8` EXTERIOR. The abbey yard is terrain-below ⇒ outdoors; the flip is the doorway.
-//! - **The indoor naming** (`0x67e670`): while indoors and the hit
-//!   GROUP is unchanged, the WHOLE updater is skipped (the dedup `[0x868608]`/`[0x86860c]`). On
-//!   an indoor change: **query A** (the whole-WMO −1 row, exact key, `0x69d830`) overrides the
-//!   ZONE slot — only when its resolved name is non-empty AND differs from the current subzone
-//!   (the inn splash; skipped at the abbey, whose default name equals its yard subzone) —
-//!   nulling the subzone; an existing-but-unnamed −1 row resolves through its `AreaTableID`'s
-//!   AreaTable name (Ironforge's unnamed city WMO), a missing row never overrides. Then
-//!   **query B** (the hit group's own row, exact key, `0x69d8f0`) re-populates the subzone
-//!   ("Main Hall"). No name-set retry, no cross-row fallback anywhere.
+//! On the first world-enter `0x494780` also sets the world map to the player's zone
+//! (`0x4a6650`); that half lives in `crate::ui_world_map::world_enter_selection`.
 //!
-//! **`0x494780` has one more effect than the election, and it does NOT live here** (2192): when
-//! the cached zone id was 0 — the first world-enter of a session — it also calls `0x4a6650`, the
-//! player→(continent, zone) resolver, and hands the answer to the world map's `SetMap` setter, so
-//! a freshly-logged-in client is already on the player's own zone map before any Lua asks. That
-//! half is modelled where the map data lives, in
-//! [`crate::ui_world_map::world_enter_selection`] — the gate there is the same precondition
-//! (`0x67e510` never reaches this updater with a zero zone id), read off our own area feed rather
-//! than off the cache below.
+//! Host globals are written before the event fires, so a handler's `GetZoneText()` sees the new
+//! state.
 //!
-//! The area *authority* stays `terrain_stream::CurrentArea` (decision 0232 — the MCNK `areaId`
-//! with the WMO-interior override, now off the same faces-only claim). Host globals are written
-//! before the event fires, so a handler's `GetZoneText()` already sees the new state.
+//! Deviation: the indoor dedup keys `(WMOID, MOGP uniqueID)`, not the client's raw per-WMO group
+//! index, because the raw index can alias across adjacent buildings.
 //!
-//! Named divergence: the dedup keys `(WMOID, MOGP uniqueID)` where the client stores the raw
-//! per-WMO group INDEX — ours changes exactly when the hit group does but never aliases across
-//! adjacent buildings the way the raw index can. INTERIM residue: the `[0x88272c]` PvP display
-//! gate (an unnamed cached boolean, verified NOT realm type) ships open.
-//!
-//! [`AreaTableRes`] is also the one shared `AreaTable.dbc` projection (0287's consolidation):
-//! the world map and this module consume it. (`area_sound.rs` keeps its own audio-FK fold —
-//! different columns, different concern.)
+//! The reference's PvP display gate `[0x88272c]` (a cached boolean, not the realm type) is
+//! untraced; ours is always open.
 
 use bevy::ecs::system::NonSendMut;
 use bevy::prelude::*;
@@ -68,12 +39,11 @@ use crate::net::{ObjectStore, SelfPlayer};
 use crate::target::Factions;
 use benilla_assets::{AssetSet, LockRecover, WorldAssets};
 
-/// The shared `AreaTable.dbc` catalog: id → (name, parent zone, flags, faction mask). Loaded once
-/// at Startup; absent if the DBC failed to read (consumers take `Option` and go quiet).
+/// The shared `AreaTable.dbc` catalog, read by the world map and this module; absent if the DBC
+/// failed to read.
 #[derive(Resource)]
 pub(crate) struct AreaTableRes(pub(crate) AreaTableCatalog);
 
-/// Startup: load the shared area catalog off the patch chain.
 fn load_area_table(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
     let Some(assets) = assets else { return };
     let loaded = {
@@ -89,32 +59,24 @@ fn load_area_table(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
     }
 }
 
-/// What the client's zone-text cache holds — the compare targets of `0x494780` (zone id + the
-/// two display strings), the minimap line's own cache (`0x494970`), and the indoor dedup pair
-/// (`[0x868608]` prev-indoor / `[0x86860c]` prev WMO-area row id).
-///
-/// Held as a [`crate::ui_script::VmMemo`], which is not a deviation from that BSS model but the
-/// completion of it: the cache's whole purpose is deduping what was last *pushed into the VM*, and
-/// the VM is built at world entry and destroyed at the character screen (decision 1290). A fresh VM
-/// is the client's own fresh BSS — the zeroed cache below is exactly the state the real client is in
-/// at that moment, so the first resolve of every login is a NEW_AREA with the globals written, which
-/// is what the zone splash and the minimap line need.
+/// The client's zone-text cache: the compare targets of `0x494780`, the minimap line's cache
+/// (`0x494970`) and the indoor dedup pair (`[0x868608]`, `[0x86860c]`). It lives per VM, so every
+/// login starts zeroed and its first resolve is a NEW_AREA.
 #[derive(Default)]
 struct ZoneCache {
-    /// `None` = never resolved (the zeroed BSS cache: the first resolve is a NEW_AREA).
+    /// `None` until the first resolve.
     zone_id: Option<u32>,
     zone_text: String,
     subzone_text: String,
     minimap_text: String,
-    /// The previous update's indoor bit (`[0x868608]`).
+    /// `[0x868608]`.
     indoor: bool,
-    /// The previous hit group's identity (`[0x86860c]` — the client stores the group index; we
-    /// scope the MOGP uniqueID by WMO): same group while indoors ⇒ the whole updater is skipped.
+    /// The previous hit group (`[0x86860c]`, keyed as the module doc's deviation says).
     wmo_id: u32,
     wmo_group: u32,
 }
 
-/// The texts + indoor bit one resolve produces (the updater's compare inputs).
+/// One resolve's compare inputs.
 struct ZoneSignal {
     zone_id: u32,
     zone_text: String,
@@ -122,8 +84,7 @@ struct ZoneSignal {
     indoor: bool,
 }
 
-/// The event election, verbatim from `0x494780`: zone id changed → NEW_AREA **alone**; else any
-/// text changed → INDOORS/CHANGED by the indoor bit; else nothing.
+/// The event election of `0x494780`.
 fn elect_event(cache: &ZoneCache, next: &ZoneSignal) -> Option<&'static str> {
     if cache.zone_id != Some(next.zone_id) {
         return Some("ZONE_CHANGED_NEW_AREA");
@@ -138,10 +99,8 @@ fn elect_event(cache: &ZoneCache, next: &ZoneSignal) -> Option<&'static str> {
     None
 }
 
-/// The zone-splash data plane (module doc). Per resolve: compute the display texts (with the
-/// indoor override), the PvP tuple, write the host globals, then fire the elected zone event
-/// and — independently, like the client's second site — `MINIMAP_ZONE_CHANGED` when the
-/// subzone-else-zone line changed.
+/// Resolves the texts and PvP info, writes the host globals, then fires the elected zone event and,
+/// independently, `MINIMAP_ZONE_CHANGED`.
 fn feed_zone_events(
     script: Option<NonSendMut<UiScript>>,
     world: benilla_world::world_point::WorldPoint,
@@ -156,12 +115,9 @@ fn feed_zone_events(
     let cache = cache.get(&script);
     let Some(leaf) = world.area() else { return };
     let Some(leaf_row) = areas.0.get(leaf) else {
-        // An id the catalog doesn't know stays unpublished (keep the last real state, like the
-        // resolver itself does for areaId 0).
+        // An unknown id keeps the last state, as the resolver does for areaId 0.
         return;
     };
-    // The zone: the leaf's single-hop parent (field 2), itself when 0 (`0x494780`'s stored row;
-    // == `top_zone` on 5875's 1–2-deep chains).
     let zone = if leaf_row.zone_id == 0 {
         leaf
     } else {
@@ -170,7 +126,7 @@ fn feed_zone_events(
     let real_zone_text = areas.0.name(zone).unwrap_or_default().to_string();
     let indoor = world.area_interior().is_some();
 
-    // The outdoor texts — the locals `0x67e670` starts from.
+    // The outdoor texts `0x67e670` starts from.
     let mut zone_text = real_zone_text.clone();
     let mut subzone_text = if leaf == zone {
         String::new()
@@ -178,30 +134,19 @@ fn feed_zone_events(
         leaf_row.name.clone()
     };
 
-    // The indoor naming (`0x67e670`, module doc): dedup-skip while the hit group
-    // holds; else the default-row name (query A) may override the zone slot and the group-row
-    // name (query B) re-populates the subzone — both EXACT-key lookups (no name-set retry).
     let mut wmo_group = 0u32;
     if let Some((k, group, default)) = world.area_interior_rows() {
-        // The dedup key: the hit GROUP's identity (the client's `[groupRec+0x7c]` group index,
-        // nonzero-gated). We key the MOGP uniqueID scoped by WMO id: it changes exactly
-        // when the hit group does, and — a named divergence — never aliases across two adjacent
-        // buildings the way the client's raw per-WMO index can.
+        // The client keys `[groupRec+0x7c]`, nonzero-gated; see the module doc's deviation.
         wmo_group = k.group_area_id;
         if cache.indoor
             && k.group_area_id != 0
             && (cache.wmo_id, cache.wmo_group) == (k.wmo_id, wmo_group)
         {
-            return; // the dedup: same WMO group ⇒ the whole updater is skipped
+            return;
         }
         cache.wmo_id = k.wmo_id;
-        // Query A (the whole-WMO −1 row): override the zone name + null the subzone — only when
-        // the resolved name is non-empty and differs from the current subzone (the abbey skip).
-        // An EXISTING-but-unnamed row falls back to an AreaTable name — the row's own
-        // `AreaTableID`, else the current leaf (how Ironforge's unnamed city WMO splashes
-        // "Ironforge"; the client's area-0 arm reads the raw terrain areaId at the node — the
-        // current leaf equals it in that arm, since an area-0 row also never overrode the leaf).
-        // A MISSING row never overrides (the client's `""` sentinel bypass).
+        // The whole-WMO -1 row. An unnamed one with `AreaTableID` 0 takes the leaf's name, which
+        // is the terrain areaId the client's area-0 arm reads.
         let a_name = default.as_ref().map(|d| {
             if !d.name.is_empty() {
                 d.name.clone()
@@ -221,7 +166,7 @@ fn feed_zone_events(
                 subzone_text = String::new();
             }
         }
-        // Query B (the hit group's own row): re-populate the subzone (empty/missing = leave it).
+        // The hit group's own row refills the subzone.
         if let Some(b) = group
             .as_ref()
             .map(|r| r.name.as_str())
@@ -236,7 +181,6 @@ fn feed_zone_events(
         subzone_text,
         indoor,
     };
-    // GetMinimapZoneText's own line: subzone-else-zone (`0xb4da28`).
     let minimap_text = if signal.subzone_text.is_empty() {
         signal.zone_text.clone()
     } else {
@@ -249,10 +193,10 @@ fn feed_zone_events(
         return;
     }
 
-    // GetZonePVPInfo (`0x48d540`): leaf row's 0x80 for isArena; zone row's mask vs the player
-    // template's friend-then-enemy masks; factionName from FactionGroup.dbc. Never "arena" as a
-    // type; "contested" (not nil) for an ownerless zone; nil only on structural failure. The
-    // `[0x88272c]` display gate ships open (module doc).
+    // GetZonePVPInfo (`0x48d540`): isArena is the leaf's Flags `0x80`; the type is the zone's
+    // FactionGroupMask against the player template's friend then enemy masks, "contested" when
+    // neither; never "arena"; nil only on structural failure. factionName is FactionGroup.dbc's
+    // Name for the zone's mask bit; the realm type never enters.
     let is_arena = leaf_row.flags & 0x80 != 0;
     let zone_mask = areas.0.get(zone).map_or(0, |r| r.faction_group_mask);
     let pvp = factions
@@ -304,7 +248,7 @@ fn feed_zone_events(
     cache.wmo_group = wmo_group;
 }
 
-/// The shared area catalog + the zone-event feed (decision 0287 + fold-back).
+/// The shared area catalog and the zone-event feed.
 pub(crate) struct AreaPlugin;
 
 impl Plugin for AreaPlugin {
@@ -312,13 +256,9 @@ impl Plugin for AreaPlugin {
         app.add_systems(Startup, load_area_table.after(AssetSet::Open))
             .add_systems(
                 Update,
-                // After the script tick, like the other feeds: the event dispatches on the next
-                // tick — a frame of latency the splash can't perceive. MINIMAP_ZONE_CHANGED's
-                // handler reads the PvP globals written above in the same call. ALSO after the
-                // leaf authority (which orders after the interior claim): leaf, indoor bit, and
-                // names must come from ONE coherent frame — the client's single-pass resolve
-                // (`0x67e510`); a fresh claim against a stale leaf fired the abbey login's
-                // spurious big splash.
+                // After the leaf authority: leaf, indoor bit and names must come from one frame,
+                // as in the client's single-pass resolve (`0x67e510`), or a stale leaf fires a
+                // spurious splash.
                 feed_zone_events
                     .after(crate::ui_script::UiInput)
                     .after(benilla_world::terrain_stream::AreaAuthoritySet),
@@ -348,48 +288,41 @@ mod tests {
         }
     }
 
-    /// The `0x494780` election domain: first-enter and zone hops take NEW_AREA alone; same-zone
-    /// text changes split INDOORS/CHANGED on the indoor bit; no change fires nothing.
+    /// The `0x494780` election.
     #[test]
     fn election_matches_the_byte_law() {
-        // First world-enter: the zeroed cache is a zone-id change.
         let c = ZoneCache::default();
         assert_eq!(
             elect_event(&c, &sig(12, "Elwynn Forest", "Northshire Valley", false)),
             Some("ZONE_CHANGED_NEW_AREA")
         );
 
-        // Zone hop: NEW_AREA alone — even though the texts changed too.
+        // Zone hop: NEW_AREA alone, though the texts changed too.
         let c = cache(Some(12), "Elwynn Forest", "");
         assert_eq!(
             elect_event(&c, &sig(40, "Westfall", "The Jansen Stead", false)),
             Some("ZONE_CHANGED_NEW_AREA")
         );
 
-        // Outdoor subzone hop: same zone, subzone text changed → ZONE_CHANGED.
         let c = cache(Some(12), "Elwynn Forest", "");
         assert_eq!(
             elect_event(&c, &sig(12, "Elwynn Forest", "Goldshire", false)),
             Some("ZONE_CHANGED")
         );
 
-        // Inn entry: same zone, the ZONE text changed by the indoor override, indoor set →
-        // INDOORS (the named-interior splash).
+        // Inn entry: the indoor override changed the zone text.
         let c = cache(Some(12), "Elwynn Forest", "Goldshire");
         assert_eq!(
             elect_event(&c, &sig(12, "Lion's Pride Inn", "", true)),
             Some("ZONE_CHANGED_INDOORS")
         );
 
-        // Inn exit: texts revert, outdoors again → plain ZONE_CHANGED (the frames re-cache
-        // silently and only the subzone line splashes — the consumer law).
         let c = cache(Some(12), "Lion's Pride Inn", "");
         assert_eq!(
             elect_event(&c, &sig(12, "Elwynn Forest", "Goldshire", false)),
             Some("ZONE_CHANGED")
         );
 
-        // No change → nothing.
         let c = cache(Some(12), "Elwynn Forest", "Goldshire");
         assert_eq!(
             elect_event(&c, &sig(12, "Elwynn Forest", "Goldshire", false)),
@@ -397,17 +330,14 @@ mod tests {
         );
     }
 
-    /// The indoor naming law (`0x67e670`) against the REAL abbey/inn data shapes — the
-    /// override-skip (whole-WMO name == yard subzone) and the override-fire (inn) branches,
-    /// run through the same WmoAreaCatalog the live feed reads. Skips without client data.
+    /// The `0x67e670` override skip (abbey) and fire (inn) branches on the install's data.
     #[test]
     fn indoor_naming_matches_the_byte_law_on_real_data() {
         let data = benilla_formats::wow_data_or_skip!();
         let mut chain = benilla_formats::open_chain(&data).expect("chain");
         let cat = benilla_formats::load_wmo_area_catalog(&mut chain).expect("WMOAreaTable");
 
-        // The abbey (WMO 59, Northshire placement name-set 1): the default row's name equals the
-        // yard subzone ⇒ the zone override SKIPS; group 1934's own name re-fills the subzone.
+        // Abbey (WMO 59, name-set 1): the default name equals the yard subzone, so no override.
         let default = cat.default_row(59, 1).expect("abbey default row");
         assert_eq!(default.name, "Northshire Abbey");
         let group = cat.group_row(59, 1, 1934).expect("abbey main hall row");
@@ -416,20 +346,15 @@ mod tests {
             group.area_table_id, 24,
             "the leaf stays Northshire Abbey (24)"
         );
-        // The dedup rides the hit-group identity (the client's group index; our MOGP
-        // uniqueID) — distinct per room, so a room hop re-fires and standing still skips.
+        // Rooms have distinct rows, so a room hop re-fires the dedup.
         let library = cat.group_row(59, 1, 1943).expect("library row");
         assert_ne!(group.id, library.id, "distinct rows exist per room");
 
-        // An unnamed room (group 1935): query B empty ⇒ the subzone keeps what the override
-        // left — with the override skipped, that's the terrain leaf name.
         let unnamed = cat.group_row(59, 1, 1935).expect("unnamed room row");
         assert!(unnamed.name.is_empty());
 
-        // The Goldshire inn (WMO 53, name-set 2 — its ONLY row is the whole-WMO one): the
-        // default name differs from the street subzone ("Goldshire") ⇒ the override FIRES (the
-        // big inn splash), and with no named group row the subzone stays nulled — the un-doubled
-        // inn entry. Its AreaTableID is 0, so the leaf stays the terrain chunk's (Goldshire).
+        // Goldshire inn (WMO 53, name-set 2): only a whole-WMO row, named unlike the street, so
+        // the override fires and the subzone stays nulled.
         let inn = cat.default_row(53, 2).expect("the inn's whole-WMO row");
         assert_eq!(inn.name, "Lion's Pride Inn");
         assert_eq!(inn.area_table_id, 0);
diff --git a/crates/benilla-app/src/area_poi.rs b/crates/benilla-app/src/area_poi.rs
index eb78090e..b75c3012 100644
--- a/crates/benilla-app/src/area_poi.rs
+++ b/crates/benilla-app/src/area_poi.rs
@@ -1,26 +1,16 @@
-//! The shared `AreaPOI.dbc` catalog — the world's named points of interest, and the **one** copy
-//! of that table in the process.
-//!
-//! It used to live inside `MinimapAssets`, because the minimap's nearest-3 landmark blips
-//! (decision 0203 phase 3) were its only reader. The world map is the second (decision 1586: the
-//! `0x4a67a0` landmark pass — city icons, the "Under Attack" indicators, the Eastern Plaguelands
-//! towers), and two owners of one DBC is how the two surfaces drift apart on what a POI *is*. So
-//! it is hoisted here, beside [`crate::area::AreaTableRes`], on 0287's precedent — the same move,
-//! for the same reason, on the sibling table.
-//!
-//! Loaded once at Startup; absent if the DBC failed to read, which every consumer takes as
-//! `Option` and goes quiet about (no landmark blips, no map icons, everything else intact).
+//! The one shared `AreaPOI.dbc` catalog, read by the minimap's landmark blips and the world map's
+//! landmark pass (`0x4a67a0`). Absent when the DBC fails to load; every reader then shows no POIs.
 
 use bevy::prelude::*;
 
 use benilla_assets::{AssetSet, LockRecover, WorldAssets};
 use benilla_formats::AreaPoiCatalog;
 
-/// The shared `AreaPOI.dbc` catalog, in file order (see [`AreaPoiCatalog`]).
+/// The `AreaPOI.dbc` rows, in file order.
 #[derive(Resource)]
 pub(crate) struct AreaPoiRes(pub(crate) AreaPoiCatalog);
 
-/// Startup: load the shared POI catalog off the patch chain.
+/// Startup: load the catalog off the patch chain.
 fn load_area_poi(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
     let Some(assets) = assets else { return };
     let loaded = {
diff --git a/crates/benilla-app/src/area_trigger.rs b/crates/benilla-app/src/area_trigger.rs
index 1ef12615..5ee19531 100644
--- a/crates/benilla-app/src/area_trigger.rs
+++ b/crates/benilla-app/src/area_trigger.rs
@@ -1,49 +1,18 @@
-//! Area triggers — the client's half of every portal, instance entrance and "explore here" quest.
+//! Area triggers: notice the player entering an `AreaTrigger.dbc` volume and send
+//! `CMSG_AREATRIGGER`; the server decides what the trigger does.
 //!
-//! `AreaTrigger.dbc` is a table of invisible volumes. The client's *entire* job is geometry: notice
-//! that the player has walked into one, and send `CMSG_AREATRIGGER` naming its id. The **server**
-//! decides what the trigger means — a teleport (`areatrigger_teleport`: the Darnassus/Rut'theran
-//! portals, every dungeon and raid entrance), a quest's explore objective
-//! (`areatrigger_involvedrelation`), the inn's rested state, a battleground's entrance list. The
-//! client never knows and never needs to.
+//! The reference's check (`0x5e2110`, containment `0x5e22d0`): only the current map's rows are
+//! candidates (`0x5e2080`); while the player is still inside the latched trigger nothing is sent;
+//! once they leave, the first containing row in file order is latched and sent; a map change
+//! clears the latch. So a portal fires once per entry, and a portal's destination is authored
+//! outside the return trigger, so a round trip is not a loop.
 //!
-//! Until this module existed, benilla sent that opcode from nowhere: a portal did nothing, and an
-//! instance entrance did nothing, because the server was never told we were standing in one (ledger
-//! **B70**, **N02**). The teleport that answers it has worked since decision 0455.
+//! The server re-checks the claim with 5 yd of slop and ignores it while taxi-flying
+//! (vmangos `Handlers/MiscHandler.cpp:622`).
 //!
-//! ## The law, from the reference
-//!
-//! From `0x5e2110` (the per-frame check) and `0x5e22d0` (containment); the geometry itself is
-//! [`AreaTriggerRow::contains`](benilla_formats::AreaTriggerRow::contains).
-//!
-//! - The map's rows are the only candidates (`0x5e2080` narrows the map-sorted table to a
-//!   `[first, end)` window before any test).
-//! - **One latch, and it is an *exit* latch.** The check holds the trigger it is currently inside;
-//!   while the player is still inside *that* volume it returns immediately and sends nothing. Only
-//!   once they have left does it scan for a new one — so standing in a portal fires it exactly once,
-//!   and overlapping volumes never fight.
-//! - The **first** containing row in file order wins.
-//! - A map change clears the latch.
-//!
-//! Two things the reference's shape buys us, worth stating because they are load-bearing: a trigger
-//! cannot re-fire while you stand in it (a portal would otherwise re-teleport you every frame), and
-//! the *destination* of a portal pair is authored to land outside the return trigger (Darnassus's
-//! exit lands 13.9 yd from the entrance's 10-yd sphere), so a round trip is not a loop.
-//!
-//! The server re-checks our claim with 5 yd of slop and ignores it while taxi-flying
-//! (`HandleAreaTriggerOpcode`, vmangos `Handlers/MiscHandler.cpp:622`), so a wrong id is refused
-//! rather than obeyed.
-//!
-//! ## ⚠ Probing this with `.go` is not the same as walking in
-//!
-//! A GM teleport that drops you *inside* a volume sends this message in the same millisecond as the
-//! teleport ack, and the server re-checks the claim against the position it has stored — which is
-//! sometimes still the pre-teleport one. Measured: five such teleport-ins were obeyed and one
-//! (Darnassus's trigger 527) was silently ignored, while drifting into the same trigger under
-//! movement fired it and teleported 40 ms later. So an ignored `.go` probe is the harness racing
-//! the server, not this check failing — and the latch, faithfully, does not retry (it latches on
-//! the *send*; the client never learns whether the server obeyed). Step out and back in, or better,
-//! park outside and move in.
+//! A GM teleport straight into a volume sends this in the same instant as the teleport ack, and
+//! the server may test it against the pre-teleport position and ignore it; the latch does not
+//! retry. Probe by moving into the volume instead.
 
 use benilla_assets::coords::bevy_to_wow;
 use benilla_formats::AreaTriggerCatalog;
@@ -55,30 +24,18 @@ use benilla_assets::{AssetSet, LockRecover, WorldAssets};
 use benilla_world::schedule::WorldStage;
 use benilla_world::world_map::CurrentMap;
 
-/// The `AreaTrigger.dbc` catalog, bucketed by map. Absent when the client data didn't load — the
-/// check then does nothing, like every other data-driven system here.
+/// The `AreaTrigger.dbc` catalog, bucketed by map; absent when the data did not load.
 #[derive(Resource)]
 pub(crate) struct AreaTriggers(pub(crate) AreaTriggerCatalog);
 
-/// The trigger we are currently standing **inside**, with the map it is on — the reference's single
-/// "current trigger" pointer (`DAT_00c4d73c`).
-///
-/// Keyed by map so it can never leak across a worldport (the reference clears it on the map change;
-/// carrying the map id makes the same guarantee without a hook). It deliberately survives a
-/// reconnect on the same map, which is also what the reference does — its clear runs off the map
-/// change, not the socket — and it is the safer half of that coin: reconnecting inside a portal
-/// does not teleport you.
+/// The latched trigger and its map: the reference's current-trigger pointer (`0xc4d73c`), cleared
+/// on a map change and kept across a same-map reconnect, as the reference does.
 #[derive(Resource, Default)]
 pub(crate) struct InsideTrigger(Option<(u32, u32)>);
 
 impl InsideTrigger {
-    /// One check, as the reference orders it (`0x5e2110`): if we are still inside the latched
-    /// volume, report nothing; otherwise unlatch, and latch + report the **first** trigger on this
-    /// map containing `p`, if any. `Some(id)` means "send `CMSG_AREATRIGGER` for this one".
-    ///
-    /// Pure, and separate from the system, because the property that matters is a state machine
-    /// rather than a query: it must fire **once** per entry. Firing per frame would be a packet
-    /// flood at best and, on a teleport trigger, an infinite loop — arrive, fire, arrive.
+    /// One check in the reference's order (`0x5e2110`): nothing while still inside the latched
+    /// volume, else latch and return the first trigger on this map containing `p`.
     fn step(&mut self, triggers: &AreaTriggerCatalog, map_id: u32, p: [f32; 3]) -> Option<u32> {
         if let Some((latched_map, id)) = self.0 {
             let still_in = latched_map == map_id
@@ -104,9 +61,8 @@ impl Plugin for AreaTriggerPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<InsideTrigger>()
             .add_systems(Startup, load_area_triggers.after(AssetSet::Open))
-            // In the Stream band: after Input has moved the avatar (and applied any teleport
-            // snap), so the position tested is the one this frame ends at — the same one the
-            // movement stream reports, which is what the server re-checks us against.
+            // After Input has moved the avatar, so the position tested is the one the movement
+            // stream reports, which the server re-checks the claim against.
             .add_systems(
                 Update,
                 check_area_triggers
@@ -128,7 +84,7 @@ fn load_area_triggers(mut commands: Commands, assets: Option<Res<WorldAssets>>)
     }
 }
 
-/// The per-frame check — the reference's `0x5e2110`, in the same order it runs.
+/// The per-frame check (`0x5e2110`).
 fn check_area_triggers(
     triggers: Option<Res<AreaTriggers>>,
     map: Option<Res<CurrentMap>>,
@@ -139,8 +95,7 @@ fn check_area_triggers(
     let (Some(triggers), Some(map)) = (triggers, map) else {
         return;
     };
-    // Before the server has placed us, `pos` is wherever the free-flying camera left the avatar —
-    // not a position the server would recognise, and not one worth reporting.
+    // Before the server has placed us, `pos` is not a server position.
     if !player.active {
         return;
     }
@@ -148,11 +103,8 @@ fn check_area_triggers(
     let Some(trigger_id) = inside.step(&triggers.0, map.0, here) else {
         return;
     };
-    // Fire-and-forget, like every other send: a down write thread drops it.
     let _ = net.0.send(ClientCommand::AreaTrigger { trigger_id });
-    // At `info`, deliberately: entering a trigger is rare (you must cross a volume boundary), and
-    // when a portal or instance entrance "does nothing", the first question is whether the client
-    // saw the volume at all. One line answers it.
+    // At `info`: entries are rare, and this line tells whether the client saw the volume at all.
     info!(
         "area_trigger: entered {trigger_id} on map {} at [{:.2}, {:.2}, {:.2}]",
         map.0, here[0], here[1], here[2]
@@ -169,18 +121,14 @@ mod tests {
         Some(benilla_formats::load_area_trigger_catalog(&mut chain).expect("AreaTrigger.dbc"))
     }
 
-    /// The whole state machine over the **real** table, walking the exact route the live probe
-    /// walked: the Darnassus portal pair (B70) and the Southshore inn's box (the shape the sphere
-    /// tests can't reach). Skips without client data.
-    ///
-    /// The second assertion is the load-bearing one — a portal that reported every frame would
-    /// teleport you the instant you arrived, forever.
+    /// The state machine over the real table: the Darnassus portal pair and the Southshore inn's
+    /// box trigger. Skips without client data.
     #[test]
     fn a_trigger_fires_once_per_entry_and_re_arms_on_leaving() {
         let Some(cat) = real_catalog() else { return };
         let mut inside = InsideTrigger::default();
 
-        // Rut'theran Village's portal (542, a 10-yd sphere): step in, and it reports once.
+        // Rut'theran Village's portal (542, a 10 yd sphere).
         let ruttheran = [8799.41, 969.787, 30.2409];
         assert_eq!(inside.step(&cat, 1, ruttheran), Some(542));
         assert_eq!(
@@ -189,29 +137,24 @@ mod tests {
             "standing in a portal must not re-report it — that is the teleport loop"
         );
 
-        // The server answers by putting us at the Darnassus end. That landing spot is deliberately
-        // OUTSIDE the return trigger (527, also 10 yd) — 17.2 yd from its centre, and 13.9 yd the
-        // other direction — which is why a round trip is not a loop. Nothing fires, and the latch
-        // re-arms.
+        // The Darnassus landing spot lies outside the return trigger (527, 10 yd), 17.2 yd from
+        // its centre: nothing fires and the latch re-arms.
         let darnassus_arrival = [9946.25, 2612.97, 1316.49];
         assert_eq!(inside.step(&cat, 1, darnassus_arrival), None);
 
-        // Walk into the return portal proper: it reports, having re-armed.
         assert_eq!(inside.step(&cat, 1, [9947.48, 2630.04, 1318.6]), Some(527));
 
-        // A map change cannot leak the latch: the Southshore inn's BOX trigger (708) is on map 0
-        // and fires immediately, even though a trigger is still latched from map 1.
+        // The Southshore inn's box trigger (708) on map 0 fires while one is latched on map 1.
         assert_eq!(
             inside.step(&cat, 0, [-854.547, -576.314, 18.4659]),
             Some(708)
         );
         assert_eq!(inside.step(&cat, 0, [-854.593, -576.207, 18.5563]), None);
 
-        // Deadmines' entrance (78) — the instance-portal case (N02), a 7-yd sphere on map 0.
+        // The Deadmines entrance (78), an instance portal: a 7 yd sphere on map 0.
         assert_eq!(inside.step(&cat, 0, [-11208.5, 1685.34, 25.7612]), Some(78));
     }
 
-    /// Empty air reports nothing, and an unknown map is not an error.
     #[test]
     fn open_ground_and_unknown_maps_are_silent() {
         let Some(cat) = real_catalog() else { return };
diff --git a/crates/benilla-app/src/asset_churn.rs b/crates/benilla-app/src/asset_churn.rs
index e6831d30..880221f1 100644
--- a/crates/benilla-app/src/asset_churn.rs
+++ b/crates/benilla-app/src/asset_churn.rs
@@ -1,20 +1,7 @@
-//! `WOW_ASSET_CHURN=1` — what the app rewrites in `Assets<T>` every frame, and how big it is.
-//!
-//! The question this answers: Bevy's `prepare_assets<GpuImage>` re-uploads any image that was
-//! **modified** since last frame, and `extract_render_asset` re-extracts it. Both showed up as a
-//! flat multi-millisecond per-frame cost on the login screen — a static background image — where
-//! nothing should be modified at all. A trace can name the *system* that pays; only the asset
-//! events name the *asset* that made it pay.
-//!
-//! Prints one line per second: for each watched asset type, the per-frame Added/Modified counts,
-//! and for images the megabytes those modifications ask the render world to re-upload, plus the
-//! top offenders by how many frames they were touched in.
-//!
-//! The megabytes come from the image's `texture_descriptor`, not from `data.len()`. A
-//! `RenderAssetUsages::RENDER_WORLD` image has its bytes MOVED into the render world on extract, so
-//! main-side `data` is `None` from then on — measuring it read 0 for the sprite sheets, the effect
-//! textures and all three terrain arrays, i.e. for most of the texture set. The meter was blind to
-//! precisely the assets it exists to catch.
+//! `WOW_ASSET_CHURN=1`: once a second, logs per asset type the Added/Modified events per frame,
+//! the image megabytes those modifications re-upload, and the images touched in the most frames.
+//! Sizes come from the `texture_descriptor`: a `RENDER_WORLD` image's main-side `data` is `None`
+//! after extract.
 
 use std::collections::HashMap;
 
@@ -25,8 +12,7 @@ use bevy::time::Real;
 
 pub(crate) struct AssetChurnPlugin;
 
-/// Off unless `WOW_ASSET_CHURN=1`, read once (the plugin is skipped entirely, so an ordinary run
-/// carries no systems at all — not even a disabled one).
+/// Off unless `WOW_ASSET_CHURN=1`, read once; when off the plugin adds no systems.
 pub(crate) fn enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var("WOW_ASSET_CHURN").as_deref() == Ok("1"))
@@ -47,12 +33,9 @@ struct Churn {
     frames: u32,
     /// asset type -> (added, modified) event totals this window.
     counts: HashMap<&'static str, (u64, u64)>,
-    /// Image id -> how many DISTINCT frames it was modified in, the last frame index that counted
-    /// (so several Modified events in one frame count once), and its byte size when last seen.
-    /// Counting events instead printed "touched in 77/9 frames" — a ratio above 1.0 is the
-    /// instrument telling you it is measuring something other than what its label says.
+    /// Per image: distinct frames modified, not events, so the ratio never exceeds 1.
     images: HashMap<AssetId<Image>, ImageChurn>,
-    /// Bytes of image data modification asks the render world to re-upload, this window.
+    /// Image bytes modification asks the render world to re-upload, this window.
     image_bytes: u64,
     last_report: f32,
 }
@@ -62,9 +45,9 @@ struct Churn {
 struct ImageChurn {
     /// Distinct frames this image was modified in.
     frames: u64,
-    /// The last frame index already counted, so N events in one frame count once.
+    /// The last frame counted, so several events in one frame count once.
     last_frame: Option<u32>,
-    /// Its data size when last seen (what a modification asks to be re-uploaded).
+    /// Its GPU size when last seen.
     bytes: usize,
 }
 
diff --git a/crates/benilla-app/src/bindings.rs b/crates/benilla-app/src/bindings.rs
index ef50cf06..045f9645 100644
--- a/crates/benilla-app/src/bindings.rs
+++ b/crates/benilla-app/src/bindings.rs
@@ -1,45 +1,26 @@
-//! **Key bindings** (decision 0997) — the one chord→command engine every rebindable input runs
-//! through, replacing the per-site hardcoded key reads (and the four independent copies of
-//! 0585's bare-binding modifier rule they carried).
+//! Key bindings: the one chord-to-command engine every rebindable input runs through. The table
+//! lives engine-side ([`benilla_ui::script::keybind`], which the Key Bindings window's Lua edits);
+//! this module derives an exact-match dispatch map from it whenever its generation moves.
 //!
-//! The split mirrors the CVar table (0954): the **string-domain truth** lives engine-side
-//! ([`benilla_ui::script::keybind`] — the table the Key Bindings window's Lua edits
-//! synchronously), and this module derives the app's **dispatch view** from it whenever its
-//! generation moves: canonical chord strings parsed ([`chord`]) into an exact-match map.
-//!
-//! Dispatch (the [`latch_and_dispatch`] system, ordered inside [`crate::ui_script::UiInput`]
-//! right after the UI key feed):
-//! - a press probes its **exact** chord and then, only on a miss, **once more** with its leftmost
-//!   modifier dropped ([`Chord::fallback`], decision 1142) — which is why `Shift`+`W` walks while
-//!   `SHIFT-W` is bound to nothing, and why a bound `SHIFT-TAB` still beats bare `TAB` (the exact
-//!   probe is always first). Super held matches nothing;
-//! - [`Kind::Held`] commands **latch** on the matching press and unlatch on the *base key's*
-//!   release — the reference's `runOnUp` movement law, which is why tapping Shift mid-run does
-//!   not stop you, and why **nothing the UI does stops you**: a chat box taking focus and a
-//!   fullscreen frame eating a key both suppress the *press* and release nothing already held
-//!   (decision 2196). The only things that end a latch are the base key's release, the
-//!   [stuck-latch sweep](latch_and_dispatch) that stands in for a release the window never saw
-//!   (OS focus loss, the loading cover), and the VM swap;
+//! Dispatch ([`latch_and_dispatch`], in [`crate::ui_script::UiInput`] after the UI key feed):
+//! - a press probes its exact chord, then once more with its leftmost modifier dropped
+//!   ([`Chord::fallback`]); Super held matches nothing;
+//! - [`Kind::Held`] commands latch on the press and unlatch on the base key's release (the
+//!   reference's `runOnUp` law). UI focus suppresses presses and releases nothing already held;
+//!   a latch ends only on its base key's release, the stuck-latch sweep (OS focus loss, the
+//!   loading cover) or a VM swap;
 //! - [`Kind::Edge`]/[`Kind::EdgeUpDown`] run their 1.12 Lua bodies in the VM;
-//! - [`Kind::Host`] lands in [`BindingsState::fired`] for engine consumers (chat open, TAB
-//!   targeting, nameplates, autorun, camera zoom, …).
+//! - [`Kind::Host`] lands in [`BindingsState::fired`] for engine consumers.
 //!
-//! **An addon's `Bindings.xml` rows dispatch here too** (decision 1188 phase 4). They are not in
-//! [`SPECS`] — they are read off disk at addon load ([`benilla_ui::bindings_xml`]) — so a resolved
-//! chord names a [`Bound`], which is either a registry [`Cmd`] or an index into this frame's
-//! addon table. That enum is the whole design: an addon row is a *runtime* `String` body run with
-//! the reference's `keystate` global, and every `SPECS[cmd]` in this file would be a latent panic
-//! if it were instead an index past the end of the static table.
+//! An addon's `Bindings.xml` rows ([`benilla_ui::bindings_xml`]) dispatch here too: a resolved
+//! chord names a [`Bound`], either a registry [`Cmd`] or an index into the addon table.
 //!
-//! While the Keybindings page (the Options window's category since 1008) has a capsule
-//! selected it arms the **capture seam** (`BenillaBindCapture`): raw input is swallowed here,
-//! canonicalized (`ALT-CTRL-SHIFT-<TOKEN>`), and handed back to the page's own capture handler
-//! — the 1.12 law (lone modifiers ignored, left/right clicks stay UI clicks, ESC binds like
-//! any key).
+//! While the Keybindings page has a capsule selected (`BenillaBindCapture`), raw input is
+//! canonicalized (`ALT-CTRL-SHIFT-<TOKEN>`) and handed to the page, by the 1.12 law: lone
+//! modifiers ignored, left and right clicks stay UI clicks, ESC binds like any key.
 //!
-//! Persistence: `benilla-config/bindings/account.txt` + `<Realm>-<Char>.txt` ([`store`], through
-//! [`crate::local_state`]); the character file's existence is the character-set state, deleted
-//! on the confirmed switch back to general — the reference's own semantics.
+//! Persistence: `benilla-config/bindings/account.txt` and `<Realm>-<Char>.txt` ([`store`]); the
+//! character file's existence is the character-set state, as in the reference.
 
 use bevy::input::keyboard::KeyboardInput;
 use bevy::input::mouse::{AccumulatedMouseScroll, MouseScrollUnit};
@@ -60,56 +41,37 @@ use chord::{BindKey, Chord};
 pub(crate) use commands::cmd;
 use commands::{Cmd, Kind, SPECS};
 
-/// What a bound chord names — a registry command, or an addon's `Bindings.xml` body
-/// (decision 1188 phase 4).
-///
-/// **An enum rather than one index space with a sentinel in it.** The tempting shape is
-/// "`Cmd(u16)`, and anything `>= SPECS.len()` is an addon" — which would turn every one of this
-/// file's eleven `SPECS[cmd.0 as usize]` reads into a panic waiting for the first addon binding to
-/// be pressed. The compiler is what should be enforcing that split, so it does: `state.fired` /
-/// `state.just` / `state.amounts` stay [`Cmd`]-typed (a host command is always a built-in and
-/// there is nothing for an addon to fire into), and only the map and the latches carry a `Bound`.
+/// What a bound chord names: a registry command or an addon's `Bindings.xml` body. An enum, not
+/// one index space, so no `SPECS[cmd]` read can be handed an addon index.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 enum Bound {
-    /// A registry command — indexes [`SPECS`].
+    /// A registry command, an index into [`SPECS`].
     Spec(Cmd),
-    /// An addon-declared binding — indexes [`BindingDispatch::addons`].
+    /// An addon-declared binding, an index into [`BindingDispatch::addons`].
     Addon(u16),
 }
 
-/// The derived chord→binding map — rebuilt whenever the engine table's generation moves. Probed
-/// through [`BindingDispatch::resolve`], never directly: the lookup is two probes, not one.
+/// The chord-to-binding map, rebuilt whenever the engine table's generation moves. Probe it
+/// through [`BindingDispatch::resolve`]: the lookup is two probes.
 #[derive(Resource, Default)]
 struct BindingDispatch {
     map: std::collections::HashMap<Chord, Bound>,
-    /// The addon-declared bindings [`Bound::Addon`] indexes, in the engine table's registration
-    /// order — re-snapshotted with the map, so the two can never disagree about what an index
-    /// means. Empty in every session with no addon bindings, which is every session today.
+    /// The addon bindings [`Bound::Addon`] indexes, in registration order; snapshotted with the
+    /// map so the two agree on what an index means.
     addons: Vec<AddonBindingBody>,
-    /// The engine table's generation this map was built from. **Session-keyed** (1290): a fresh VM
-    /// restarts its counter at 0, so a bare memo could hold a higher number than the live VM will
-    /// ever reach and gate the rebuild off for the whole session.
+    /// The engine table's generation this map was built from, keyed per VM: a fresh VM restarts
+    /// its counter at 0.
     seen_generation: crate::ui_script::VmMemo<Option<u64>>,
 }
 
 impl BindingDispatch {
-    /// Resolve a press to its command — the reference's lookup (`CBindings::ExecuteBinding`
-    /// `0x4b7990`, decision 1142): the exact chord, then **one** retry with the leftmost modifier
-    /// dropped ([`Chord::fallback`]). The exact probe always runs first, so a bound specific chord
-    /// always beats the general one.
+    /// Resolve a press as the reference's `CBindings::ExecuteBinding` (`0x4b7990`) does: the exact
+    /// chord, then one retry with the leftmost modifier dropped ([`Chord::fallback`]).
     ///
-    /// `dev_plane` suppresses the **retry only**, and only on the keyboard path. `Ctrl`+`Shift` is
-    /// ours ([`benilla_world::modkeys::DEV_CHORD`]), and 0870 picked it on the argument that the plane
-    /// was empty — an argument that rested on the exact-match law 1142 corrects. It is
-    /// *nearly* empty anyway under the real law, because the single strip drops `CTRL` and leaves
-    /// `SHIFT-`*key*, never reaching the bare letter — but "nearly" is not a plane: `SHIFT-P` is a
-    /// live 1.12 default (`TOGGLECHARACTER3`, 1057), so `Ctrl`+`Shift`+`P` would open the pet
-    /// paper doll under the perf HUD. That is 0585's original bug, and this is the same fix it
-    /// made, now correctly scoped: an *exact* `CTRL-SHIFT-` binding still dispatches, so the
-    /// reference's own two (`CTRL-SHIFT-TAB`, `CTRL-SHIFT-PAGEDOWN`) and anything a player binds
-    /// there are untouched. Only the plane's fallback shadow is ours. Mouse and wheel are not
-    /// suppressed — every dev instrument is a letter, so a modified click is nobody's but the
-    /// game's.
+    /// Deviation, dev builds only: `dev_plane` suppresses the keyboard retry, because
+    /// `Ctrl`+`Shift` is the dev overlays' plane ([`benilla_world::modkeys::DEV_CHORD`]) and
+    /// `Ctrl`+`Shift`+`P` would otherwise fall back to `SHIFT-P` (`TOGGLECHARACTER3`). An exact
+    /// `CTRL-SHIFT-` binding still dispatches; mouse and wheel are never suppressed.
     fn resolve(&self, chord: Chord, dev_plane: bool) -> Option<Bound> {
         if let Some(&bound) = self.map.get(&chord) {
             return Some(bound);
@@ -121,42 +83,33 @@ impl BindingDispatch {
     }
 }
 
-/// This frame's binding activity — what the engine-side consumers read instead of raw keys.
+/// This frame's binding activity, which engine-side consumers read instead of raw keys.
 #[derive(Resource, Default)]
 pub(crate) struct BindingsState {
-    /// Live latches: (base key, binding) — a [`Kind::Held`], [`Kind::EdgeUpDown`] or `runOnUp`
-    /// addon press that has not released yet.
+    /// Live latches, (base key, binding): a [`Kind::Held`], [`Kind::EdgeUpDown`] or `runOnUp`
+    /// addon press not yet released.
     latched: Vec<(BindKey, Bound)>,
     /// Commands whose first latch began this frame (the press edge).
     just: Vec<Cmd>,
     /// Host-edge commands fired this frame.
     fired: Vec<Cmd>,
-    /// Accumulated analog amount per host command this frame (wheel notches; a key press adds
-    /// the reference's own 1.0 step) — the camera zoom's input.
+    /// Analog amount per host command this frame (wheel notches; a key press adds the
+    /// reference's 1.0 step), the camera zoom's input.
     amounts: Vec<(Cmd, f32)>,
-    /// **The pressed-key set — what makes a press a REPEAT** (decision 2204). The reference
-    /// classifies auto-repeat off its own list of keys it believes are down (`0x4248b3`), *not*
-    /// off the Win32 `lParam` repeat bit — so the OS bit is not what this reads either.
-    ///
-    /// Base keys, normalized ([`chord::normalize_key`]) exactly as [`latched`](Self::latched) is,
-    /// so `NUMPADENTER` repeating under a held `ENTER` is the repeat it looks like. Reconciled
-    /// against `ButtonInput` at the top of every pass, which is what wipes it on a window
-    /// activation change for free — and why a key still held across an alt-tab starts running
-    /// again on the way back, as it does in the reference.
-    ///
-    /// **Keyboard only, and the type says so.** The mouse plane is read as edges
-    /// (`just_pressed`), which cannot repeat, so it needs no classification of its own.
+    /// The keys we believe are down: a press of one is a repeat. The reference classifies
+    /// auto-repeat off its own list (`0x4248b3`), never the Win32 `lParam` repeat bit.
+    /// Normalized like [`latched`](Self::latched) and reconciled against `ButtonInput` every
+    /// pass, so a window deactivate empties it and a key held across an alt-tab resumes, as in
+    /// the reference. Keyboard only: mouse edges cannot repeat.
     down: Vec<KeyCode>,
 }
 
 impl BindingsState {
-    /// Is a held command latched right now? (The reference's held movement bit.) Registry
-    /// commands only — an addon's latch exists to deliver its release half, and no engine system
-    /// reads it.
+    /// Is a registry command latched right now (the reference's held movement bit)?
     pub(crate) fn pressed(&self, c: Cmd) -> bool {
         self.latched.iter().any(|&(_, l)| l == Bound::Spec(c))
     }
-    /// Did this command's latch begin this frame? (The key-DOWN edge — the autorun cancel set.)
+    /// Did this command's latch begin this frame (the key-down edge)?
     pub(crate) fn just_pressed(&self, c: Cmd) -> bool {
         self.just.contains(&c)
     }
@@ -182,20 +135,16 @@ impl BindingsState {
     }
 }
 
-/// Which files this session's bindings live in — the macros-files pattern
-/// ([`crate::ui_macro::MacroFiles`]), written by [`seed_bindings_for_vm`] and read by the save
-/// verb. It carried a session-keyed `identity` memo while the character set was loaded from a
-/// per-frame system and had to recognise "same character, new VM"; the seed runs exactly once per
-/// VM by construction, so there is nothing left to dedupe (decision 2241).
+/// Which files this session's bindings live in: written by [`seed_bindings_for_vm`], read by the
+/// save.
 #[derive(Resource, Default)]
 struct BindingFiles {
     account: Option<std::path::PathBuf>,
     character: Option<std::path::PathBuf>,
 }
 
-/// Label for this module's systems inside [`crate::ui_script::UiInput`] — the UI key feed is
-/// ordered `.before()` it (a key a focused box consumes must already be reflected in the
-/// capture gate when dispatch runs).
+/// This module's systems inside [`crate::ui_script::UiInput`]. The UI key feed runs before it, so
+/// a key a focused box consumed is already in the capture gate when dispatch runs.
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub(crate) struct BindingSet;
 
@@ -209,14 +158,9 @@ impl Plugin for BindingsPlugin {
             .add_systems(
                 Update,
                 (
-                    // **The registry and both sets are seeded at the VM's birth, not here**
-                    // (decision 2241): [`seed_bindings_for_vm`] runs inside
-                    // `load_ingame_ui_on_world_entry`, before FrameXML and every addon. A
-                    // session-keyed `Update` claim answered *which* VM but not *when* inside its
-                    // life — and this table's readers are load-edge readers: stock
-                    // `ActionButton_OnLoad` paints its hotkey corner from `GetBindingKey` at
-                    // OnLoad, and an addon's `SetBinding` on a stock command needs the command to
-                    // exist.
+                    // The registry and both sets are seeded at the VM's birth, not here:
+                    // `seed_bindings_for_vm` runs in `load_ingame_ui_on_world_entry`, before
+                    // FrameXML and every addon.
                     (sync_dispatch, latch_and_dispatch)
                         .chain()
                         .in_set(crate::ui_script::UiInput)
@@ -230,8 +174,8 @@ impl Plugin for BindingsPlugin {
     }
 }
 
-/// The registry as the engine table's registration payload — shared by the boot seed and the
-/// hermetic capture fixtures (which have no plugin seed to race, the `register_cvars` posture).
+/// The registry as the engine table's registration payload, for the boot seed and the capture
+/// fixtures.
 pub(crate) fn registry_commands() -> Vec<KeybindCommand> {
     SPECS
         .iter()
@@ -245,36 +189,21 @@ pub(crate) fn registry_commands() -> Vec<KeybindCommand> {
         .collect()
 }
 
-/// **The keybinding table goes into the VM before a single interface file runs** (decision 2241,
-/// through the seam 2240 established): the command registry, the account set, and the character's
-/// own set if it has one — all of it in one call at the VM's birth.
+/// Seed the keybinding table at the VM's birth, before any interface file runs: the command
+/// registry, the account set, and the character's set if it has one.
 ///
-/// This was two `Update` systems with session-keyed claims. That answered *which* VM the memory was
-/// about (1290) and not *when inside its life* it ran, and since 2226 the whole interface load —
-/// FrameXML, every addon's file scope, `ADDON_LOADED`, `VARIABLES_LOADED`, `PLAYER_LOGIN` — happens
-/// inside one exclusive call that precedes the first `Update`. Two readers that costs:
-///
-/// - stock `ActionButton_OnLoad` ends in `ActionButton_UpdateHotkeys`, which paints the corner from
-///   `GetBindingText(GetBindingKey(action), …)`. With no registry every hotkey corner painted blank
-///   and only recovered on the `UPDATE_BINDINGS` `sync_dispatch` fires a frame later;
-/// - an addon's own `Bindings.xml` rows ARE registered during the walk, so the table held *only*
-///   those during the burst: `GetBindingKey("TOGGLEWORLDMAP")` answered nothing, `SetBinding` on a
-///   stock command was a silent nil, and the addons' rows occupied the low indices the Key Bindings
-///   window walks.
-///
-/// Seeding before the walk is also the reference's own order, and the engine was already built for
-/// it: `seed_binding_set` keeps the diff by NAME as well as positionally precisely so a set can be
-/// seeded before a command exists (1201), and `register_bindings` is idempotent per name, so the
-/// addon rows the walk registers afterwards still land.
+/// Order matters, and is the reference's: stock `ActionButton_OnLoad` paints its hotkey corner
+/// from `GetBindingKey` at load, an addon's `SetBinding` on a stock command needs the command
+/// registered, and the registry must hold the low indices the Key Bindings window walks.
+/// `seed_binding_set` keeps the diff by name, so a stored addon row binds when the addon
+/// registers it later.
 pub(crate) fn seed_bindings_for_vm(world: &mut World, script: &mut UiScript) {
     script.register_bindings(&registry_commands());
     let account = crate::local_state::bindings_account_path();
     let overrides = read_diff(&account).unwrap_or_default();
     script.seed_binding_set(1, Some(store::resolve(&overrides)));
     script.load_binding_set(1);
-    // The pair, not just the first half: `SPECS` ∪ `ABSENT` is the client's whole 1.12 command
-    // surface, and a log line that says only how many landed cannot say how much is left
-    // (decision 1745).
+    // `SPECS` and `ABSENT` together are the client's whole 1.12 command surface.
     info!(
         "bindings: {} of {} 1.12 commands registered ({} recorded absent)",
         SPECS.len(),
@@ -282,10 +211,8 @@ pub(crate) fn seed_bindings_for_vm(world: &mut World, script: &mut UiScript) {
         commands::ABSENT.len()
     );
 
-    // The character's own set, if the roster names one — its file existing makes it the active set,
-    // the reference's own rule. The identity is the same one the edge resolves for the AddOn enable
-    // state a few lines above this call; absent (a rigged or capture run) leaves set 2 unseeded,
-    // exactly as the old per-frame system's early return did.
+    // The character's own set: its file existing makes it the active set, the reference's rule.
+    // No roster identity (a rigged or capture run) leaves set 2 unseeded.
     let id = world
         .get_resource::<crate::char_select::Roster>()
         .and_then(crate::ui_macro::identity);
@@ -309,7 +236,7 @@ pub(crate) fn seed_bindings_for_vm(world: &mut World, script: &mut UiScript) {
     }
 }
 
-/// Read + parse one diff file; `None` when absent/unreadable (defaults).
+/// Read and parse one diff file; `None` (the defaults) when absent or unreadable.
 fn read_diff(path: &Option<std::path::PathBuf>) -> Option<Vec<(String, Vec<String>)>> {
     let path = path.as_ref()?;
     match std::fs::read_to_string(path) {
@@ -322,20 +249,16 @@ fn read_diff(path: &Option<std::path::PathBuf>) -> Option<Vec<(String, Vec<Strin
     }
 }
 
-/// Drain the VM's queued binding requests.
-///
-/// Two of them. `Save` persists on the window's SaveBindings (Okay): write the set's diff; saving
-/// account while a character file exists deletes it — the confirmed permanent delete. `Run` fires
-/// a named command's action outright, which is `RunBinding(name)` — the reference's own
-/// passthrough verb, whose one shipped caller is `CinematicFrame`'s `OnKeyDown` handing the
-/// SCREENSHOT chord back to its binding while it swallows every other key (decision 1724).
+/// Drain the VM's binding requests. `Save` (`SaveBindings`) writes the set's diff; saving the
+/// account set deletes the character file. `Run` is `RunBinding(name)`, which stock keyboard
+/// frames use to pass a chord back to its binding (`CinematicFrame.xml:42`,
+/// `WorldMapFrame.xml:629`).
 fn drain_binding_requests(script: Option<NonSendMut<UiScript>>, files: Res<BindingFiles>) {
     let Some(mut script) = script else { return };
     for req in script.take_keybind_requests() {
-        // `RunBinding(name)` — fire the named command's action as if its chord had been pressed.
-        // Only the two Lua-bodied kinds can be run this way: a `Held`/`Host` command's action is a
-        // bit in the movement word, which a Lua call has no frame to assert for. The one shipped
-        // caller is `CinematicFrame`'s SCREENSHOT passthrough, and `SCREENSHOT` is `Kind::Edge`.
+        // Only the Lua-bodied kinds can run this way: a `Held`/`Host` action is engine state a Lua
+        // call cannot assert. The stock callers run `SCREENSHOT` and `TOGGLEWORLDMAP`, both
+        // `Kind::Edge`.
         let which = match req {
             KeybindRequest::Save(which) => which,
             KeybindRequest::Run(name) => {
@@ -376,9 +299,8 @@ fn drain_binding_requests(script: Option<NonSendMut<UiScript>>, files: Res<Bindi
     }
 }
 
-/// Rebuild the dispatch map when the engine table moved (a rebind, a set switch, the seed),
-/// and fire the reference's own `UPDATE_BINDINGS` so the Lua consumers repaint (the action
-/// bar's HotKey corners; the ref registers the same event for the same job).
+/// Rebuild the dispatch map when the engine table moved (a rebind, a set switch, the seed), and
+/// fire `UPDATE_BINDINGS` so the Lua consumers (the action bar's hotkey corners) repaint.
 fn sync_dispatch(script: Option<NonSendMut<UiScript>>, mut dispatch: ResMut<BindingDispatch>) {
     let Some(mut script) = script else { return };
     let generation = script.keybinds_generation();
@@ -387,9 +309,7 @@ fn sync_dispatch(script: Option<NonSendMut<UiScript>>, mut dispatch: ResMut<Bind
     }
     *dispatch.seen_generation.get(&script) = Some(generation);
     dispatch.map.clear();
-    // The addon table first: it is what the names the registry does not know resolve into. Before
-    // 1188 phase 4 an unknown name hit the `continue` below and the binding silently never fired
-    // — it registered, listed in the window, saved and loaded, and did nothing.
+    // The addon table is where names the registry does not know resolve.
     let addons = script.addon_binding_bodies();
     let mut by_name: std::collections::HashMap<&str, Bound> = SPECS
         .iter()
@@ -397,20 +317,15 @@ fn sync_dispatch(script: Option<NonSendMut<UiScript>>, mut dispatch: ResMut<Bind
         .map(|(i, s)| (s.name, Bound::Spec(Cmd(i as u16))))
         .collect();
     for (i, a) in addons.iter().enumerate() {
-        // A registry name is never overwritten — the engine table already refuses to register an
-        // addon row over one, so this only ever adds. The `try_from` is the honest form of the
-        // cast: 65k addon bindings is not a real case, and a wrapped index would dispatch the
-        // wrong body rather than none.
+        // A registry name is never overwritten. `try_from`, because a wrapped index would
+        // dispatch the wrong body rather than none.
         let Ok(i) = u16::try_from(i) else { break };
         by_name.entry(a.name.as_str()).or_insert(Bound::Addon(i));
     }
     for (name, keys) in script.keybind_snapshot() {
         let Some(&bound) = by_name.get(name.as_str()) else {
-            // A name with no home: either an uninstalled addon's row (1201 keeps those on
-            // purpose) or a 1.12 command this client does not implement. The second case is the
-            // one that used to mystify — a player carrying their own bindings over presses the
-            // key they have always pressed and nothing happens, with nothing anywhere saying
-            // why. `ABSENT` knows why, so say it (decision 1745).
+            // A name with no home: an uninstalled addon's row (kept on purpose) or a 1.12
+            // command benilla does not implement, which `ABSENT` explains in the log.
             if let Some(absent) = commands::ABSENT.iter().find(|a| a.name == name) {
                 if !keys.is_empty() {
                     warn!(
@@ -434,10 +349,8 @@ fn sync_dispatch(script: Option<NonSendMut<UiScript>>, mut dispatch: ResMut<Bind
     script.fire_event("UPDATE_BINDINGS", vec![]);
 }
 
-/// A wheel delta in **lines** — notches — whatever unit the OS reported it in. A mouse wheel
-/// arrives as `Line`; a macOS trackpad or Magic Mouse arrives as `Pixel`, many small deltas a
-/// frame apart for one gesture, and Bevy's own conversion factor is the one normalisation.
-/// Shared by every wheel reader so none of them keeps its own copy of the constant.
+/// A wheel delta in lines (notches), whatever unit the OS reported: a trackpad's `Pixel` deltas
+/// go through Bevy's own conversion factor. Every wheel reader shares it.
 pub(crate) fn wheel_lines(unit: MouseScrollUnit, dy: f32) -> f32 {
     match unit {
         MouseScrollUnit::Line => dy,
@@ -445,19 +358,11 @@ pub(crate) fn wheel_lines(unit: MouseScrollUnit, dy: f32) -> f32 {
     }
 }
 
-/// **Whole notches out of a stream of line deltas**, carrying the fraction between frames.
+/// Whole notches out of a stream of line deltas, carrying the fraction between frames.
 ///
-/// For the consumers that act per NOTCH rather than per unit of travel — the UI's
-/// `OnMouseWheel` (stock `ScrollFrameTemplate_OnMouseWheel` moves half a pane per call and
-/// `ChatFrame_OnMouseWheel` a line, both off the sign alone) and the realm list's row step. Fed a
-/// trackpad's per-frame pixel trickle raw, each of those fired once per frame, so a gentle swipe
-/// slammed a pane to its end; through this, ten frames of a tenth of a line are one notch.
-///
-/// A reversal drops the carried fraction: travel the other way is a new gesture, and it should
-/// not first have to undo the remainder of the last one.
-///
-/// A `Resource` for the UI's feed (a fact about the input device's gesture, which outlives any one
-/// VM), a `Local` for the realm list's.
+/// For consumers that act per notch off the sign alone: the UI's `OnMouseWheel` (stock
+/// `ScrollFrameTemplate_OnMouseWheel` moves half a pane per call, `UIPanelTemplates.lua:150`) and
+/// the realm list's row step. A reversal drops the carried fraction: it is a new gesture.
 #[derive(Default, Resource)]
 pub(crate) struct WheelNotches {
     carry: f32,
@@ -479,8 +384,8 @@ impl WheelNotches {
     }
 }
 
-/// The dispatch pass — see the module doc. Runs right after the UI key feed (same frame's
-/// capture gate), before `WorldStage::Input` (a bound key must act this frame, once).
+/// The dispatch pass (see the module doc). Runs after the UI key feed and before
+/// `WorldStage::Input`, so a bound key acts this frame, once.
 fn latch_and_dispatch(
     script: Option<NonSendMut<UiScript>>,
     mut keyboard: MessageReader<KeyboardInput>,
@@ -489,7 +394,7 @@ fn latch_and_dispatch(
     scroll: Res<AccumulatedMouseScroll>,
     capture: Res<UiKeyboardCapture>,
     hover: Res<PlayerUiHover>,
-    // The CHROME flag — its only reader here is the wheel branch, which says why.
+    // The chrome flag; only the wheel branch reads it.
     over_ui: Res<PointerOverUiPanel>,
     dispatch: Res<BindingDispatch>,
     mut state: ResMut<BindingsState>,
@@ -499,13 +404,9 @@ fn latch_and_dispatch(
     state.fired.clear();
     state.amounts.clear();
 
-    // A latch indexes the dispatch table snapshotted from the VM that latched it. When the VM is
-    // replaced mid-hold (a `/reload` with a key down), releasing against the NEW table would run
-    // the wrong addon's `keystate="up"` body — or swallow the release and leave a Held latched
-    // with no Stop. So latches die with the VM they were made against (decision 1291); a key
-    // still physically down re-latches on its next press edge. The reference keeps a held key
-    // running through a `ReloadUI` (its dispatch is engine-side) — dropping is the safe
-    // divergence, over the moment the key is pressed again.
+    // Deviation: latches die with the VM that made them, because a latch indexes that VM's
+    // dispatch table and releasing it against a new one would run the wrong addon's up-half. The
+    // reference keeps a held key running through `ReloadUI`; here it re-latches on its next press.
     if let Some(script) = script.as_ref() {
         if same_vm.claim(script) {
             state.latched.clear();
@@ -516,15 +417,9 @@ fn latch_and_dispatch(
     let ctrl = keys.pressed(KeyCode::ControlLeft) || keys.pressed(KeyCode::ControlRight);
     let alt = keys.pressed(KeyCode::AltLeft) || keys.pressed(KeyCode::AltRight);
     let sup = keys.pressed(KeyCode::SuperLeft) || keys.pressed(KeyCode::SuperRight);
-    // Exactly the dev overlays' plane (`modkeys::dev_chord`, minus the Super arm the `sup` gate
-    // below already covers) — it costs the keyboard its fallback probe. See
-    // [`BindingDispatch::resolve`].
-    //
-    // **Only when there is something on the plane** (decision 1179). A player build holds no dev
-    // chord at all, so suppressing the reference's fallback there buys nothing and costs fidelity:
-    // `CTRL-SHIFT-P` would resolve to `None` instead of falling through to `SHIFT-P`
-    // (`TOGGLECHARACTER3`, the pet paper doll) the way the binary does. 1176 gated what the plane
-    // *offers* and left what it *costs*; this is the other half.
+    // The dev overlays' plane (`modkeys::dev_chord`; the `sup` gate covers its Super arm), which
+    // costs the keyboard its fallback probe (`BindingDispatch::resolve`). Only in a build with dev
+    // affordances: a player build keeps the reference's `CTRL-SHIFT-P` fallback to `SHIFT-P`.
     let dev_plane = ctrl && shift && !alt && crate::run_mode::dev_affordances();
 
     let mut script = script;
@@ -537,10 +432,10 @@ fn latch_and_dispatch(
         }
     };
 
-    // ── The capture seam ── the Keybindings page has a capsule selected: swallow raw input,
-    // canonicalize, hand the chord string to the page's Lua (1.12's OnKeyDown law: lone
-    // modifiers and unknown keys ignored; Super is not a 1.12 modifier — a Super press is
-    // ignored outright; left/right stay UI clicks; the wheel is a chord like any other).
+    // ── The capture seam ── a Keybindings capsule is selected: swallow raw input and hand the
+    // chord string to the page's Lua. The 1.12 law: lone modifiers and unknown keys ignored,
+    // left and right stay UI clicks, the wheel is a chord. Super is not a 1.12 modifier, so a
+    // Super press is ignored outright.
     if armed {
         let mut captured: Option<String> = None;
         for ev in keyboard.read() {
@@ -573,58 +468,33 @@ fn latch_and_dispatch(
                 "capture",
             );
         }
-        // Releases still unlatch below (a key held across the arm must not stick), but no new
-        // latches or fires happen while armed.
+        // Releases still unlatch below so a key held across the arm cannot stick; nothing new
+        // latches or fires while armed.
     }
 
-    // ── Who owns this frame's keys ── a focused EditBox eats every key for as long as it holds
-    // focus; a shown keyboard frame ate the particular keys in `capture.consumed`. Both suppress a
-    // PRESS below and do nothing else — **a UI focus change releases nothing already held**.
+    // ── Who owns this frame's keys ── a focused EditBox eats every key while it holds focus; a
+    // shown keyboard frame ate the keys in `capture.consumed`. Both suppress a press and nothing
+    // else: in the reference a focused box makes the movement handlers no-ops, so the direction
+    // bits are frozen, not cleared. `0x514490`, which does clear them, is the OS window-deactivate
+    // handler (sole caller `0x493058`, off the root's WM_ACTIVATE slot `[root+0x1134]`); here
+    // bevy's `KeyboardFocusLost` and `ButtonInput::release_all` reach the stuck-latch sweep below.
     //
-    // This is where bug 2196 lived. The block here used to drop every [`Kind::Held`] latch on the
-    // rising edge of `capture.typing`, on a misreading of `0x514490` as "the reference's chat-focus
-    // handler": its sole caller `0x493058` hangs off the CSimpleTop root's WM_ACTIVATE callback
-    // slot (`[root+0x1134]`, event category 2, payload 0 = deactivate), so it is the **OS
-    // window-deactivate** handler, not a UI-focus one.
-    // In the reference a focused box merely turns the movement handlers into no-ops and the
-    // direction bits are *frozen, not cleared* — so holding W and pressing ENTER keeps you
-    // running, and the world map eating the `M` that closes it keeps you running too. Both
-    // regressions were one clear.
-    //
-    // The window-deactivate clear needs no code of its own: bevy's `KeyboardFocusLost` →
-    // `ButtonInput::release_all` makes every latched base key read up, and the stuck-latch sweep
-    // at the bottom of this system turns that into real releases (the loading cover reaches it the
-    // same way, through `loading_screen::input`'s `swallow`).
-    //
-    // ── The pressed-key reconcile ── the reference keeps its own list of keys it believes are
-    // down and calls a press a REPEAT when the key is already on it (`0x4248b3`) — it never reads
-    // the Win32 `lParam` repeat bit. Ours is reconciled against bevy's button planes here, before
-    // this frame's messages are read, which buys two things at once (decision 2204):
-    //
-    // - a release the window never saw drops off the list, exactly as it drops off `latched` in
-    //   the sweep below — the list cannot go stale and start swallowing real presses;
-    // - **WM_ACTIVATE's wipe of the pressed-key set comes for free.** `KeyboardFocusLost` →
-    //   `ButtonInput::release_all` empties the plane, so a key still physically held across an
-    //   alt-tab is no longer on the list when we come back, and its next auto-repeat is therefore
-    //   a fresh DOWN that re-latches. That is the reference's own behaviour and not a happy
-    //   accident: `0x514490` cleared the direction bits on the way out, and `0x424790`'s wipe of
-    //   the pressed-key set is what lets the first repeat put them back — so you resume running
-    //   without lifting the key.
+    // ── The pressed-key reconcile ── against bevy's button planes, before this frame's messages:
+    // a release the window never saw drops off the list, and a window deactivate empties it, the
+    // reference's `0x424790` wipe, so a key held across an alt-tab re-latches on its next repeat.
     state
         .down
         .retain(|&kc| physically_down(BindKey::Key(kc), &keys, &buttons));
 
-    // ── Keyboard ── press edges latch/fire (exact-modifier chord match, no repeats, gated on the
-    // two ownership terms and the capture arm); release edges unlatch and fire the runOnUp up-half.
+    // ── Keyboard ── press edges latch or fire, gated on ownership and the capture arm; release
+    // edges unlatch and fire the `runOnUp` up-half.
     let typing = capture.typing;
     for ev in keyboard.read() {
         let key = chord::normalize_key(ev.key_code);
         match ev.state {
             ButtonState::Pressed => {
-                // The alt-arrow exemption: a focused box in alt-arrow mode declines the four
-                // arrows, so their bindings DO fire even while typing — which is the whole
-                // point of the flag (turn the camera with the chat box open). Every other key
-                // a focused box still swallows. See `UiKeyboardCapture::arrows_fall_through`.
+                // A focused box in alt-arrow mode declines the four arrows, so their bindings
+                // fire while typing (`UiKeyboardCapture::arrows_fall_through`).
                 let arrow_exempt = capture.arrows_fall_through
                     && matches!(
                         ev.key_code,
@@ -633,13 +503,11 @@ fn latch_and_dispatch(
                             | KeyCode::ArrowUp
                             | KeyCode::ArrowDown
                     );
-                // A keyboard frame's existence gate ate this one key (decision 1319) — the
-                // world map's fullscreen `OnKeyDown`, a cinematic, the stack-split spinner. Per
-                // key, so the map eating its own `M` leaves every other binding alone.
+                // A keyboard frame ate this one key (the world map's `OnKeyDown`, a cinematic);
+                // per key, so every other binding is untouched.
                 let eaten = capture.consumed.contains(&ev.key_code);
-                // **A repeat is a key we already believe is down** — the reference's own test, not
-                // the OS's repeat bit (2204). Registered before the gates below, so a key held
-                // through a focused chat box is still "down" and its repeats stay repeats.
+                // A repeat is a key we already believe is down, the reference's test. Recorded
+                // before the gates below, so a key held through a focused box stays down.
                 let repeat = state.down.contains(&key);
                 if !repeat {
                     state.down.push(key);
@@ -680,8 +548,8 @@ fn latch_and_dispatch(
         }
     }
 
-    // ── Mouse buttons ── same law; presses only while the cursor is over the world (a frame
-    // under the cursor owns its clicks), releases always.
+    // ── Mouse buttons ── presses only with the cursor over the world (a frame owns its clicks),
+    // releases always.
     for b in [
         MouseButton::Left,
         MouseButton::Right,
@@ -723,21 +591,13 @@ fn latch_and_dispatch(
         }
     }
 
-    // ── Wheel ── **a notch is a press AND its release, back to back.** The reference builds one
-    // chord and hands it to `CBindings::ExecuteBinding` twice — `isDown=1` at `0x483d6f`, then
-    // `isDown=0` at `0x483d82` — so a `runOnUp` command
-    // runs both halves in the same frame and a plain one runs its single half (the up leg is the
-    // `RunCommand 0x4b7b50` no-op: `UP + !runOnUp` returns without running anything). Before this
-    // the notch was a press with no release, which quietly made every press+release command a
-    // dead wheel binding. Over UI the wheel belongs to the hovered frame.
-    // Trackpads report pixel deltas — normalized to line-equivalents ([`wheel_lines`]) so the
-    // zoom consumer's feel is unchanged from when it read the scroll itself.
+    // ── Wheel ── a notch is a press and its release, back to back: the reference hands one chord
+    // to `CBindings::ExecuteBinding` with `isDown=1` (`0x483d6f`) then `isDown=0` (`0x483d82`).
+    // A `runOnUp` command runs both halves in the frame; a plain one's up leg is the
+    // `RunCommand` (`0x4b7b50`) no-op.
     let wheel = wheel_lines(scroll.unit, scroll.delta.y);
-    // **Over CHROME**, not over any UI at all: the wheel still zooms with the cursor on a
-    // nameplate, which is a mouse-enabled widget and not a panel (`PointerOverUiPanel`). Plates sit
-    // over exactly the things you look at, so the raw flag silently killed scroll-zoom wherever one
-    // happened to be — a regression of the day the plate became a widget (2148), found in the
-    // 2168 audit.
+    // Over chrome only (`PointerOverUiPanel`): the wheel still zooms with the cursor on a
+    // nameplate, a mouse-enabled widget but not a panel.
     if wheel != 0.0 && !armed && !sup && !over_ui.0 {
         let (key, amount) = if wheel > 0.0 {
             (BindKey::WheelUp, wheel)
@@ -751,19 +611,15 @@ fn latch_and_dispatch(
             key,
         };
         match dispatch.resolve(chord, false) {
-            // A host command is the one thing the press/release pair cannot carry: its input is
-            // the notch's ANALOG MAGNITUDE (the camera zoom's), where [`press`] can only spend
-            // the reference's 1.0 key step. It has no release half either way.
+            // A host command takes the notch's analog magnitude (the camera zoom), which `press`
+            // cannot carry: it spends the 1.0 key step. It has no release half.
             Some(Bound::Spec(cmd)) if matches!(SPECS[cmd.0 as usize].kind, Kind::Host) => {
                 state.fired.push(cmd);
                 state.amounts.push((cmd, amount));
             }
-            // Everything else is the reference's own pair. `Kind::Edge` runs its one body and
-            // has nothing to release; `Kind::EdgeUpDown` runs BOTH halves now (a wheel-bound
-            // action button presses and releases in the notch, which is what makes it cast); an
-            // addon's `runOnUp` body runs twice, `keystate` "down" then "up". `Kind::Held`
-            // latches and unlatches before any consumer can observe it — which is the
-            // reference's behaviour too, its movement bit being set and cleared in the one tick.
+            // Everything else is the reference's pair: `Kind::EdgeUpDown` runs both halves (a
+            // wheel-bound action button casts), an addon's `runOnUp` body runs down then up, and
+            // `Kind::Held` sets and clears in the one tick, as the reference's movement bit does.
             Some(bound) => {
                 press(&mut state, &mut script, run_lua, &dispatch, bound, key);
                 release(&mut state, &mut script, run_lua, &dispatch, key);
@@ -772,14 +628,12 @@ fn latch_and_dispatch(
         }
     }
 
-    // ── The stuck-latch sweep ── a release the window never saw: any latch whose base key reads
-    // up in the input state unlatches now, firing its up-half so a pushed action button unsticks
-    // visibly. This is also where the reference's two real bulk clears land, because bevy already
-    // zeroes `ButtonInput` for both: **OS window deactivate** (`KeyboardFocusLost` →
-    // `release_all` — `0x514490`'s `and eax,0xfffff00f`, the direction bits released while
-    // autorun survives) and the loading cover (`loading_screen::input`'s `swallow` — the
-    // world-enter cascade's `0x5144c0`, which clears everything). Nothing about the UI's own
-    // keyboard focus reaches here, and that is the point (2196).
+    // ── The stuck-latch sweep ── a release the window never saw: a latch whose base key reads up
+    // unlatches now and fires its up-half. The reference's two bulk clears land here, since bevy
+    // zeroes `ButtonInput` for both: OS window deactivate (`0x514490`'s `and eax,0xfffff00f`, the
+    // direction bits released while autorun survives) and the loading cover
+    // (`loading_screen::input`'s `swallow`, the world-enter `0x5144c0`, which clears everything).
+    // UI keyboard focus never reaches here.
     let mut stuck: Vec<BindKey> = Vec::new();
     for &(k, _) in &state.latched {
         if !physically_down(k, &keys, &buttons) && !stuck.contains(&k) {
@@ -793,9 +647,7 @@ fn latch_and_dispatch(
 
 #[cfg(test)]
 impl BindingDispatch {
-    /// A dispatch seeded straight from the registry defaults — the no-VM test seam. No addon
-    /// bindings: an addon body is Lua, and a harness with no VM could only assert it vacuously
-    /// (the with-VM harness below is where those live).
+    /// A dispatch seeded from the registry defaults, the no-VM test seam; no addon bindings.
     fn test_defaults() -> Self {
         let mut map = std::collections::HashMap::new();
         for (i, s) in SPECS.iter().enumerate() {
@@ -814,15 +666,9 @@ impl BindingDispatch {
     }
 }
 
-/// Is this base key physically down right now, per bevy's own button planes?
-///
-/// The one place that question is answered, because two callers ask it for two reasons and an
-/// answer that drifted between them would be a stuck latch on one side or a lost repeat on the
-/// other: the [stuck-latch sweep](latch_and_dispatch) (a release the window never saw) and the
-/// pressed-key reconcile beside it ([`BindingsState::down`]).
-///
-/// `ENTER` is the case that needs saying: [`chord::normalize_key`] folds `NUMPADENTER` into it, so
-/// the normalized key is down while *either* physical key is.
+/// Is this base key physically down, per bevy's button planes? The stuck-latch sweep and the
+/// pressed-key reconcile must agree, so both ask here. `ENTER` is down while either physical
+/// key is, since [`chord::normalize_key`] folds `NUMPADENTER` into it.
 fn physically_down(
     key: BindKey,
     keys: &ButtonInput<KeyCode>,
@@ -839,7 +685,7 @@ fn physically_down(
     }
 }
 
-/// One matching press: latch the held kinds, run/fire by class.
+/// One matching press: latch the held kinds, run or fire by kind.
 fn press(
     state: &mut BindingsState,
     script: &mut Option<NonSendMut<UiScript>>,
@@ -850,9 +696,8 @@ fn press(
 ) {
     let cmd = match bound {
         Bound::Spec(cmd) => cmd,
-        // An addon's press: run its one body with `keystate = "down"`, and latch it only if it
-        // asked for the release half — the `Kind::Edge` / `Kind::EdgeUpDown` fork, decided by the
-        // file's `runOnUp` instead of by our own registry.
+        // Run the body with `keystate = "down"`; latch only if its `runOnUp` asks for the
+        // release half.
         Bound::Addon(i) => {
             if let Some(a) = dispatch.addons.get(i as usize) {
                 run_addon(script, a, "down");
@@ -886,8 +731,8 @@ fn press(
     }
 }
 
-/// A base key's release: drop its latch; a runOnUp pair fires its up-half (delivered even while
-/// typing — the reference completes a pressed binding's release regardless of focus).
+/// A base key's release: drop its latch and fire a `runOnUp` up-half, even while typing (the
+/// reference completes a pressed binding's release regardless of focus).
 fn release(
     state: &mut BindingsState,
     script: &mut Option<NonSendMut<UiScript>>,
@@ -904,8 +749,7 @@ fn release(
                         run_lua(script, up, SPECS[cmd.0 as usize].name);
                     }
                 }
-                // The same body again, this time with `keystate = "up"` — the one law that makes
-                // an addon's `runOnUp` binding one chunk instead of two.
+                // The same body again, with `keystate = "up"`.
                 Bound::Addon(a) => {
                     if let Some(a) = dispatch.addons.get(a as usize) {
                         run_addon(script, a, "up");
@@ -918,30 +762,17 @@ fn release(
     }
 }
 
-/// Run one addon binding's body with the reference's `keystate` global set **for the duration of
-/// the call, and restored after**.
+/// Run one addon binding's body with the `keystate` global set for the call and restored after.
 ///
-/// A `Bindings.xml` body is **one Lua chunk read twice**: `runOnUp="true"` means it runs on the
-/// press and again on the release, and every shipped body forks on the bare global `keystate`
-/// (`if ( keystate == "down" ) then MoveForwardStart(); else MoveForwardStop(); end`). So the
-/// global is set in `_G` where the chunk will look for it — not prepended to the source, which
-/// would shift every line number in the addon's own error messages.
-///
-/// **Restoring it is not tidiness.** `keystate` is absent from the 1.12.1 client's in-world `_G`
-/// (`reference/1.12-globals.tsv`) even though its own `Bindings.xml` bodies read it as a bare
-/// global — which is only possible if the reference sets it transiently around the call, exactly
-/// as it does `this`/`event`/`arg1` (`invoke_with_globals`; `0x703f50` → `0x704f10`). Leaving it
-/// set would hand every addon a global the reference does not have, and an addon that
-/// feature-detects it would take a path we cannot honour — decision 1189's
-/// "a superset is not free", one call deeper.
-///
-/// Save-and-restore rather than set-and-delete, because these bodies nest: a binding whose Lua
-/// fires another binding must not clear the outer one's `keystate` on the way out.
+/// A `runOnUp` body is one chunk run on press and release, forking on the bare global `keystate`
+/// (`Bindings.xml:4`); it is set in `_G`, not prepended, so the addon's line numbers hold.
+/// `keystate` is absent from the 1.12 client's in-world `_G` (`reference/1.12-globals.tsv`), so
+/// the reference sets it transiently, as it does `this`/`arg1` (`0x703f50` → `0x704f10`).
+/// Save-and-restore because bodies nest: an inner binding must not clear the outer `keystate`.
 fn run_addon(script: &mut Option<NonSendMut<UiScript>>, bind: &AddonBindingBody, keystate: &str) {
     let Some(s) = script.as_mut() else { return };
     let globals = s.lua().globals();
-    // `Option<String>` rather than a raw Lua value: benilla-app does not depend on mlua, and
-    // `keystate` is a string or nothing — `None` converts back to nil on the way out.
+    // `Option<String>`, since benilla-app does not depend on mlua; `None` converts back to nil.
     let prior: Option<String> = globals.get("keystate").unwrap_or(None);
     if let Err(e) = globals.set("keystate", keystate) {
         warn!("bindings({}): setting keystate: {e}", bind.name);
@@ -962,10 +793,8 @@ mod tests {
 
     use super::*;
 
-    /// A minimal app around [`latch_and_dispatch`] with the registry defaults and NO VM — the
-    /// keyboard/mouse laws end-to-end from real input events, exactly the way winit feeds them
-    /// (InputPlugin turns the events into `ButtonInput`/`AccumulatedMouseScroll` in PreUpdate;
-    /// the dispatch runs in Update).
+    /// A minimal app around [`latch_and_dispatch`] with the registry defaults and no VM, fed real
+    /// input events through `InputPlugin` as winit feeds them.
     fn harness() -> App {
         let mut app = App::new();
         app.add_plugins((MinimalPlugins, bevy::input::InputPlugin))
@@ -994,8 +823,7 @@ mod tests {
     fn release_key(app: &mut App, k: KeyCode) {
         key(app, k, bevy::input::ButtonState::Released, false);
     }
-    /// A press the OS has flagged as auto-repeat. Whether it *acts* as one is ours to decide
-    /// (2204), which is the whole point of the tests that use this.
+    /// A press the OS has flagged as auto-repeat; whether it acts as one is ours to decide.
     fn repeat_key(app: &mut App, k: KeyCode) {
         key(app, k, bevy::input::ButtonState::Pressed, true);
     }
@@ -1003,16 +831,14 @@ mod tests {
         app.world().resource::<BindingsState>()
     }
 
-    /// What a keyboard FRAME ate this frame — the list `feed_ui_input` rewrites every pass, which
-    /// this harness has no copy of, so it is **set** rather than pushed (an accumulating list would
-    /// keep suppressing a key the frame stopped eating rounds ago).
+    /// What a keyboard frame ate this frame. Set, not pushed: `feed_ui_input` rewrites the list
+    /// every pass.
     fn frame_ate(app: &mut App, keys: &[KeyCode]) {
         app.world_mut().resource_mut::<UiKeyboardCapture>().consumed = keys.to_vec();
     }
 
-    /// One addon's `Bindings.xml`, in the reference's own shape: a `runOnUp` binding whose single
-    /// body forks on `keystate`, and a one-shot beside it. Each half counts itself in a global, so
-    /// the assertions below read what the VM actually ran rather than what we told it to run.
+    /// One addon's `Bindings.xml` in the reference's shape: a `runOnUp` binding forking on
+    /// `keystate`, and a one-shot. Each half counts itself in a global.
     const PROBE_BINDINGS: &str = r#"<Bindings>
         <Binding name="PROBEHOLD" runOnUp="true" header="PROBE">
             if ( keystate == "down" ) then
@@ -1027,12 +853,8 @@ mod tests {
         </Binding>
     </Bindings>"#;
 
-    /// The **with-VM** harness: a real engine table (the whole registry plus one addon's parsed
-    /// `Bindings.xml`) with the real [`sync_dispatch`] chained in front of [`latch_and_dispatch`].
-    ///
-    /// Deliberately not [`BindingDispatch::test_defaults`]: the bug 1188 phase 4 removes lived in
-    /// the *derivation* — `sync_dispatch` dropped every name it could not find in `SPECS`, so a
-    /// hand-built map would assert past exactly the code that was wrong.
+    /// The with-VM harness: a real engine table with the real [`sync_dispatch`] chained before
+    /// [`latch_and_dispatch`], so the map's derivation is under test too.
     fn vm_harness(script: UiScript) -> App {
         let mut app = App::new();
         app.add_plugins((MinimalPlugins, bevy::input::InputPlugin))
@@ -1046,7 +868,7 @@ mod tests {
         app
     }
 
-    /// A counter a binding body left in the VM — `0` when the body never ran.
+    /// A counter a binding body left in the VM; `0` when the body never ran.
     fn lua_count(app: &App, global: &str) -> i64 {
         app.world()
             .non_send_resource::<UiScript>()
@@ -1054,7 +876,7 @@ mod tests {
             .expect("eval")
     }
 
-    /// A string a binding body left in the VM — `""` when it never ran.
+    /// A string a binding body left in the VM; `""` when it never ran.
     fn lua_str(app: &App, global: &str) -> String {
         app.world()
             .non_send_resource::<UiScript>()
@@ -1062,17 +884,8 @@ mod tests {
             .expect("eval")
     }
 
-    /// **An addon's binding actually fires** (decision 1188 phase 4) — the assertion the whole
-    /// phase exists for. Before it, an addon's `Bindings.xml` registered, listed in the Key
-    /// Bindings window, saved and loaded, and then did *nothing*: `sync_dispatch` silently dropped
-    /// every name that was not in [`SPECS`], so no chord ever reached the body.
-    ///
-    /// The `runOnUp` half is the part that cannot be guessed from the built-in path, because it is
-    /// shaped differently: our own registry holds two Lua strings ([`Kind::EdgeUpDown`]), an
-    /// addon holds **one chunk run twice** with the global `keystate` set to `"down"` then
-    /// `"up"`. A dispatch that ran the body once, or twice with the same `keystate`, leaves the
-    /// player's key held down forever — which is what every shipped `runOnUp` body's `else` branch
-    /// is there to prevent.
+    /// An addon's `runOnUp` body is one chunk run twice, `keystate` "down" then "up"; our own
+    /// registry holds two strings ([`Kind::EdgeUpDown`]) instead.
     #[test]
     fn an_addon_binding_fires_its_lua_and_runs_again_on_release_when_it_asked_to() {
         let mut script = UiScript::new().expect("VM");
@@ -1081,9 +894,7 @@ mod tests {
             "ProbeAddon",
             &benilla_ui::bindings_xml::parse(PROBE_BINDINGS).expect("well-formed"),
         );
-        // A `<Binding>` ships no default chord in 1.12 — the shipped defaults live in the engine's
-        // own table — so an addon binding starts unbound and the player binds it, which is what
-        // the Key Bindings window does through exactly this call.
+        // A 1.12 `<Binding>` ships no default chord, so an addon binding starts unbound.
         script
             .run(r#"SetBinding("J", "PROBEHOLD"); SetBinding("G", "PROBEEDGE")"#)
             .expect("bind");
@@ -1115,8 +926,7 @@ mod tests {
             "the release runs the chunk with keystate=up, not the down half a second time"
         );
 
-        // The one-shot binding: press runs it, release does not — the `Kind::Edge` behaviour,
-        // decided here by the file's missing `runOnUp` rather than by our registry.
+        // The one-shot binding (no `runOnUp`): press runs it, release does not.
         press_key(&mut app, KeyCode::KeyG);
         app.update();
         assert_eq!(lua_count(&app, "PROBE_EDGE"), 1);
@@ -1128,7 +938,7 @@ mod tests {
             "no runOnUp, no second run — an addon that toggled here would toggle back"
         );
 
-        // And the registry dispatches unchanged beside them: the enum routes, it does not divert.
+        // The registry dispatches unchanged beside them.
         press_key(&mut app, KeyCode::KeyW);
         app.update();
         assert!(state(&app).pressed(cmd::MOVE_FORWARD));
@@ -1138,11 +948,8 @@ mod tests {
             "a built-in press is nobody else's"
         );
 
-        // **`keystate` does not outlive the call.** It is absent from the 1.12.1 client's in-world
-        // `_G` (`reference/1.12-globals.tsv`) even though its own binding bodies read it, so the
-        // reference sets it transiently — as it does `this`/`arg1`. Leaving it set would hand
-        // every addon a global the reference lacks, and one that feature-detects `if keystate`
-        // would take a branch we cannot honour (decision 1189's "a superset is not free").
+        // `keystate` does not outlive the call: the 1.12 client's in-world `_G` has none
+        // (`reference/1.12-globals.tsv`).
         assert_eq!(
             lua_str(&app, "tostring(keystate)"),
             "nil",
@@ -1150,18 +957,10 @@ mod tests {
         );
     }
 
-    /// **The alt-arrow exemption: you can turn while the chat box has focus.**
-    ///
-    /// A focused EditBox swallows every key — that is the reference's own handler returning 1 on
-    /// every path (`0x77b35e`) and our `UiKeyboardCapture::typing` gate. The four arrow codes are
-    /// the single exception: with the box in alt-arrow mode (`ignoreArrows` in XML,
-    /// `SetAltArrowKeyMode` in Lua) and ALT not held, the handler returns 0 at `0x77b1c4`, the
-    /// strata walk carries the key down to `CGWorldFrame`, and `ExecuteBinding` runs `TURNLEFT`.
-    /// The reference's own chat box ships the flag, so this is the default experience.
-    ///
-    /// benilla read the flag as "consumed but inert, unless Ctrl" until the bytes corrected both
-    /// halves — the modifier is ALT, and the key is not consumed at all. Under the old reading,
-    /// holding LEFT with the chat box open did nothing whatever.
+    /// A focused EditBox swallows every key (the reference's handler returns 1 on every path,
+    /// `0x77b35e`), except that in alt-arrow mode (`ignoreArrows`, `SetAltArrowKeyMode`) with ALT
+    /// up it returns 0 for the four arrows (`0x77b1c4`) and their bindings run. The stock chat box
+    /// ships the flag.
     #[test]
     fn a_flagged_editbox_lets_the_arrow_keys_through_to_their_bindings() {
         let mut app = harness();
@@ -1188,7 +987,7 @@ mod tests {
             "a flagged box declines the arrow, so TURNLEFT runs"
         );
 
-        // And the exemption is FOUR KEYS, not a hole in the typing gate: W is still swallowed.
+        // The exemption is four keys, not a hole in the typing gate: W is still swallowed.
         press_key(&mut app, KeyCode::KeyW);
         app.update();
         assert!(
@@ -1197,14 +996,8 @@ mod tests {
         );
     }
 
-    /// **Nothing a box taking focus does releases what is already held** (2196), and a `runOnUp`
-    /// addon latch still delivers its up-half when the key finally goes up.
-    ///
-    /// The reference's focused box turns the movement handlers into no-ops — the direction bits are
-    /// frozen, not cleared — so a held binding of ANY kind rides the focus change out. This test
-    /// used to assert the opposite for [`Kind::Held`] (`assert!(!pressed(MOVE_FORWARD))`), on the
-    /// misreading of `0x514490` as a chat-focus handler that 2196 corrects: its sole caller hangs
-    /// off the WM_ACTIVATE slot, so it is the OS window-deactivate clear.
+    /// A box taking focus releases nothing already held: the reference's focused box freezes the
+    /// direction bits rather than clearing them (`0x514490` is the OS window-deactivate clear).
     #[test]
     fn a_held_latch_rides_out_a_box_taking_focus_and_still_releases() {
         let mut script = UiScript::new().expect("VM");
@@ -1222,8 +1015,7 @@ mod tests {
         assert!(state(&app).pressed(cmd::MOVE_FORWARD));
         assert_eq!(lua_count(&app, "PROBE_DOWN"), 1);
 
-        // A box takes focus. Both latches ride it out: the reference freezes the direction bits,
-        // it does not clear them.
+        // A box takes focus; both latches ride it out.
         app.world_mut().resource_mut::<UiKeyboardCapture>().typing = true;
         app.update();
         assert!(
@@ -1236,7 +1028,7 @@ mod tests {
             "the focus edge is not a release — nothing has run the up half yet"
         );
 
-        // And the keys still stop when the player lets go, box focused or not.
+        // The keys still stop when the player lets go, box focused or not.
         release_key(&mut app, KeyCode::KeyW);
         release_key(&mut app, KeyCode::KeyJ);
         app.update();
@@ -1251,10 +1043,7 @@ mod tests {
         );
     }
 
-    /// **The armed capture seam, driven by real input events** (B265). The page's own tests call
-    /// `KeyBindings_OnHostKey` directly, so nothing asserted that a real notch/press ever
-    /// produces that call — and the wheel is the one input that reaches this branch through
-    /// neither `KeyboardInput` nor `MouseButtonInput`.
+    /// The armed capture seam, driven by a real wheel event.
     #[test]
     fn an_armed_capture_takes_a_wheel_notch() {
         let mut script = UiScript::new().expect("VM");
@@ -1285,7 +1074,7 @@ mod tests {
             "the armed seam swallows the notch — it must not also zoom"
         );
 
-        // Down, and a modified notch: the canonical prefix order rides the same path.
+        // Down, and a modified notch.
         app.world_mut().write_message(MouseWheel {
             unit: MouseScrollUnit::Line,
             x: 0.0,
@@ -1305,10 +1094,8 @@ mod tests {
         assert_eq!(lua_str(&app, "tostring(CAPTURED)"), "SHIFT-MOUSEWHEELUP");
     }
 
-    /// **The whole wheel-bind path in one harness** (B265): the real Keybindings page, a capsule
-    /// armed by a real click, a real notch fed the way winit feeds it, and then the bound chord
-    /// dispatching. The page's own tests call `KeyBindings_OnHostKey` by hand and this module's
-    /// tests carry no page — between them the join was never asserted.
+    /// The whole wheel-bind path: the real Keybindings page, a capsule armed by a click, a real
+    /// notch, then the bound chord dispatching.
     #[test]
     fn a_wheel_notch_binds_through_the_real_page_and_then_dispatches() {
         benilla_formats::wow_data_or_skip!();
@@ -1317,8 +1104,8 @@ mod tests {
         let mut s = crate::ui_script::keybindings_tests::harness();
         crate::ui_script::keybindings_tests::on_page(&mut s);
         const ROW: &str = "BenillaOptionsFrameContainerBodyKeybindingsRow";
-        // Expand Movement and arm JUMP's first capsule — JUMP is the classic wheel bind, and one
-        // of the 1.12 commands that is NOT `runOnUp`, so the reference accepts the wheel on it.
+        // Expand Movement and arm JUMP's first capsule: JUMP is not `runOnUp`, so the reference
+        // accepts the wheel on it.
         s.run(&format!("{ROW}1Header:Click()")).expect("expand");
         s.run(&format!("{ROW}9Key1Button:Click()")).expect("select");
         assert_eq!(
@@ -1347,7 +1134,7 @@ mod tests {
             assert!(!s.bind_capture_armed(), "the completed bind disarms");
         }
 
-        // …and the bound chord now dispatches: the next notch jumps rather than binding.
+        // The bound chord now dispatches: the next notch jumps rather than binding.
         app.world_mut().write_message(MouseWheel {
             unit: MouseScrollUnit::Line,
             x: 0.0,
@@ -1362,13 +1149,9 @@ mod tests {
         );
     }
 
-    /// **A notch is a press AND its release** — the reference dispatches the one chord twice,
-    /// `isDown=1` then `isDown=0` (`0x483d6f` / `0x483d82`). So a `runOnUp` binding on the wheel
-    /// runs both halves in the same frame; before this it ran neither, and the binding was dead.
-    ///
-    /// Seeded through the stored set rather than `SetBinding`, because the table refuses to put a
-    /// wheel chord on a press+release command — this is the "hand-edited file smuggles one in"
-    /// case, which is exactly the state the old arm silently dropped on the floor.
+    /// A notch is a press and its release (`0x483d6f`, `0x483d82`), so a `runOnUp` binding on the
+    /// wheel runs both halves in one frame. Seeded through the stored set, since `SetBinding`
+    /// refuses a wheel chord on a press-and-release command: the hand-edited file case.
     #[test]
     fn a_wheel_notch_runs_both_halves_of_a_press_and_release_binding() {
         let mut script = UiScript::new().expect("VM");
@@ -1401,24 +1184,16 @@ mod tests {
             "…and its release half, in the same frame — a notch has no key left to lift"
         );
         assert_eq!(lua_str(&app, "PROBE_LAST"), "up");
-        // Nothing is left latched: a wheel latch that outlived its notch would hold the down
-        // state forever, with no key to press to end it.
+        // Nothing is left latched: no key could end a wheel latch.
         assert!(app.world().resource::<BindingsState>().latched.is_empty());
     }
 
-    /// **Auto-repeat is classified off OUR pressed-key set, not the OS bit** (2204), and the
-    /// window-deactivate wipe is what makes a held key resume on the way back.
-    ///
-    /// Three laws in one run, because they are one mechanism:
-    ///
-    /// 1. a repeat of a key we already believe is down does NOT re-run its binding — the
-    ///    reference's own test (`0x4248b3`), which matters for the kinds that never latch (a held
-    ///    SPACE must jump once, not every 33 ms);
-    /// 2. a press carrying `repeat: true` that we do NOT have down is a fresh DOWN. The OS bit is
-    ///    not the authority — the reference reads its own list and never the Win32 `lParam` bit;
-    /// 3. so after a window deactivate — bevy's `KeyboardFocusLost` → `release_all`, which is our
-    ///    `0x514490`+`0x424790` pair — the first repeat of a key still physically held re-latches,
-    ///    and **you start running again without lifting the key**, as the reference does.
+    /// Auto-repeat is classified off our pressed-key set, as the reference's (`0x4248b3`), not the
+    /// OS bit:
+    /// 1. a repeat of a key we have down does not re-run its binding (a held SPACE jumps once);
+    /// 2. a flagged repeat of a key we do not have down is a fresh press;
+    /// 3. so after a window deactivate (`0x514490` and `0x424790`), the first repeat of a key
+    ///    still held re-latches, and running resumes without lifting the key.
     #[test]
     fn a_repeat_is_a_key_we_already_have_down_so_a_held_key_resumes_after_an_alt_tab() {
         let mut app = harness();
@@ -1426,8 +1201,7 @@ mod tests {
         app.update();
         assert!(state(&app).fired(cmd::JUMP), "the first press jumps");
 
-        // (1) A repeat of a key we have down fires nothing — JUMP never latches, so the
-        // pressed-key set is the only thing standing between a held SPACE and a jump per frame.
+        // (1) JUMP never latches, so only the pressed-key set stops a jump per repeat.
         repeat_key(&mut app, KeyCode::Space);
         app.update();
         assert!(
@@ -1440,8 +1214,8 @@ mod tests {
         app.update();
         assert!(state(&app).pressed(cmd::MOVE_FORWARD));
 
-        // (3) The window is deactivated. Bevy empties the keyboard plane, which unlatches through
-        // the stuck-latch sweep AND empties our pressed-key set — the reference's two wipes.
+        // (3) The window is deactivated: bevy empties the keyboard plane, which unlatches through
+        // the stuck-latch sweep and empties our pressed-key set.
         app.world_mut()
             .resource_mut::<ButtonInput<KeyCode>>()
             .release_all();
@@ -1451,8 +1225,8 @@ mod tests {
             "the deactivate releases the direction bits (0x514490)"
         );
 
-        // (2)+(3) Back in the window, still holding W. The OS calls this a repeat; we do not have
-        // the key down any more, so it is a fresh press — and you run again without lifting it.
+        // (2) and (3): back in the window, still holding W. The OS calls this a repeat; we do not
+        // have the key down, so it is a fresh press.
         repeat_key(&mut app, KeyCode::KeyW);
         app.update();
         assert!(
@@ -1464,7 +1238,7 @@ mod tests {
     #[test]
     fn held_commands_latch_across_frames_and_release_per_base_key() {
         let mut app = harness();
-        // W and UP are both MOVEFORWARD: press both, release one — still moving.
+        // W and UP are both MOVEFORWARD: press both, release one, still moving.
         press_key(&mut app, KeyCode::KeyW);
         app.update();
         assert!(state(&app).pressed(cmd::MOVE_FORWARD));
@@ -1496,13 +1270,12 @@ mod tests {
         assert!(!state(&app).just_pressed(cmd::MOVE_FORWARD));
     }
 
-    /// **The two-probe lookup, table-wide** (decision 1142): the exact chord, then one retry with
-    /// the leftmost modifier dropped, and never a third. The bug that bought this test was a
-    /// modifier held over a movement key eating the movement — so the movement case leads.
+    /// The two-probe lookup: the exact chord, then one retry with the leftmost modifier dropped,
+    /// never a third.
     #[test]
     fn a_press_probes_its_chord_then_falls_back_once() {
-        // The reported bug: Shift held, W pressed. `SHIFT-W` is nobody's, so the retry drops
-        // SHIFT and MOVEFORWARD latches — the reference's `strchr` step, `0x4b7990`.
+        // Shift held, W pressed: `SHIFT-W` is unbound, so the retry drops SHIFT and MOVEFORWARD
+        // latches (the reference's `strchr` step, `0x4b7990`).
         let mut app = harness();
         press_key(&mut app, KeyCode::ShiftLeft);
         press_key(&mut app, KeyCode::KeyW);
@@ -1511,14 +1284,13 @@ mod tests {
             state(&app).pressed(cmd::MOVE_FORWARD),
             "SHIFT-W falls back to W — the whole point of 1142"
         );
-        // And it unlatches on the base key with the modifier still down (the reference replays
-        // the press-time chord at key-up, `0x483bd0`; we latch the resolved command instead —
-        // same observable).
+        // It unlatches on the base key with the modifier still down (the reference replays the
+        // press-time chord at key-up, `0x483bd0`; latching the resolved command is equivalent).
         release_key(&mut app, KeyCode::KeyW);
         app.update();
         assert!(!state(&app).pressed(cmd::MOVE_FORWARD));
-        // Bare Z is the sheath toggle; ALT-Z is TOGGLEUI. The exact probe runs first, so the
-        // specific chord wins outright — a fallback never overrides a real entry.
+        // Bare Z is the sheath toggle, ALT-Z is TOGGLEUI: the exact probe runs first, so a
+        // fallback never overrides a real entry.
         let mut app = harness();
         press_key(&mut app, KeyCode::KeyZ);
         app.update();
@@ -1533,9 +1305,8 @@ mod tests {
             "ALT-Z is TOGGLEUI (0870)"
         );
         assert!(!state(&app).fired(cmd::TOGGLE_SHEATH));
-        // CTRL-ALT-Z still fires nothing — but for the real reason, not 0585's. The single strip
-        // drops the LEFTMOST modifier (`ALT-CTRL-Z` → `CTRL-Z`, unbound) and stops: it never
-        // reaches ALT-Z, and never reaches bare Z. This is the assertion that pins "one retry".
+        // CTRL-ALT-Z fires nothing: the single strip drops the leftmost modifier (`ALT-CTRL-Z`
+        // to `CTRL-Z`, unbound) and stops, never reaching ALT-Z or Z.
         release_key(&mut app, KeyCode::KeyZ);
         press_key(&mut app, KeyCode::ControlLeft);
         press_key(&mut app, KeyCode::KeyZ);
@@ -1544,7 +1315,7 @@ mod tests {
             !state(&app).fired(cmd::TOGGLE_UI) && !state(&app).fired(cmd::TOGGLE_SHEATH),
             "ALT-CTRL-Z probes CTRL-Z and stops — no second strip to ALT-Z or Z"
         );
-        // TAB vs SHIFT-TAB: both bound, so both resolve exactly and neither borrows the other.
+        // TAB and SHIFT-TAB are both bound, so each resolves exactly.
         let mut app = harness();
         press_key(&mut app, KeyCode::Tab);
         app.update();
@@ -1555,8 +1326,7 @@ mod tests {
         app.update();
         assert!(state(&app).fired(cmd::TARGET_PREVIOUS_ENEMY));
         assert!(!state(&app).fired(cmd::TARGET_NEAREST_ENEMY));
-        // Super/Cmd is never a binding modifier: a super-held press builds no chord at all, so it
-        // has no fallback either.
+        // Super is never a binding modifier: a Super-held press builds no chord, so no fallback.
         let mut app = harness();
         press_key(&mut app, KeyCode::SuperLeft);
         press_key(&mut app, KeyCode::KeyZ);
@@ -1564,41 +1334,33 @@ mod tests {
         assert!(!state(&app).fired(cmd::TOGGLE_SHEATH));
     }
 
-    /// **The dev plane spends the keyboard's fallback probe, and nothing else** (1142). 0870 chose
-    /// `Ctrl`+`Shift` for the overlays because the plane looked empty under 0585's exact-match
-    /// law; under the real law it is *nearly* empty — the single strip lands on `SHIFT-`*key*, not
-    /// the bare letter — and `SHIFT-P` is exactly the entry that makes "nearly" insufficient.
-    ///
-    /// Asserted on [`BindingDispatch::resolve`] rather than through the event harness because the
-    /// colliding command is `Kind::Edge` — its whole effect is a Lua body, and the harness has no
-    /// VM, so an end-to-end assertion here could only ever be vacuously true.
+    /// The dev plane spends the keyboard's fallback probe and nothing else. Asserted on
+    /// [`BindingDispatch::resolve`] because the colliding command is `Kind::Edge`, which the no-VM
+    /// harness cannot observe.
     #[test]
     fn the_dev_plane_keeps_its_letters_without_stealing_bound_chords() {
         let by_name =
             |n: &str| Cmd(SPECS.iter().position(|s| s.name == n).expect("registered") as u16);
-        let pet_paper_doll = by_name("TOGGLECHARACTER3"); // SHIFT-P, decision 1057
+        let pet_paper_doll = by_name("TOGGLECHARACTER3"); // SHIFT-P
         let mut dispatch = BindingDispatch::test_defaults();
         let plane_p = Chord::parse("CTRL-SHIFT-P").expect("parses");
-        // Ctrl+Shift+P is the perf HUD's. Off the plane it would fall back onto SHIFT-P — which
-        // is 0585's original "one key did two things" bug, reborn one strip further along...
+        // Ctrl+Shift+P is the perf HUD's; off the plane it falls back onto SHIFT-P...
         assert_eq!(
             dispatch.resolve(plane_p, false),
             Some(Bound::Spec(pet_paper_doll)),
             "without the plane rule the retry does reach SHIFT-P — this is what is being blocked"
         );
-        // ...so on the plane, the retry is what it costs.
+        // ...so on the plane the retry is suppressed.
         assert_eq!(dispatch.resolve(plane_p, true), None);
-        // The suppression is the FALLBACK only — an exact CTRL-SHIFT- entry still resolves. No
-        // shipped default proves it (1.12's own two, CTRL-SHIFT-TAB and CTRL-SHIFT-PAGEDOWN,
-        // belong to commands the honest tree doesn't carry yet), so the entry is made here: this
-        // is the case a player creates the moment they bind anything on the plane.
+        // Only the fallback is suppressed: an exact CTRL-SHIFT- entry, as a player would bind,
+        // still resolves.
         dispatch.map.insert(plane_p, Bound::Spec(pet_paper_doll));
         assert_eq!(
             dispatch.resolve(plane_p, true),
             Some(Bound::Spec(pet_paper_doll)),
             "the plane spends the retry, never the exact probe"
         );
-        // And SHIFT-P itself is still the pet paper doll: the plane costs nothing outside itself.
+        // SHIFT-P itself is still the pet paper doll.
         let shift_p = Chord::parse("SHIFT-P").expect("parses");
         assert_eq!(
             dispatch.resolve(shift_p, false),
@@ -1606,10 +1368,8 @@ mod tests {
         );
     }
 
-    /// **The pet lane routes on the CTRL digits, and the number row is untouched** (B218,
-    /// decision 1052). The two share their base keys, so the only thing keeping them apart is
-    /// the exact-modifier law — worth pinning on the pair that actually collides rather than
-    /// trusting the law in the abstract. CTRL-0 is slot **10**, the 1.12 cache's own wrap.
+    /// The pet bar routes on the CTRL digits and the number row is untouched: the two share base
+    /// keys, kept apart only by the exact-modifier probe. CTRL-0 is slot 10.
     #[test]
     fn the_pet_lane_dispatches_on_the_ctrl_digits() {
         let by_name =
@@ -1623,12 +1383,12 @@ mod tests {
             !state(&app).pressed(by_name("ACTIONBUTTON1")),
             "the modifier decides: CTRL-1 is not the number row's"
         );
-        // The runOnUp half: the latch drops on the BASE key's release (which is what runs
-        // PetActionButtonUp → CastPetAction in the app's VM), Ctrl still held.
+        // The latch drops on the base key's release with Ctrl still held; in the VM that release
+        // runs `PetActionButtonUp`, which casts.
         release_key(&mut app, KeyCode::Digit1);
         app.update();
         assert!(!state(&app).pressed(by_name("BONUSACTIONBUTTON1")));
-        // CTRL-0 → slot 10.
+        // CTRL-0 is slot 10.
         press_key(&mut app, KeyCode::Digit0);
         app.update();
         assert!(state(&app).pressed(by_name("BONUSACTIONBUTTON10")));
@@ -1640,13 +1400,8 @@ mod tests {
         assert!(!state(&app).pressed(by_name("BONUSACTIONBUTTON1")));
     }
 
-    /// **The typing gate blocks NEW presses and releases nothing already held** (2196).
-    ///
-    /// The two halves used to be one: the gate's rising edge dropped every [`Kind::Held`] latch, so
-    /// holding W and pressing ENTER stopped you dead. It rests on nothing — `0x514490`, the clear
-    /// that reading cited, is the OS window-deactivate handler (sole caller `0x493058`, off the
-    /// WM_ACTIVATE callback slot), and the reference's focused box only makes the movement handlers
-    /// no-ops: the bits are frozen, not cleared.
+    /// The typing gate blocks new presses and releases nothing already held: holding W and
+    /// pressing ENTER keeps you running.
     #[test]
     fn the_typing_gate_blocks_new_input_but_a_held_binding_keeps_running() {
         let mut app = harness();
@@ -1682,15 +1437,9 @@ mod tests {
         assert!(state(&app).fired(cmd::SIT_OR_STAND));
     }
 
-    /// **The world map's shape** (2196, the director's report): a shown keyboard-enabled frame eats
-    /// the key that closes it, and that must cost the key its binding and nothing else.
-    ///
-    /// `WorldMapFrame` is `frameStrata="FULLSCREEN" enableKeyboard="true"` with an `<OnKeyDown>`
-    /// that re-matches `GetBindingKey("TOGGLEWORLDMAP")` in Lua and calls `RunBinding` itself, so
-    /// under the existence gate (decision 1319) it consumes every key while shown — including the
-    /// `M` that closes it. benilla reported that consumption as `typing`, whose rising edge then
-    /// dropped the movement latch: holding W and tapping `M` twice left you standing in a closed
-    /// map. The consumption is per KEY now, and releases nothing.
+    /// A shown keyboard frame eating the key that closes it costs that key its binding and
+    /// nothing else. `WorldMapFrame` is a keyboard-enabled fullscreen frame whose `OnKeyDown`
+    /// runs `RunBinding("TOGGLEWORLDMAP")` itself (`WorldMapFrame.xml:629`), so it eats every key.
     #[test]
     fn a_keyboard_frame_eating_its_own_toggle_key_does_not_stop_a_held_run() {
         let mut app = harness();
@@ -1698,9 +1447,8 @@ mod tests {
         app.update();
         assert!(state(&app).pressed(cmd::MOVE_FORWARD));
 
-        // The map is open and eats this frame's `M` (its own Lua runs the toggle). `M` carries a
-        // `Kind::Edge` binding, which a no-VM harness cannot observe — so the suppression half is
-        // asserted on `X` below, and this leg asserts the half the report is about.
+        // The map eats this frame's `M`. `M` is `Kind::Edge`, invisible to a no-VM harness, so
+        // the suppression is asserted on `X` below.
         frame_ate(&mut app, &[KeyCode::KeyM]);
         press_key(&mut app, KeyCode::KeyM);
         app.update();
@@ -1709,7 +1457,7 @@ mod tests {
             "the frame ate the toggle key; you are still running (2196)"
         );
 
-        // The eaten key loses its binding…
+        // The eaten key loses its binding...
         release_key(&mut app, KeyCode::KeyM);
         app.update();
         frame_ate(&mut app, &[KeyCode::KeyX]);
@@ -1720,7 +1468,7 @@ mod tests {
             "the frame ate this key: its binding must not also fire"
         );
 
-        // …and only that key. The old whole-frame flag suppressed every binding in the frame.
+        // ...and only that key.
         release_key(&mut app, KeyCode::KeyX);
         app.update();
         frame_ate(&mut app, &[KeyCode::KeyM]);
@@ -1803,34 +1551,18 @@ mod tests {
         );
     }
 
-    /// **B opens the backpack, SHIFT-B opens all of them** — the director's report, pinned end to
-    /// end (1494): a real keyboard event, through the chord table and the registry's shipped
-    /// defaults, into the binding body, into the Lua that shows the windows.
-    ///
-    /// This is the seam the bug lived in and nothing else covers it. `bag_tests` drive the Lua
-    /// globals directly, so they could not see that BOTH chords were registered on one command;
-    /// the registry tests read the table, so they could not see what the bodies do. Only pressing
-    /// the key joins the two.
-    ///
-    /// **The windows on the far end are the reference's own now** (1751). `BenillaBagFrame`/
-    /// `BenillaBagFrame2` were five static frames our `BagFrame.xml` declared, so this test could
-    /// name them and load six files by hand; the live windows are `ContainerFrame1..12`, generated
-    /// on demand off the player's chain and RECYCLED across containers, so the question is
-    /// `IsBagOpen(id)` and never a frame name. Two consequences, both deliberate:
-    ///   * the interface is loaded with the app's own [`crate::ui_script::load_default_ui`] rather
-    ///     than a hand-listed six, because the chain half of the manifest is what makes the bag
-    ///     windows exist at all and a private six-file reader cannot express it — which also makes
-    ///     this test the load order the player gets;
-    ///   * it needs client data, like every test that touches a chain entry.
+    /// B opens the backpack and SHIFT-B opens every bag, end to end: a real key event, the shipped
+    /// defaults, the binding body and the stock Lua. The windows are the stock
+    /// `ContainerFrame1..12`, recycled across containers, so the test asks `IsBagOpen(id)`; the
+    /// interface loads through [`crate::ui_script::load_default_ui`], so it needs client data.
     #[test]
     fn b_opens_the_backpack_and_shift_b_opens_every_bag() {
         let _data = benilla_formats::wow_data_or_skip!();
         let mut script = UiScript::new().expect("VM");
         script.register_bindings(&registry_commands());
         script.set_screen_size(1024.0, 768.0);
-        // The in-game UI materializes on world entry (1051), so a player always exists by the time
-        // the manifest loads — and the stock macro window's character tab formats
-        // `UnitName("player")` into its label in its own OnLoad (decision 1848).
+        // A player exists by the time the in-game UI loads, and the stock macro window formats
+        // `UnitName("player")` into its character tab in OnLoad.
         script.set_unit(
             "player",
             Some(benilla_ui::script::UnitState {
@@ -1846,10 +1578,8 @@ mod tests {
             "default UI failed to load: {failures:?}"
         );
         script.set_money(0);
-        // The backpack, plus one equipped bag in slot 2 — so "all bags" is two windows and
-        // "the backpack alone" is visibly different from it. Fed BEFORE any key: the reference
-        // builds a window only for a container that exists (`OpenBag`'s `size > 0` gate), where
-        // our own `BenillaBagFrame*` were static frames that showed regardless.
+        // The backpack plus one bag in slot 2, fed before any key: stock `OpenBag` builds a
+        // window only for a container with `size > 0`.
         script.set_container(
             0,
             Some(benilla_ui::script::ContainerState {
@@ -1867,8 +1597,7 @@ mod tests {
             }),
         );
         let mut app = vm_harness(script);
-        // `IsBagOpen(id)` — the reference's own scan over `ContainerFrame1..12`, and the only
-        // honest way to ask: which window a bag lands in depends on what else is open.
+        // `IsBagOpen(id)` scans `ContainerFrame1..12`: which window a bag lands in varies.
         let open = |app: &App, id: i64| {
             app.world()
                 .non_send_resource::<UiScript>()
@@ -1876,7 +1605,7 @@ mod tests {
                 .expect("eval")
         };
 
-        // B — TOGGLEBACKPACK's shipped default. The backpack, and nothing else.
+        // B, TOGGLEBACKPACK's default: the backpack and nothing else.
         press_key(&mut app, KeyCode::KeyB);
         app.update();
         release_key(&mut app, KeyCode::KeyB);
@@ -1894,7 +1623,7 @@ mod tests {
         app.update();
         assert!(!open(&app, 0), "B again shuts it");
 
-        // SHIFT-B — OPENALLBAGS' shipped default, a DIFFERENT command with a different body.
+        // SHIFT-B, OPENALLBAGS' default: a different command with a different body.
         press_key(&mut app, KeyCode::ShiftLeft);
         press_key(&mut app, KeyCode::KeyB);
         app.update();
@@ -1902,7 +1631,7 @@ mod tests {
         app.update();
         assert!(open(&app, 0) && open(&app, 2), "SHIFT-B opens every bag");
 
-        // …and closes them again, the count now reading all-open.
+        // SHIFT-B again closes them all.
         press_key(&mut app, KeyCode::KeyB);
         app.update();
         release_key(&mut app, KeyCode::KeyB);
diff --git a/crates/benilla-app/src/bindings/chord.rs b/crates/benilla-app/src/bindings/chord.rs
index 7687d86b..f64e9a75 100644
--- a/crates/benilla-app/src/bindings/chord.rs
+++ b/crates/benilla-app/src/bindings/chord.rs
@@ -1,19 +1,10 @@
-//! The chord codec (decision 0997): Bevy's physical input ↔ the reference's canonical binding
-//! strings — `[ALT-][CTRL-][SHIFT-]<TOKEN>`, where the token set is 1.12's own (`W`, `SPACE`,
-//! `NUMPAD0`, `BUTTON4`, `MOUSEWHEELUP`, the bare punctuation characters). These strings are what
-//! the table stores, the window displays (through the `KEY_*` GlobalStrings), and the files save.
+//! The chord codec: Bevy input to and from the 1.12 binding strings `[ALT-][CTRL-][SHIFT-]<TOKEN>`,
+//! with 1.12's own token set. These strings are what the table stores, the window shows and the
+//! files save; a press matches by equality, then once more with its leftmost modifier dropped.
 //!
-//! A press is matched against them by string equality — and then, on a miss, **once more** with
-//! its leftmost modifier dropped ([`Chord::fallback`], decision 1142; this is the half 0585 got
-//! wrong and 0997 carried).
-//!
-//! Prefix order is ALT-CTRL-SHIFT, verified from 1.12's own capture Lua (`Blizzard_BindingUI.lua`
-//! prepends SHIFT, then CTRL, then ALT), its saved cache (`CTRL-SHIFT-PAGEDOWN`), and the engine's
-//! own emitter (`0x4b6630` walks the `{bitIndex,name}` table at `0x846bd0` downward). It is not
-//! only cosmetic: that order is what decides *which* modifier the fallback drops.
-//!
-//! The Super/Cmd key is **not** a 1.12 binding modifier: a chord never carries it, a super-modified
-//! press never matches (0585's `sup` addition), and a capture with Super held is ignored outright.
+//! Prefix order is ALT-CTRL-SHIFT (`Blizzard_BindingUI.lua:176-182`; the emitter `0x4b6630` walks
+//! the table at `0x846bd0`), and it decides which modifier the fallback drops. Super/Cmd is not a
+//! 1.12 modifier: a chord never carries it and a press with it held never matches.
 
 use bevy::input::mouse::MouseButton;
 use bevy::prelude::KeyCode;
@@ -27,8 +18,7 @@ pub(crate) enum BindKey {
     WheelDown,
 }
 
-/// One parsed binding chord: the modifier set + the base input. Equality is how a press is
-/// probed; [`Chord::fallback`] is the second and last probe when that misses.
+/// One parsed binding chord: the modifier set and the base input, matched by equality.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub(crate) struct Chord {
     pub alt: bool,
@@ -38,9 +28,8 @@ pub(crate) struct Chord {
 }
 
 impl Chord {
-    /// Parse a canonical chord string (`"ALT-CTRL-SHIFT-F1"`, `"CTRL--"` = Ctrl+minus). Unknown
-    /// base tokens return `None` — the table may hold them (a future command's key), the
-    /// dispatcher just can't press them.
+    /// Parse a canonical chord string (`"CTRL--"` is Ctrl+minus); an unknown base token is `None`,
+    /// held in the table but never pressable.
     pub(crate) fn parse(s: &str) -> Option<Chord> {
         let (mut alt, mut ctrl, mut shift) = (false, false, false);
         let mut rest = s;
@@ -66,20 +55,10 @@ impl Chord {
         })
     }
 
-    /// The **one** retry the reference allows after an exact miss — drop the leftmost modifier
-    /// present, in the emitted prefix order ALT → CTRL → SHIFT. `None` once there is none left,
-    /// which is where the lookup ends (decision 1142).
-    ///
-    /// `CBindings::ExecuteBinding` (`0x4b7990`) does this by string surgery: on a miss it calls
-    /// `strchr(chord, '-')` (`0x4b7a2b`/`0x4b7a2d`) and re-probes the text after the **first**
-    /// `'-'` (`0x4b7a49 inc eax`). Both second-probe misses land on `0x4b7b41 xor eax,eax` —
-    /// there is no third probe and no loop, so `ALT-CTRL-Z` reaches `CTRL-Z` and stops without
-    /// ever seeing `ALT-Z` or bare `Z`. Hence `Option`, not an iterator: the chain is two long.
-    ///
-    /// Cutting at the first `'-'` *is* dropping the leftmost prefix, byte for byte — including
-    /// for the one token that contains a `'-'` of its own, the minus key. With a modifier held
-    /// the first `'-'` still terminates that prefix (`SHIFT--` → `-`); bare, the reference's
-    /// retry lands on the empty string and can only miss, which is exactly the `None` here.
+    /// The one retry after an exact miss: drop the leftmost modifier (ALT, then CTRL, then SHIFT).
+    /// `0x4b7990` re-probes the text after the first `'-'` (`0x4b7a2b`-`0x4b7a49`) and never
+    /// again (`0x4b7b41`), so `ALT-CTRL-Z` reaches `CTRL-Z` and stops. A bare `-` retries the
+    /// empty string there and misses, the `None` here.
     pub(crate) fn fallback(self) -> Option<Chord> {
         if self.alt {
             Some(Chord { alt: false, ..self })
@@ -99,8 +78,7 @@ impl Chord {
     }
 }
 
-/// Build the canonical chord string from live modifier state + a base token — the capture arm's
-/// output (prefix order ALT-CTRL-SHIFT, the 1.12 canon).
+/// Build the canonical chord string from live modifier state and a base token.
 pub(crate) fn chord_string(alt: bool, ctrl: bool, shift: bool, token: &str) -> String {
     let mut s = String::new();
     if alt {
@@ -116,12 +94,8 @@ pub(crate) fn chord_string(alt: bool, ctrl: bool, shift: bool, token: &str) -> S
     s
 }
 
-/// The 1.12 token for a physical key — `None` for keys the reference has no name for (they are
-/// ignored for binding, the client's own `UNKNOWN` posture). Modifier keys are deliberately
-/// absent: they are chord *prefixes*, never base keys (`IsKeyPressIgnoredForBinding`).
-///
-/// `NumpadEnter` shares `ENTER` with the main Enter key (1.12 has one token; [`normalize_key`]
-/// folds the pair for dispatch too).
+/// The 1.12 token for a physical key; `None` for a key the reference names `UNKNOWN` and for the
+/// modifiers, which are only prefixes (`IsKeyPressIgnoredForBinding`). Both Enters are `ENTER`.
 pub(crate) fn key_token(k: KeyCode) -> Option<&'static str> {
     use KeyCode::*;
     Some(match k {
@@ -173,36 +147,17 @@ pub(crate) fn key_token(k: KeyCode) -> Option<&'static str> {
         F10 => "F10",
         F11 => "F11",
         F12 => "F12",
-        // **On a Mac keyboard the print-screen key IS F13 — read out of the Mac binary now, not
-        // inferred.** The 1.12.1 Mac slice's key table `0x5bf320` maps Mac virtual keycode `0x69`
-        // (F13) to `0x212`, the same `PRINTSCREEN` the Windows table reaches from `VK_SNAPSHOT`.
-        // (This arm shipped as an inference off `KEY_PRINTSCREEN_MAC = "F13"`; the Mac table
-        // settled it at the bytes.) macOS has no PrintScreen keycode at
-        // all, so without this the byte-real `PRINTSCREEN SCREENSHOT` default is a dead key on
-        // every Mac — not fidelity, a broken key.
+        // On a Mac F13 is print-screen: the Mac key table `0x5bf320` maps keycode `0x69` to
+        // `0x212`, `PRINTSCREEN`, and macOS has no PrintScreen keycode.
         #[cfg(target_os = "macos")]
         F13 => "PRINTSCREEN",
-        // **F13-F24: bindable strings, and `F16` a real reference code.**
-        // `IsValidBindingKeyString` arm 3 takes `F` + digits with no ceiling (`0x846c04`), and the
-        // Mac table really does reach `F16` — keycode `0x6A` → `0x30d`. Naming only F1-F12 meant
-        // `SetBinding("F16", …)` stored a chord this codec could never press: the key vanished
-        // into `unpressable chord` at the next seed.
-        //
-        // **Above F12 this is a benilla extension, deliberately.** The reference cannot reach
-        // them: Windows' fixed table stops at `VK_F12` and everything past it falls to
-        // `MapVirtualKeyA(vk, MAPVK_VK_TO_CHAR)`, which returns 0 for an F-key and drops the
-        // message outright. That is a 2004 lookup table's silence, not a rule about keys.
+        // `IsValidBindingKeyString` accepts `F` + any digits (`0x846c04`) and the Mac table maps
+        // keycode `0x6A` to `F16` (`0x30d`). Deviation: the Windows key table stops at `VK_F12`
+        // and drops later F-keys; they are named here so a stored `F13`-`F24` can be pressed.
         #[cfg(not(target_os = "macos"))]
         F13 => "F13",
-        // **F14 and F15 are the Mac's ScrollLock and Pause, and those two are unbindable.** The
-        // Mac table sends keycode `0x6B` (F14) to `0x210` and `0x71` (F15) to `0x211` — the exact
-        // pair the namer calls `UNKNOWN` — so on a Mac they are refused for the same reason
-        // ScrollLock and Pause are refused below: they ARE those keys. (1.12's
-        // `KEY_SCROLLLOCK_MAC` / `KEY_PAUSE_MAC` are dead labels for the same reason; neither
-        // binary carries a `SCROLLLOCK` or `PAUSE` string at all.)
-        //
-        // The line that draws: a key the reference deliberately maps to `UNKNOWN` stays
-        // unbindable; a key it simply never mapped, we may name.
+        // On a Mac F14 and F15 are ScrollLock and Pause: keycodes `0x6B` and `0x71` map to
+        // `0x210` and `0x211`, which the namer calls `UNKNOWN`, so they stay unbindable there.
         #[cfg(not(target_os = "macos"))]
         F14 => "F14",
         #[cfg(not(target_os = "macos"))]
@@ -246,16 +201,12 @@ pub(crate) fn key_token(k: KeyCode) -> Option<&'static str> {
         NumpadDivide => "NUMPADDIVIDE",
         NumpadMultiply => "NUMPADMULTIPLY",
         NumpadDecimal => "NUMPADDECIMAL",
-        // The Mac numeric keypad's `=` key. It is in the reference's namer (`0x30c`) and in
-        // `IsValidBindingKeyString`'s 26-name table, and it was in OUR validator too — but not
-        // here, so it was the one token `SetBinding` accepted and the dispatcher could not press.
+        // The Mac keypad's `=`: the namer's `0x30c`, and in `IsValidBindingKeyString`'s table.
         NumpadEqual => "NUMPADEQUALS",
         NumLock => "NUMLOCK",
         PrintScreen => "PRINTSCREEN",
-        // ScrollLock and Pause are deliberately absent: the reference's namer (`0x4b66b0`) calls
-        // their key codes (`0x210`/`0x211`) `UNKNOWN`, so they are unbindable there, and
-        // `IsValidBindingKeyString` (`0x4b7890`) would refuse the names anyway — its 26-name table
-        // holds neither.
+        // No ScrollLock or Pause: the namer (`0x4b66b0`) calls `0x210`/`0x211` `UNKNOWN`, and
+        // `IsValidBindingKeyString` (`0x4b7890`) has neither name.
         CapsLock => "CAPSLOCK",
         Minus => "-",
         Equal => "=",
@@ -277,20 +228,16 @@ pub(crate) fn key_token(k: KeyCode) -> Option<&'static str> {
 pub(crate) fn normalize_key(k: KeyCode) -> KeyCode {
     match k {
         KeyCode::NumpadEnter => KeyCode::Enter,
-        // The Mac print-screen key — see [`key_token`]'s arm for the evidence. Folded here as well
-        // as there because the two arms serve different halves: `key_token` names the key the
-        // capture arm just swallowed, this one makes a press DISPATCH against a chord parsed from
-        // the token. Only both together make `PRINTSCREEN` a working binding on a Mac.
+        // The Mac print-screen key; must agree with `key_token`, which names it for capture.
         #[cfg(target_os = "macos")]
         KeyCode::F13 => KeyCode::PrintScreen,
         other => other,
     }
 }
 
-/// The 1.12 token for a mouse button. BUTTON4 is winit's `Forward` and BUTTON5 `Back` —
-/// deliberately keeping the thumb button that toggled autorun before 0997 (macOS winit maps
-/// NSEvent buttonNumber 4 → `Forward`; see the old `player.rs` site) on the 1.12 default
-/// (`BUTTON4 TOGGLEAUTORUN`), so the director's in-hand behavior survives the refactor.
+/// The 1.12 token for a mouse button: BUTTON4 is winit's `Forward` and BUTTON5 its `Back`, so the
+/// 1.12 default `BUTTON4 TOGGLEAUTORUN` sits on `Forward`. Which physical button the reference
+/// calls BUTTON4 is untraced.
 pub(crate) fn mouse_token(b: MouseButton) -> Option<&'static str> {
     Some(match b {
         MouseButton::Left => "BUTTON1",
@@ -298,26 +245,19 @@ pub(crate) fn mouse_token(b: MouseButton) -> Option<&'static str> {
         MouseButton::Middle => "BUTTON3",
         MouseButton::Forward => "BUTTON4",
         MouseButton::Back => "BUTTON5",
-        // **The extra buttons on a real mouse.** The reference names them the same way it names
-        // the first five and then some: `0x4b6aa0`'s fallback arm bit-scans from bit 3 upward and
-        // `sprintf("BUTTON%{d}", n)`, and `IsValidBindingKeyString` arm 3 takes `BUTTON` +
-        // digits with no ceiling — so `BUTTON6` was always a storable, listable, *unpressable*
-        // chord here. winit hands the platform's own button number through `Other(n)`, and on
-        // macOS that is `NSEvent.buttonNumber` — 0-4 already spoken for by the five named
-        // variants, so the sixth physical button arrives as `Other(5)` and is `BUTTON6`.
+        // The reference names further buttons `BUTTON<n>` (`0x4b6aa0`'s bit-scan fallback).
+        // winit passes the platform's button number, so the sixth button is `Other(5)`.
         MouseButton::Other(n) => return EXTRA_BUTTONS.get(usize::from(n).wrapping_sub(5)).copied(),
     })
 }
 
-/// `BUTTON6`…`BUTTON20`, indexed by `Other(n) - 5`. A bounded table rather than a formatted
-/// string because these names are `&'static str` on both sides of the codec; twenty buttons is
-/// past every mouse anyone ships and the reference's own namer stops at the first gap too.
+/// `BUTTON6` to `BUTTON20`, indexed by `Other(n) - 5`.
 const EXTRA_BUTTONS: &[&str] = &[
     "BUTTON6", "BUTTON7", "BUTTON8", "BUTTON9", "BUTTON10", "BUTTON11", "BUTTON12", "BUTTON13",
     "BUTTON14", "BUTTON15", "BUTTON16", "BUTTON17", "BUTTON18", "BUTTON19", "BUTTON20",
 ];
 
-/// Token → base input (the parse side of [`key_token`]/[`mouse_token`], plus the wheel pair).
+/// Token to base input: the inverse of [`key_token`] and [`mouse_token`], plus the wheel pair.
 fn token_key(t: &str) -> Option<BindKey> {
     use KeyCode::*;
     if let Some(b) = match t {
@@ -447,18 +387,8 @@ fn token_key(t: &str) -> Option<BindKey> {
         "`" => Backquote,
         _ => return None,
     };
-    // **Through the alias fold, and only if the namer agrees.** Two invariants, both of which
-    // this codec broke somewhere before 1745:
-    //
-    // 1. A chord parsed from a token must compare equal to the one a press BUILDS, and a press is
-    //    normalized ([`normalize_key`]) — so `ENTER` has to land on the same `KeyCode` the
-    //    numpad's Enter folds to.
-    // 2. A token this side accepts must be one [`key_token`] would produce, on THIS platform.
-    //    Otherwise the two tables drift: on a Mac `F13` is the print-screen key and `F14`/`F15`
-    //    are the unbindable ScrollLock/Pause pair, so parsing those strings to their raw
-    //    `KeyCode`s would make a chord the capture arm can never write and the window can never
-    //    show, reachable only by hand-editing the file. Asking the namer closes it structurally
-    //    rather than by remembering to cfg both sides.
+    // Fold aliases so a parsed chord equals a normalized press, and accept only a token the
+    // namer produces on this platform (on a Mac, F13-F15 are other keys).
     let k = normalize_key(k);
     if key_token(k) != Some(t) {
         return None;
@@ -470,15 +400,8 @@ fn token_key(t: &str) -> Option<BindKey> {
 mod tests {
     use super::*;
 
-    /// **Every token this codec names is one `SetBinding` will actually take** (decision 1295).
-    /// The namer here and `IsValidBindingKeyString` in the engine table are two transcriptions of
-    /// the same reference, and nothing but this ties them together — a token we name but the
-    /// validator refuses is a key the capture seam happily offers and `SetBinding` then drops on
-    /// the floor, which is exactly what `SCROLLLOCK` and `PAUSE` were until 1295.
-    ///
-    /// The registry's default chords are covered exhaustively; `KeyCode` cannot be enumerated, so
-    /// the namer is covered by one key of every SHAPE it produces (letter, digit, F-key, numpad
-    /// digit, numpad name, arrow, the named editing/lock keys, punctuation).
+    /// Ties this namer to the engine's `IsValidBindingKeyString`: every default chord, and one key
+    /// of each token shape, since `KeyCode` cannot be enumerated.
     #[test]
     fn every_token_the_codec_names_is_one_setbinding_accepts() {
         use benilla_ui::script::keybind::normalize_binding_key;
@@ -545,35 +468,20 @@ mod tests {
         for token in ["MOUSEWHEELUP", "MOUSEWHEELDOWN"] {
             assert!(normalize_binding_key(token).is_some());
         }
-        // The other half of the same law: the reference's namer calls these two `UNKNOWN`
-        // (`0x210`/`0x211`), so we must not name them either — nothing downstream could bind them.
+        // The reference's namer calls these `UNKNOWN` (`0x210`/`0x211`).
         assert_eq!(key_token(KeyCode::ScrollLock), None);
         assert_eq!(key_token(KeyCode::Pause), None);
     }
 
-    /// **And the way back — the direction that actually bit.** The test above walks the codec's
-    /// output into the validator; nothing walked the validator's *input space* back into the
-    /// codec, and three families lived in the gap: `NUMPADEQUALS` (in the reference's namer at
-    /// `0x30c`, in the 26-name table, in our validator — and nowhere here), `F13`-`F24`
-    /// (`IsValidBindingKeyString` arm 3 is `F` + digits with no ceiling), and `BUTTON6`+ (arm 3
-    /// again, and `0x4b6aa0`'s bit-scan fallback). Each was a key `SetBinding` accepted, the
-    /// window listed, the file saved — and the dispatcher could never press, so it came back as
-    /// `bindings: <cmd>: unpressable chord` and the player's key did nothing.
-    ///
-    /// The accept set is infinite (any single character, `F`/`NUMPAD`/`BUTTON` + any digits), so
-    /// this pins the families that name a key a real keyboard or mouse HAS. Past those — `F25`,
-    /// `BUTTON21`, `NUMPAD11` — the validator still accepts and the codec still refuses, which is
-    /// correct and deliberate: there is no physical key to press, and inventing a `KeyCode` for
-    /// one would be inventing hardware.
+    /// The validator's accept set is infinite, so this covers the tokens a real keyboard or mouse
+    /// has; `F25`, `BUTTON21` and `NUMPAD11` stay unpressable, as no such key exists.
     #[test]
     fn every_token_setbinding_accepts_for_a_real_key_is_one_the_codec_can_press() {
         use benilla_ui::script::keybind::normalize_binding_key;
 
         let mut tokens: Vec<String> = Vec::new();
         tokens.extend((1..=24).map(|n| format!("F{n}")));
-        // On a Mac those three are other keys: F13 IS print-screen (`0x5bf320`: keycode `0x69` →
-        // `0x212`) and F14/F15 are the unbindable ScrollLock/Pause pair (`0x210`/`0x211`). The
-        // codec refuses them there on purpose, so the list has to as well.
+        // On a Mac F13 is print-screen and F14/F15 are the unbindable ScrollLock and Pause.
         if cfg!(target_os = "macos") {
             tokens.retain(|t| !matches!(t.as_str(), "F13" | "F14" | "F15"));
         }
@@ -631,7 +539,6 @@ mod tests {
 
     #[test]
     fn the_codec_round_trips_every_keyboard_token() {
-        // Every key with a token parses back to itself (through the alias fold).
         let mut checked = 0;
         for k in [
             KeyCode::KeyW,
@@ -654,14 +561,11 @@ mod tests {
             checked += 1;
         }
         assert_eq!(checked, 10);
-        // The alias fold: both Enters share the token and the parsed key.
         assert_eq!(key_token(KeyCode::NumpadEnter), Some("ENTER"));
         assert_eq!(token_key("ENTER"), Some(BindKey::Key(KeyCode::Enter)));
     }
 
-    /// The Mac print-screen fold (decision 1487). macOS delivers no `PrintScreen` at all — a PC
-    /// keyboard's PrtSc arrives as F13 — so BOTH arms have to agree that F13 *is* `PRINTSCREEN`,
-    /// or the shipped `PRINTSCREEN SCREENSHOT` default is a key nobody on a Mac can press.
+    /// macOS has no `PrintScreen`, so capture and dispatch must both read F13 as `PRINTSCREEN`.
     #[cfg(target_os = "macos")]
     #[test]
     fn f13_is_print_screen_on_a_mac() {
@@ -693,7 +597,7 @@ mod tests {
                 key: BindKey::Key(KeyCode::F1)
             })
         );
-        // `CTRL--` is Ctrl + the minus key — the prefix strip never splits the base token.
+        // `CTRL--` is Ctrl + the minus key.
         assert_eq!(
             Chord::parse("CTRL--"),
             Some(Chord {
@@ -722,7 +626,6 @@ mod tests {
             })
         );
         assert_eq!(Chord::parse("BOGUS"), None);
-        // The builder emits the same canon the parser reads.
         assert_eq!(
             chord_string(true, false, true, "PAGEDOWN"),
             "ALT-SHIFT-PAGEDOWN"
diff --git a/crates/benilla-app/src/bindings/commands.rs b/crates/benilla-app/src/bindings/commands.rs
index b1441b8b..84876fc9 100644
--- a/crates/benilla-app/src/bindings/commands.rs
+++ b/crates/benilla-app/src/bindings/commands.rs
@@ -1,35 +1,16 @@
-//! The command registry (decision 0997) — every binding command benilla actually implements, in
-//! 1.12 `Bindings.xml` order, with the 1.12 default chords (byte-real: the client's own
-//! `bindings-cache.wtf`, account ONE) and each command's dispatch class.
+//! The binding command registry: every command benilla implements, in 1.12 `Bindings.xml` order,
+//! with the stock default chords (`WTF\DefaultBindings.wtf`) and each command's dispatch class.
+//! A command appears only over a real engine action; the rest are in [`ABSENT`], and the two
+//! together are exactly the client's 228 live bindings. Labels and headers are the 1.12
+//! `BINDING_NAME_*`/`BINDING_HEADER_*` GlobalStrings.
 //!
-//! **Honest tree**: a command appears here only over a real engine action — the same law as the
-//! options rows (0954). The 1.12 commands with no benilla mechanism yet are absent, not stubbed;
-//! the page shows only what's here, and only non-empty categories (era law). Labels/headers are
-//! the 1.12 GlobalStrings (`BINDING_NAME_*`/`BINDING_HEADER_*`), defined in the window's XML.
-//!
-//! **…and the absence is written down** ([`ABSENT`], decision 1745). The honest tree's one hole
-//! was that nothing noticed when a mechanism ARRIVED: 0997 promised "each returns the day its
-//! mechanism lands, one registry row", and then the keyring (0765), the pet book (1050), the
-//! reputation and honor pages, the six action-bar pages and the two vertical multibars (1500)
-//! all shipped their mechanism with no row — some for five hundred commits, none of them a
-//! mistake anyone could see. `SPECS` ∪ `ABSENT` is now exactly the client's 228 live bindings,
-//! and each absent row names the Lua globals whose arrival falsifies it.
-//!
-//! Three dispatch classes:
-//! - [`Kind::Held`] — press latches, base-key release unlatches (the reference's `runOnUp`
-//!   movement pairs); engine systems read the latch ([`super::BindingsState`]).
-//! - [`Kind::Edge`] / [`Kind::EdgeUpDown`] — fires Lua in the VM (the reference's binding body,
-//!   quoted 1:1 where our FrameXML port has the same functions).
-//! - [`Kind::Host`] — fires into [`super::BindingsState::fired`]; an engine system consumes it
-//!   (chat open, TAB targeting, nameplates, autorun, …).
-//!
-//! Recorded default divergences (0997): `TOGGLEUI` ships `ALT-Z` (0870: the cache's `CTRL-Z` is
-//! a player rebind all three accounts inherited, not the shipped default — the one row that does
-//! not trust the cache). That is now the ONLY one — the bag row's divergence (`OPENALLBAGS` wearing
-//! both `B` and `SHIFT-B`, because benilla had a single all-bags knob) is gone as of 1494: the
-//! reference's split ships whole, keys and bodies alike.
+//! Dispatch classes:
+//! - [`Kind::Held`]: press latches, base-key release unlatches (the `runOnUp` movement pairs);
+//!   engine systems read the latch ([`super::BindingsState`]).
+//! - [`Kind::Edge`] / [`Kind::EdgeUpDown`]: runs the reference's binding body as Lua.
+//! - [`Kind::Host`]: fires into [`super::BindingsState::fired`] for an engine system.
 
-/// A command's index into [`SPECS`] — the engine-side handle (`cmd::JUMP`).
+/// A command's index into [`SPECS`], the engine-side handle (`cmd::JUMP`).
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub(crate) struct Cmd(pub u16);
 
@@ -46,19 +27,17 @@ pub(crate) enum Kind {
 
 pub(crate) struct Spec {
     pub name: &'static str,
-    /// The category header's global-string key (`BINDING_HEADER_MOVEMENT`) — the window's
-    /// sidebar groups by it, era-style.
+    /// The category header's global-string key (`BINDING_HEADER_MOVEMENT`).
     pub category: &'static str,
     pub kind: Kind,
-    /// The 1.12 default chords (canonical strings; `None` = shipped unbound).
+    /// The 1.12 default chords; `None` is shipped unbound.
     pub d1: Option<&'static str>,
     pub d2: Option<&'static str>,
 }
 
 impl Spec {
-    /// Press+release semantics — the reference's `<Binding runOnUp=…>`, whose ONE reader is
-    /// `RunCommand 0x4b7bf1`: it gates the release half and nothing else. (It used to gate a
-    /// mousewheel refusal at `SetBinding` time here; that refusal is not in the client — 1295.)
+    /// The reference's `<Binding runOnUp=…>`; its one reader (`0x4b7bf1`) gates the release half
+    /// and nothing else.
     pub(crate) fn run_on_up(&self) -> bool {
         matches!(self.kind, Kind::Held | Kind::EdgeUpDown(..))
     }
@@ -76,21 +55,11 @@ macro_rules! spec {
     };
 }
 
-/// Engine-side handles for the host-dispatched commands (indexes into [`SPECS`], asserted by
-/// test). Lua-bodied commands need no handle — nothing in Rust names them.
+/// Engine-side handles for the host-dispatched commands, as indexes into [`SPECS`].
 pub(crate) mod cmd {
     use super::{Cmd, TABLE};
 
-    /// Resolve a command NAME to its [`Cmd`] handle at compile time — a linear scan of [`TABLE`]
-    /// in a `const fn`, so a name that is not in the registry is a BUILD error, not a runtime
-    /// surprise.
-    ///
-    /// These handles used to be hand-written row numbers, and every row that landed ahead of one
-    /// silently re-pointed it at its neighbour: 1057's `TOGGLECHARACTER3` moved three of them
-    /// 86/87/88 → 87/88/89, 1136's `TOGGLEACTIONBARLOCK` moved the same three again, and 1494's
-    /// bag family would have moved them a third time (`TOGGLE_UI` landing on `MINIMAPZOOMOUT`). A
-    /// guard test named the drift but the numbers still had to be re-typed by hand each time; the
-    /// name is the thing we actually mean, so the name is what the table is asked for now.
+    /// Resolve a command name to its [`Cmd`] at compile time; an unknown name is a build error.
     const fn by_name(name: &str) -> Cmd {
         let mut i = 0;
         while i < TABLE.len() {
@@ -140,11 +109,8 @@ pub(crate) mod cmd {
     pub(crate) const CAMERA_ZOOM_OUT: Cmd = by_name("CAMERAZOOMOUT");
 }
 
-/// The registry, 1.12 `Bindings.xml` order. Sub-tables (action buttons, shapeshift, raid
-/// targets) are written out because each row carries its own Lua body string.
-///
-/// `TABLE` is the `const` view [`cmd::by_name`] scans at compile time (a `static` cannot be read
-/// during const evaluation); `SPECS` is the one everything else uses.
+/// The registry, in 1.12 `Bindings.xml` order. `TABLE` is the `const` view [`cmd::by_name`] scans,
+/// since a `static` cannot be read during const evaluation.
 pub(crate) static SPECS: &[Spec] = TABLE;
 
 const TABLE: &[Spec] = &[
@@ -229,9 +195,7 @@ const TABLE: &[Spec] = &[
         Some("R"),
         None
     ),
-    // The other reply: the last person YOU told, not the last who told you
-    // (`ChatEdit_GetLastToldTarget`, ChatFrame.lua l.1650). The memory was already being kept by
-    // the send path and read by nothing — 1745.
+    // The last person you told, not the last who told you (`ChatFrame.lua:1650`).
     spec!(
         "REPLY2",
         CHAT,
@@ -239,9 +203,7 @@ const TABLE: &[Spec] = &[
         Some("SHIFT-R"),
         None
     ),
-    // The combat-log four (Bindings.xml l.108-119): ChatFrame2's own paging and the reference's
-    // `ToggleCombatLog`, both FloatingChatFrame.lua's since the chat window became the
-    // reference's (1948). Chords from `bindings-cache.wtf`, account ONE.
+    // The combat-log four (`Bindings.xml:108-119`): ChatFrame2's paging and `ToggleCombatLog`.
     spec!(
         "COMBATLOGPAGEUP",
         CHAT,
@@ -271,8 +233,7 @@ const TABLE: &[Spec] = &[
         None
     ),
     // ── Action bar (BINDING_HEADER_ACTIONBAR) ───────────────────────────────────────────
-    // The ref's runOnUp pair (Bindings.xml:121: DOWN shows the pushed visual, UP fires) —
-    // exactly what the old hardcoded number-row table sent.
+    // The `runOnUp` pair (`Bindings.xml:121`): down shows the pushed visual, up fires.
     spec!(
         "ACTIONBUTTON1",
         ACTIONBAR,
@@ -357,13 +318,9 @@ const TABLE: &[Spec] = &[
         Some("="),
         None
     ),
-    // The stance/shapeshift row (ref ShapeshiftBar_ChangeForm(n)) — ours clicks the bar's own
-    // buttons, which carry the full form-switch law (stock BonusActionBarFrame.xml, 1938).
-    // ── The self-cast dozen (1.12 `Bindings.xml`:257-293) ───────────────────────────────
-    // The same two halves as ACTIONBUTTON, with `ActionButtonUp`'s second argument set: the
-    // reference's own `onSelf`, which stock `ActionButtonUp` forwards to `UseAction`'s third
-    // and the host used to drop (1745). `ALT-1`…`ALT-=` are byte-real from DefaultBindings.wtf,
-    // and they sit one modifier off the plain bar exactly as the reference lays them out.
+    // ── Self-cast (`Bindings.xml:205-288`) ─────────────────────────────────────────────
+    // ACTIONBUTTON's halves with `ActionButtonUp`'s `onSelf` argument set, which stock
+    // `ActionButtonUp` forwards to `UseAction`.
     spec!(
         "SELFACTIONBUTTON1",
         ACTIONBAR,
@@ -448,6 +405,8 @@ const TABLE: &[Spec] = &[
         Some("ALT-="),
         None
     ),
+    // The reference body is `ShapeshiftBar_ChangeForm(n)`; this clicks the visible stock
+    // button, whose OnClick calls it (`BonusActionBarFrame.xml:37`).
     spec!(
         "SHAPESHIFTBUTTON1",
         ACTIONBAR,
@@ -538,14 +497,9 @@ const TABLE: &[Spec] = &[
         Some("CTRL-F10"),
         None
     ),
-    // The PET bar's row — 1.12 calls it BONUSACTIONBUTTON and files it under this same ACTIONBAR
-    // header (Bindings.xml:321-390 carries no `header` attribute, so it inherits l.121's), which
-    // is why "Secondary Action Button 1-10" reads under Action Bar in the reference's own window.
-    // The ref's body is BonusActionButtonDown/Up(id), and those two are one-liners onto
-    // PetActionButtonDown/Up (BonusActionBarFrame.lua:106-112) — the PET bar's buttons, not the
-    // bonus bar's. benilla has no bonus bar at all, so the pet bar is the whole lane, exactly as
-    // the reference wires it. Defaults are byte-real and unanimous: CTRL-1..CTRL-0 in all three
-    // of the install's `bindings-cache.wtf` files (unlike TOGGLEUI's rebind, 0870).
+    // The pet bar, which 1.12 names BONUSACTIONBUTTON under the ACTIONBAR header
+    // (`Bindings.xml:321-390`); its `BonusActionButtonDown/Up` only call
+    // `PetActionButtonDown/Up` (`BonusActionBarFrame.lua:106-112`).
     spec!(
         "BONUSACTIONBUTTON1",
         ACTIONBAR,
@@ -616,12 +570,9 @@ const TABLE: &[Spec] = &[
         Some("CTRL-0"),
         None
     ),
-    // ── The action-bar PAGES (1.12 `Bindings.xml`:395-431) ──────────────────────────────
-    // The bar is six pages of twelve (action slots 1..72) and it has been since 1500 shipped the
-    // multibars; `ChangeActionBarPage` is the engine's (it fires ACTIONBAR_PAGE_CHANGED and nothing
-    // else — 1938) and the `ActionBar_Page{Up,Down}` wrap is stock ActionButton.lua's. `SHIFT-1..6`
-    // and the SHIFT-arrow / SHIFT-wheel steps are
-    // byte-real from `WTF\\DefaultBindings.wtf`.
+    // ── Action-bar pages (`Bindings.xml:391-432`) ──────────────────────────────────────
+    // Six pages of twelve (slots 1-72). `ChangeActionBarPage` is an engine verb that only fires
+    // `ACTIONBAR_PAGE_CHANGED`; the `ActionBar_Page{Up,Down}` wrap is stock ActionButton.lua's.
     spec!(
         "ACTIONPAGE1",
         ACTIONBAR,
@@ -696,13 +647,8 @@ const TABLE: &[Spec] = &[
         Some("SHIFT-DOWN"),
         Some("SHIFT-MOUSEWHEELDOWN")
     ),
-    // The action-bar lock (decision 1136), the ref's own binding body verbatim (Bindings.xml:433-
-    // 439) — it flips the `LOCK_ACTIONBAR` uvar OptionsFrame.xml declares (1938), the same global the
-    // Options window's Action Bars row writes. It sits here because the reference files it under
-    // this header (l.433 carries no `header=`, so it inherits l.121's ACTIONBAR), and it ships
-    // **unbound**: no `TOGGLEACTIONBARLOCK` line in any of the install's three
-    // `bindings-cache.wtf` files, which is also what the option's own tooltip implies ("can be
-    // bound to a function key in the keybindings interface").
+    // Flips the `LOCK_ACTIONBAR` uvar the Options window's Lock ActionBars row writes
+    // (`Bindings.xml:433-439`).
     spec!(
         "TOGGLEACTIONBARLOCK",
         ACTIONBAR,
@@ -712,9 +658,6 @@ const TABLE: &[Spec] = &[
         None,
         None
     ),
-    // The `autoSelfCast` CVar's own toggle, the reference's body verbatim — real since 1745
-    // wired that CVar to the cast arm's `AutoSelfCast` knob, which had been welded to a Resource
-    // default with nothing able to move it. Ships unbound, like the reference.
     spec!(
         "TOGGLEAUTOSELFCAST",
         ACTIONBAR,
@@ -740,9 +683,7 @@ const TABLE: &[Spec] = &[
         Some("SHIFT-TAB"),
         None
     ),
-    // The friendly cone — the same scan with the reaction test flipped (1745). `CTRL-TAB` /
-    // `CTRL-SHIFT-TAB`, byte-real; the reverse flag is the reference's own
-    // `TargetNearestFriend(1)`, and its `Bindings.xml` comment says so out loud.
+    // The friendly scan; `1` is the reverse flag (`Bindings.xml:458`).
     spec!(
         "TARGETNEARESTFRIEND",
         TARGETING,
@@ -757,8 +698,7 @@ const TABLE: &[Spec] = &[
         Some("CTRL-SHIFT-TAB"),
         None
     ),
-    // The self/party bodies are 1.12's own, 1:1 (Bindings.xml:460-509 — already-targeted
-    // falls through to the pet).
+    // An already-targeted unit falls through to its pet (`Bindings.xml:460-494`).
     spec!(
         "TARGETSELF",
         TARGETING,
@@ -878,21 +818,8 @@ const TABLE: &[Spec] = &[
         Some("C"),
         None
     ),
-    // The bag family, in the reference's own `Bindings.xml` order and with its own bodies and
-    // defaults (1494). 0997 collapsed all of this onto ONE command — `OPENALLBAGS` wearing both
-    // `B` and `SHIFT-B` over a `ToggleBackpack()` that opened every bag — because benilla had a
-    // single all-bags knob to hang keys off. The reference has three knobs and the director
-    // reported the difference: `B` opens the backpack ALONE, `SHIFT-B` opens the lot.
-    //
-    // Every default here is byte-real from the client's own `bindings-cache.wtf`, identical across
-    // all three independent accounts (ONE, TWO, WINUSER) — which is what rules out a player rebind
-    // (the `TOGGLEUI` trap, 0870).
-    //
-    // Each body is the bare GLOBAL, exactly the ref's own `Bindings.xml` — NOT a button's OnClick
-    // handler: a handler carries the button's checked bookkeeping, and routing a key through it
-    // drags that onto a path the reference keeps clean (with a bag addon holding `ToggleBackpack`,
-    // the key press is the path that lights the backpack button on the real client — the addon's
-    // OnShow write is the last word).
+    // The bag family: `B` opens the backpack alone, `SHIFT-B` every bag. Each body is the bare
+    // global, as in `Bindings.xml`, never a button's OnClick, which would add its checked state.
     spec!(
         "TOGGLEBACKPACK",
         INTERFACE,
@@ -900,8 +827,8 @@ const TABLE: &[Spec] = &[
         Some("B"),
         Some("F12")
     ),
-    // TOGGLEBAG**N** is bag **5-N**: the reference's numbering runs the bar right-to-left, so F8
-    // opens the slot FARTHEST from the backpack. Quoted from ref Bindings.xml l.564-575.
+    // TOGGLEBAGn is bag 5-n, so F8 opens the slot farthest from the backpack
+    // (`Bindings.xml:564-575`).
     spec!(
         "TOGGLEBAG1",
         INTERFACE,
@@ -937,9 +864,6 @@ const TABLE: &[Spec] = &[
         Some("SHIFT-B"),
         None
     ),
-    // The keyring's own toggle (1.12 `Bindings.xml`; ships UNBOUND, and the reference's page
-    // shows it as such). 0765 landed the keyring plate and its `HasKey` gate; the row it was
-    // owed has been missing since.
     spec!(
         "TOGGLEKEYRING",
         INTERFACE,
@@ -954,8 +878,7 @@ const TABLE: &[Spec] = &[
         Some("P"),
         None
     ),
-    // The PET book is the same window forked on `bookType` — 1050's law, and the reason this is
-    // a second command rather than a second key on the first.
+    // The pet book is the same window forked on `bookType`.
     spec!(
         "TOGGLEPETBOOK",
         INTERFACE,
@@ -970,9 +893,8 @@ const TABLE: &[Spec] = &[
         Some("N"),
         None
     ),
-    // TOGGLECHARACTER**N** is the reference's PAGE number, not our tab index: 0 = PaperDoll,
-    // 1 = Skill, 2 = Reputation, 3 = PetPaperDoll, 4 = Honor. The rows run 4, 3, 2, 1 in the
-    // file, and the file's order is this table's order.
+    // TOGGLECHARACTERn is the reference's page number, not a tab index: 0 PaperDoll, 1 Skill,
+    // 2 Reputation, 3 PetPaperDoll, 4 Honor; the file runs them 4, 3, 2, 1.
     spec!(
         "TOGGLECHARACTER4",
         INTERFACE,
@@ -980,9 +902,6 @@ const TABLE: &[Spec] = &[
         Some("H"),
         None
     ),
-    // `SHIFT-P` is byte-real from the client's own `bindings-cache.wtf`, and identical in two
-    // independent accounts (ONE and WINUSER) — which is what rules out a player rebind (the
-    // `TOGGLEUI` trap, 0870). Decision 1057.
     spec!(
         "TOGGLECHARACTER3",
         INTERFACE,
@@ -1069,10 +988,8 @@ const TABLE: &[Spec] = &[
         None,
         None
     ),
-    // The battleground scoreboard and the battlefield minimap — the Interface block's last two
-    // (Bindings.xml l.630-635), both Lua-bodied: `ToggleWorldStateScoreFrame` is the stock
-    // WorldStateFrame.lua's since 1972 and `ToggleBattlefieldMinimap` UIParent.xml's (ref
-    // UIParent.lua l.216-221). Defaults byte-real from `WTF\DefaultBindings.wtf`.
+    // `ToggleWorldStateScoreFrame` is stock WorldStateFrame.lua's, `ToggleBattlefieldMinimap`
+    // stock `UIParent.lua:216` (`Bindings.xml:630-635`).
     spec!(
         "TOGGLEWORLDSTATESCORES",
         INTERFACE,
@@ -1102,8 +1019,8 @@ const TABLE: &[Spec] = &[
         Some("NUMPADMINUS"),
         None
     ),
-    // The sound toggles/steps flip the same CVars the ref's SoundOptionsFrame_* bodies do
-    // (1.12 SoundOptionsFrame.lua: master enable = MasterSoundEffects, step 0.1).
+    // The CVars stock SoundOptionsFrame.lua moves: `MasterSoundEffects` is the master enable,
+    // `MasterVolume` steps by 0.1.
     spec!(
         "TOGGLEMUSIC",
         MISC,
@@ -1140,25 +1057,9 @@ const TABLE: &[Spec] = &[
         Some("CTRL--"),
         None
     ),
-    // ALT-Z, not the cache's CTRL-Z — settled by 0870: all three of the install's accounts
-    // descend from one profile whose TOGGLEUI had been rebound; ALT-Z is the shipped default
-    // (the one command whose default does NOT trust the cache file).
+    // ALT-Z is the shipped default; a `bindings-cache.wtf` holding CTRL-Z is a player rebind.
     spec!("TOGGLEUI", MISC, Kind::Host, Some("ALT-Z"), None),
-    // Print screen (decision 1487). The body is the reference's own one-liner because our
-    // `TakeScreenshot` has the same contract its does (ScreenshotStatus.xml) — hide the last
-    // shot's confirmation, then ask the engine.
-    //
-    // `PRINTSCREEN` comes from the SHIPPED default, not a player's cache: `DefaultBindings.wtf`
-    // lives inside `patch.MPQ` and its line 128 is `bind PRINTSCREEN SCREENSHOT` (the install's
-    // account-ONE `bindings-cache.wtf` agrees). `Edge`, not `EdgeUpDown`, is also byte-real: the
-    // `<Binding>` carries no `runOnUp`, and the reference's dispatcher returns on key-up unless
-    // that flag is set (`0x4b7bea`).
-    //
-    // On a Mac keyboard the token arrives as F13, which is the reference's own Mac mapping rather
-    // than an accommodation (`KEY_PRINTSCREEN_MAC = "F13"`); `super::chord` does the translation.
-    // The stock WorldFrame.lua's framerate readout (decision 1983): `FramerateLabel`/`FramerateText`
-    // toggled by `ToggleFramerate()`, refreshed off `GetFramerate()` every quarter second by
-    // `WorldFrame_OnUpdate`. CTRL-R is the install's own DefaultBindings.wtf chord (1804).
+    // Stock WorldFrame.lua's framerate readout.
     spec!(
         "TOGGLEFPS",
         MISC,
@@ -1166,6 +1067,8 @@ const TABLE: &[Spec] = &[
         Some("CTRL-R"),
         None
     ),
+    // `Edge`: the `<Binding>` has no `runOnUp`, and the dispatcher returns on key-up without it
+    // (`0x4b7bea`).
     spec!(
         "SCREENSHOT",
         MISC,
@@ -1174,11 +1077,9 @@ const TABLE: &[Spec] = &[
         None
     ),
     // ── Camera (BINDING_HEADER_CAMERA) ──────────────────────────────────────────────────
-    // The five named camera views (decision 1745) — `player::camera_view`, whose defaults are the
-    // reference's own `0x84f488` table. NEXTVIEW/PREVVIEW ship on END/HOME and **do not wrap**
-    // (`0x50faa0`/`0x50fac0` are hard stops); Set/Save/Reset ship unbound, and 1.12 files no
-    // SAVEVIEW1/RESETVIEW1 row even though its engine accepts view 1 — that is a `Bindings.xml`
-    // decision, so the table follows the file.
+    // The five camera views (defaults: the table at `0x84f488`). NEXTVIEW/PREVVIEW stop at the
+    // ends (`0x50faa0`/`0x50fac0`); 1.12 has no SAVEVIEW1/RESETVIEW1 row though the engine
+    // accepts view 1.
     spec!(
         "NEXTVIEW",
         CAMERA,
@@ -1228,12 +1129,9 @@ const TABLE: &[Spec] = &[
         None
     ),
     // ── MultiActionBar (BINDING_HEADER_MULTIACTIONBAR) ──────────────────────────────────
-    // The two bottom bars' buttons (stock MultiActionBars.xml renders exactly these; 1.12's right bars
-    // and their MULTIACTIONBAR3/4 commands stay out — honest tree). Ref bodies are the
-    // MultiActionButtonDown/Up runOnUp pair (Bindings.xml:799-966), defined in stock
-    // MultiActionBars.lua; shipped UNBOUND like the ref (no MULTIACTIONBAR* line in any of the
-    // install's bindings-cache.wtf files). 1.12 files bar 2 under a BLANK spacer-header;
-    // both bars sit under the one MULTIACTIONBAR header here (1008, recorded).
+    // The four multibars' `runOnUp` pairs (`Bindings.xml:799-1134`), stock MultiActionBars.lua's.
+    // Deviation: 1.12 files bars 2-4 under the spacer headers `BLANK`, `BLANK2` and `BLANK3`; they
+    // sit under MULTIACTIONBAR here because this page's sections are named.
     spec!(
         "MULTIACTIONBAR1BUTTON1",
         MULTIACTIONBAR,
@@ -1474,11 +1372,7 @@ const TABLE: &[Spec] = &[
         None,
         None
     ),
-    // ── The two VERTICAL bars (1.12 files them under its own `BLANK2`/`BLANK3` spacer
-    // headers; they join bar 2 under MULTIACTIONBAR here for the same reason 1008 folded that
-    // one — a spacer is a display device in the reference's flat list, and this page's sections
-    // are named). Both bars are real since 1500; `MultiBarRight` is bar 3, `MultiBarLeft` bar 4,
-    // and both ship UNBOUND exactly as the reference does.
+    // The vertical bars: `MultiBarRight` is bar 3, `MultiBarLeft` bar 4.
     spec!(
         "MULTIACTIONBAR3BUTTON1",
         MULTIACTIONBAR,
@@ -1720,8 +1614,7 @@ const TABLE: &[Spec] = &[
         None
     ),
     // ── Raid targeting (BINDING_HEADER_RAID_TARGET) ─────────────────────────────────────
-    // 1.12 bodies 1:1 (SetRaidTargetIcon toggles when the unit already wears the icon; 0
-    // clears — party.rs's registered semantics). All unbound by default, like the client.
+    // `SetRaidTargetIcon` toggles an icon the unit already wears off; 0 clears.
     spec!(
         "RAIDTARGET1",
         RAID_TARGET,
@@ -1787,34 +1680,15 @@ const TABLE: &[Spec] = &[
     ),
 ];
 
-/// One 1.12 binding command this client does **not** register — and the mechanism it waits on.
-///
-/// The honest tree (0997) says a command appears in [`SPECS`] only over a real engine action. That
-/// rule is right and it stays; what it never had was a way to notice when the action *arrived*.
-/// 0997's own residue promised "each returns the day its mechanism lands, one registry row" and
-/// then five mechanisms landed without their rows: the keyring (0765), the pet book (1050), the
-/// reputation and honor pages (1057-era), the six action-bar pages and the two vertical multibars
-/// (1500). Nothing was wrong with any of those commits — nothing was *watching*.
-///
-/// So the absence is written down rather than merely true, and it is written down in a form that
-/// goes stale loudly: [`needs`] names the Lua globals the reference's own binding body calls that
-/// this client does not define, and
-/// `the_absent_commands_are_still_absent` fails the day the last one lands.
+/// One 1.12 binding command this client does not register, and the mechanism it waits on; a
+/// test fails once every global in [`needs`] is defined.
 ///
 /// [`needs`]: Absent::needs
 pub(crate) struct Absent {
     /// The 1.12 command name, exactly as `Bindings.xml` spells it.
     pub name: &'static str,
-    /// Lua globals the reference's body calls that this client does not define. **This is the
-    /// falsifier**: while at least one is missing the absence is real; when they are all defined
-    /// the mechanism has landed and the row belongs in [`SPECS`].
-    ///
-    /// Empty is allowed and means *there is no Lua-global signal* — the missing mechanism is
-    /// host-side behind a global that already exists (self-cast lives behind `UseAction`'s third
-    /// argument, which the Lua passes and the host drops). Those rows carry the whole weight in
-    /// [`why`], and they are the ones to be suspicious of.
-    ///
-    /// [`why`]: Absent::why
+    /// Lua globals the reference's body calls that this client does not define; never empty, and
+    /// once all are defined the row belongs in [`SPECS`].
     #[cfg_attr(
         not(test),
         expect(
@@ -1825,7 +1699,7 @@ pub(crate) struct Absent {
         )
     )]
     pub needs: &'static [&'static str],
-    /// What would have to exist here — one line, mechanism-first.
+    /// What would have to exist, in one line.
     pub why: &'static str,
 }
 
@@ -1839,9 +1713,8 @@ macro_rules! absent {
     };
 }
 
-/// The 1.12 commands benilla does not implement, in `Bindings.xml` order — the other half of the
-/// registry, and the half that used to be invisible. `SPECS` ∪ `ABSENT` is exactly the client's
-/// 228 live bindings, asserted by [`tests::every_1_12_command_is_registered_or_recorded_absent`].
+/// The 1.12 commands benilla does not implement, in `Bindings.xml` order; with `SPECS`, exactly
+/// the client's 228 live bindings.
 pub(crate) static ABSENT: &[Absent] = &[
     // ── Movement ────────────────────────────────────────────────────────────────────────
     absent!(
@@ -1855,14 +1728,9 @@ pub(crate) static ABSENT: &[Absent] = &[
         ["PitchDownStart", "PitchDownStop"],
         "no keyboard pitch — see PITCHUP"
     ),
-    // ── Action bar ──────────────────────────────────────────────────────────────────────
-    // ── Interface ───────────────────────────────────────────────────────────────────────
     // ── Misc ────────────────────────────────────────────────────────────────────────────
-    // The nine `hidden="true" debug="true"` rows. Every one of them names an instrument benilla
-    // really has (the tri counter, the collision display, the portal draw, the perf pill) — they
-    // are absent because those instruments answer to the dev plane's chords (0702/1043), not to a
-    // binding. Whether that is right is a real question and 1745 takes it; until then the rows
-    // stay recorded rather than quietly missing.
+    // The nine `hidden="true" debug="true"` rows: benilla's instruments for these answer to the
+    // dev plane's chords, not to a binding.
     absent!(
         "TOGGLESTATS",
         ["ToggleStats"],
@@ -1909,11 +1777,8 @@ pub(crate) static ABSENT: &[Absent] = &[
         "a dev-plane instrument (1043)"
     ),
     // ── The mouse's own three (hidden) ──────────────────────────────────────────────────
-    // These are the reference's mouse-look bindings — BUTTON2 turn-or-action, BUTTON1
-    // select-or-move, CTRL-BUTTON1 the sticky variant — and they are `hidden` because the window
-    // never lists them, not because they are debug. benilla's mouse-look is hardwired in
-    // `player/camera.rs` instead, which is exactly the shape 1043 spent a decision undoing for
-    // the keyboard.
+    // The reference's mouse-look bindings (BUTTON2, BUTTON1, CTRL-BUTTON1), hidden from the
+    // window; benilla's mouse-look is hardwired in `player/camera.rs`.
     absent!(
         "TURNORACTION",
         ["TurnOrActionStart", "TurnOrActionStop"],
@@ -1930,9 +1795,7 @@ pub(crate) static ABSENT: &[Absent] = &[
         "left-button select/move is hardwired, not routed through a binding"
     ),
     // ── iTunes remote (platform="mac") ──────────────────────────────────────────────────
-    // The one place 1.12's own binding file is OS-specific: five rows carrying `platform="mac"`,
-    // the whole use of that attribute in the client. They remote the *system* music player, not
-    // the game's, and benilla has nothing to remote.
+    // 1.12's only `platform="mac"` rows; they remote the system music player, not the game's.
     absent!(
         "ITUNES_PLAYPAUSE",
         ["MusicPlayer_PlayPause"],
@@ -1964,8 +1827,6 @@ pub(crate) static ABSENT: &[Absent] = &[
 mod tests {
     use super::*;
 
-    /// Every default chord in the table parses — a typo'd token would otherwise silently ship
-    /// an unpressable default.
     #[test]
     fn every_default_chord_parses() {
         for s in SPECS {
@@ -1979,11 +1840,7 @@ mod tests {
         }
     }
 
-    /// No two commands ship the SAME default chord. One key, one command is the binding table's
-    /// own law (the steal pass in [`super::store::resolve`] enforces it at load), so a duplicate
-    /// here would ship a table that eats itself: registration order would decide the winner and
-    /// the loser would come up silently unbound. Cheap tripwire for the one mistake a new block
-    /// of rows can make — 1052's CTRL-1..CTRL-0 went in with nothing to catch a collision.
+    /// One key, one command: a duplicate default would leave the loser of the steal pass unbound.
     #[test]
     fn no_two_commands_ship_the_same_default_chord() {
         let mut seen: std::collections::HashMap<&str, &str> = std::collections::HashMap::new();
@@ -1996,7 +1853,6 @@ mod tests {
         }
     }
 
-    /// Names are unique (the table is keyed by them everywhere: files, Lua, the window).
     #[test]
     fn names_are_unique() {
         let mut seen = std::collections::HashSet::new();
@@ -2005,17 +1861,8 @@ mod tests {
         }
     }
 
-    /// **The registry against the real client's own two files.** Two columns of this table are
-    /// pure transcription from the 1.12 install, and both are load-bearing in a way nothing else
-    /// here can see: `runOnUp` — which decides whether a wheel notch delivers a release half at
-    /// all (1295), and which B265 turned entirely on — and every command's default chords. A
-    /// hand-typed table drifts; this reads the source of truth instead of trusting the typing.
-    ///
-    /// `Interface\FrameXML\Bindings.xml` carries the flag, `WTF\DefaultBindings.wtf` the chords.
-    /// Both are install content, read at runtime, never committed; the test skips (passes)
-    /// without a client, the house pattern for a real-data test. Running Blizzard's own 234-row
-    /// file through our [`benilla_ui::bindings_xml`] is a second gate riding along — that is the
-    /// parser every addon's `Bindings.xml` lands in.
+    /// Every row's `runOnUp` against the install's `Bindings.xml`, and its default chords against
+    /// `WTF\DefaultBindings.wtf`.
     #[test]
     fn the_registry_matches_the_installs_own_bindings() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -2033,8 +1880,7 @@ mod tests {
             .map(|b| (b.name.as_str(), b.run_on_up))
             .collect();
 
-        // `bind <CHORD> <COMMAND>`, in the file's own order — which is the order the command's
-        // Key 1 and Key 2 slots take.
+        // `bind <CHORD> <COMMAND>`; file order is the Key 1, Key 2 order.
         let wtf = String::from_utf8_lossy(
             &chain
                 .read_file("WTF\\DefaultBindings.wtf")
@@ -2076,20 +1922,8 @@ mod tests {
         }
     }
 
-    /// **The coverage gate** (decision 1745): every one of the client's 228 live bindings is
-    /// either in [`SPECS`] or in [`ABSENT`], and never both.
-    ///
-    /// This is the half [`the_registry_matches_the_installs_own_bindings`] could not see. That
-    /// test walks OUR rows and checks them against the install, so a command we never wrote down
-    /// is invisible to it — which is how the keyring, the pet book, the reputation and honor
-    /// pages, the six action-bar pages and the two vertical multibars all shipped their mechanism
-    /// and kept their key unbound, some of them for five hundred commits. Walking the INSTALL's
-    /// rows instead makes an unwritten command a build failure the day it becomes reachable.
-    ///
-    /// `hidden` rides along: 1.12 marks twelve bindings `hidden="true"` (the nine debug toggles
-    /// and the three mouse-look ones) and the window never lists them. This client registers none
-    /// of them, and this asserts that stays true — a hidden row in `SPECS` would be a row the
-    /// Keybindings page shows and the reference does not.
+    /// Every one of the client's 228 live bindings is in exactly one of [`SPECS`] and [`ABSENT`],
+    /// none of the twelve `hidden="true"` ones is in `SPECS`, and `SPECS` keeps the file's order.
     #[test]
     fn every_1_12_command_is_registered_or_recorded_absent() {
         let Some(reference) = install_bindings() else {
@@ -2130,8 +1964,7 @@ mod tests {
             );
         }
 
-        // The table's order IS the Keybindings page's row order, and the module claims it is the
-        // file's. It was not: TOGGLECHARACTER1/3 sat ahead of TOGGLESPELLBOOK until 1745.
+        // The table's order is the Keybindings page's row order.
         let order: Vec<&str> = reference.iter().map(|b| b.name.as_str()).collect();
         let mut at = 0usize;
         for s in SPECS {
@@ -2146,14 +1979,8 @@ mod tests {
         }
     }
 
-    /// **The staleness half.** Each [`ABSENT`] row names the Lua globals the reference's own body
-    /// calls that this client does not define; while at least one is still missing the absence is
-    /// real. When they are all defined the mechanism has landed and the row is owed to [`SPECS`] —
-    /// which is precisely the event nothing was watching for.
-    ///
-    /// "Defined" is read from source, not from a VM: a harness would have to load the whole of
-    /// FrameXML to answer, and the question here is "has anyone written it yet", which the sources
-    /// say directly. Same posture as `tests/world_api_wall.rs`.
+    /// An [`ABSENT`] row whose `needs` are all defined belongs in [`SPECS`]. "Defined" is read
+    /// from source, not from a VM.
     #[test]
     fn the_absent_commands_are_still_absent() {
         let defined = lua_globals_defined();
@@ -2179,10 +2006,8 @@ mod tests {
         }
     }
 
-    /// The absent table is well formed: unique names, and every row either carries a falsifier or
-    /// is one of the host-side ones the header calls out. The second half is not a formality — a
-    /// row with no `needs` can rot silently, so the count of them is pinned and moving it is a
-    /// deliberate act.
+    /// Unique names, a reason on every row, and no row without `needs`, which could go stale
+    /// unnoticed.
     #[test]
     fn the_absent_table_is_well_formed() {
         let mut seen = std::collections::HashSet::new();
@@ -2202,21 +2027,8 @@ mod tests {
         );
     }
 
-    /// **The scanner's own falsifier.** [`the_absent_commands_are_still_absent`] is only a gate
-    /// while `lua_globals_defined` really sees every kind of definition; a scanner that quietly
-    /// returned nothing would pass every row forever, which is the exact failure it exists to
-    /// end. So: one global of each kind that is certainly defined, and one that certainly is not.
-    ///
-    /// **There are THREE kinds since decision 1751, and this test found the third the hard way.**
-    /// `ToggleKeyRing` sat in the FrameXML row below and started failing the day the bag windows
-    /// migrated: it is defined in `ContainerFrame.lua`, which this client no longer ships — it
-    /// EXECUTES it off the player's own patch chain. The honest repair was not to swap the name
-    /// for one still in `assets/ui`; it was that the scan had gone blind to a whole store, and
-    /// blind to it in exactly the direction that matters (1751 §4 makes "ship the stock files off
-    /// the chain" the default for a NEW window, so the global that retires an ABSENT row —
-    /// `ToggleBattlefieldMinimap`, say — will appear in neither Rust nor `assets/ui`). So
-    /// `lua_globals_defined` reads the chain half of the manifest too, and `ToggleKeyRing` stays
-    /// here as the witness for it.
+    /// `lua_globals_defined` sees each store it reads and invents nothing; a blind scanner would
+    /// pass every [`ABSENT`] row.
     #[test]
     fn the_global_scanner_sees_both_kinds_of_definition() {
         benilla_formats::wow_data_or_skip!();
@@ -2227,17 +2039,16 @@ mod tests {
                 "the Rust scan missed the host registration `{host}`"
             );
         }
-        // Each is defined ONLY in `assets/ui` — the reference's own homes for them
-        // (CharacterFrame.lua, ActionBarFrame.lua, UIParent.lua) are not among the files
-        // `benilla.toc` sources, so the chain scan below cannot cover for a broken one.
+        // None of these is in `assets/ui`: `ChangeActionBarPage` is a host registration and the
+        // other two come from stock CharacterFrame.lua and UIParent.lua off the chain, so this
+        // loop does not isolate the `assets/ui` scan.
         for shipped in ["ToggleCharacter", "ChangeActionBarPage", "ShowUIPanel"] {
             assert!(
                 defined.contains(shipped),
                 "the assets/ui scan missed `{shipped}`"
             );
         }
-        // The chain half needs a client, like every other reader of install content — and the
-        // two rows above still run without one, so the test keeps its teeth either way.
+        // Stock ContainerFrame.lua's, sourced off the chain by `benilla.toc`.
         if benilla_formats::wow_data().is_some() {
             for sourced in ["ToggleKeyRing", "ToggleBag", "OpenAllBags"] {
                 assert!(
@@ -2253,13 +2064,8 @@ mod tests {
         );
     }
 
-    /// The parser's own header, read against the file it describes. `benilla_ui::bindings_xml`
-    /// quotes the shape of `Interface\FrameXML\Bindings.xml` — 228 live bindings, 94 `runOnUp`,
-    /// 13 `header`, 12 `hidden`, the commented-out `MOVEVIEW*` family that a text search counts and
-    /// a parser must not — and until 2331 the test that pinned those numbers lived beside the
-    /// parser, keyed on a `BENILLA_BINDINGS_XML` path nothing ever set, so it had never run. It
-    /// lives here because here is where the install is (`install_bindings`, off the player's own
-    /// chain); a wrong count is either a wrong file or a header that drifted from the client.
+    /// The install's `Bindings.xml` has the shape `benilla_ui::bindings_xml` documents; the
+    /// commented-out `MOVEVIEW*` family must not register.
     #[test]
     fn the_installs_bindings_xml_reads_as_the_parsers_header_says() {
         let Some(binds) = install_bindings() else {
@@ -2285,7 +2091,7 @@ mod tests {
         );
     }
 
-    /// The install's own `Bindings.xml`, parsed — `None` (and a skipped test) without a client.
+    /// The install's own `Bindings.xml`, parsed.
     fn install_bindings() -> Option<Vec<benilla_ui::bindings_xml::AddonBinding>> {
         let data = benilla_formats::wow_data_or_skip!(None);
         let mut chain = benilla_formats::open_chain(&data).expect("open the 1.12 patch chain");
@@ -2298,25 +2104,11 @@ mod tests {
         Some(benilla_ui::bindings_xml::parse(&xml).expect("Blizzard's own file parses"))
     }
 
-    /// Every Lua global this client defines, read out of its own sources — **all three stores**:
-    /// the host registrations (`g.set("Name", …)` anywhere in the workspace), our own FrameXML
-    /// port's function definitions (`function Name(` / `Name = function` inside the `<Script>`
-    /// blocks of `assets/ui`), and the reference's own FrameXML that decision 1751 executes off
-    /// the player's installed patch chain.
-    ///
-    /// The third store is not decoration. Until the bag windows migrated, "the FrameXML this
-    /// client runs" and "the files in `assets/ui`" were the same set; they are not any more, and
-    /// 1751 §4 makes the divergence grow — a NEW window ships as the stock files off the chain
-    /// plus the engine verbs they call, so the global that would retire an [`ABSENT`] row can land
-    /// without a line changing in either half this scan used to read. `benilla.toc` is the one
-    /// ordered list of both stores (a manifest entry carrying a path is the reference's file), so
-    /// it is what the chain half walks. No install ⇒ no chain half, the standard degradation.
-    ///
-    /// Deliberately syntactic and deliberately generous — a false "defined" fails the gate loudly
-    /// (it asks for a row that turns out not to work), while a false "missing" would let a landed
-    /// mechanism stay silent, which is the failure this whole gate exists to end. A reference
-    /// file's `local function name()` is therefore counted as well; that is the generous direction
-    /// on purpose.
+    /// Every Lua global this client defines, read from source: host registrations
+    /// (`g.set("Name", …)`), function definitions in `assets/ui`'s `<Script>` blocks, and the
+    /// stock files `benilla.toc` sources off the chain (none without an install). Deliberately
+    /// generous, `local function` included: a false "defined" fails loudly, a false "missing"
+    /// would hide a landed mechanism.
     fn lua_globals_defined() -> std::collections::HashSet<String> {
         fn walk(dir: &std::path::Path, ext: &str, out: &mut Vec<std::path::PathBuf>) {
             let Ok(entries) = std::fs::read_dir(dir) else {
@@ -2344,8 +2136,7 @@ mod tests {
             }
         }
 
-        /// One Lua-carrying text's own definitions — a `<Script>` block of ours or a reference
-        /// `.lua` off the chain, the same two shapes either way.
+        /// The `function Name(` and `Name = function` definitions in one Lua-carrying text.
         fn scan_lua(text: &str, names: &mut std::collections::HashSet<String>) {
             let mut rest = text;
             while let Some(i) = rest.find("function ") {
@@ -2370,10 +2161,8 @@ mod tests {
             }
         }
 
-        /// The `.lua` files an XML document pulls in through `<Script file="…"/>`. Only a script
-        /// reference ends in `.lua` — a `<Texture file=>` names art — so the extension is the
-        /// whole test, and the paths come back relative to the document's own directory, which is
-        /// how the loader resolves them (1186).
+        /// The `.lua` files an XML document pulls in through `<Script file="…"/>`, relative to the
+        /// document's directory, as the loader resolves them.
         fn script_files(text: &str) -> Vec<String> {
             let mut out = Vec::new();
             let mut rest = text;
@@ -2388,7 +2177,6 @@ mod tests {
             out
         }
 
-        // `crates/benilla-app/` → the workspace root.
         let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
             .parent()
             .and_then(|p| p.parent())
@@ -2403,8 +2191,7 @@ mod tests {
             let Ok(text) = std::fs::read_to_string(&path) else {
                 continue;
             };
-            // `.set("Name"` — the host-registration idiom, over any amount of intervening
-            // whitespace (rustfmt breaks the long ones onto their own line).
+            // `.set("Name"`, across any whitespace, as rustfmt breaks long ones onto a new line.
             let mut rest = text.as_str();
             while let Some(i) = rest.find(".set(") {
                 rest = &rest[i + ".set(".len()..];
@@ -2427,8 +2214,6 @@ mod tests {
             scan_lua(&text, &mut names);
         }
 
-        // The chain half of the manifest — the reference's own files, read the way the client
-        // reads them.
         let Some(data) = benilla_formats::wow_data() else {
             return names;
         };
@@ -2441,9 +2226,8 @@ mod tests {
             .lines()
             .map(str::trim)
             .filter(|l| !l.is_empty() && !l.starts_with('#'))
-            // The manifest's own rule for which store an entry names
-            // (`ui_script::reference_ui::is_chain_entry`): our tree is flat, so a separator is a
-            // path and a path is the reference's. The bare names were walked above.
+            // An entry with a path separator is a stock file
+            // (`ui_script::reference_ui::is_chain_entry`).
             .filter(|l| l.contains('\\') || l.contains('/'))
         {
             let Ok(bytes) = chain.read_file(entry) else {
diff --git a/crates/benilla-app/src/bindings/store.rs b/crates/benilla-app/src/bindings/store.rs
index c02fab0c..9995d7c1 100644
--- a/crates/benilla-app/src/bindings/store.rs
+++ b/crates/benilla-app/src/bindings/store.rs
@@ -1,29 +1,23 @@
-//! Binding persistence (decision 0997): `benilla-config/bindings/account.txt` and
-//! `benilla-config/bindings/<Realm>-<Char>.txt`, through [`crate::local_state`] like every resident.
-//!
-//! Format is **command-centric diff-vs-defaults** — one line per command whose keys moved:
+//! Binding persistence in `benilla-config/bindings/account.txt` and `<Realm>-<Char>.txt`: one
+//! line per command whose keys differ from its defaults.
 //!
 //! ```text
-//! # benilla key bindings (decision 0997)
+//! # benilla key bindings
 //! bind JUMP F
 //! bind MOVEFORWARD W
 //! bind TOGGLESHEATH
 //! ```
 //!
-//! `bind <COMMAND> [key...]` replaces that command's whole key list; no tokens = deliberately
-//! unbound; a command absent from the file = its registered defaults. This diverges from the
-//! reference's full-snapshot `bindings-cache.wtf` deliberately (recorded in 0997): benilla grows
-//! commands weekly, and a wholesale snapshot would ship every new command unbound to anyone with
-//! a saved file. Tokens are the canonical chord strings, which never contain spaces, so
-//! whitespace splitting is safe (`-` and `=` are key tokens, hence no sentinel for "empty" —
-//! absence of tokens is the sentinel).
+//! `bind <COMMAND> [key...]` replaces the command's key list; no tokens means unbound, an absent
+//! command keeps its defaults. Tokens are canonical chord strings and never contain spaces.
+//! Deviation: the reference saves a full snapshot (`bindings-cache.wtf`); a diff is stored
+//! because a full snapshot would leave every command added later unbound for a saved file.
 
 use std::collections::HashMap;
 
 use super::commands::SPECS;
 
-/// Serialize the live table as the diff file. `snapshot` is `(command, keys)` in registry order
-/// ([`benilla_ui::script::UiScript::keybind_snapshot`]'s shape).
+/// Serialize the live `(command, keys)` table, in registry order, as the diff file.
 pub(crate) fn to_diff(snapshot: &[(String, Vec<String>)]) -> String {
     let defaults: HashMap<&str, Vec<&str>> = SPECS
         .iter()
@@ -48,9 +42,8 @@ pub(crate) fn to_diff(snapshot: &[(String, Vec<String>)]) -> String {
     out
 }
 
-/// Parse a diff file into `(command, keys)` overrides — the shape
-/// [`benilla_ui::script::UiScript::seed_binding_set`] takes. Unknown commands are kept (a file
-/// from a newer build stays intact through load/save); malformed lines are skipped.
+/// Parse a diff file into `(command, keys)` overrides; unknown commands are kept, malformed lines
+/// skipped.
 pub(crate) fn from_diff(text: &str) -> Vec<(String, Vec<String>)> {
     let mut out = Vec::new();
     for line in text.lines() {
@@ -71,10 +64,8 @@ pub(crate) fn from_diff(text: &str) -> Vec<(String, Vec<String>)> {
     out
 }
 
-/// Resolve a diff into the **full** per-command key table (defaults with the overrides applied,
-/// steal law honored file-order) — what a stored set seeds. The steal pass matters: a file that
-/// binds `W` to JUMP must also strip `W` from MOVEFORWARD even if MOVEFORWARD has no line (older
-/// file, new default collision) — one key, one command, always.
+/// Resolve a diff into the full key table: defaults, then each override in file order stealing
+/// its keys from every other command, so one key always maps to one command.
 pub(crate) fn resolve(diff: &[(String, Vec<String>)]) -> Vec<(String, Vec<String>)> {
     let mut table: Vec<(String, Vec<String>)> = SPECS
         .iter()
@@ -98,12 +89,8 @@ pub(crate) fn resolve(diff: &[(String, Vec<String>)]) -> Vec<(String, Vec<String
         }
         match table.iter_mut().find(|(n, _)| n == name) {
             Some((_, slot)) => *slot = keys.clone(),
-            // **A name that is not in SPECS is an ADDON's command, and it is kept** (decision
-            // 1201). Dropping it here is what made an addon binding forget its key every restart:
-            // the row was written by `to_diff`, read back by `from_diff`, had its chord stolen
-            // from whoever else held it by the pass above — and was then thrown away, so the
-            // binding registered at world entry with nothing to restore. `Bindings.txt` is a flat
-            // list in the reference too; an addon's row is a row like any other.
+            // A name not in SPECS is an addon's command, registered later at world entry: keep
+            // its row so the binding has its keys to restore.
             None => table.push((name.clone(), keys.clone())),
         }
     }
@@ -116,7 +103,7 @@ mod tests {
 
     #[test]
     fn the_diff_round_trips_and_defaults_stay_silent() {
-        // All-defaults snapshot → header-only file.
+        // All defaults: a header-only file.
         let snapshot: Vec<(String, Vec<String>)> = SPECS
             .iter()
             .map(|s| {
@@ -168,8 +155,6 @@ mod tests {
 
     #[test]
     fn resolve_steals_across_commands_even_without_a_line_for_the_victim() {
-        // A file that binds W to JUMP: MOVEFORWARD keeps UP but loses W, with no MOVEFORWARD
-        // line in the file at all.
         let resolved = resolve(&[("JUMP".to_string(), vec!["W".to_string()])]);
         let fwd = &resolved.iter().find(|(n, _)| n == "MOVEFORWARD").unwrap().1;
         assert_eq!(fwd, &vec!["UP".to_string()]);
@@ -187,13 +172,7 @@ mod tests {
                 ("BOGUSCMD".to_string(), vec!["Q".to_string()]),
             ]
         );
-        // **A command the registry does not know is KEPT** (decision 1201). It used to be
-        // dropped after its keys were stolen, which was right for a genuinely bogus line and
-        // catastrophic for the case that actually occurs: an ADDON's command, whose
-        // `Bindings.xml` registers at world entry, hours after this file was read. Dropping it
-        // meant the binding registered with nothing to restore and forgot the player's chord
-        // every restart (1192 §4). The steal still happens either way, so the file's intent
-        // ("Q belongs to that command, not STRAFELEFT") holds for the commands we do have.
+        // An unknown command (an addon's, registered later) is kept, and still steals its key.
         let resolved = resolve(&parsed);
         let bogus = &resolved.iter().find(|(n, _)| n == "BOGUSCMD").unwrap().1;
         assert_eq!(bogus, &vec!["Q".to_string()]);
diff --git a/crates/benilla-app/src/blob_shadow.rs b/crates/benilla-app/src/blob_shadow.rs
index 25da649c..79857a72 100644
--- a/crates/benilla-app/src/blob_shadow.rs
+++ b/crates/benilla-app/src/blob_shadow.rs
@@ -1,91 +1,35 @@
-//! The **unit blob shadow** — the soft dark oval under every unit (the player, every NPC, every
-//! creature), the reference's per-frame shadow pass rebuilt on the shared surface-decal projector
-//! ([`benilla_world::decal`]), drawn on the shared effect stream (0733).
+//! The unit blob shadow: the dark oval under every player, NPC and creature, drawn by the
+//! reference's `0x6d7920` and rebuilt here on the shared surface-decal projector.
 //!
-//! **The mechanism** (`0x6d7920` IS the unit shadow draw):
-//! - **Draw path**: a per-frame pass over registered model nodes (`0x683dd0`, list `[0xc7cb10]`)
-//!   → gate `0x6d78f0` (model streamed, master toggle) → `0x6d7920` → the **same decal chain the
-//!   selection ring uses** (`0x6d7330 → 0x6d6fa0 → 0x6d7480`), collector flags `0x2f0122` = the
-//!   ring's `0x200122` **+ the liquid receivers** (a gap here: liquid isn't in the
-//!   [`GroundDecalSurface`] set yet — the shadow lands on terrain + WMO faces only).
-//! - **Frame slot**: PHASE 1, among the opaque drains — `0x6812c5 call 0x683dd0`, fifth of the
-//!   row `0x6812b1`–`0x6812ca` inside `0x681070`, which the driver `0x483460` calls at
-//!   `0x48361d`. `0x683dd0` is the **M2 node drain**, and the same loop body ticks each node's
-//!   object first (`0x48160c call [obj vt+0x38]` → the selection ring) and draws its shadow second
-//!   (`0x683ec3`) — so per unit the additive ring goes down and this modulate darkens it, never the
-//!   other way round. That second step is **not** a gate: both exits of the tick `0x481540` return
-//!   1, so `0x683ea5`'s `je` is dead. What the tick DOES do is write the alpha this draw is about
-//!   to read, 30 bytes later — which is the whole of §"Appearance" below. So the shadow
-//!   lands after terrain and WMO and **before** everything else: the footprint decals
-//!   (`0x483654`), the M2 opaque pass (`0x4836a6`), the water surfaces (phase 3, drawn *between*
-//!   the two M2 transparent passes) and both of those passes. Every transparent in the world
-//!   paints over it — which is what [`Rung::SHADOW_SORT`](benilla_world::sky_order::Rung) now
-//!   expresses, and what it did not until B347: at the old positive rung the shadow was the one
-//!   thing in the scene a river or a portal effect could not attenuate.
-//! - **Texture**: `Textures\ShadowBlob.blp` — a 32×32 grayscale radial blob (flat gray-160 core,
-//!   linear rim to white) under a binary alpha disc. The reference multitextures a procedural 64×8
-//!   trapezoid ramp on a second stage (`0x6d81a0`/`0x6d82d0`, blend-mode-selected); its combine
-//!   wiring is open (an apitrace question) — here the ramp is the vertex-alpha vertical fade below.
-//! - **Box law** (`0x711a20` + the `0x6d7920` corner build): a sequence CAaBox, clamped INTO ±5
-//!   per axis (a cap, never a floor), scaled by the world matrix, yaw-rotated with the unit's
-//!   facing then **axis-aligned-bounded**. Vertical about the model origin: `+1.0·(zExt/2)` up,
-//!   `−(5/3)·(zExt/2)` down. A degenerate horizontal box is the reference's no-op exit (no
-//!   shadow). **No** `OBJECT_FIELD_SCALE_X` re-read (the transform scale already carries it), no
-//!   ring-style `sqrt` compression, no floor. **WHICH sequence — settled at bytes + pixels**
-//!   (decision 0316): the draw re-reads
-//!   `playableAnimationLookup[0]` every frame — **slot 0 = Stand for characters, from the file
-//!   image, so the value never changes** (not the playing sequence: the director's gait-stable
-//!   observation falsified that first reading, and reference captures confirmed — 1,682 measured
-//!   draws, six bit-stable box sizes, HumanMale 0.9134 × 1.0805 yd permanently, Walk/Run extents
-//!   never appear). Full extents, no missing half/scale factor — the standing size IS the law.
-//! - **Appearance**: multiplicative darken — `GL_DST_COLOR/GL_ZERO` with the fade riding the
-//!   combine, which is exactly the lane's `EffectBlend::Multiply` (`dst × lerp(1, src, α)`).
-//!   Vertex diffuse is **white** with α = the model's **base** alpha — `CM2Model+0x180`, read
-//!   through the accessor `0x710ca0` (`fld [ecx+0x180]`) at `0x6d7fd6`, then clamped to `[0,1]`,
-//!   ×255, `__ftol`, packed `(a<<24)|0x00FFFFFF`. VERIFIED, and it is `+0x180` and not `+0x19c`:
-//!   over the whole draw every `0x19c` operand is the stack local `[ebp-0x19c]`, and `this` is
-//!   touched at exactly three `mov ecx,ebx; call` sites (box `0x711a20`, matrix `0x710600`,
-//!   alpha `0x710ca0`), which makes that list the complete field census.
+//! - Draw path: the per-frame model-node pass `0x683dd0` gates at `0x6d78f0` and draws through
+//!   the selection ring's decal chain (`0x6d7330 → 0x6d6fa0 → 0x6d7480`). Its collector flags
+//!   `0x2f0122` add liquid receivers to the ring's; `GroundDecalSurface` has none yet, so the
+//!   shadow lands on terrain and WMO faces only.
+//! - Frame slot: phase 1, among the opaque drains (`0x6812c5` in `0x681070`). Per unit the ring
+//!   ticks first and the shadow draws second (`0x683ec3`), so the multiply darkens the ring. It
+//!   lands after terrain and WMO and before footprints, M2 opaque, water and both M2 transparent
+//!   passes, so every transparent paints over it: `Rung::SHADOW_SORT`.
+//! - Texture: `Textures\ShadowBlob.blp`, a 32×32 grayscale radial blob under a binary alpha
+//!   disc. The reference adds a 64×8 trapezoid ramp on a second stage (`0x6d81a0`/`0x6d82d0`)
+//!   whose combine is untraced; here the ramp is a vertical vertex-alpha fade.
+//! - Box (`0x711a20`, `0x6d7920`): the `playableAnimationLookup[0]` sequence's box (Stand, fixed
+//!   per model, not the playing sequence), clamped into ±5 per axis pre-scale (a cap, never a
+//!   floor), scaled, yaw-rotated and axis-aligned-bounded. Vertically `+(h/2)` up and
+//!   `-(5/3)(h/2)` down about the origin. A zero horizontal box draws nothing.
+//! - Appearance: multiply (`GL_DST_COLOR/GL_ZERO`, `EffectBlend::Multiply`), white vertices with
+//!   alpha = the model's base alpha `CM2Model+0x180` (read at `0x6d7fd6`). That carries the
+//!   appear and despawn fades, the first-person fade and the stealth or ghost aura fade
+//!   (`0x60d180` drives the same `0x614f80`), but not the M2 colour and texture-weight tracks
+//!   (`0x707aea`), exactly like `UnitRenderAlpha`. Unlit, no fog, no depth write; the texture is
+//!   `Rgba8Unorm`, so the multiply runs on raw bytes as the reference's does.
+//! - Registration: units, players and corpses cast one; game objects and dynamic objects never do
+//!   (`0x670e94`, `0x613e10`). The reference's `shadowLOD` toggle is not built: always on.
+//! - Deviation: the shadow is gated on `InheritedVisibility`, though the reference draws one under
+//!   an undrawn body (`0x48161d`), because benilla's exterior-scene election hides units the
+//!   reference never loads, and their shadows would stay on the floor below.
 //!
-//!   **What rides in, at the bytes** (2026-09-06): the 2 s appear ramp and the despawn
-//!   ramp (`obj+0xf4`, `0x613b1e`'s `0x7d0`), the self first-person fade, **and the CharProc-14
-//!   aura transition** — stealth's `0.3`, ghost/invisibility's `0.5`. The aura is not a second
-//!   channel: `0x60d180` drives the SAME `StartAlphaFade` (`0x614f80`) the appear fade uses, and
-//!   `0x614a90` writes `model+0x180 = obj+0x100 · obj+0xf4` unconditionally given a model handle.
-//!   A stealthed unit's blob shadow dims with its body, on the same 1000 ms cubic.
-//!
-//!   **What does not**: the M2 animated colour / texture-weight tracks. The body's per-batch
-//!   alpha is `+0x19c · M2Color[i].alpha · M2TextureWeight[j].value` (`0x707aea`–`0x707b33`);
-//!   this draw reads `+0x180` raw, so an asset-authored transparency track fades the body and
-//!   leaves its shadow at full strength. [`benilla_world::model_fade::UnitRenderAlpha`] is that
-//!   same product and stops at the same place.
-//!
-//!   The darkness lives in the texture RGB. Unlit, no fog, no depth write. The texture loads as the default `WorldArt`
-//!   `Rgba8Unorm`, so the modulate multiplies raw bytes in the gamma lane — the reference's own
-//!   arithmetic (0161).
-//! - **Gating**: the reference's `shadowLOD` cvar {0,1} is the master toggle (default on) — we are
-//!   always-on; `shadowBias` (default 0.1) is its depth-bias knob — [`SHADOW_DEPTH_BIAS`] plays
-//!   that role here. No dead/mount/kind test exists on the draw path, and **which** objects
-//!   register is now settled (2026-09-06):
-//!   `[node+0x90]` bit `0x400` is `NOT(arg bit1)` (`0x670e94`), and `0x613e10` takes that arg off
-//!   `OBJECT_FIELD_TYPE` — `0xb` GAMEOBJECT, `2` DYNAMICOBJECT, `0` otherwise. **GameObjects and
-//!   DynamicObjects never cast a blob shadow; units, players and corpses always do.** Which is
-//!   the v1 policy this lane already ran (every Player/Unit with a built animated model), now a
-//!   byte-fact rather than a guess.
-//!
-//!   **One benilla divergence, deliberate.** `0x6d78f0`/`0x6d7920` read no visibility state at
-//!   all — the body's draw flag `[CM2Model+0x50]` comes from `ShouldRender` at `0x48174e`, which
-//!   is consumed at `0x48161d`, *after* the tick — so the reference can and does draw a shadow
-//!   under an undrawn body (a unit whose skin composite is still unbaked, `0x477860`). We gate on
-//!   `InheritedVisibility` anyway, because benilla's exterior-scene election is not a mechanism
-//!   the reference has and left Tanaris mobs' shadows on the Caverns of Time floor (decision
-//!   1277). Keeping that gate is the 1277 call; it is named here so it reads as a choice.
-//!
-//! One shadow record per unit, its projected triangles rebuilt only when the inputs move
-//! ([`ShadowKey`]) and pushed onto the effect stream every shown frame — an idle unit costs a
-//! key compare plus one memcpy of its cached slice. (The stream has no per-draw frustum cull;
-//! an off-screen shadow's triangles are vertex-clipped GPU-side — dozens of ~50-vert slices,
-//! below any ledger line.)
+//! Each shadow's triangles are rebuilt only when [`ShadowKey`] moves and copied onto the effect
+//! stream every shown frame.
 
 use benilla_assets::ModelAnimations;
 use benilla_protocol::EntityKind;
@@ -99,26 +43,21 @@ use benilla_world::particles::buffer::{begin_effect_frame, EffectVertex};
 use benilla_world::schedule::WorldStage;
 use benilla_world::view::WorldCamera;
 
-/// The reference's shadow disc (`Textures\ShadowBlob.blp`, created by `0x6d8070`): grayscale
-/// radial blob (gray-160 core → white rim) under a binary alpha disc, multiplied onto the ground.
+/// The reference's shadow disc, created by `0x6d8070`.
 const SHADOW_TEXTURE: &str = "mpq://textures/shadowblob.blp";
-/// The byte clamp on the animation box: each corner component is clamped INTO ±5 yd pre-scale
-/// (`0x6992c0` MAX(−5) / `0x699250` MIN(+5) — a cap on huge authored boxes, never a floor).
+/// Each box corner component is clamped into ±5 yd pre-scale (`0x6992c0`, `0x699250`).
 const BOX_CLAMP: f32 = 5.0;
-/// Degenerate-box epsilon (the reference's `[0x8029d4]` = 2.384e-7): a zero horizontal extent is
-/// the no-op exit — no shadow.
+/// The reference's degenerate-box epsilon (`[0x8029d4]`).
 const DEGENERATE_EPS: f32 = 2.384e-7;
 
-/// One unit's shadow record (a top-level entity — no render components; the cached projection
-/// rides the effect stream). Despawned when the owner goes.
+/// One unit's shadow record, a top-level entity despawned with its owner.
 #[derive(Component)]
 struct BlobShadow {
     owner: Entity,
 }
 
-/// Last frame's rebuild inputs — the projection is redone only when one moves. `surfaces` counts
-/// the [`GroundDecalSurface`] colliders: a tile streaming in under a *standing* unit changes it,
-/// re-arming the rebuild its stillness would otherwise skip.
+/// Last frame's rebuild inputs. `surfaces` counts the decal receivers, so a tile streaming in
+/// under a standing unit still re-arms the rebuild.
 #[derive(Component, Default)]
 struct ShadowKey {
     feet: Vec3,
@@ -130,13 +69,12 @@ struct ShadowKey {
     shown: bool,
 }
 
-/// The cached projection: world-space effect triangles (white × the ramp/fade alpha), pushed
-/// onto the stream every shown frame, rebuilt on [`ShadowKey`] change. Empty = hidden.
+/// The cached world-space triangles; empty when hidden.
 #[derive(Component, Default)]
 struct ShadowVerts(Vec<EffectVertex>);
 
-/// The one shadow texture (kept so the census can report the image's load state — a texture
-/// that never arrives withholds every shadow draw at the render-side residency gate, silently).
+/// The shadow texture, kept so the census can report its load state: a missing texture
+/// silently withholds every draw.
 #[derive(Resource)]
 struct ShadowAssets {
     texture: Handle<Image>,
@@ -151,11 +89,10 @@ impl Plugin for BlobShadowPlugin {
                 Update,
                 (sync_shadows, update_shadows)
                     .chain()
-                    // After net motion + input: the decal follows this frame's unit transforms.
+                    // After net motion and input, so the decal follows this frame's transforms.
                     .after(WorldStage::Input),
             )
-            // The stream push: after the frame's stream clear (the caches were rebuilt in
-            // `Update`, so this is a pure copy).
+            // After the frame's stream clear.
             .add_systems(PostUpdate, push_shadows.after(begin_effect_frame));
     }
 }
@@ -166,16 +103,13 @@ fn setup_shadow_assets(mut commands: Commands, asset_server: Res<AssetServer>) {
     commands.insert_resource(ShadowAssets { texture });
 }
 
-/// Keep one shadow record per eligible unit: spawn for new Player/Unit entities whose model has
-/// built (an animated model — [`ModelAnimations`] arrives with it), despawn orphans (owner
-/// destroyed / streamed out). The registration *policy* is still open; this is the v1 set (see
-/// module docs).
+/// Keep one shadow record per player or unit whose animated model has built; despawn the ones
+/// whose owner went. Corpses, which the reference also shadows (module docs), get none here.
 #[allow(clippy::type_complexity)] // the filtered spawn-gate query, commented inline
 fn sync_shadows(
     mut commands: Commands,
-    // A mount child never gets its own decal: its `Transform` is parent-relative (a shadow
-    // keyed on it would project at the world origin) — the mounted composite casts ONE shadow,
-    // the unit's, which reads the mount's box while mounted (`update_shadows`, decision 0441).
+    // A mount child's `Transform` is parent-relative, so it casts none; the rider's shadow reads
+    // the mount's box instead.
     units: Query<
         (Entity, &NetEntity),
         (
@@ -184,10 +118,8 @@ fn sync_shadows(
         ),
     >,
     shadows: Query<(Entity, &BlobShadow)>,
-    // The reconciler's inputs move only when a unit's animated model arrives or leaves, or a
-    // unit becomes or stops being a mount child (the `units` filter's two terms); a frame with
-    // none of those has the same answer it had last frame, and used to pay a set build plus a
-    // walk of every unit for it.
+    // The answer changes only when a model or a mount arrives or leaves; any other frame is
+    // skipped.
     grew: Query<(), Added<ModelAnimations>>,
     mut shrank: RemovedComponents<ModelAnimations>,
     mounted: Query<(), Added<crate::entities::mount::MountBody>>,
@@ -202,7 +134,6 @@ fn sync_shadows(
     }
     let mut shadowed = EntityHashSet::default();
     for (entity, shadow) in &shadows {
-        // Owner gone or no longer eligible (model torn down) → the decal goes with it.
         if units.get(shadow.owner).is_err() {
             commands.entity(entity).despawn();
         } else {
@@ -230,7 +161,6 @@ fn update_shadows(
     shadow_assets: Option<Res<ShadowAssets>>,
     images: Res<Assets<Image>>,
     decals: WorldDecal,
-    // The unit's render alpha, asked of the unit — see the alpha block below.
     unit_alpha: benilla_world::model_fade::UnitRenderAlpha,
     owners: Query<
         (
@@ -238,24 +168,17 @@ fn update_shadows(
             &ModelAnimations,
             Has<Embodied>,
             Option<&crate::entities::mount::MountChild>,
-            // …and whether the owner is drawn at all. A body the exterior-scene election sent to
-            // pass 2 is not in the reference's scene, so it casts nothing (decision 1277). The
-            // election writes the ROOT's `Visibility`; this is that verdict after propagation.
+            // The exterior-scene election's verdict on the root, after propagation.
             Option<&InheritedVisibility>,
         ),
         Without<BlobShadow>,
     >,
-    // The mounted box source: the composite's one shadow reads the MOUNT's Stand box at the
-    // mount's rendered scale while a mount model is attached (the mount IS the footprint on the
-    // ground; the rider's box would undersize it). The mount-vs-body source of the client's own
-    // shadow box is untraced — this is the named approximation of decision 0441's P2, carried
-    // until that source is known.
+    // Mounted, the shadow reads the mount's Stand box at the mount's scale; which box the
+    // reference uses for a mounted unit is untraced.
     mount_anims: Query<(&NetEntity, &ModelAnimations), With<crate::entities::mount::MountBody>>,
     mut shadows: Query<(&BlobShadow, &mut ShadowKey, &mut ShadowVerts)>,
-    // Once-a-second census at debug level (`RUST_LOG=benilla_app::blob_shadow=debug` — the lib
-    // target is `benilla_app`; a `benilla::` filter silently matches nothing): how many
-    // shadows exist and why the hidden ones hid — the first question of any "no shadow under X"
-    // report, answerable from a log instead of a debugger.
+    // A once-a-second census of shadows and why the hidden ones hid, at
+    // `RUST_LOG=benilla_app::blob_shadow=debug` (a `benilla::` filter matches nothing).
     mut census_at: Local<f32>,
 ) {
     let now = time.elapsed_secs();
@@ -265,40 +188,30 @@ fn update_shadows(
     }
     let (mut n_total, mut n_shown, mut n_no_owner, mut n_no_clip, mut n_degen, mut n_no_ground) =
         (0u32, 0u32, 0u32, 0u32, 0u32, 0u32);
-    // Counted apart from `n_no_owner`: a body the exterior election sent to pass 2 HAS an owner,
-    // and folding the two would make the census answer "why did it hide" with a lie. This is the
-    // instrument's whole job (decision 1283).
+    // Apart from `n_no_owner`: an undrawn body still has an owner.
     let mut n_undrawn = 0u32;
     let surface_count = decals.receiver_count();
     for (shadow, mut key, mut verts) in &mut shadows {
         n_total += 1;
         let Ok((unit, anims, is_self, mount_child, drawn)) = owners.get(shadow.owner) else {
-            // sync_shadows despawns next frame; keep it cleared meanwhile.
+            // `sync_shadows` despawns it next frame.
             hide(&mut key, &mut verts);
             n_no_owner += 1;
             continue;
         };
-        // An owner that is not drawn casts nothing. The director's report from inside Caverns of
-        // Time (decision 1277): the exterior election had correctly stopped drawing the Tanaris
-        // mobs overhead, and their shadows carried on being projected onto the cavern floor,
-        // because this lane keys off the unit's `Transform` and never asked whether the unit was
-        // in the scene. The census counts it separately, so "why is there a shadow with no
-        // creature" is answerable from the log rather than from a debugger.
+        // The visibility deviation (module docs): an undrawn owner casts nothing.
         if !drawn.is_none_or(|v| v.get()) {
             hide(&mut key, &mut verts);
             n_undrawn += 1;
             continue;
         }
-        // Mounted: the box and the extra scale column come from the mount child (the
-        // `mount_anims` doc above); until its model lands, the rider's own box carries the frame.
+        // Until the mount's model lands, the rider's own box stands in.
         let (anims, extra_scale) = match mount_child.and_then(|mc| mount_anims.get(mc.0).ok()) {
             Some((mnet, manims)) => (manims, mnet.scale),
             None => (anims, 1.0),
         };
-        // The byte+pixel law (0316): the box is playableAnimationLookup[0]'s
-        // sequence — Stand, permanently (the reference re-reads it per frame from the file image;
-        // the value can't change). resolve(0) walks the same baked table, so Stand-less models
-        // land on their substitute exactly like the binary's row-0 fast path.
+        // The box is `playableAnimationLookup[0]`'s sequence, Stand, fixed per model; `resolve(0)`
+        // walks the same table, so a Stand-less model gets the reference's substitute.
         let stand = catalog.as_deref().map_or(0, |c| anims.resolve(0, &c.0).id);
         let clip = anims.find(stand);
         let Some(clip) = clip else {
@@ -306,7 +219,7 @@ fn update_shadows(
             n_no_clip += 1;
             continue;
         };
-        // The box law (see module docs): clamp INTO ±5 pre-scale, scale, yaw-rotate + AA-bound.
+        // Clamp into ±5 pre-scale, then scale.
         let s = (unit.scale.x * extra_scale).max(0.0);
         let bmin = clip
             .bounds_min
@@ -322,21 +235,8 @@ fn update_shadows(
             n_degen += 1;
             continue;
         }
-        // **The unit's render alpha, asked of the unit** — the shadow rides the model's fade slot
-        // (module docs), so it takes the engine's answer rather than reconstructing one.
-        //
-        // It used to gather the live `RenderFade`s off this unit's *part* entities and read "no
-        // part is fading" as `1.0`. That is true of a settled unit and exactly backwards for the
-        // state a unit spends its whole arrival in: a streamed unit holds `PendingAppearFade` —
-        // no `RenderFade` anywhere yet — until the world is actually shown, so its parts are
-        // deliberately invisible while this walk found nothing to attribute and drew the shadow
-        // **fully opaque**. A dark oval on the ground under no creature for the length of the
-        // load (2.9 s on a probe login), snapping to zero the instant the ramp armed, then easing
-        // back in with the body. `UnitRenderAlpha` asks the root, where `UnitAppearFade` tells
-        // pending from settled — the distinction a part-side walk cannot make.
-        //
-        // The self first-person fade comes with it (the reference rides the same slot), which is
-        // why there is no `is_self` term here any more.
+        // The unit's render alpha from the root, which also tells a pending appear fade (zero)
+        // from a settled unit, and carries the first-person fade.
         let alpha = unit_alpha.get(shadow.owner);
         if alpha <= 0.0 {
             hide(&mut key, &mut verts);
@@ -355,9 +255,8 @@ fn update_shadows(
             n_shown += 1;
             continue;
         }
-        // Horizontal: the model box's 4 rect corners through the unit's rotation with the
-        // vertical column dead (`rot × (x, 0, z)`, XZ taken — the byte build zeroes the z-terms),
-        // then axis-aligned-bounded.
+        // The four horizontal corners through the rotation with the vertical term zeroed, as
+        // the reference's build does, then axis-aligned-bounded.
         let (mut min_x, mut max_x) = (f32::MAX, f32::MIN);
         let (mut min_z, mut max_z) = (f32::MAX, f32::MIN);
         for (x, z) in [
@@ -370,8 +269,7 @@ fn update_shadows(
             (min_x, max_x) = (min_x.min(w.x), max_x.max(w.x));
             (min_z, max_z) = (min_z.min(w.z), max_z.max(w.z));
         }
-        // Vertical about the model origin: `+1.0·(zExt/2)` up, `−(5/3)·(zExt/2)` down (the byte
-        // constants `[0xcea60c]`/`[0xcea610]`).
+        // Vertically `+(h/2)` up, `-(5/3)(h/2)` down (`[0xcea60c]`, `[0xcea610]`).
         let half_v = (bmax.y - bmin.y) * 0.5;
         let frame = DecalFrame {
             center: unit.translation,
@@ -391,10 +289,8 @@ fn update_shadows(
                 &mut verts.0,
                 &frame,
                 |p| {
-                    // The trapezoid ramp over the vertical span (the reference's second texture
-                    // stage, `0x6d81a0`: rise x<2, flat, fall x≥10 over x = 12·u). *Interim
-                    // seat*: that the ramp runs vertically is inferred from the box's asymmetric
-                    // vertical reach; the combine wiring is the flagged apitrace item.
+                    // The reference's second-stage ramp (`0x6d81a0`), run vertically: inferred
+                    // from the asymmetric vertical reach, its combine being untraced.
                     alpha * shadow_ramp((p.y - frame.min_y) / span_v)
                 },
                 |x, z| frame.rect_uv(x, z),
@@ -408,10 +304,8 @@ fn update_shadows(
             n_no_ground += 1;
         }
         if census && is_self {
-            // The census's self row: where the OWN shadow's projection actually went — the
-            // "shadow missing under me" report's second question (the first is the gate line
-            // below). Y-extents vs feet split "landed on the surface I stand on" from "fell
-            // through to a receiver below" in one read.
+            // Where the own shadow's projection went: vertex y against feet y tells the surface
+            // stood on from a receiver below.
             let (mut y_min, mut y_max) = (f32::MAX, f32::MIN);
             let (mut x_min, mut x_max) = (f32::MAX, f32::MIN);
             let (mut z_min, mut z_max) = (f32::MAX, f32::MIN);
@@ -423,8 +317,7 @@ fn update_shadows(
                 z_min = z_min.min(v.pos[2]);
                 z_max = z_max.max(v.pos[2]);
             }
-            // World-XZ extents of what was actually emitted vs the frame rect: if these disagree,
-            // the projector inflated/displaced the box (the -8844,669 hunt).
+            // Emitted XZ extents against the frame rect: a mismatch indicts the projector.
             debug!(
                 "self shadow world span: x [{:.3}, {:.3}] ({:.3}), z [{:.3}, {:.3}] ({:.3}); \
                  feet ({:.3}, {:.3}), yaw {:.1} deg",
@@ -451,17 +344,14 @@ fn update_shadows(
                 y_min,
                 y_max
             );
-            // The -8844,669 hunt's uv probe: a span check alone can't see a DEGENERATE mapping
-            // (all uv.y at the rim still spans 0..1) — print the actual per-vert uv pairs.
+            // Per-vertex uvs: a span check cannot see a degenerate mapping.
             let uvs: Vec<String> = verts
                 .0
                 .iter()
                 .map(|v| format!("({:.3},{:.3})", v.uv[0], v.uv[1]))
                 .collect();
             debug!("self shadow uvs: {}", uvs.join(" "));
-            // And the box/rect numbers: measured on the reference client, HumanFemale's
-            // footprint is 0.77x0.74 yd nearly centred; a bigger or offset rect indicts the box
-            // math, not the projector.
+            // On the reference, HumanFemale's footprint is 0.77x0.74 yd, nearly centred.
             debug!(
                 "self shadow box: bmin {:?} bmax {:?} rect x [{:.3}, {:.3}] z [{:.3}, {:.3}] \
                  (extent {:.3}x{:.3}, centre offset ({:.3}, {:.3}))",
@@ -479,8 +369,7 @@ fn update_shadows(
         }
     }
     if census && n_total > 0 {
-        // Not just "loaded": the CONTENT. A white-decoded blob multiplies to a no-op — an
-        // invisible shadow whose every draw-side reading looks healthy (the -8844,669 hunt).
+        // The texture's content, not just its load: a white-decoded blob multiplies to nothing.
         let tex = shadow_assets.map_or("no-resource".into(), |a| {
             images.get(&a.texture).map_or("MISSING".into(), |img| {
                 let (w, h) = (img.width(), img.height());
@@ -492,8 +381,7 @@ fn update_shadows(
                         d.get(i..i + 4).map(|p| format!("{p:?}"))
                     })
                     .unwrap_or_else(|| "no-data".into());
-                // The -8844,669 hunt: the whole centre ROW, not one texel — the ink radius and
-                // alpha reach decide how much of the box the disc visibly fills.
+                // The whole centre row: how much of the box the disc visibly fills.
                 if let Some(d) = img.data.as_ref() {
                     let row: Vec<String> = (0..w as usize)
                         .map(|x| {
@@ -516,9 +404,8 @@ fn update_shadows(
     }
 }
 
-/// Push every shown shadow's cached triangles onto the stream — one Multiply draw per unit at
-/// the shadow rung (the pre-water decal band's floor, the module header's frame slot), fog off:
-/// the reference's shadow pass state.
+/// Push every shown shadow onto the stream: one multiply draw per unit at the shadow rung, fog
+/// off, the reference's shadow pass state.
 fn push_shadows(
     assets: Option<Res<ShadowAssets>>,
     cam: Query<Entity, With<WorldCamera>>,
@@ -531,8 +418,7 @@ fn push_shadows(
         if verts.0.is_empty() {
             continue;
         }
-        // Multiply: the modulate decal is its own darkening — the scene light is already in the
-        // ground it multiplies, which is why the lane's unlit default is right here.
+        // Unlit: the scene light is already in the ground it multiplies.
         let mut batch = draw
             .batch(cam, assets.texture.id())
             .multiply()
@@ -547,14 +433,13 @@ fn push_shadows(
     }
 }
 
-/// Clear the record and drop the cache key so the next eligible frame rebuilds from scratch.
+/// Clear the record so the next eligible frame rebuilds.
 fn hide(key: &mut ShadowKey, verts: &mut ShadowVerts) {
     key.shown = false;
     verts.0.clear();
 }
 
-/// Did any rebuild input move beyond noise? Position/box at a millimetre, rotation at ~0.05°,
-/// alpha at under a colour step.
+/// Whether an input moved beyond noise: a millimetre, ~0.05°, under one colour step.
 fn key_changed(a: &ShadowKey, b: &ShadowKey) -> bool {
     const POS_EPS: f32 = 1e-3;
     a.feet.distance_squared(b.feet) > POS_EPS * POS_EPS
@@ -565,8 +450,8 @@ fn key_changed(a: &ShadowKey, b: &ShadowKey) -> bool {
         || a.surfaces != b.surfaces
 }
 
-/// The reference's trapezoid alpha ramp (`0x6d81a0`/`0x6d82d0`: `x = 12·u` — rise `x<2 → x/2`,
-/// flat `2≤x<10 → 1`, fall `x≥10 → (12−x)/2`, clamped at 0).
+/// The reference's trapezoid alpha ramp (`0x6d81a0`/`0x6d82d0`): over `x = 12u`, `x/2` below 2,
+/// 1 through 10, `(12-x)/2` after.
 fn shadow_ramp(u: f32) -> f32 {
     let x = 12.0 * u.clamp(0.0, 1.0);
     if x < 2.0 {
@@ -582,8 +467,7 @@ fn shadow_ramp(u: f32) -> f32 {
 mod tests {
     use super::*;
 
-    /// The ramp's byte-verified shape: rise to 1 at x=2 (u=1/6), flat through x=10 (u=5/6), fall
-    /// to 0 at x=12 (u=1).
+    /// Rise to 1 at u=1/6, flat through u=5/6, fall to 0 at u=1.
     #[test]
     fn ramp_matches_reference_trapezoid() {
         assert_eq!(shadow_ramp(0.0), 0.0);
@@ -598,13 +482,13 @@ mod tests {
         assert_eq!(shadow_ramp(2.0), 0.0);
     }
 
-    /// The box law: clamp INTO ±5 pre-scale (a cap, not a floor), then scale.
+    /// The ±5 clamp is a pre-scale cap, not a floor.
     #[test]
     fn box_clamp_caps_pre_scale() {
         let raw = Vec3::new(-7.0, 0.0, 3.0);
         let clamped = raw.clamp(Vec3::splat(-BOX_CLAMP), Vec3::splat(BOX_CLAMP));
         assert_eq!(clamped, Vec3::new(-5.0, 0.0, 3.0));
-        // A scale-2 unit's clamped box still doubles — the cap is pre-scale.
+        // A scale-2 unit's clamped box still doubles.
         assert_eq!(clamped * 2.0, Vec3::new(-10.0, 0.0, 6.0));
     }
 }
diff --git a/crates/benilla-app/src/bowstring.rs b/crates/benilla-app/src/bowstring.rs
index ff3d0467..432069aa 100644
--- a/crates/benilla-app/src/bowstring.rs
+++ b/crates/benilla-app/src/bowstring.rs
@@ -1,44 +1,31 @@
-//! The engine-drawn **bowstring**: bow M2s carry NO string geometry — the real client registers a
-//! bow-only per-frame draw callback (`0x611ff0`) that spans the bow's `$WTT`/`$WTB` limb-tip event
-//! markers with a **2-segment line list**, middle vertex at the character's HandArrow attach while
-//! the nock latch (`[+0xd58] & 0x4000`) holds, else the tip midpoint — so the string tracks the
-//! draw hand while nocked and relaxes to a straight chord at rest.
+//! The engine-drawn bowstring: bow M2s have no string geometry. The reference's per-frame callback
+//! (`0x611ff0`) draws a two-segment line between the `$WTT`/`$WTB` limb-tip markers, its middle
+//! vertex at the HandArrow attach while the nock latch (`[+0xd58] & 0x4000`) holds, else the tip
+//! midpoint. Drawn here as gizmo lines; the color and width are inferred, since the reference's
+//! packed vertex color is not decoded.
 //!
-//! Benilla's transcription draws the two segments through Bevy's gizmo lines — the same
-//! immediate-mode screen-space-width primitive class as the client's GX lines. Named
-//! deviation (decision record): the string color/width are inferred (the callback emits a
-//! packed vertex color that is not decoded — a dark cord is used).
-//!
-//! **The tips are POSED** (decision 2281). The bow prop animates — `$BWP` arms BowPull(160) on the
-//! prop's own model and `$BWR` returns it to Stand(0) — so the `$WTT`/`$WTB` markers ride limb
-//! bones that bend through the draw. Composing them through the prop's rigid root frame instead
-//! (which is all this file could do while the prop rested at bind pose) leaves the chord pinned to
-//! the un-bent limb tips while the mesh around it moves: the string would visibly leave the bow.
+//! The tips are posed: `$BWP` plays BowPull (160) on the prop and `$BWR` returns it to Stand (0),
+//! so the markers ride limb bones that bend through the draw.
 
 use bevy::prelude::*;
 
 use crate::creature_anim::NockLatch;
 use crate::entities::BoneAttach;
 
-/// The HandArrow attach id (35 — `0x6121b8`): the string's middle control point while nocked,
-/// the same point the nocked-arrow model rides.
+/// The HandArrow attach id (35, `0x6121b8`): the string's middle point while nocked.
 const HAND_ARROW: u16 = 0x23;
 
-/// Marks a spawned **bow prop root** (the held-item child of the hand joint) whose model authors
-/// the `$WTT`/`$WTB` string anchors. Inserted by the held-item attach; despawned with the prop
-/// (a sheath change / weapon swap tears the prop down, which is the client's clear too).
+/// Marks a bow prop root whose model authors the `$WTT`/`$WTB` anchors; despawned with the prop.
 #[derive(Component)]
 pub(crate) struct Bowstring {
-    /// The unit wearing the bow — the HandArrow middle vertex and nock latch live on it.
+    /// The unit wearing the bow, which carries the HandArrow attach and the nock latch.
     pub(crate) owner: Entity,
-    /// The `$WTT` top / `$WTB` bottom anchors as `(bone, model-local Bevy offset)` — the bone is
-    /// load-bearing on an animated prop (see the module note): the limb tips move with the draw.
+    /// The `$WTT` top and `$WTB` bottom anchors as `(bone, model-local offset)`.
     pub(crate) top: (u16, Vec3),
     pub(crate) bottom: (u16, Vec3),
 }
 
-/// Draw every visible bow's string (per frame, post-propagation so the prop/joint frames are
-/// this frame's). Two segments: tip → middle → tip.
+/// Draws every visible bow's string, tip to middle to tip, from this frame's joint frames.
 fn draw_bowstrings(
     bows: Query<(
         &Bowstring,
@@ -54,30 +41,25 @@ fn draw_bowstrings(
     joints: Query<&GlobalTransform>,
     mut gizmos: Gizmos,
 ) {
-    // A dark waxed-cord tone, inferred: the ref's packed vertex color is not decoded.
+    // Inferred: the reference's packed vertex color is not decoded.
     const STRING_COLOR: Color = Color::srgb(0.12, 0.10, 0.08);
     for (bs, prop, vis, flex) in &bows {
         if !vis.get() {
             continue;
         }
-        // The prop's own pose when it flexes (`joints_root` IS this entity, so its
-        // `GlobalTransform` is the frame `posed_point` wants); its rigid frame otherwise, which is
-        // the same answer for a bow standing at bind pose.
+        // The prop's own pose when it flexes (`joints_root` is this entity); its rigid frame
+        // otherwise.
         let tip = |(bone, offset): (u16, Vec3)| {
             flex.and_then(|p| p.posed_point(prop, bone, offset))
                 .unwrap_or_else(|| prop.transform_point(offset))
         };
         let top = tip(bs.top);
         let bottom = tip(bs.bottom);
-        // The middle control point: the owner's HandArrow attach world position while the nock
-        // latch holds (the drawn string follows the hand), else the relaxed straight chord.
         let middle = owners
             .get(bs.owner)
             .ok()
             .filter(|(_, _, latched)| *latched)
             .and_then(|(bones, pose, _)| {
-                // A pure position read — `posed_point` off the composed pose, no anchor entity
-                // (decision 1355).
                 let &(bone, offset) = bones.points.get(&HAND_ARROW)?;
                 pose.posed_point(joints.get(pose.joints_root).ok()?, bone, offset)
             })
@@ -87,9 +69,7 @@ fn draw_bowstrings(
     }
 }
 
-/// Registers the string drawer after the palette pass (the middle vertex reads the HandArrow
-/// joint's frame — its translation is palette-invariant, but same-frame ordering keeps every
-/// consumer of joint frames on one side of the rewrite).
+/// Registers the string drawer after the palette pass, beside the other joint-frame readers.
 pub(crate) struct BowstringPlugin;
 
 impl Plugin for BowstringPlugin {
diff --git a/crates/benilla-app/src/camera_shake.rs b/crates/benilla-app/src/camera_shake.rs
index b5f56132..493fbb00 100644
--- a/crates/benilla-app/src/camera_shake.rs
+++ b/crates/benilla-app/src/camera_shake.rs
@@ -1,55 +1,16 @@
-//! **Camera shake** — the thump a heavy creature's footfall puts through the camera, the one-off
-//! jolt as its body lands, and the jolt a spell effect puts through it (B298; decisions 1540/1849).
+//! Camera shake: a heavy creature's footfall, its death thud, and spell effects, all spawned
+//! through the reference's one spawner, `AddShake(id, worldPos)` (`0x511d40`).
 //!
-//! **Four producers, two id spaces, one evaluator.** Every producer ends at the same spawner —
-//! `AddShake(id, worldPos)` (`0x511d40`), whose five call sites are the whole population (proven by
-//! xref sweep: no address-dword reference to it anywhere, and no Lua, console, cinematic or quake
-//! path).
+//! `CreatureModelData.FootstepShakeSize` (field 11, on the visual footfall tags, not `$FSD`) and
+//! `DeathThudShakeSize` (field 12, on `$DTH`) name a `CameraShakes.dbc` preset. `SpellVisualKit`
+//! field 14 and the `$SHK` event name a `SpellEffectCameraShakes.dbc` group of up to three.
 //!
-//! The **creature** pair names a `CameraShakes.dbc` preset **directly**:
-//!
-//! - **`CreatureModelData.FootstepShakeSize`** (field 11) → fired from the **visual** footfall
-//!   channel — the per-foot plant tags (`$FL0`/`$FR0`/`$RL0`/`$RR0`…), the same stream
-//!   [`crate::footprints`] reads. **Not `$FSD`**, which is the sound handler's alone.
-//! - **`CreatureModelData.DeathThudShakeSize`** (field 12) → the same table, fired on `$DTH`.
-//!
-//! The **spell** pair names a `SpellEffectCameraShakes.dbc` **group** — up to three presets at one
-//! point ([`benilla_formats::SpellShakeGroup`]):
-//!
-//! - **`SpellVisualKit` field 14** (`kit+0x38`, the `ShakeID` column) → once per kit play, via
-//!   [`SpellKitShake`] and [`fire_kit_shakes`], which carries the mechanism and the one deviation.
-//! - **the `$SHK` animation event** → its payload *is* a group id, fired ungated at the event's own
-//!   bone-transformed point — the fired key's own, carried on the event (decision 1904).
-//!
-//! **`$SHK` is decoded by exactly two handlers**, hanging off the GameObject (typemask `0x20`,
-//! `0x5f3e20`) and DynamicObject (`0x40`, `0x5d58c0`) trampolines — the dword `0x4b485324` occurs
-//! twice image-wide, and of the six dispatchers `0x7133a0` registers only those two decode it.
-//! **`CGUnit_C::HandleAnimEvent` is not one of them**, so a `$SHK` on a creature M2 logs
-//! `UNHANDLEDANIMEVENT` and does nothing — which is not academic: CryptLord and Thunderaan both
-//! author markers on their death/emerge clips and the reference plays neither. That gate is why no
-//! creature shake can be `$SHK`-driven, and it is enforced in [`fire_shakes`].
-//!
-//! Only 25 of the 430 shipped models carry a footstep shake, and the set is exactly the
-//! thumping-giant list; 49 carry one of the two, and 58 of the 1772 kits carry a shake group. See
-//! `benilla-extract shakecensus`, which maps all four producers onto the 24 presets.
-//!
-//! ## The law
-//!
-//! **Emission — the footstep**, gated in this order (`0x5fbf70`): not hovering · `BYTES_1` byte 3
-//! bit `0x2` clear (our stealth bit) · not a player-ghost · **`|camera − footplant|² ≤ 2500`
-//! (50 yd)**. The shake sits *outside* the `showfootprints` CVar gate and *outside* the 25 yd gate
-//! that follows it, so it reaches twice as far as a footprint decal and does not turn off with
-//! them. The position is the planted foot's world point, exactly as the decal derives it.
-//!
-//! **Emission — the death thud** (`0x625c30`): **no gates at all** — no hover, no ghost, no
-//! distance, no CVar — at the unit's own world position.
-//!
-//! **Per live record, per frame** (`0x511760`/`0x5116e0`):
+//! Per live record, per frame (`0x511760`/`0x5116e0`):
 //!
 //! ```text
-//! t = (now − start) + phase                 // seconds; phase is a TIME pre-roll, not an angle
-//! if !(t < duration) → retire
-//! A = amplitude / 36                        // the DBC column is inches; yards on the wire out
+//! t = (now − start) + phase                 // seconds; phase is a time pre-roll, not an angle
+//! if !(t < duration) → retire               // a hard cutoff, no taper
+//! A = amplitude / 36                        // the DBC column is inches
 //! d² = |eye − pos|²                         // pos is snapshotted at spawn
 //! if d² > 6400 → contribute nothing (the record survives)
 //! if d² >   81 → A *= 0.7^((√d² − 9) / 9)
@@ -57,45 +18,9 @@
 //! if shake_type == 1 → a *= exp(−coefficient · t)
 //! ```
 //!
-//! Three corrections to the conventional column map, all from the consumer: **`Phase` is a time
-//! pre-roll in seconds**, not an angle — it advances the sine *and* the decay, and shortens the
-//! real life to `duration − phase`; **`Duration` is a hard cutoff with no taper**, so a
-//! `shake_type == 0` row is cut off mid-swing at full strength; and **`ShakeType` is a one-bit
-//! decay switch**, not a type — `== 1` exactly enables the `exp` envelope, and `Coefficient` is
-//! that rate in 1/s and is dead data on every `shake_type == 0` row. The decay is base **e**.
-//!
-//! **What moves.** A pure world-space **translation of the eye** — no rotation, no FOV change; the
-//! look-at target is rebuilt as `eye + forward`, so it rides along. `Direction` selects an axis in
-//! the **followed unit's body frame**, re-read every frame, which is why turning the player
-//! rotates an in-flight horizontal shake:
-//!
-//! | `direction` | reference (WoW axes) | ours (Bevy) |
-//! |---|---|---|
-//! | 0 | `(a·cos φ, a·sin φ, 0)` | `a ·` forward |
-//! | 1 | `(−a·sin φ, a·cos φ, 0)` | `a ·` left |
-//! | 2 | `(0, 0, a)` | `a ·` up |
-//!
-//! (`bevy = (−wow.y, wow.z, −wow.x)` — decision 0002 — and our yaw about `+Y` equals the WoW
-//! facing, so axis 0/1 land exactly on the unit's forward/left.) **Every creature row is
-//! `direction = 2`**, so in practice a footstep shake is purely vertical; the other two axes are
-//! reachable only from the spell-side table and are implemented for completeness. Axes 0 and 1 are
-//! *not* independent — both sum into the horizontal plane.
-//!
-//! **Combination.** Three slots, one per axis, each keeping the single strongest live shake — same-axis
-//! shakes do **not** sum, the losers are dropped outright, and at most three shakes play in a frame.
-//! This is what a spell **group** is shaped for: its three slots name the `direction` 0·1·2 members
-//! of one preset family, so they land on three different axes and all three contribute. They are
-//! slots and not axes, though — group 4 is `15 · 14 · 15`, and the duplicate loses the tie-break.
-//! Ties keep the incumbent, and the walk is oldest→newest, so ties keep the **older** record.
-//!
-//! **Lifetime.** A record holds a *snapshot* position and no reference to its source, so a shake
-//! fully outlives the creature that spawned it. The whole evaluation is skipped — offset zero,
-//! nothing expiring — while the **followed unit** (the far-sight subject when there is one, our own
-//! body otherwise) is **swimming** or riding a **fly-or-swim spline**: the reference's two suspend
-//! gates, both of which jump the same block.
-//!
-//! Not modelled, deliberately: the reference's second wholesale free on `SetTarget(nullptr)`, and
-//! its destructor's unlink-without-free (a shipped leak — our `Vec` cannot reproduce it).
+//! The result translates the eye along an axis of the followed unit's body frame (`direction` 0
+//! forward, 1 left, 2 up), re-read every frame. Each axis keeps only its strongest live shake, so
+//! same-axis shakes never sum.
 
 use std::f32::consts::TAU;
 
@@ -114,34 +39,33 @@ use benilla_protocol::EntityKind;
 use benilla_world::schedule::WorldStage;
 use benilla_world::view::WorldCamera;
 
-/// Beyond this the record contributes nothing but is **not** retired (`0x5116e9`, `80 yd²`).
+/// Beyond 80 yd a record contributes nothing but is not retired (`0x5116e9`).
 const CULL_DISTANCE_SQ: f32 = 6400.0;
-/// Inside this the shake plays at full authored strength (`9 yd²`).
+/// Inside 9 yd a shake plays at full authored strength.
 const FULL_DISTANCE_SQ: f32 = 81.0;
-/// The falloff's half-life base and its per-9-yd exponent divisor.
+/// Beyond 9 yd the amplitude falls by 0.7 per 9 yd.
 const FALLOFF_BASE: f32 = 0.7;
 const FALLOFF_SPAN: f32 = 9.0;
-/// `CameraShakes.Amplitude` is authored in inches; the client scales it at spawn (`0x511d78`).
+/// `CameraShakes.Amplitude` is in inches; the client scales it at spawn (`0x511d78`).
 const INCHES_TO_YARDS: f32 = 1.0 / 36.0;
 
-/// One live shake: the authored row, where it happened, and when it started.
+/// One live shake.
 struct LiveShake {
     row: CameraShake,
-    /// World position, **snapshotted at spawn** — the record never looks at its source again.
+    /// World position, snapshotted at spawn: a shake outlives the unit that spawned it.
     pos: Vec3,
     /// App-clock seconds at spawn.
     start: f32,
 }
 
-/// The live shake set and the eye offset it composes for this frame.
+/// The live shake set.
 #[derive(Resource, Default)]
 pub(crate) struct CameraShakes {
     live: Vec<LiveShake>,
 }
 
 impl CameraShakes {
-    /// Enqueue a shake at a world point. The row is copied in whole — the DBC is the only source
-    /// of shape, and nothing downstream re-reads the catalog.
+    /// Enqueue a shake at a world point.
     fn add(&mut self, row: CameraShake, pos: Vec3, now: f32) {
         self.live.push(LiveShake {
             row,
@@ -150,12 +74,9 @@ impl CameraShakes {
         });
     }
 
-    /// Enqueue a whole `SpellEffectCameraShakes` **group** at a world point — the spell side's
-    /// only spawn shape (`0x6ecb40`, byte-read 2026-09-02): walk the three slots `+0x4/+0x8/+0xc`
-    /// in ascending order, skip the zeros, and `AddShake(id, pos)` each. A slot the preset table
-    /// does not carry is dropped by the same bounds check the reference makes (`0x511d40`'s
-    /// `cmp ecx,[maxId]`); a group naming the same preset twice (group 4 is `15 · 14 · 15`)
-    /// enqueues it twice and the duplicate simply loses [`Self::evaluate`]'s strict-`>` tie-break.
+    /// Enqueue a `SpellEffectCameraShakes` group (`0x6ecb40`): its three slots in order, zeros
+    /// skipped, a preset the table lacks dropped (`0x511d40`'s bounds check). A slot repeated
+    /// (group 4 is `15 · 14 · 15`) enqueues twice and the copy loses the tie-break.
     fn add_group(
         &mut self,
         group: &SpellShakeGroup,
@@ -168,25 +89,17 @@ impl CameraShakes {
         }
     }
 
-    /// Retire what has expired and compose this frame's offset.
-    ///
-    /// `suspended` is the reference's skip — **two** gates that both jump the same block
-    /// (`0x50ea87` / `0x50ea8b` → `0x50eb01`): the followed unit
-    /// is **swimming** (`[[unit+0x118]+0x40] & 0x200000`), or it is riding a **flying server
-    /// spline** (`MI = [[unit+0x118]+0xa4]` non-null, not done, Flying bit set) — a taxi flight.
-    /// The accumulator is zeroed *before* both gates, so a suspended frame yields the offset zero
-    /// **and expires nothing**: a shake resumes mid-flight on surfacing or landing, rather than
-    /// having quietly aged out while the camera was not reading it.
+    /// Retire what has expired and compose this frame's offset. A suspended frame (`0x50ea87`,
+    /// `0x50ea8b` → `0x50eb01`) yields zero and expires nothing, so a shake resumes afterwards.
     fn evaluate(&mut self, eye: Vec3, facing_yaw: f32, now: f32, suspended: bool) -> Vec3 {
         if suspended {
             return Vec3::ZERO;
         }
-        // Retire on the *unattenuated* clock: distance decides contribution, never lifetime.
+        // Distance decides contribution, never lifetime.
         self.live.retain(|s| s.elapsed(now) < s.row.duration);
 
-        // One slot per axis, each holding (compare key, signed value). The walk is oldest→newest
-        // and the compare is strict, so a tie keeps the older record — the reference's own
-        // `jne`-skips-the-write shape.
+        // One (compare key, signed value) slot per axis; walked oldest first with a strict
+        // compare, so a tie keeps the older record, as the reference does.
         let mut slots: [Option<(f32, f32)>; 3] = [None; 3];
         for s in &self.live {
             let Some((key, value)) = s.sample(eye, now) else {
@@ -194,15 +107,15 @@ impl CameraShakes {
             };
             let axis = s.row.direction as usize;
             let Some(slot) = slots.get_mut(axis) else {
-                continue; // direction ≥ 3 writes nothing (and corrupts the reference's frame)
+                continue; // direction ≥ 3 writes nothing
             };
             if slot.is_none_or(|(best, _)| key > best) {
                 *slot = Some((key, value));
             }
         }
 
-        // Axis 0/1 are the followed unit's forward/left, 2 is world up (module doc's table). Our
-        // yaw about +Y is the WoW facing, so forward is exactly `(−sin, 0, −cos)`.
+        // Axes 0/1 are the followed unit's forward/left, 2 is world up; our yaw about +Y is the
+        // WoW facing.
         let (sin, cos) = facing_yaw.sin_cos();
         let forward = Vec3::new(-sin, 0.0, -cos);
         let left = Vec3::new(-cos, 0.0, sin);
@@ -212,16 +125,13 @@ impl CameraShakes {
 }
 
 impl LiveShake {
-    /// Seconds into the shake, including `phase` — which is a **time pre-roll**, so it advances
-    /// both the sine and the decay and shortens the real life to `duration − phase`.
+    /// Seconds into the shake, `phase` included, so the real life is `duration − phase`.
     fn elapsed(&self, now: f32) -> f32 {
         (now - self.start) + self.row.phase
     }
 
-    /// This record's `(compare key, signed offset)` at `eye`, or `None` when out of cull range.
-    ///
-    /// The compare key is the **distance-attenuated amplitude** — a per-record quantity that does
-    /// not swing with the sine — the stored slot the reference compares at `0x5118a5`.
+    /// This record's `(compare key, signed offset)` at `eye`; the key is the distance-attenuated
+    /// amplitude, which the reference compares at `0x5118a5`.
     fn sample(&self, eye: Vec3, now: f32) -> Option<(f32, f32)> {
         let d2 = eye.distance_squared(self.pos);
         if d2 > CULL_DISTANCE_SQ {
@@ -233,7 +143,7 @@ impl LiveShake {
         }
         let t = self.elapsed(now);
         let mut value = amp * (TAU * self.row.frequency * t).sin();
-        // `shake_type == 1` exactly — the one-bit decay switch, base e, rate in 1/s.
+        // `shake_type == 1` exactly: base-e decay, `coefficient` in 1/s.
         if self.row.shake_type == 1 {
             value *= (-self.row.coefficient * t).exp();
         }
@@ -247,13 +157,8 @@ impl Plugin for CameraShakePlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<CameraShakes>()
             .add_systems(Startup, load_shakes.after(AssetSet::Open))
-            // Present, like the footprints and the footstep sounds: the same event stream, after
-            // the frame's animation drive and transforms have settled the foot bones.
-            //
-            // Capture-gated in step with the applier ([`crate::player`] schedules that one). The
-            // pairing is not cosmetic: the applier is what retires expired records, so an emitter
-            // still running while it is gated off would push a record per footfall that nothing
-            // ever reaps — a slow leak across a long capture.
+            // Capture-gated with the applier (in `crate::player`), which is what retires
+            // records: an emitter running without it would leak a record per footfall.
             .add_systems(
                 Update,
                 (fire_shakes, fire_kit_shakes)
@@ -313,34 +218,27 @@ fn fire_shakes(
         let thud = &ev.ident == b"$DTH";
         let shk = &ev.ident == b"$SHK";
         if !thud && !shk && footfall_side(&ev.ident).is_none() {
-            continue; // `$FSD` is the sound handler's; only the VISUAL channel shakes
+            continue; // `$FSD` is the sound handler's; only the visual channel shakes
         }
         let Ok((net, transform)) = units.get(ev.entity) else {
             continue;
         };
         if shk {
-            // `$SHK`: the payload is a **group** id, and the tag is decoded by exactly two
-            // handlers — the GameObject (`0x5f3e20`, typemask 0x20) and DynamicObject
-            // (`0x5d58c0`, 0x40) dispatchers. `CGUnit_C::HandleAnimEvent` decodes no `$SHK`
-            // (the dword occurs twice image-wide), so a creature's marker is inert and this gate
-            // is what keeps it that way: CryptLord and Thunderaan both author one on their
-            // death/emerge clips, and the reference plays neither.
+            // `$SHK` names a group; only the GameObject (`0x5f3e20`) and DynamicObject
+            // (`0x5d58c0`) handlers decode it, so on a creature it does nothing.
             if !matches!(net.kind, EntityKind::GameObject | EntityKind::DynamicObject) {
                 continue;
             }
             let Some(group) = shakes.0.group(ev.data) else {
-                continue; // a payload the group table lacks — the reference bounds-checks too
+                continue; // a payload the group table lacks; the reference bounds-checks too
             };
-            // **No gates at all** — no distance, visibility, CVar or state test (the sibling
-            // `$DSL` arm and the footstep path both have them; this one has none). The position is
-            // the event's own bone-transformed point, not the object's origin.
+            // No gates; at the event's own bone-transformed point, not the object's origin.
             let at = ev.pos.unwrap_or_else(|| transform.translation());
             live.add_group(group, &shakes.0, at, now);
             continue;
         }
-        // The shake reads the ROOT unit's own model row — a mount's row is never stored there, so
-        // a rider on a kodo gets the kodo's *footprints* and not its shake (`0x607a00` writes only
-        // the decal fields). The root is also where the state gates live.
+        // The root unit's own model row and state: a rider gets its mount's footprints but not
+        // its shake (`0x607a00` writes only the decal fields).
         let mut root = ev.entity;
         while let Ok(child_of) = parents.get(root) {
             root = child_of.parent();
@@ -356,17 +254,18 @@ fn fire_shakes(
                 creatures.footstep_shake(d)
             }
         }) else {
-            continue; // the overwhelming majority of models shake nothing
+            continue; // most models shake nothing
         };
         let Some(row) = shakes.0.get(id) else {
             continue;
         };
         if thud {
-            // No gates whatsoever, and the unit's own world position — not a bone.
+            // The death thud (`0x625c30`): no gates, at the unit's own position, not a bone.
             live.add(*row, transform.translation(), now);
             continue;
         }
-        // The footstep's three state gates, in the reference's order.
+        // The footstep gates in the reference's order (`0x5fbf70`): hover, stealth, ghost, then
+        // 50 yd from the camera, outside the `showfootprints` gate.
         if movement.is_some_and(|m| m.flags & move_flags::HOVER != 0) {
             continue;
         }
@@ -375,10 +274,8 @@ fn fire_shakes(
                 continue;
             }
         }
-        // The planted foot: the FIRED key's own point, resolved once by the scanner exactly as
-        // the kernel snapshots it (decision 1904), not a by-4CC re-find of the marker table. The
-        // difference is real — 75 shipped models author some 4CC more than once at different
-        // points — and it is the same quantity the decal derives.
+        // The fired key's own point, as the decal derives it: 75 shipped models author some
+        // 4CC more than once.
         let foot = ev.pos.unwrap_or_else(|| transform.translation());
         if footfall_culls(eye, foot) {
             continue;
@@ -387,26 +284,12 @@ fn fire_shakes(
     }
 }
 
-/// Fire the camera shake a spell-visual kit's field 14 names — the **spell-side producer**
-/// (decision 1849), the counterpart of `crate::sound::spell`'s kit-sound route.
+/// Fire the shake group a spell-visual kit's field 14 names, once per kit play, with no stage test
+/// and no cancel (`0x620e11`, or `0x60f4e6` when the play created no effect node).
 ///
-/// One shake per kit play, unconditionally: the reference reaches it from the first-created effect
-/// node's one-time arm pass (`0x620e11`, gated on that node's flags snapshot carrying bit `0x10`)
-/// and falls back to the kit tail (`0x60f4e6`) only when the play created no node at all. Neither
-/// site tests the stage, and there is no cancel path — a shake outlives its kit.
-///
-/// **One deliberate deviation, and it is the whole reason this doc paragraph exists.** The
-/// reference's primary site passes `&node+0x48` — a position field the bone-attached node
-/// constructor `0x61fdd0` **never writes**, and which the site that would write it (`0x62101d`)
-/// fills twelve instructions *later*, for the sound. So in the real client a kit whose first
-/// created node is bone-attached shakes at `(0, 0, 0)` and is culled by the 80 yd cut: **26 of the
-/// 58 shipped shake kits are silently dead**, including every summon (kit 138) and Goblin Sapper
-/// Charge (1424). That is a read-before-write of a zero-initialised field, not a design — the
-/// value it wants is unambiguous, being the same one the sound leg uses a moment later — so we
-/// spawn at the kit play's real position and the authored data plays. benilla implements the
-/// mechanism, not the quirk (`docs/METHOD.md` §3, `docs/METHOD.md` step 3); the reference's own numbers are
-/// in `decisions/1849`, and reverting to them would mean deliberately modelling an uninitialised
-/// field we do not have.
+/// The shake spawns at the kit play's position. The reference reads `&node+0x48` before
+/// `0x62101d` writes it, so a bone-attached first node (`0x61fdd0`) shakes at the origin and is
+/// culled, silencing 26 of the 58 shipped shake kits; that read-before-write is not copied.
 fn fire_kit_shakes(
     mut events: MessageReader<SpellKitShake>,
     time: Res<Time>,
@@ -430,67 +313,33 @@ fn fire_kit_shakes(
             SpellKitShake::PlayAt { pos, group } => (group, pos),
         };
         let Some(row) = shakes.0.group(group) else {
-            continue; // a kit naming a group the table lacks — none ship, the bounds check is the
-                      // reference's own (`0x6ecb4d`)
+            continue; // a group the table lacks; the reference bounds-checks too (`0x6ecb4d`)
         };
         live.add_group(row, &shakes.0, at, now);
     }
 }
 
-/// The applier's read of the followed unit: its facing (the shake's body frame), its move flags
-/// (the swim half of the reference's skip) and its live path (the spline half).
+/// The followed unit's facing, move flags and live path.
 type FollowedUnit = (
     &'static Transform,
     Option<&'static MovementState>,
     Option<&'static Spline>,
 );
 
-/// Is the whole shake block skipped this frame? The reference's two suspend gates, OR'd — both
-/// `jmp` past the same block (`0x50ea87` / `0x50ea8b` → `0x50eb01`), on the **followed unit**.
-///
-/// **Swimming** is its move flags (`[[unit+0x118]+0x40] & 0x200000`).
-///
-/// **The spline gate** is read through to the LIVE path, exactly as the anim selector's `unify`
-/// does ([`crate::creature_anim`], `0x5fd19c`) — the reference re-reads
-/// `[[unit+0x118]+0xa4]` every frame rather than trusting a stamped flag, and our stored
-/// [`MovementState::flying`] is the selector's own derived value, left `false` on the controller's
-/// component. The [`Spline`]'s *presence* is the reference's "descriptor non-null **and** not done"
-/// (`sample_splines` removes the component the frame the path completes — the `& 0x4` DONE term),
-/// and `!grounded` is spline flag `0x200`.
-///
-/// **`0x200` is the shared fly-*or*-swim spline bit, not "taxi"** (`0x616cb0`) —
-/// so this arm covers a swimming server path as well as a flight, which is the same reason it
-/// sits beside a swim gate at all. Naming it "the taxi arm" (as 1540 did, and as this was first
-/// built) over-specifies what the bit means. A **ground** spline — Charge, knockback, a fleeing
-/// walk, all of which install the same component — does not suspend anything.
+/// The reference's two suspend gates on the followed unit (`0x50ea87`, `0x50ea8b`): swimming
+/// (move flag `0x200000`), or a live, not-done spline (`[[unit+0x118]+0xa4]`) carrying `0x200`,
+/// the shared fly-or-swim bit (`0x616cb0`). A ground spline such as Charge does not suspend.
 fn suspended(mv: Option<&MovementState>, spline: Option<&Spline>) -> bool {
     mv.is_some_and(|m| m.flags & move_flags::SWIMMING != 0) || spline.is_some_and(|s| !s.grounded)
 }
 
-/// Add this frame's shake to the camera's seated eye.
+/// Add this frame's shake to the seated eye.
 ///
-/// Filtered on [`WorldCamera`], never on `Camera3d`: the portrait booths are `Camera3d`s too, and a
-/// bare `Camera3d` query here would shake an off-screen booth — the same trap that once yanked the
-/// booths to the scenario eye and blanked every portrait. `WorldCamera` and `FlyCam` sit on the one
-/// entity `control` seats, which is the entity this must add to.
-///
-/// Runs **after** the camera is seated, which is what makes the falloff honest: `control` rewrites
-/// the base pose every frame, so the transform this reads is the un-shaken eye rather than last
-/// frame's shaken one. A zero offset writes nothing at all, preserving the camera's bit-equality
-/// no-op gate (decision 1362) — a still camera stays bit-stable and its propagation stays quiet.
-///
-/// **The body frame and both suspend gates come from the FOLLOWED unit** — `[cam+0x88/0x8c]` in
-/// the reference, never `0x468550` (the active player). Ordinarily they are the same object; under
-/// far sight (Mind Vision, Eye of Kilrogg, and possession, which rides the same field) they are
-/// not, and the camera orbits the subject while our body walks on somewhere else. Reading our own
-/// body there would frame the shake on the wrong facing and suspend it on the wrong unit's swim
-/// state. [`ViewSubject`] already resolves exactly this object for the rig.
-///
-/// The reference additionally requires the followed object to be **TYPEMASK_UNIT**
-/// (`0x50e90d`–`0x50e92c`) before reading its `CMovement` at all. That falls out here: the
-/// fallback is our own body, and a resolved far-sight subject with no [`MovementState`] and no
-/// [`Spline`] — a GameObject or a DynamicObject — reads as "not suspended", which is what a
-/// unit-only gate on a non-unit yields.
+/// Filtered on [`WorldCamera`], never `Camera3d`: the portrait booths are `Camera3d`s too. Runs
+/// after the camera is seated, so it reads the un-shaken eye, and a zero offset writes nothing so
+/// a still camera stays bit-stable. The body frame and suspend gates come from the followed unit
+/// (`[cam+0x88/0x8c]`, the far-sight subject when there is one), never the active player; a
+/// non-unit subject reads as not suspended, as the reference's unit-only gate (`0x50e90d`) does.
 pub(crate) fn apply_camera_shake(
     mut live: ResMut<CameraShakes>,
     time: Res<Time>,
@@ -521,7 +370,7 @@ pub(crate) fn apply_camera_shake(
 mod tests {
     use super::*;
 
-    /// `CameraShakes.dbc` row **1** — the Ancient Protector's / kodo's footstep, verbatim.
+    /// `CameraShakes.dbc` row 1, the kodo's footstep, verbatim.
     const FOOTSTEP_1: CameraShake = CameraShake {
         id: 1,
         shake_type: 1,
@@ -532,7 +381,7 @@ mod tests {
         phase: 0.06,
         coefficient: 1.0,
     };
-    /// Row **2** — the Ancient of Lore/War, the giants and the dragons. Amplitude 7.0.
+    /// Row 2, the giants' and dragons' footstep.
     const FOOTSTEP_2: CameraShake = CameraShake {
         amplitude: 7.0,
         ..FOOTSTEP_1
@@ -549,41 +398,35 @@ mod tests {
         at(row, Vec3::ZERO).evaluate(Vec3::X * d, 0.0, t, false).y
     }
 
-    /// `Phase` is a **time pre-roll in seconds**, not an angle: at `t = 0` the sine is already
-    /// advanced to `2π·f·phase`. Row 1 opens at `sin(2π·3·0.06) = +0.905`, so a footstep kicks the
-    /// eye UP first — the verdict's own observable.
+    /// Row 1 opens at `sin(2π·3·0.06) = +0.905`, so a footstep kicks the eye up first.
     #[test]
     fn phase_is_a_time_preroll_and_the_first_kick_is_upward() {
         let expected = (2.0 / 36.0) * (TAU * 3.0 * 0.06).sin() * (-0.06f32).exp();
         let got = vertical(FOOTSTEP_1, 0.0, 0.0);
         assert!((got - expected).abs() < 1e-6, "{got} vs {expected}");
         assert!(got > 0.0, "the first kick is UP, not down: {got}");
-        // Read as an angle instead, the opening sample would be sin(0.06) ≈ 0.06 — 15× smaller.
         let as_angle = (2.0 / 36.0) * 0.06f32.sin();
         assert!(got > as_angle * 10.0, "phase must not be read as an angle");
     }
 
-    /// `Phase` also shortens the real life: the record retires at `elapsed + phase >= duration`.
     #[test]
     fn phase_shortens_the_life() {
         let mut s = at(FOOTSTEP_1, Vec3::ZERO);
-        // 0.33 s in: 0.33 + 0.06 = 0.39 < 0.4, still alive.
+        // 0.33 + 0.06 = 0.39 < 0.4: alive.
         assert!(s.evaluate(Vec3::ZERO, 0.0, 0.33, false).y != 0.0);
         assert_eq!(s.live.len(), 1);
-        // 0.35 s in: 0.41 >= 0.4 — gone, a full 0.05 s before its nominal duration.
+        // 0.35 + 0.06 = 0.41 >= 0.4: gone.
         assert_eq!(s.evaluate(Vec3::ZERO, 0.0, 0.35, false), Vec3::ZERO);
         assert!(s.live.is_empty(), "retired at duration − phase");
     }
 
-    /// `Duration` is a hard cutoff with **no taper** — a `shake_type == 0` row is still at full
-    /// authored strength on its last frame. (The creature rows all decay; this is the spell shape.)
     #[test]
     fn duration_is_a_cutoff_not_a_taper() {
         let undecayed = CameraShake {
             shake_type: 0,
             phase: 0.0,
             duration: 1.0,
-            frequency: 0.25, // a quarter-cycle at t = 1 → sine near its peak
+            frequency: 0.25, // a quarter cycle at t = 1: the sine's peak
             ..FOOTSTEP_1
         };
         let last = vertical(undecayed, 0.0, 0.999);
@@ -599,7 +442,6 @@ mod tests {
         );
     }
 
-    /// The decay is base **e** at `coefficient` 1/s, and only when `shake_type == 1`.
     #[test]
     fn the_decay_switch_is_one_bit() {
         let t = 0.2;
@@ -620,8 +462,6 @@ mod tests {
         );
     }
 
-    /// Full strength inside 9 yd; `0.7^((d−9)/9)` beyond; **nothing past 80 yd — but the record
-    /// survives**, so walking back into range resumes it.
     #[test]
     fn the_distance_falloff_culls_without_retiring() {
         let near = vertical(FOOTSTEP_2, 0.0, 0.0);
@@ -641,28 +481,24 @@ mod tests {
         assert_eq!(s.live.len(), 1, "culled, not retired");
     }
 
-    /// Same-axis shakes do **not** sum — the strongest wins outright — and the key is the
-    /// distance-attenuated amplitude, so a tie keeps the OLDER record.
     #[test]
     fn same_axis_shakes_do_not_sum() {
         let mut s = CameraShakes::default();
         s.add(FOOTSTEP_1, Vec3::ZERO, 0.0); // amplitude 2
-        s.add(FOOTSTEP_2, Vec3::ZERO, 0.0); // amplitude 7 — wins
+        s.add(FOOTSTEP_2, Vec3::ZERO, 0.0); // amplitude 7, wins
         let both = s.evaluate(Vec3::ZERO, 0.0, 0.0, false).y;
         let alone = vertical(FOOTSTEP_2, 0.0, 0.0);
         assert!(
             (both - alone).abs() < 1e-6,
             "the loser is dropped, not added: {both} vs {alone}"
         );
-        // A tie keeps the incumbent, which is the older — the reference's jne-skips-the-write.
         let mut t = CameraShakes::default();
         t.add(FOOTSTEP_1, Vec3::ZERO, 0.0);
-        t.add(FOOTSTEP_1, Vec3::X * 40.0, 0.0); // same row, further away ⇒ strictly smaller key
+        t.add(FOOTSTEP_1, Vec3::X * 40.0, 0.0); // same row, farther: a smaller key
         assert_eq!(t.evaluate(Vec3::ZERO, 0.0, 0.0, false).y, alone / 3.5);
     }
 
-    /// `Direction` is an axis in the followed unit's **body frame**: 2 is up, 0 is forward, 1 is
-    /// left — so turning the player rotates an in-flight horizontal shake.
+    /// 2 is up, 0 is forward, 1 is left, so turning rotates an in-flight horizontal shake.
     #[test]
     fn direction_selects_the_body_frame_axis() {
         let up = at(FOOTSTEP_1, Vec3::ZERO).evaluate(Vec3::ZERO, 0.0, 0.0, false);
@@ -691,8 +527,7 @@ mod tests {
         assert!(l.y.abs() < 1e-7 && l.z.abs() < 1e-6 && l.x < 0.0, "{l:?}");
     }
 
-    /// The three spell rows a `SpellEffectCameraShakes` group names, one per axis — group 1's
-    /// `4 · 5 · 6`, verbatim.
+    /// Group 1's presets `4 · 5 · 6`, one per axis, verbatim.
     const SPELL_4: CameraShake = CameraShake {
         id: 4,
         shake_type: 0,
@@ -717,7 +552,7 @@ mod tests {
         ..SPELL_4
     };
 
-    /// A catalog holding the three spell presets plus the two groups the tests below name.
+    /// The three spell presets and the groups the tests below name.
     fn spell_catalog() -> CameraShakeCatalog {
         CameraShakeCatalog::default()
             .with_row(SPELL_4)
@@ -728,21 +563,18 @@ mod tests {
                 id: 1,
                 slots: [4, 5, 6],
             })
-            // Group 3's shape: one populated slot, two zeros.
+            // Group 3's shape: one slot, two zeros.
             .with_group(SpellShakeGroup {
                 id: 3,
                 slots: [6, 0, 0],
             })
-            // A group naming a preset the table lacks, beside one it has — the reference's own
-            // bounds check drops the first and keeps the second.
+            // A preset the table lacks, beside one it has.
             .with_group(SpellShakeGroup {
                 id: 9,
                 slots: [4, 999, 0],
             })
     }
 
-    /// A **group** is the spell side's whole spawn shape: three slots walked in order, zeros
-    /// skipped, each landing on its own axis — so one group play moves the eye on all three.
     #[test]
     fn a_group_spawns_one_shake_per_populated_slot() {
         let table = spell_catalog();
@@ -750,14 +582,14 @@ mod tests {
         s.add_group(table.group(1).unwrap(), &table, Vec3::ZERO, 0.0);
         assert_eq!(s.live.len(), 3, "one record per populated slot");
 
-        // A quarter-second in, all three axes are moving: 4 → forward, 5 → left, 6 → up.
+        // 4 → forward, 5 → left, 6 → up.
         let at = 0.25;
         let offset = s.evaluate(Vec3::ZERO, 0.0, at, false);
         assert!(
             offset.z != 0.0 && offset.x != 0.0 && offset.y != 0.0,
             "{offset:?}"
         );
-        // And each axis carries exactly its own preset's value — the slots do not sum.
+        // Each axis carries only its own preset's value.
         assert_eq!(
             offset.y,
             vertical(SPELL_6, 0.0, at),
@@ -765,8 +597,7 @@ mod tests {
         );
     }
 
-    /// Zeros are skipped and a slot the preset table does not carry is dropped — the reference's
-    /// own `test/je` and its `cmp ecx,[maxId]`. Neither is an error; both just contribute nothing.
+    /// The reference's own `test/je` and `cmp ecx,[maxId]`.
     #[test]
     fn a_group_skips_zero_slots_and_unknown_presets() {
         let table = spell_catalog();
@@ -780,9 +611,7 @@ mod tests {
         assert_eq!(dangling.live[0].row.id, 4);
     }
 
-    /// The shipped groups 4 and 7 name the **same preset twice** (`15 · 14 · 15`), which is the
-    /// proof the three slots are slots and not axes. Both records spawn; the duplicate loses the
-    /// strict-`>` tie-break, so the axis reads exactly as it would with one.
+    /// The shipped groups 4 and 7 name a preset twice (`15 · 14 · 15`).
     #[test]
     fn a_duplicate_slot_spawns_but_never_doubles_the_offset() {
         let table = spell_catalog();
@@ -805,7 +634,6 @@ mod tests {
         );
     }
 
-    /// A `direction` the reference cannot index writes nothing (rather than panicking on our side).
     #[test]
     fn an_out_of_range_direction_contributes_nothing() {
         let bad = CameraShake {
@@ -818,8 +646,6 @@ mod tests {
         );
     }
 
-    /// A suspended frame bypasses the whole block: zero offset, and **nothing expires** — the
-    /// shake resumes on surfacing (or on landing off a taxi).
     #[test]
     fn swimming_freezes_rather_than_retires() {
         let mut s = at(FOOTSTEP_1, Vec3::ZERO);
@@ -829,9 +655,6 @@ mod tests {
         assert!(s.live.is_empty(), "and it retires the moment we surface");
     }
 
-    /// The two suspend gates are independent and either one alone suspends — and a **ground**
-    /// spline (a charge, a knockback, a fleeing walk) is not one of them: only spline flag
-    /// `0x200`, the shared fly-or-swim bit, is.
     #[test]
     fn either_gate_suspends_and_a_ground_spline_does_not() {
         let swimming = MovementState {
diff --git a/crates/benilla-app/src/char_create/mod.rs b/crates/benilla-app/src/char_create/mod.rs
index 48e6cc10..075ca2f9 100644
--- a/crates/benilla-app/src/char_create/mod.rs
+++ b/crates/benilla-app/src/char_create/mod.rs
@@ -1,21 +1,6 @@
-//! The character-creation screen — the v1 glue overlay (decision 0423, phase 4).
-//!
-//! A disposable Bevy-UI screen (the same register as [`crate::char_select`], not GlueXML — the
-//! faithful glue arc is 0193's) arranged like the reference client's `CharacterCreate.xml` and
-//! driving the live preview booth ([`crate::portrait`]'s `"create"` slot): the left tower holds the
-//! faction-bannered race grid, the gender pair, the per-race class grid (only the CharBaseInfo-valid
-//! classes, like the ref), the five appearance dials (ranges data-derived per (race, sex) —
-//! [`crate::entities::CharCreate`]; labels per-race via the ChrRaces customization tokens), and
-//! Randomize; the right stack quotes the GlueStrings faction/race/class paragraphs; the model floats
-//! center over the page (transparent booth); name + Accept/Back sit along the bottom. The real art,
-//! captions, and click sounds come from the player's own client data ([`art`]'s `GlueArt`,
-//! [`crate::glue_strings::GlueStrings`], [`crate::sound::GlueSound`]) — never embedded. Every
-//! `SMSG_CHAR_CREATE` result maps to its 1.12 GlueStrings text in the status line; a success
-//! re-enums (phase 1) and returns to select with the new row armed.
-//!
-//! The module is split by concern: [`art`] (client-data art + the frozen tables), [`parts`] (the
-//! component vocabulary), [`widgets`] (the glue button shapes), [`screen`] (the authored layout),
-//! [`refresh`] (the systems driving it), and this file (state, input, wire).
+//! The character-creation screen: a Bevy-UI overlay laid out like the 1.12 `CharacterCreate.xml`,
+//! driving the `"create"` preview booth, with art, captions and sounds read from the player's
+//! install. This file holds the selection state, input and the wire.
 
 mod panels;
 mod parts;
@@ -38,24 +23,19 @@ use crate::net::{CharActionResultMessage, CharPick, CharRequest};
 use crate::portrait::{CreateLook, GlueLook, GluePreview};
 use crate::sound::GlueSound;
 
-/// Alliance / Horde race columns, top to bottom — the order the reference screen shows
-/// (director's screenshot, 2026-07-19). `CharacterCreate.lua`'s `CharacterCreateEnumerateRaces`
-/// fills `CharacterCreateRaceButton1..8` in the order the engine's `GetAvailableRaces()` returns,
-/// and `CharacterCreate.xml` chains buttons 1–4 down column A from (33,−68) with button 5 anchored
-/// right of button 1 (+46) and 6–8 chained below it — so the flat engine order fills Alliance then
-/// Horde, ascending race id within each. (`RACE_ICON_TCOORDS` is a name→UV lookup; its literal table
-/// order never reaches layout — reading it as the button order is what got this wrong before.)
+/// Alliance and Horde race columns, top to bottom: `CharacterCreateEnumerateRaces` fills buttons
+/// 1..8 in `GetAvailableRaces()` order and `CharacterCreate.xml` chains 1-4 down the first column,
+/// 5-8 down the second, so Alliance then Horde, ascending race id. `RACE_ICON_TCOORDS`'s table
+/// order is a name-to-UV lookup and never the layout order.
 ///
-/// `pub(crate)` on the Alliance half because it is also the race→side split
-/// `ui_unit::race_faction_group` answers `UnitFactionGroup("player")` with during world entry —
-/// one home for the mapping, pinned by [`tests::race_columns_match_the_reference_screen`], rather
-/// than a second copy that can disagree with this one.
+/// The Alliance half is also the race-to-side split `ui_unit::race_faction_group` answers
+/// `UnitFactionGroup("player")` with.
 pub(crate) const ALLIANCE: [u8; 4] = [1, 3, 4, 7]; // Human, Dwarf, Night Elf, Gnome
 const HORDE: [u8; 4] = [2, 5, 6, 8]; // Orc, Scourge, Tauren, Troll
-/// The ref's initial model facing (`SetCharacterCreateFacing(-15)`), reset on every race switch.
+/// The reference's initial facing (`SetCharacterCreateFacing(-15)`), reset on every race switch.
 const INITIAL_FACING: f32 = -15.0 * std::f32::consts::PI / 180.0;
 
-/// The character-creation subsystem (decision 0423): the screen + its selection state.
+/// The character-creation screen and its selection state.
 pub(crate) struct CharCreatePlugin;
 
 impl Plugin for CharCreatePlugin {
@@ -89,10 +69,8 @@ impl Plugin for CharCreatePlugin {
     }
 }
 
-/// The end-to-end create instrument (`WOW_CHARCREATE_NAME=<name>`, decision 0423): a few seconds
-/// after the create screen is up, fill the name and fire Create — so the whole screen → wire →
-/// server → result → back-to-select path is verifiable headlessly (pair with `WOW_CHARCREATE_SHOT=1`
-/// to reach the screen). Inert without the env; fires once.
+/// `WOW_CHARCREATE_NAME=<name>`: a few seconds after the screen is up, fill the name and fire
+/// Create once, exercising the whole create path unattended (pair with `WOW_CHARCREATE_SHOT=1`).
 fn debug_auto_create(
     mut sel: ResMut<CreateSelection>,
     pick: Res<CharPick>,
@@ -110,7 +88,7 @@ fn debug_auto_create(
     let now = time.elapsed_secs();
     let start = *armed_at.get_or_insert(now);
     if now - start < 6.0 {
-        return; // let the model settle + the socket park
+        return; // let the model settle and the socket park
     }
     sel.name.set_text(&name);
     sel.creating = true;
@@ -119,8 +97,7 @@ fn debug_auto_create(
     info!("char create: auto-create fired for {:?}", sel.name.text);
 }
 
-/// The screen-shot instrument (`WOW_CHARCREATE_SHOT=1`, decision 0423): jump to the create screen a
-/// few seconds after boot so a live shot / eyeball reaches it without a click. Inert without the env.
+/// `WOW_CHARCREATE_SHOT=1`: jump to the create screen a few seconds after boot, without a click.
 fn debug_enter(
     state: Res<State<ClientState>>,
     mut next: ResMut<NextState<ClientState>>,
@@ -137,12 +114,8 @@ fn debug_enter(
     }
 }
 
-/// The shot instrument's race/sex/class pick (`WOW_CHARCREATE_PICK="race,sex[,class]"`): applied
-/// once as soon as the create screen is up (after its enter reset), so a probe shot can capture any
-/// race's scene — the ref comparisons are per-race. The optional third field picks the class, which
-/// selects the starting outfit the preview wears (decision 0527) — so an A/B of the same race at two
-/// classes machine-checks the dressing path. An out-of-range class for the race is ignored (the
-/// race's first class stands). Inert without the env.
+/// `WOW_CHARCREATE_PICK="race,sex[,class]"`: applied once the screen is up, after its enter reset;
+/// a class the race may not be is ignored.
 fn debug_pick(
     state: Res<State<ClientState>>,
     catalog: Option<Res<CharCreate>>,
@@ -163,8 +136,6 @@ fn debug_pick(
     let mut it = spec.split(',').map(|s| s.trim().parse::<u8>().ok());
     sel.race = it.next().flatten().unwrap_or(1).max(1);
     sel.sex = it.next().flatten().unwrap_or(0).min(1);
-    // `clamp` seats the race's first class; the optional third field overrides it, honored only if
-    // the race may actually be that class.
     sel.clamp(catalog.as_deref());
     if let Some(class) = it.next().flatten() {
         if race_classes(catalog.as_deref(), sel.race).contains(&class) {
@@ -176,10 +147,8 @@ fn debug_pick(
             );
         }
     }
-    // The appearance dials (`WOW_CHARCREATE_DIALS="skin,face,hairStyle,hairColor,facialHair"`):
-    // each field optional, a missing/blank one leaves that dial at 0. Every value is clamped into
-    // the (race, sex)'s real range, so a probe can name a specific look — e.g. the bald + bearded
-    // combination that leaves an orc/gnome male's facial hair without a hair texture.
+    // `WOW_CHARCREATE_DIALS="skin,face,hairStyle,hairColor,facialHair"`: each field optional
+    // (missing leaves 0), each clamped into the (race, sex)'s range.
     if let Ok(spec) = std::env::var("WOW_CHARCREATE_DIALS") {
         let counts = dial_counts(catalog.as_deref(), sel.race, sel.sex);
         for (i, field) in spec.split(',').take(5).enumerate() {
@@ -205,10 +174,8 @@ fn debug_pick(
     *done = true;
 }
 
-/// The shot writer (`WOW_CHARCREATE_SHOT_OUT=<path>`): once the create screen has been up a few
-/// seconds (art + model settled), write one PNG of the window via Bevy's own framebuffer readback —
-/// so an agent run can machine-check the screen's geometry without macOS screen-recording
-/// permission. Pairs with `WOW_CHARCREATE_SHOT=1`; inert without the env.
+/// `WOW_CHARCREATE_SHOT_OUT=<path>`: once the screen has settled, write one PNG of the window
+/// through Bevy's framebuffer readback. Pairs with `WOW_CHARCREATE_SHOT=1`.
 fn debug_shot(
     mut commands: Commands,
     time: Res<Time>,
@@ -236,27 +203,22 @@ fn debug_shot(
 
 // ── The selection state ──────────────────────────────────────────────────────────────────────────
 
-/// What the create screen currently has selected. The five dials are `[skin, face, hairStyle,
-/// hairColor, facialHair]` indices; the ranges come from [`CharCreate`], and are re-clamped whenever
-/// race/gender changes (so a dial never points past the new race's range). `class` reaches the booth
-/// too — it picks the starting outfit the preview wears (decision 0527).
+/// What the create screen has selected. The dials are `[skin, face, hairStyle, hairColor,
+/// facialHair]` indices into [`CharCreate`]'s ranges, re-clamped on every race or gender change;
+/// `class` picks the starting outfit the preview wears.
 #[derive(Resource, Default)]
 pub(crate) struct CreateSelection {
     race: u8,
     sex: u8,
     class: u8,
     dials: [u8; 5],
-    /// The typed name — a real [`EditBoxState`] (decision 0704), so it has the caret, selection,
-    /// Ctrl+A and clipboard the chat box has. Letters-only and the 12-cap are enforced by the
-    /// shared feed, on pasted text as well as typed.
+    /// The typed name; the shared feed enforces letters only and the 12-character cap, pasted too.
     name: EditBoxState,
-    /// A create is in flight (waiting on `SMSG_CHAR_CREATE`) — the Create button is disarmed and the
-    /// status shows progress.
+    /// Waiting on `SMSG_CHAR_CREATE`: Create is disarmed.
     creating: bool,
 }
 
-/// The five dial counts for a (race, sex), or `[1; 5]` when the catalog is missing (so the UI still
-/// renders, degenerate).
+/// The five dial counts for a (race, sex), or `[1; 5]` without the catalog.
 fn dial_counts(catalog: Option<&CharCreate>, race: u8, sex: u8) -> [u8; 5] {
     catalog
         .and_then(|c| c.0.ranges(race, sex))
@@ -265,7 +227,7 @@ fn dial_counts(catalog: Option<&CharCreate>, race: u8, sex: u8) -> [u8; 5] {
 }
 
 impl CreateSelection {
-    /// Reset to a valid default for the catalog (Human, male, its first class, dials 0).
+    /// Reset to Human, male, its first class, dials 0.
     fn reset(&mut self, catalog: Option<&CharCreate>) {
         self.race = 1;
         self.sex = 0;
@@ -277,7 +239,7 @@ impl CreateSelection {
         self.creating = false;
     }
 
-    /// Re-clamp class + dials into the current (race, sex)'s valid ranges — after a race/gender change.
+    /// Re-clamp class and dials into the current (race, sex)'s valid ranges.
     fn clamp(&mut self, catalog: Option<&CharCreate>) {
         if let Some(c) = catalog {
             if !c.0.allows(self.race, self.class) {
@@ -294,8 +256,7 @@ impl CreateSelection {
         }
     }
 
-    /// The look to show in the booth: race/gender/class + appearance. Class dresses the preview in
-    /// the (race, class, sex) starting outfit (decision 0527), so a class change re-bakes the model.
+    /// The booth's look; the class dresses the (race, class, sex) starting outfit.
     fn look(&self) -> CreateLook {
         CreateLook {
             race: self.race,
@@ -309,7 +270,6 @@ impl CreateSelection {
         }
     }
 
-    /// The wire request for the current selection.
     fn request(&self) -> CharCreateReq {
         CharCreateReq {
             name: self.name.text.clone(),
@@ -325,36 +285,35 @@ impl CreateSelection {
     }
 }
 
-/// One clickable control on the screen — a single component so one query dispatches every button.
+/// One clickable control on the screen.
 #[derive(Component, Clone, Copy, PartialEq, Eq, Debug)]
 enum CreateAction {
     Race(u8),
     Gender(u8),
-    /// A class-grid slot (index into the selected race's valid-class list — the ref enumerates only
-    /// the classes the race may be, so the slot→class mapping shifts per race).
+    /// An index into the race's valid classes: the reference lists only those, so the slot's class
+    /// shifts per race.
     ClassSlot(u8),
-    /// A dial spinner arrow: dial index 0..5, direction ±1.
+    /// Dial index 0..5, direction ±1.
     Dial(u8, i8),
     Randomize,
     Create,
     Back,
-    /// Hold-to-rotate (the ref's rotate buttons, ±2°/frame).
+    /// Hold to rotate, like the reference's rotate buttons.
     RotateLeft,
     RotateRight,
-    /// The model pane (drag to rotate — no click action, but it carries the tag for the drag test).
+    /// The model pane: drag to rotate, no click action.
     Model,
 }
 
-/// The classes the selected race may be, ascending class id (the CharBaseInfo file order — the
-/// ref's `GetClassesForRace` enumeration).
+/// The classes the race may be, ascending class id: CharBaseInfo order, as `GetClassesForRace`
+/// enumerates them.
 fn race_classes(catalog: Option<&CharCreate>, race: u8) -> Vec<u8> {
     catalog
         .map(|c| c.0.classes_for_race(race))
         .unwrap_or_else(|| vec![1, 2, 3, 4, 5, 7, 8, 9, 11])
 }
 
-/// A class id's GlueStrings fileString (`CLASS_<FILE>`, `CLASS_ICON_TCOORDS` key) — a frozen enum
-/// of the build.
+/// A class id's file string, the `CLASS_ICON_TCOORDS` key.
 fn class_file(class: u8) -> &'static str {
     match class {
         1 => "WARRIOR",
@@ -372,13 +331,8 @@ fn class_file(class: u8) -> &'static str {
 
 // ── Input ────────────────────────────────────────────────────────────────────────────────────────
 
-/// The name box's caret blink clock (the ref's `blinkSpeed`, f32 default 0.5 s — `0x77a790`,
-/// period `E+0x370` / accumulator `E+0x374`), reset on every keystroke
-/// so the caret is solid while you type.
-///
-/// Its own resource rather than a [`CreateSelection`] field on purpose: ticking it there would trip
-/// that resource's change detection every frame and defeat `refresh_dynamic`'s `is_changed` gate,
-/// re-running the whole dial/panel/icon refresh 60× a second.
+/// Clicks, name typing, Enter and Escape. The name caret blinks at the reference's `blinkSpeed`,
+/// 0.5 s (`0x77a790`).
 fn create_input(
     buttons: Query<(Entity, &CreateAction)>,
     clicks: Res<crate::glue::GlueClicks>,
@@ -386,7 +340,7 @@ fn create_input(
     keys: Res<ButtonInput<KeyCode>>,
     catalog: Option<Res<CharCreate>>,
     mut sel: ResMut<CreateSelection>,
-    // The host pasteboard + the window handle its Wayland backend needs (decision 0702).
+    // The host pasteboard and the window handle its Wayland backend needs.
     mut clipboard: NonSendMut<HostClipboard>,
     raw_handle: Query<&bevy::window::RawHandleWrapper, With<bevy::window::PrimaryWindow>>,
     time: Res<Time>,
@@ -404,17 +358,15 @@ fn create_input(
     let mut changed_look = false;
     let mut do_create = false;
 
-    // Every control on this screen is a Button, and a Button fires on the RELEASE, over the
-    // button that took the press (1533, `crate::glue::glue_clicks`). The name box needs no
-    // press-to-focus: the screen has one field and it is always focused while up.
+    // A Button fires on the release over the button that took the press (`glue::glue_clicks`).
     for (entity, action) in &buttons {
         if !clicks.hit(entity) {
             continue;
         }
         match *action {
             CreateAction::Race(r) => {
-                // The ref plays the click always, switches only on a real change — and a switch
-                // resets the class to the race's first and the facing to −15°.
+                // The reference always clicks; a real switch resets the class to the race's first
+                // and the facing to -15°.
                 sounds.write(GlueSound("gsCharacterCreationClass"));
                 if sel.race != r {
                     sel.race = r;
@@ -433,9 +385,7 @@ fn create_input(
                 }
             }
             CreateAction::ClassSlot(slot) => {
-                // The ref plays the click always, and re-dresses the model only on a real change:
-                // `SelectClass` (`0x470f50`) → `cc_apply_sections` re-applies equipment, because the
-                // class picks the starting outfit the preview wears (decision 0527).
+                // The reference always clicks and re-dresses only on a real change (`0x470f50`).
                 if let Some(&class) = race_classes(cat, sel.race).get(slot as usize) {
                     sounds.write(GlueSound("gsCharacterCreationClass"));
                     if sel.class != class {
@@ -463,7 +413,6 @@ fn create_input(
         }
     }
 
-    // Name typing + Enter/Esc.
     for ev in keyboard.read() {
         if ev.state != ButtonState::Pressed {
             continue;
@@ -506,8 +455,7 @@ fn cycle_dial(sel: &mut CreateSelection, catalog: Option<&CharCreate>, dial: usi
     sel.dials[dial] = (cur + dir as i32).rem_euclid(count) as u8;
 }
 
-/// Set every dial to a random valid index (a tiny xorshift, seeded off a per-run counter — the
-/// screen has no need for a real RNG dependency; captures never hit Randomize).
+/// Set every dial to a random valid index, from a small xorshift.
 fn randomize(sel: &mut CreateSelection, catalog: Option<&CharCreate>, rng: &mut u64) {
     let counts = dial_counts(catalog, sel.race, sel.sex);
     for (d, &n) in sel.dials.iter_mut().zip(&counts) {
@@ -519,10 +467,7 @@ fn randomize(sel: &mut CreateSelection, catalog: Option<&CharCreate>, rng: &mut
     }
 }
 
-/// Paint the name box from its [`EditBoxState`] — the display segments, the selection highlight and
-/// the caret at the cursor — through the shared [`crate::glue::widgets::paint_glue_field`], so it
-/// draws exactly like the login boxes (decision 0704). Only the five name-box row items carry a
-/// `GlueFieldPart`, so requiring it is enough to pick them out of every other `DynText`.
+/// Paint the name box through the shared `paint_glue_field`, so it draws like the login boxes.
 fn refresh_name_box(
     sel: Res<CreateSelection>,
     mut parts: Query<(
@@ -531,19 +476,12 @@ fn refresh_name_box(
         &mut Visibility,
     )>,
 ) {
-    // One field, no focus model: it is focused whenever the screen is up.
     crate::glue::widgets::paint_glue_field(&sel.name, true, parts.iter_mut());
 }
 
-/// Rotate the preview: drag on the model pane (the ref's full-frame mouse rotation: `facing +=
-/// Δcursor·CHARACTER_ROTATION_CONSTANT` — dragging right *increases* the facing, same sign as the
-/// right rotate button), or hold a rotate button (the ref's ±2°-per-frame
-/// `RotateLeft/Right_OnUpdate`; left decrements the facing).
-///
-/// The drag constant is the select screen's, because in the reference it is literally the same
-/// number: `CHARACTER_ROTATION_CONSTANT = 0.6` is declared once in `CharacterSelect.lua` and read
-/// by both screens' `OnUpdate`. This screen carried a bare `0.01` rad/px (0.573°/px) instead — a
-/// 4.5 % drift from the screen next door, against a comment that already claimed 0.6 (1533).
+/// Rotate the preview by dragging the model pane (dragging right increases the facing) or holding
+/// a rotate button (left decrements it). The drag uses the select screen's constant: the reference
+/// declares `CHARACTER_ROTATION_CONSTANT = 0.6` once in `CharacterSelect.lua` for both screens.
 fn rotate_model(
     panes: Query<(&Interaction, &CreateAction)>,
     motion: Res<AccumulatedMouseMotion>,
@@ -591,10 +529,8 @@ fn create_result(
             char_result_text(&strings, msg.code)
         );
         if msg.code == benilla_protocol::messages::CHAR_CREATE_SUCCESS {
-            // The fresh roster already arrived (`net::io` re-enumerates and emits it BEFORE the
-            // result), so `note_created` selects the new row against the list already in hand —
-            // arming a flag for "the next roster update" waited for a message that never comes
-            // again, and the select screen came back on the old row (B119).
+            // `net::io` re-enumerates and emits the fresh roster before the result, so the new
+            // row is selected against the list already in hand; no later roster update comes.
             roster.note_created(sel.name.text.clone());
             next.set(ClientState::CharSelect);
         } else if let Ok(mut text) = status.single_mut() {
@@ -603,26 +539,10 @@ fn create_result(
     }
 }
 
-/// A `SMSG_CHAR_CREATE` result byte → its **GlueStrings key**, resolved off the player's own
-/// `GlueStrings.lua` with a built-in caption as the fallback — `login::world_refusal_text`'s shape,
-/// and the reference's own (a key first, a literal only when the chain lacks it).
-///
-/// The codes are vmangos's `ResponseCodes`, anchored at `CHAR_CREATE_SUCCESS = 0x2E`; every key
-/// below was derived by matching our old text against the shipped file rather than by name, then
-/// corrected where the *semantics* disagreed with the match. Three things that hiding behind
-/// literals had concealed (decision 2045):
-///
-/// - **`0x36` was missing a sentence.** Our copy of `CHAR_CREATE_SERVER_QUEUE` stopped at
-///   "…temporarily disabled." where the shipped string continues "Please try again during off peak
-///   hours." A re-typed string is a string nobody diffed.
-/// - **`0x50` was invented.** "You cannot use consecutive spaces in a name" has no 1.12
-///   counterpart — there is no `CHAR_NAME_CONSECUTIVE_SPACES` in this chain — so it takes the
-///   default arm, `CHAR_CREATE_INVALID_NAME`, exactly as any code the table does not name does.
-///   Composing a better sentence for a code the client has no string for is what 2035 was about.
-/// - **`0x4B` named the wrong key.** It resolved `CHAR_CREATE_NAME_IN_USE` because that key's text
-///   *equals* `CHAR_NAME_RESERVED`'s in enUS — "That name is unavailable" — but the code is the
-///   reserved-name one. Identical text, different key: a locale that words them apart would have
-///   shown the wrong sentence, and no amount of text comparison could ever have found it.
+/// A `SMSG_CHAR_CREATE` result code (vmangos `ResponseCodes`, `CHAR_CREATE_SUCCESS = 0x2E`) to its
+/// GlueStrings key, read off the player's chain, with a built-in caption only when the key is
+/// missing. `0x50` has no 1.12 string and takes the default arm; `0x4B` is `CHAR_NAME_RESERVED`,
+/// whose enUS text equals `CHAR_CREATE_NAME_IN_USE`'s.
 fn char_result_text<'a>(strings: &'a GlueStrings, code: u8) -> &'a str {
     let (key, fallback): (&str, &'a str) = match code {
         0x2E => ("CHAR_CREATE_SUCCESS", "Character created"),
@@ -694,28 +614,22 @@ fn char_result_text<'a>(strings: &'a GlueStrings, code: u8) -> &'a str {
 
 #[cfg(test)]
 mod tests {
-    /// **Every char-create result resolves to the sentence 1.12 actually ships**, read off the
-    /// player's own chain — `GlueStrings.lua` with `GlueLocalization.lua`'s `Localize()` patch over
-    /// it, assembled by the loader's own helper so this cannot assert a sentence the running client
-    /// would not show (2052). The regression for three bugs that literals had hidden (decision
-    /// 2045). Skips without client data.
+    /// The chain is assembled by the loader's own helper, `GlueLocalization.lua`'s `Localize()`
+    /// over `GlueStrings.lua`, so this asserts what the running client shows.
     #[test]
     fn every_char_create_result_resolves_in_the_real_glue_strings() {
         let data = benilla_formats::wow_data_or_skip!();
         let mut chain = benilla_formats::open_chain(&data).expect("open chain");
         let strings = crate::glue_strings::table_from_chain(&mut chain);
 
-        // `0x36` used to stop at "…temporarily disabled."; the shipped string carries a second
-        // sentence, and a re-typed string is one nobody diffed.
+        // The shipped `0x36` string has a second sentence.
         assert_eq!(
             char_result_text(&strings, 0x36),
             "This server is currently queued and new character creation is temporarily disabled. \
              Please try again during off peak hours."
         );
 
-        // `0x50` is INVENTED text: 1.12 has no `CHAR_NAME_CONSECUTIVE_SPACES`, so the code takes
-        // the default arm like any other the table does not name. If a chain ever *does* carry
-        // such a key this assert is what will say so.
+        // 1.12 has no `CHAR_NAME_CONSECUTIVE_SPACES`, so `0x50` takes the default arm.
         assert_eq!(
             char_result_text(&strings, 0x50),
             char_result_text(&strings, 0xFE),
@@ -723,8 +637,6 @@ mod tests {
         );
         assert_eq!(char_result_text(&strings, 0xFE), "Invalid character name");
 
-        // Every named code must resolve to a REAL key — the fallback caption never showing is the
-        // whole point, since a fallback that matches hides a missing key forever.
         for code in [
             0x2Eu8, 0x2F, 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x45, 0x46, 0x47, 0x48,
             0x49, 0x4A, 0x4B, 0x4C, 0x4D, 0x4E, 0x4F,
@@ -734,20 +646,13 @@ mod tests {
         }
     }
 
-    /// **`0x4B` is the reserved-name code, and text alone can never prove it.**
-    ///
-    /// It used to resolve `CHAR_CREATE_NAME_IN_USE`, whose enUS value is *identical* to
-    /// `CHAR_NAME_RESERVED`'s — "That name is unavailable" — so no comparison of the displayed
-    /// string could distinguish right from wrong. This asserts the key by *name* against the
-    /// shipped file, which is the only thing that can. A locale that words the two apart is
-    /// exactly the case this protects.
+    /// The two keys share their enUS text, so the key is asserted by name through a sentinel.
     #[test]
     fn the_reserved_name_code_names_the_reserved_key_not_the_in_use_one() {
         let data = benilla_formats::wow_data_or_skip!();
         let mut chain = benilla_formats::open_chain(&data).expect("open chain");
         let map = crate::glue_strings::table_from_chain(&mut chain).into_map();
 
-        // Both keys exist and agree in enUS — which is why the mix-up was invisible.
         let reserved = map.get("CHAR_NAME_RESERVED").expect("CHAR_NAME_RESERVED");
         let in_use = map
             .get("CHAR_CREATE_NAME_IN_USE")
@@ -757,39 +662,26 @@ mod tests {
             "if these ever differ, the mix-up becomes visible"
         );
 
-        // Prove we read the RESERVED one: a table with only that key altered must move 0x4B.
         let mut probe = map.clone();
         probe.insert("CHAR_NAME_RESERVED".into(), "RESERVED-SENTINEL".into());
         let strings = GlueStrings::from_map(probe);
         assert_eq!(char_result_text(&strings, 0x4B), "RESERVED-SENTINEL");
-        // …and 0x31, the genuine in-use code, must NOT have moved.
         assert_eq!(char_result_text(&strings, 0x31), in_use.as_str());
     }
 
     use super::*;
 
-    /// The race grid's column order, pinned against the reference screen (director's screenshot,
-    /// 2026-07-19): Alliance reads Human · Dwarf · Night Elf · Gnome, Horde reads Orc · Scourge ·
-    /// Tauren · Troll. This is a *regression* test with history: the columns were previously ordered
-    /// off `RACE_ICON_TCOORDS`'s table order, which is a name→UV lookup that never reaches layout —
-    /// the real order is whatever `GetAvailableRaces()` enumerates into buttons 1–8, which the XML
-    /// chains 1–4 down column A and 5–8 down column B.
     #[test]
     fn race_columns_match_the_reference_screen() {
         assert_eq!(ALLIANCE, [1, 3, 4, 7], "Human, Dwarf, Night Elf, Gnome");
         assert_eq!(HORDE, [2, 5, 6, 8], "Orc, Scourge, Tauren, Troll");
-        // Together the columns are exactly the eight playable races, no repeats.
         let mut all: Vec<u8> = ALLIANCE.iter().chain(&HORDE).copied().collect();
         all.sort_unstable();
         assert_eq!(all, (1..=8).collect::<Vec<u8>>());
-        // Each column ascends by race id — the engine's per-faction enumeration order.
         assert!(ALLIANCE.windows(2).all(|w| w[0] < w[1]));
         assert!(HORDE.windows(2).all(|w| w[0] < w[1]));
     }
 
-    /// The booth look carries the class, so a class click re-dresses the model (decision 0527).
-    /// Guards the regression this test was written for: `CreateSelection.class` was set by the
-    /// class buttons but never reached `GluePreview`, so the starting outfit never changed.
     #[test]
     fn look_carries_the_class() {
         let mut sel = CreateSelection {
@@ -799,7 +691,7 @@ mod tests {
             ..default()
         };
         let warrior = sel.look();
-        sel.class = 8; // mage — a different starting outfit (robe, not the recruit set)
+        sel.class = 8; // mage, a different starting outfit
         let mage = sel.look();
         assert_eq!(warrior.class, 1);
         assert_eq!(mage.class, 8);
@@ -809,22 +701,10 @@ mod tests {
         );
     }
 
-    /// **The chosen race / gender / class icon is LOCK-HIGHLIGHTED** — the reference's own verb:
-    /// `SetCharacterRace`, `SetCharacterClass` and `SetCharacterGender` each call
-    /// `button:LockHighlight()` on the one that is chosen and `UnlockHighlight()` on the rest
-    /// (`CharacterCreate.lua` l.171/254/326). In 1.12 that lock *is* the whole selected visual:
-    /// `CharacterCreateIconButtonTemplate` has its `<CheckedTexture>` commented out, leaving the
-    /// ADD `ButtonHilight-Square` and the HIGHLIGHT-layer `$parentHighlightText` — both of which
-    /// the lock is what lights.
-    ///
-    /// **The regression this exists for** (director, 2026-09-17: *"it doesn't show that mage is
-    /// selected"*): 2072 moved the sheen to one owner and gave this screen's visuals query a
-    /// `&mut LockHighlight` term — but [`crate::glue::widgets::icon_button`], the only spawn site
-    /// for all eighteen of these icons, inserted no such component. A `&mut T` term is a filter,
-    /// so the query matched **nothing**: no selected sheen and no icon name on race, gender or
-    /// class, for ten days. Every existing sheen test hand-spawned the flag, so the consumer was
-    /// covered and the producer was not — hence this one builds the icons with the real
-    /// `icon_button` and runs the real system.
+    /// `SetCharacterRace`, `SetCharacterClass` and `SetCharacterGender` `LockHighlight()` the
+    /// chosen button (`CharacterCreate.lua`); with the template's `<CheckedTexture>` commented out,
+    /// that lock is the whole selected visual. Built with the real `icon_button`, which must insert
+    /// the `LockHighlight` the refresh query needs.
     #[test]
     fn the_chosen_icons_are_lock_highlighted() {
         use crate::glue::art::GlueArt;
@@ -877,8 +757,7 @@ mod tests {
 
         let mut app = App::new();
         app.init_resource::<GlueArt>()
-            // Human, female, MAGE — the director's own case. With no catalog loaded
-            // `race_classes` is the full list, so mage (8) is slot 6.
+            // Human, female, mage: without a catalog `race_classes` is the full list, so slot 6.
             .insert_resource(CreateSelection {
                 race: 1,
                 sex: 1,
@@ -909,7 +788,7 @@ mod tests {
              unmarked"
         );
 
-        // …and the selection moving takes the lock with it, rather than lighting a second icon.
+        // Moving the selection moves the lock, never lights a second icon.
         app.world_mut().resource_mut::<CreateSelection>().class = 1; // warrior, slot 0
         app.update();
         let locked: Vec<CreateAction> = app
diff --git a/crates/benilla-app/src/char_create/panels.rs b/crates/benilla-app/src/char_create/panels.rs
index 07ced84b..d1120c9e 100644
--- a/crates/benilla-app/src/char_create/panels.rs
+++ b/crates/benilla-app/src/char_create/panels.rs
@@ -1,9 +1,6 @@
-//! The create screen's right info stack (`CharacterCreateCharacterFaction/Race/Class`, 240 wide at
-//! TOPRIGHT (−20,−20), heights 160/260/210, 10 apart): each a `TextPanel-Border` backdrop whose bg
-//! tints with the faction, the header icon overhanging the corner, the scrollable title + body +
-//! gold ability lines — and the `GlueScrollFrameTemplate` scrollbar along the right edge (16² arrow
-//! buttons above/below a knob track, the CharacterCreate decorative track art behind it, everything
-//! hidden while the panel has nothing to scroll — the ref's `scrollBarHideable`).
+//! The create screen's right info stack, `CharacterCreateCharacterFaction/Race/Class`: each a
+//! faction-tinted `TextPanel-Border` backdrop with a header icon, scrollable text and a
+//! `GlueScrollFrameTemplate` scrollbar.
 
 use bevy::prelude::*;
 use bevy::ui::FocusPolicy;
@@ -55,8 +52,7 @@ pub(super) fn right_stack(
                 }
                 panel.with_children(|panel| {
                     if framed {
-                        // The backdrop: tiled `UI-Tooltip-Background` inset (8,4,4,8) under the
-                        // untinted `TextPanel-Border` (the ref tints only the bg).
+                        // The reference tints only the bg, never the `TextPanel-Border`.
                         panel.spawn((
                             DynTint::BoxFill,
                             tiled_bg_node(
@@ -81,9 +77,8 @@ pub(super) fn right_stack(
                             Color::WHITE,
                         );
                     }
-                    // The header icon, overhanging the top-left corner (48² at (−3, −8)) — ABOVE
-                    // the scroll content: the ref's IconFrame `OnLoad` bumps its frame level +1,
-                    // so scrolled text slides UNDER the icon, never over it.
+                    // Above the scroll content: the reference's IconFrame `OnLoad` raises its
+                    // frame level by 1, so scrolled text slides under the icon.
                     panel.spawn((
                         DynIcon::Info(kind),
                         ImageNode {
@@ -93,7 +88,6 @@ pub(super) fn right_stack(
                         ZIndex(1),
                         abs(s, -3.0, -8.0, 48.0, 48.0),
                     ));
-                    // The scrollable content (the ref's GlueScrollFrame, 190 wide at (17,−10)).
                     let scroll = panel
                         .spawn((
                             InfoScroll,
@@ -146,8 +140,7 @@ pub(super) fn right_stack(
                                 font,
                                 s,
                             );
-                            // The racial abilities under the race paragraph, gold — the ref's
-                            // separate `CharacterCreateRaceAbilityText` (`GlueFontNormalSmall`).
+                            // The reference's separate gold `CharacterCreateRaceAbilityText`.
                             if kind == InfoKind::Race {
                                 outlined_text(
                                     inner,
@@ -177,10 +170,8 @@ pub(super) fn right_stack(
         });
 }
 
-/// One panel's scrollbar (`GlueScrollFrameTemplate` resolved to panel coordinates): the decorative
-/// track art behind, then the 16-wide slider column 6px right of the scroll frame — up button,
-/// knob track, down button. Every piece carries [`ScrollHides`] (the whole bar vanishes while the
-/// panel fits its text, like the ref's `scrollBarHideable` frames).
+/// One panel's scrollbar, `GlueScrollFrameTemplate` in panel coordinates; the whole bar hides
+/// while the panel fits its text, like the reference's `scrollBarHideable`.
 fn scrollbar(
     panel: &mut ChildSpawnerCommands,
     sc: &ScrollArt,
@@ -188,11 +179,11 @@ fn scrollbar(
     panel_h: f32,
     s: f32,
 ) {
-    // The frame is inset 10 top/bottom; the slider is inset 16 more for the buttons.
+    // The frame is inset 10 top and bottom; the slider 16 more for the buttons.
     let bar_h = panel_h - 20.0;
     let track_h = bar_h - 32.0;
-    // `UI-CharacterCreate-ScrollBar-Top` (32×128 at frame TOPRIGHT (−3,4)) and the ClassTrainer
-    // strip (30×123 at frame BOTTOMRIGHT (−3,−2), the authored sub-rect) — panel x 204.
+    // `UI-CharacterCreate-ScrollBar-Top` (32×128 at frame TOPRIGHT (-3,4)) and the ClassTrainer
+    // strip's authored sub-rect (30×123 at BOTTOMRIGHT (-3,-2)), both at panel x 204.
     if let Some((top, _)) = &sc.track_top {
         panel.spawn((
             ScrollHides { scroll },
@@ -228,8 +219,8 @@ fn scrollbar(
                         step: track_h * s / 2.0,
                     },
                     Button,
-                    // At the end of its travel this arrow is disabled — `scroll_visuals` writes it
-                    // and `crate::glue::glue_hilights` reads it, so the sheen dies with the arrow.
+                    // Disabled at the end of travel: `scroll_visuals` writes it and
+                    // `glue_hilights` reads it, so the sheen goes with the arrow.
                     crate::glue::widgets::GlueDisabled(false),
                     ImageNode {
                         image: art.up.clone(),
diff --git a/crates/benilla-app/src/char_create/parts.rs b/crates/benilla-app/src/char_create/parts.rs
index 0b0c8f29..3f2ffa80 100644
--- a/crates/benilla-app/src/char_create/parts.rs
+++ b/crates/benilla-app/src/char_create/parts.rs
@@ -1,16 +1,13 @@
-//! The create screen's component vocabulary — the markers [`super::screen`] spawns and
-//! [`super::refresh`] drives. Pure data; no systems. (The screen-agnostic widget markers —
-//! `Hilight`, `ArtSwap`, `GlueBtn`, … — live in [`crate::glue::widgets`], decision 0465.)
+//! The create screen's markers: [`super::screen`] spawns them, [`super::refresh`] drives them.
 
 use bevy::prelude::*;
 
-/// The screen root (despawned whole on exit); `s` is the glue scale the tree was baked at —
-/// [`super::screen::rescale_screen`] rebuilds it when a window resize changes the scale.
+/// The screen root; `s` is the glue scale the tree was built at, rebuilt when it changes.
 #[derive(Component)]
 pub(super) struct CharCreateUi {
     pub(super) s: f32,
 }
-/// The status line (also written by [`super::create_result`]).
+/// The status line.
 #[derive(Component)]
 pub(super) struct StatusLine;
 
@@ -25,9 +22,9 @@ pub(super) enum InfoKind {
 /// An icon whose texture rect follows the selection.
 #[derive(Component)]
 pub(super) enum DynIcon {
-    /// A race button's icon (rect follows the selected sex).
+    /// A race button's icon; the rect follows the selected sex.
     Race(u8),
-    /// A class slot's icon (the class it maps to follows the selected race).
+    /// A class slot's icon; its class follows the selected race.
     ClassSlot(u8),
     /// An info-panel header icon.
     Info(InfoKind),
@@ -40,46 +37,45 @@ pub(super) enum DynText {
     Name,
     InfoTitle(InfoKind),
     InfoBody(InfoKind),
-    /// The race panel's ability lines — the ref's separate gold `CharacterCreateRaceAbilityText`,
-    /// never part of the white paragraph.
+    /// The race panel's ability lines, the reference's separate gold
+    /// `CharacterCreateRaceAbilityText`.
     InfoAbilities,
-    /// A class slot's hover label (name follows the mapped class).
+    /// A class slot's hover label.
     ClassSlotLabel(u8),
 }
 
-/// A tint that follows the selected faction: the page backdrop, or a panel's backdrop-bg piece
-/// (the ref's `SetBackdropColor` — an `ImageNode` tint with art, a `BackgroundColor` without).
+/// A tint that follows the selected faction, the reference's `SetBackdropColor`: an `ImageNode`
+/// tint with art, a `BackgroundColor` without.
 #[derive(Component)]
 pub(super) enum DynTint {
     Backdrop,
     BoxFill,
 }
 
-/// A dial spinner row (row 4 — facial hair — hides when the race's token is `NONE`, the ref rule).
+/// A dial row; row 4, facial hair, hides when the race's token is `NONE`, as in the reference.
 #[derive(Component)]
 pub(super) struct DialRow(pub(super) u8);
-/// An info panel's scrollable body (mouse wheel while hovered).
+/// An info panel's scrollable body, wheel-scrolled while hovered.
 #[derive(Component)]
 pub(super) struct InfoScroll;
-/// A scrollbar arrow (`GlueScrollUp/DownButtonTemplate`): steps its scroll frame by half a track
-/// per click; disabled art at its end stop.
+/// A scrollbar arrow (`GlueScrollUp/DownButtonTemplate`), disabled at its end stop.
 #[derive(Component)]
 pub(super) struct ScrollArrow {
     pub(super) scroll: Entity,
-    /// `true` = the up button (scrolls toward 0).
+    /// The up button, scrolling toward 0.
     pub(super) up: bool,
-    /// The click step, logical px — the ref's `GetHeight()/2` (half the track).
+    /// The click step in logical px, the reference's `GetHeight()/2`: half the track.
     pub(super) step: f32,
 }
-/// The scrollbar knob (`UI-ScrollBar-Knob`): rides the scroll fraction along its track; drags.
+/// The scrollbar knob (`UI-ScrollBar-Knob`), draggable.
 #[derive(Component)]
 pub(super) struct ScrollThumb {
     pub(super) scroll: Entity,
-    /// The knob's travel (track minus knob), logical px.
+    /// Track minus knob, logical px.
     pub(super) travel: f32,
 }
-/// A scrollbar piece that hides while its frame has nothing to scroll — the ref's
-/// `scrollBarHideable` (the whole slider) + the Top/Bottom track art's range-changed hide.
+/// A scrollbar piece hidden while its frame has nothing to scroll: the reference's
+/// `scrollBarHideable` slider and the track art's range-changed hide.
 #[derive(Component)]
 pub(super) struct ScrollHides {
     pub(super) scroll: Entity,
diff --git a/crates/benilla-app/src/char_create/refresh.rs b/crates/benilla-app/src/char_create/refresh.rs
index c0e6bc7f..212404b3 100644
--- a/crates/benilla-app/src/char_create/refresh.rs
+++ b/crates/benilla-app/src/char_create/refresh.rs
@@ -1,7 +1,5 @@
-//! The create screen's live refresh (decision 0423's polish passes) — everything that follows the
-//! selection or the pointer after [`super::screen`] spawns the tree: icon rects, per-race dial
-//! labels, the GlueStrings info paragraphs, faction tints, the ref's hover/selected visuals
-//! (`LockHighlight`, `HighlightFont`, up/down art states), and the info panels' wheel scroll.
+//! The create screen's live refresh: everything that follows the selection or the pointer once
+//! [`super::screen`] has spawned the tree.
 
 use bevy::input::mouse::{AccumulatedMouseMotion, MouseScrollUnit, MouseWheel};
 use bevy::prelude::*;
@@ -21,8 +19,8 @@ use crate::glue::art::{
 };
 use crate::glue::widgets::{FallbackFace, GlueDisabled, Hilight, HoverLabel, LockHighlight};
 
-/// Refill everything that follows the selection — icon rects, dial labels, info texts, faction
-/// tints, class-slot mapping — on selection change or a fresh spawn.
+/// Refill icon rects, dial labels, info texts, faction tints and class slots on a selection
+/// change or a fresh spawn.
 #[allow(clippy::type_complexity)]
 pub(super) fn refresh_dynamic(
     sel: Res<CreateSelection>,
@@ -96,7 +94,7 @@ pub(super) fn refresh_dynamic(
         if let Some((image, rect)) = tc {
             node.image = image;
             node.rect = Some(rect);
-            node.color = Color::WHITE; // spawned transparent until real art lands
+            node.color = Color::WHITE; // spawned transparent until the art lands
         }
     }
 
@@ -117,8 +115,7 @@ pub(super) fn refresh_dynamic(
                     .text(&format!("FACIAL_HAIR_{facial_tok}"), "Facial Hair")
                     .to_string(),
             },
-            // The name box is five flex items (segments + carets), painted from its
-            // `EditBoxState` by `refresh_name_box` — never a single string here (decision 0704).
+            // Painted by `refresh_name_box`.
             DynText::Name => continue,
             DynText::InfoTitle(InfoKind::Faction) => strings
                 .text(
@@ -128,11 +125,8 @@ pub(super) fn refresh_dynamic(
                 .to_string(),
             DynText::InfoTitle(InfoKind::Race) => race_name(sel.race).to_string(),
             DynText::InfoTitle(InfoKind::Class) => class_name(sel.class).to_string(),
-            // The info bodies keep the shipped strings VERBATIM: every `FACTION_INFO_*`/
-            // `RACE_INFO_*`/`CLASS_*` opens with eight literal spaces — that indent IS the ref's
-            // first-line clearance past the header icon (the FontString is full-width at x=0;
-            // GlueStrings.lua authors the inset into the text). Trimming it ran line 1 under the
-            // icon (director's report, 2026-07-20).
+            // Never trimmed: each `FACTION_INFO_*`, `RACE_INFO_*` and `CLASS_*` string opens with
+            // eight spaces, which is the reference's first-line clearance past the header icon.
             DynText::InfoBody(InfoKind::Faction) => strings
                 .text(
                     if alliance {
@@ -147,8 +141,7 @@ pub(super) fn refresh_dynamic(
                 strings.text(&format!("RACE_INFO_{file}"), "").to_string()
             }
             DynText::InfoAbilities => {
-                // The ref's `CharacterCreateEnumerateRaces` join: every `ABILITY_INFO_<FILE><n>`
-                // line, newline-separated, into the gold ability text.
+                // `CharacterCreateEnumerateRaces` joins every `ABILITY_INFO_<FILE><n>` by newline.
                 let mut lines = Vec::new();
                 let mut n = 1;
                 while let Some(a) = strings.get(&format!("ABILITY_INFO_{file}{n}")) {
@@ -170,8 +163,7 @@ pub(super) fn refresh_dynamic(
         }
     }
 
-    // The faction tints: the page lean, and the panels' backdrop-bg color (the ref's
-    // `SetBackdropColor` — the border stays untinted, its color table entry commented out).
+    // The reference's `SetBackdropColor` tints only the bg; the border's entry is commented out.
     for (tint, bg, node) in &mut tints {
         let fill = if alliance { ALLIANCE_FILL } else { HORDE_FILL };
         match tint {
@@ -186,7 +178,7 @@ pub(super) fn refresh_dynamic(
             }
             DynTint::BoxFill => {
                 if let Some(mut node) = node {
-                    node.color = fill; // the texture's own alpha rides along
+                    node.color = fill; // the texture keeps its own alpha
                 } else if let Some(mut bg) = bg {
                     bg.0 = fill.with_alpha(FALLBACK_ALPHA);
                 }
@@ -194,8 +186,7 @@ pub(super) fn refresh_dynamic(
         }
     }
 
-    // The facial dial hides when the race's token is NONE (the ref rule; no 5875 row is, but the
-    // mechanism is the authored one).
+    // The facial dial hides when the race's token is `NONE`, as in the reference (no 1.12 row is).
     for (row, mut node) in &mut dial_rows {
         if row.0 == 4 {
             node.display = if facial_tok == "NONE" {
@@ -206,8 +197,7 @@ pub(super) fn refresh_dynamic(
         }
     }
 
-    // Unused class slots collapse (the ref enumerates the valid classes into the first buttons and
-    // hides the rest — same compaction).
+    // The reference fills the valid classes into the first buttons and hides the rest.
     for (action, mut node) in &mut slots {
         if let CreateAction::ClassSlot(i) = action {
             node.display = if (*i as usize) < classes.len() {
@@ -219,24 +209,15 @@ pub(super) fn refresh_dynamic(
     }
 }
 
-/// Per-frame interaction visuals the CREATE screen owns: which icon is *chosen* (the ref's
-/// `LockHighlight`, which [`crate::glue::glue_hilights`] then renders), hover labels, the no-art
-/// fallback shade, and the Create button's disabled latch while a create is in flight. The
-/// screen-agnostic passes — up/down art swaps, the glue buttons' art + caption color, outline
-/// mirroring — are [`crate::glue`]'s, registered beside this in the plugin chain.
-///
-/// **The chosen-icon write is its own query, deliberately.** It used to be a sixth term on the
-/// hover query below, which meant a button without a [`LockHighlight`] dropped out of the hover
-/// visuals too — and since no spawn site on this screen had one, that query matched *nothing*:
-/// no selected sheen and no icon name anywhere on the create screen. Two jobs, two queries, so a
-/// missing component can only ever cost its own job.
+/// The create screen's own per-frame visuals: the chosen icon's `LockHighlight`, hover labels,
+/// the no-art fallback shade and Create's disabled latch; the shared passes are [`crate::glue`]'s.
+/// The lock write keeps its own query, so a button without a `LockHighlight` still gets hover.
 #[allow(clippy::type_complexity)]
 pub(super) fn refresh_hover(
     sel: Res<CreateSelection>,
     catalog: Option<Res<CharCreate>>,
     art: Res<GlueArt>,
-    // The glue-panel buttons (Accept/Back/Randomize) are the shared visuals pass's whole —
-    // art states, caption, fallback shade, hover highlight — hence `Without<GlueBtn>` here.
+    // Accept, Back and Randomize are wholly the shared visuals pass's.
     mut buttons: Query<
         (
             &CreateAction,
@@ -260,9 +241,8 @@ pub(super) fn refresh_hover(
         _ => false,
     };
 
-    // `SetCharacterRace`/`SetCharacterClass`/`SetCharacterGender`: `LockHighlight()` on the one
-    // that is chosen, `UnlockHighlight()` on the rest. Nothing about visibility — the sheen is
-    // `crate::glue::glue_hilights`' alone.
+    // `SetCharacterRace`/`Class`/`Gender`: `LockHighlight()` the chosen one, unlock the rest;
+    // `glue_hilights` draws the sheen.
     for (action, mut locked) in &mut locks {
         let is_sel = selected(action);
         if locked.0 != is_sel {
@@ -274,14 +254,13 @@ pub(super) fn refresh_hover(
         let is_sel = selected(action);
         let hovered = *interaction != Interaction::None;
         let lit = is_sel || hovered;
-        // No-art fallback only: buttons spawned with a plain face get a hover shade. (Every node
-        // *has* a `BackgroundColor` — only a `FallbackFace`'s belongs to us.)
+        // Every node has a `BackgroundColor`; only a `FallbackFace`'s is ours to shade.
         if fallback {
             bg.0 = if lit { BTN_HOVER } else { BTN_BG };
         }
         for child in children {
             if let Ok(mut vis) = labels.get_mut(*child) {
-                // Without icon art the label IS the button face — always visible.
+                // Without icon art the label is the button face.
                 let show = lit || art.races.is_none();
                 *vis = if show {
                     Visibility::Inherited
@@ -292,7 +271,6 @@ pub(super) fn refresh_hover(
         }
     }
 
-    // The Create button disarms while a create is in flight (the shared visuals pass renders it).
     for (action, mut disabled) in &mut disables {
         if matches!(action, CreateAction::Create) {
             let want = sel.creating;
@@ -303,7 +281,7 @@ pub(super) fn refresh_hover(
     }
 }
 
-/// Wheel-scroll a hovered info panel (the ref's GlueScrollFrame `OnMouseWheel`).
+/// Wheel-scroll a hovered info panel, the reference's GlueScrollFrame `OnMouseWheel`.
 pub(super) fn scroll_info(
     mut wheel: MessageReader<MouseWheel>,
     mut boxes: Query<(&Interaction, &ComputedNode, &mut ScrollPosition), With<InfoScroll>>,
@@ -326,8 +304,8 @@ fn max_scroll(node: &ComputedNode) -> f32 {
     ((node.content_size.y - node.size.y) * node.inverse_scale_factor).max(0.0)
 }
 
-/// The scrollbar's inputs (`GlueScrollBarTemplate`): an arrow click steps half a track (the ref's
-/// `SetValue(GetValue() ± GetHeight()/2)`), the knob drags.
+/// The scrollbar's inputs (`GlueScrollBarTemplate`): an arrow click steps half a track,
+/// `SetValue(GetValue() ± GetHeight()/2)`, and the knob drags.
 pub(super) fn scroll_drive(
     motion: Res<AccumulatedMouseMotion>,
     arrows: Query<(Entity, &ScrollArrow)>,
@@ -335,8 +313,7 @@ pub(super) fn scroll_drive(
     thumbs: Query<(&ScrollThumb, &Interaction)>,
     mut scrolls: Query<(&ComputedNode, &mut ScrollPosition), With<InfoScroll>>,
 ) {
-    // The arrow steps on the RELEASE — it is a `<Button>` with an `<OnClick>`, not a slider (1533).
-    // The knob below is the slider half, and a drag is a held press by definition.
+    // The arrow is a `<Button>` with an `<OnClick>`, so it steps on the release; the knob drags.
     for (entity, arrow) in &arrows {
         if !clicks.hit(entity) {
             continue;
@@ -359,10 +336,8 @@ pub(super) fn scroll_drive(
     }
 }
 
-/// The scrollbar's look: the knob rides the scroll fraction, the arrows swap up/down/disabled art
-/// (disabled at their end stop, the additive highlight on hover), and every [`ScrollHides`] piece
-/// vanishes while the panel has nothing to scroll (the ref's `scrollBarHideable` + the Top/Bottom
-/// track art's range-changed hide).
+/// The scrollbar's look: the knob follows the scroll fraction, the arrows swap up, down and
+/// disabled art, and every [`ScrollHides`] piece hides while there is nothing to scroll.
 #[allow(clippy::type_complexity)]
 pub(super) fn scroll_visuals(
     art: Res<GlueArt>,
@@ -399,8 +374,7 @@ pub(super) fn scroll_visuals(
         if img.image != *face {
             img.image = face.clone();
         }
-        // A scroll arrow at the end of its travel is genuinely disabled — said once, in the
-        // component the shared sheen pass already reads, rather than re-derived beside it.
+        // The shared sheen pass reads this.
         if off.0 != disabled {
             off.0 = disabled;
         }
diff --git a/crates/benilla-app/src/char_create/screen.rs b/crates/benilla-app/src/char_create/screen.rs
index 720d20e6..c7323048 100644
--- a/crates/benilla-app/src/char_create/screen.rs
+++ b/crates/benilla-app/src/char_create/screen.rs
@@ -1,17 +1,6 @@
-//! The create screen's **layout** — the reference `CharacterCreate.xml` arrangement rebuilt in
-//! Bevy UI (decision 0423's polish passes), full-bleed and scaled to the window: the glue engine
-//! renders a 1024×768 virtual screen scaled to the display, so every authored offset/size below is
-//! the ref's number times `height / 768`. The widget shapes it places live in [`super::widgets`],
-//! the component vocabulary in [`super::parts`], the art in [`super::art`], and the systems that
-//! drive it all in [`super::refresh`].
-//!
-//! Left: the configuration tower — `UI-CharacterCreate-Background` under three stacked
-//! `OuterBorder` pieces, the faction banners behind the 2×4 race grid, the gender pair, the
-//! valid-classes-only grid, the five `LabelFrame` dial spinners, Randomize. Right: the three
-//! `TextPanel-Border` info panels (faction/race/class), bg-tinted per faction like the ref's
-//! `SetBackdropColor`, quoting the GlueStrings paragraphs. Center: the transparent-booth model,
-//! full-height, drag- or button-rotatable (the big `UI-RotationRight` pair, bottom-left). Bottom:
-//! NAME over the `Glue-Tooltip-Border` edit box; Accept over Back in the corner.
+//! The create screen's layout, the reference's `CharacterCreate.xml` in Bevy UI. The glue engine
+//! scales a 1024×768 virtual screen to the window, so every authored offset and size below is the
+//! reference's number times `height / 768`.
 
 use bevy::prelude::*;
 use bevy::ui_render::ui_material::MaterialNode;
@@ -68,10 +57,8 @@ pub(super) fn enter_create(
     );
 }
 
-/// Rebuild the tree when a window resize (mac fullscreen, a drag) has changed the glue scale it
-/// was baked at — the create screen has no per-frame materialize (it spawns on entry, after the
-/// boot-order traps the other screens dodge), so the rescale watch lives here. Selection and the
-/// typed name live in resources and repaint via [`super::refresh`], so the rebuild loses nothing.
+/// Rebuild the tree when a resize changes the glue scale; the selection and name live in
+/// resources, so the rebuild loses nothing.
 pub(super) fn rescale_screen(
     mut commands: Commands,
     existing: Query<(Entity, &CharCreateUi)>,
@@ -106,14 +93,12 @@ fn spawn_screen(
     window: &Query<&Window, With<PrimaryWindow>>,
 ) {
     let font = wow_font(assets);
-    // The edit box types in `GlueEditBoxFont` — ARIALN, not FRIZQT (GlueFonts.xml).
+    // The edit box types in `GlueEditBoxFont`, ARIALN, not FRIZQT (`GlueFonts.xml`).
     let edit_font: Handle<Font> = assets.load("mpq://Fonts/ARIALN.ttf");
     let model_image = match portraits.0.get(GLUE_SLOT) {
         Some(PortraitSource::Live(h)) => Some(h.clone()),
         _ => None,
     };
-    // The glue engine scales a 1024×768 virtual screen to the window; scale the authored sizes the
-    // same way so the ref proportions hold at any size.
     let s = crate::glue::screen_scale(window.single().ok());
     let px = |v: f32| Val::Px(v * s);
     let empty = GlueStrings::default();
@@ -132,12 +117,9 @@ fn spawn_screen(
             BackgroundColor(BACKDROP),
         ))
         .with_children(|ui| {
-            // The 3D scene, full-bleed and first (everything else draws over it) — the ref's
-            // screen IS a fullscreen ModelFFX: the per-race background with the character standing
-            // in it (the booth renders both into this window-sized target). The whole pane drags
-            // to rotate, the ref's full-frame mouse rotation; the page tint behind it is the
-            // no-art fallback. It keeps the WINDOW while the chrome below does not: a pillarbox's
-            // bars are the booth camera's own output clear inside this same target (1619 §3).
+            // The 3D scene first, full window: the reference's screen is a fullscreen ModelFFX,
+            // the race background with the character in it, and the whole frame drags to rotate.
+            // A pillarbox's bars are the booth camera's own clear inside this target.
             let mut pane = ui.spawn((
                 CreateAction::Model,
                 Button,
@@ -156,15 +138,13 @@ fn spawn_screen(
         })
         .id();
 
-    // ...and every piece of chrome hangs off the CANVAS — the boxed scene's own rect (decision
-    // 2091). The race/class towers are this screen's edge-anchored chrome: against the window they
-    // stand over the bars, and 1587's "no void at 21:9" held only because they did (1619 §2).
+    // The chrome hangs off the canvas, the boxed scene's rect, never the window.
     let mut canvas = commands.spawn((crate::glue::glue_canvas(), ChildOf(root)));
     canvas.with_children(|ui| {
         left_tower(ui, art, &font, s, strings);
 
-        // The WoW logo (`CharacterCreateWoWLogo`, 256×128 at (3,−7)) — after the tower, like the
-        // ref's frame order (child frames draw over the parent's border art).
+        // `CharacterCreateWoWLogo` (256×128 at (3,-7)), after the tower, as the reference's
+        // frame order draws it over the border art.
         if let Some(logo) = &art.logo {
             ui.spawn((ImageNode::new(logo.clone()), abs(s, 3.0, 7.0, 256.0, 128.0)));
         }
@@ -173,8 +153,7 @@ fn spawn_screen(
         name_cluster(ui, art, &font, &edit_font, s, strings);
         rotate_cluster(ui, art, &font, s);
 
-        // Accept over Back, bottom-right (`CharCreateOkayButton` 160×35 over `BackButton` 120×30
-        // at BOTTOMRIGHT (−50, 20)).
+        // `CharCreateOkayButton` 160×35 over `BackButton` 120×30 at BOTTOMRIGHT (-50,20).
         ui.spawn((Node {
             position_type: PositionType::Absolute,
             right: px(50.0),
@@ -211,8 +190,7 @@ fn spawn_screen(
     });
 }
 
-/// The configuration tower (`CharacterCreateConfigurationFrame`, 206×600 at TOPLEFT (28,−74)):
-/// frame art, banners, faction headers, the race/gender/class grids, the dial rows, Randomize —
+/// The configuration tower, `CharacterCreateConfigurationFrame` (206×600 at TOPLEFT (28,-74)),
 /// every child at its authored offset.
 fn left_tower(
     ui: &mut ChildSpawnerCommands,
@@ -231,9 +209,8 @@ fn left_tower(
         ..default()
     },))
         .with_children(|tower| {
-            // The frame: `UI-CharacterCreate-Background` stretched behind (TOPLEFT of border1 +6 →
-            // BOTTOMLEFT of border3 +6), three `OuterBorder` pieces stacked over it (224 wide,
-            // centered on the 206 frame → x −9; heights 236/240/210 with the authored texcoords).
+            // `UI-CharacterCreate-Background` behind three stacked `OuterBorder` pieces, 224 wide
+            // centered on the 206 frame (x -9).
             if let Some(bg) = &art.tower_bg {
                 tower.spawn((ImageNode::new(bg.clone()), abs(s, -3.0, 0.0, 218.0, 680.0)));
             }
@@ -253,16 +230,14 @@ fn left_tower(
                     ));
                 }
             }
-            // The banners (`CharacterCreateBanners`, 256×259 at TOP (−2,−60)) behind the race grid.
+            // `CharacterCreateBanners`, 256×259 at TOP (-2,-60), behind the race grid.
             if let Some(banners) = &art.banners {
                 tower.spawn((
                     ImageNode::new(banners.clone()),
                     abs(s, -27.0, 60.0, 256.0, 259.0),
                 ));
             }
-            // Alliance | Horde over the banner tops (bottom-anchored ±50 of the banner center).
-            // The XML's `text="ALLIANCE"` is a localization key — GlueStrings renders it
-            // mixed-case ("Alliance"), never the raw key.
+            // The XML's `text="ALLIANCE"` is a GlueStrings key, shown as "Alliance".
             for (key, fallback, center) in
                 [("ALLIANCE", "Alliance", 51.0), ("HORDE", "Horde", 151.0)]
             {
@@ -285,8 +260,7 @@ fn left_tower(
                 );
             }
 
-            // The race grid: two columns of 48² check-buttons (col A at (33,68), col B at (127,68),
-            // row pitch 48+5).
+            // Two columns of 48² buttons at (33,68) and (127,68), row pitch 48+5.
             for (faction, left) in [(ALLIANCE, 33.0), (HORDE, 127.0)] {
                 tower
                     .spawn((Node {
@@ -314,7 +288,7 @@ fn left_tower(
                     });
             }
 
-            // The gender pair (below race col A: race4's BOTTOMLEFT + (20,−28)).
+            // The gender pair at race button 4's BOTTOMLEFT + (20,-28).
             tower
                 .spawn((Node {
                     position_type: PositionType::Absolute,
@@ -348,9 +322,7 @@ fn left_tower(
                     }
                 });
 
-            // The class grid (3-wide under the banners: cols at x 27/79/131, rows touching) — 8
-            // slots refreshed to the selected race's valid classes; unused slots collapse (the
-            // ref's enumerate-then-hide compacts the same way).
+            // Three wide, columns at x 27/79/131; 8 slots, unused ones collapse.
             tower
                 .spawn((Node {
                     position_type: PositionType::Absolute,
@@ -378,8 +350,7 @@ fn left_tower(
                     }
                 });
 
-            // The five dial spinners (`CharacterCustomizationFrameTemplate`, 198×32 rows stacked
-            // from (4,480) — centered under the class grid).
+            // `CharacterCustomizationFrameTemplate`, 198×32 rows stacked from (4,480).
             tower
                 .spawn((Node {
                     position_type: PositionType::Absolute,
@@ -395,10 +366,9 @@ fn left_tower(
                     }
                 });
 
-            // RANDOMIZE (146×30, centered on the row column). The XML anchors it 25 below the
-            // dials, but `CharacterCreate_UpdateFacialHairCustomization` re-anchors it on every
-            // race set — `SetPoint("TOP", Frame5, "BOTTOM", 0, -5)` — so the shipped client always
-            // shows the 5px gap.
+            // The XML anchors it 25 below the dials, but
+            // `CharacterCreate_UpdateFacialHairCustomization` re-anchors it on every race set,
+            // `SetPoint("TOP", Frame5, "BOTTOM", 0, -5)`, so the 1.12 client shows a 5 px gap.
             tower
                 .spawn((Node {
                     position_type: PositionType::Absolute,
@@ -422,8 +392,8 @@ fn left_tower(
         });
 }
 
-/// One dial spinner row: the `CharacterCreate-LabelFrame` 3-slice (64-tall art overhanging the
-/// 32-tall row), the centered per-race label, and the 32² arrow pair on the right.
+/// One dial row: the `CharacterCreate-LabelFrame` 3-slice (64-tall art over the 32-tall row),
+/// the per-race label and the arrow pair.
 fn dial_row(
     dials: &mut ChildSpawnerCommands,
     art: &GlueArt,
@@ -442,8 +412,7 @@ fn dial_row(
             },
         ))
         .with_children(|row| {
-            // LabelFrame: Left 25 at (−5), Middle stretched, Right 25 ending at x 154 (RIGHT −44,
-            // clearing the arrows) — the 128×64 art's 25|78|25 horizontal slices.
+            // The 128×64 art's 25|78|25 slices: Left at x -5, Right ending at x 154 (RIGHT -44).
             if let Some((frame, size)) = &art.label_frame {
                 for (left, width, tc) in [
                     (-5.0, 25.0, [0.0, 0.1953125, 0.0, 1.0]),
@@ -460,7 +429,7 @@ fn dial_row(
                     ));
                 }
             }
-            // The per-race label, centered on the frame middle (`GlueFontHighlightSmall`).
+            // `GlueFontHighlightSmall`, centered on the frame middle.
             outlined_text(
                 row,
                 Node {
@@ -500,8 +469,7 @@ fn dial_row(
         });
 }
 
-/// NAME over the edit box (`CharacterCreateNameEdit`, 156×40 at BOTTOM (8,50), backdropped in
-/// `Glue-Tooltip-Border` — always Alliance-tinted, the ref's `OnLoad`), our status line beneath.
+/// NAME over `CharacterCreateNameEdit` (156×40 at BOTTOM (8,50)), with the status line beneath.
 fn name_cluster(
     ui: &mut ChildSpawnerCommands,
     art: &GlueArt,
@@ -536,8 +504,7 @@ fn name_cluster(
                 font,
                 s,
             );
-            // The shared glue edit-box chrome (decision 0539) — Alliance-tinted, always (the
-            // ref's `OnLoad`); the create refresh writes the typed name into the marker.
+            // Always Alliance-tinted, as the reference's `OnLoad` sets it.
             crate::glue::widgets::glue_edit_box(
                 cluster,
                 art,
@@ -549,8 +516,7 @@ fn name_cluster(
                 (15.0, 0.0, 0.0, 0.0), // CharacterCreate.xml: TextInsets left 15 only
                 s,
             );
-            // Empty until a create fails — the ref surfaces errors in a dialog; this line is our
-            // minimal stand-in, never an idle hint.
+            // Empty until a create fails; the reference shows the error in a dialog, not built.
             outlined_text(
                 cluster,
                 Node::default(),
@@ -568,8 +534,8 @@ fn name_cluster(
         });
 }
 
-/// The rotate pair (`CharacterCreateRotateLeft/Right`: 50² at BOTTOMLEFT (237,0), overlapping
-/// −19) — `UI-RotationRight-Big` art, the left button mirrored, `UI-Common-MouseHilight` on hover.
+/// `CharacterCreateRotateLeft/Right`: 50² at BOTTOMLEFT (237,0), overlapping -19, the left one
+/// the mirrored `UI-RotationRight-Big`.
 fn rotate_cluster(ui: &mut ChildSpawnerCommands, art: &GlueArt, font: &Handle<Font>, s: f32) {
     let px = |v: f32| Val::Px(v * s);
     ui.spawn((Node {
@@ -647,8 +613,7 @@ pub(super) fn exit_create(
     for e in &roots {
         commands.entity(e).despawn();
     }
-    // Clear the booth + scene. Back to CharSelect re-establishes both the same frame
-    // (its `OnEnter` runs after this `OnExit`).
+    // CharSelect's `OnEnter` runs after this and re-establishes both the same frame.
     preview.look = None;
     preview.scene = None;
 }
diff --git a/crates/benilla-app/src/char_select/addons.rs b/crates/benilla-app/src/char_select/addons.rs
index a6db2ce8..bae7ad50 100644
--- a/crates/benilla-app/src/char_select/addons.rs
+++ b/crates/benilla-app/src/char_select/addons.rs
@@ -1,49 +1,17 @@
-//! The **character-select AddOns screen** (decisions 1197, 1293) — the one addon surface (the
-//! in-game panel was retired at the director's call, 2026-08-14; `ReloadUI` itself stays).
+//! The character-select AddOns screen, the reference's `GlueXML\AddonList.xml/.lua` layout drawn
+//! natively: per row a tri-state checkbox (`GetAddOnEnableState`), the title gold when loadable,
+//! red when enabled and broken except `DEP_DISABLED` (grey), and the `ADDON_<reason>` status. A
+//! row has no highlight and no click; only its checkbox toggles. Okay is `SaveAddOns` (the next
+//! login applies it), Cancel, Escape and the X are `ResetAddOns`.
 //!
-//! The reference is `Interface\GlueXML\AddonList.xml/.lua`, read off the player's own patch chain
-//! (`patch.MPQ` — 1293 located it after 1197 believed it missing), and **this screen now draws the
-//! authored layout**: the six `HelpFrame-*` plate pieces that are the whole framed panel, the
-//! `UI-DialogBox-Header` title plate, the `GlueCloseButton`, the `GlueDropDownMenuTemplate`
-//! control, the 19×(16+4) entry column, the `GlueScrollFrameTemplate` bar with the
-//! `UI-Character-ScrollBar` track, and the four-button bottom row in the reference's own order
-//! (Disable All · Enable All ··· Okay · Cancel). Geometry constants below are the authored
-//! numbers, resolved top-down into the 640×512 plate. Behaviour is **re-expressed natively** —
-//! written under 1234's rule, which 1602 has since retired; the native form stays as a design
-//! choice, not a law.
+//! Deviation: no Script Memory dial, because there is no Lua heap cap here; no URL or update
+//! buttons, because launching a browser is an outward action (`## URL` shows in the tooltip); no
+//! security icon, because no installed addon carries `## Secure` honestly and it would always
+//! read insecure.
 //!
-//! ## What the reference does, and what we do
-//!
-//! `AddonList_Update` per row: a **tri-state** checkbox (`GetAddOnEnableState` → 0/1/2, the grey
-//! check drawn with `UI-CheckBox-Check-Disabled`), the title (`## Title` else the folder name)
-//! coloured **gold when loadable, red when enabled-and-broken — except `DEP_DISABLED`, which reads
-//! grey** (AddonList.lua's own exception), and the status token (`getglobal("ADDON_"..reason)`) in
-//! `GlueFontNormalSmall` 30 units right of the title box. Titles render their `|cAARRGGBB` markup
-//! as colour, exactly as every FontString does — as does every other string on this screen,
-//! the tooltip included ([`crate::glue::widgets::markup_spans`]). Hovering a row raises
-//! `AddonTooltip` (title + notes + `ADDON_DEPENDENCIES`) anchored to the row's left; hovering a
-//! MIXED checkbox raises `ENABLED_FOR_SOME`. **A row has no hover highlight and no row-click** —
-//! only the checkbox toggles (the entry template carries no `HighlightTexture` and no `OnClick`);
-//! reproducing that is also what killed the hover-respawn flashing the director reported: the
-//! spawned tree no longer changes under the cursor at all.
-//!
-//! Carried from 1197/1293: the character dropdown ("All" + the realm roster, staging
-//! per-character), the `checkAddonVersion`-inverted force-load checkbox, Okay = `SaveAddOns`
-//! (write the per-character enable files; the next login IS the apply point), Cancel/ESC/the X =
-//! `ResetAddOns` (discard). **Not built**, per 1197's standing rejections (Script Memory
-//! reaffirmed by the director, 2026-08-14): the Script Memory dial, the URL/update launch buttons
-//! (`## URL` shows in the tooltip instead — information, not a trigger), the security icon.
-//!
-//! ## Why it reads the folder rather than the VM
-//!
-//! At character select no addon has been *loaded* — `load_third_party` is a world-entry step
-//! (1191 §2) — so `GetNumAddOns()` would answer 0. The screen asks
-//! [`crate::ui_script::addons::installed_rows`] instead, and resolves the enable bits through
-//! [`crate::ui_script::addons::EnableStore`] exactly as the world-entry walk does: the same
-//! discovery, the same manifest parser, the same store. Two views of one folder, never two
-//! folders. Both reads happen **once at open** ([`AddonsPanel::open_for`]) — the folder walk used
-//! to run once per roster character, which decision 2311 retired along with the per-character
-//! `installed()` it was there to feed.
+//! No addon is loaded at the glue, so `GetNumAddOns()` would answer 0: the screen reads the folder
+//! once at open through [`crate::ui_script::addons::installed_rows`] and
+//! [`crate::ui_script::addons::EnableStore`], as world entry does.
 
 use bevy::prelude::*;
 use bevy::ui_render::ui_material::MaterialNode;
@@ -63,18 +31,18 @@ use crate::ui_script::addons::{self, InstalledAddOn};
 
 use super::wow_font;
 
-// ── The authored geometry (AddonList.xml, patch chain) — y resolved top-down in the plate ────────
+// ── The authored geometry (`AddonList.xml`), y resolved top-down in the plate ──────────────────
 
-/// `AddonListBackground` — the 640×512 `HelpFrame-*` plate, anchored CENTER +(24, 0).
+/// `AddonListBackground`, the 640×512 `HelpFrame-*` plate, anchored CENTER +(24, 0).
 const BG_W: f32 = 640.0;
 const BG_H: f32 = 512.0;
 const BG_CENTER_OFF_X: f32 = 24.0;
-/// `MAX_ADDONS_DISPLAYED` (AddonList.lua l.2).
+/// `MAX_ADDONS_DISPLAYED` (`AddonList.lua:2`).
 const MAX_ROWS: usize = 19;
-/// `ADDON_BUTTON_HEIGHT` (l.1); each entry anchors TOP to the previous BOTTOM at (0, −4).
+/// `ADDON_BUTTON_HEIGHT` (`AddonList.lua:1`); each entry's TOP sits 4 below the previous BOTTOM.
 const ROW_H: f32 = 16.0;
 const ROW_PITCH: f32 = ROW_H + 4.0;
-/// Entry 1 sits at TOPLEFT (37, −80); entries are 520 wide.
+/// Entry 1 sits at TOPLEFT (37, -80); entries are 520 wide.
 const ROW_LEFT: f32 = 37.0;
 const ROW_TOP: f32 = 80.0;
 const ROW_W: f32 = 520.0;
@@ -82,8 +50,8 @@ const ROW_W: f32 = 520.0;
 const TITLE_LEFT: f32 = 42.0;
 const TITLE_W: f32 = 220.0;
 const STATUS_LEFT: f32 = TITLE_LEFT + TITLE_W + 30.0;
-/// `AddonCharacterDropDown` at TOPLEFT (0, −38); its `CharacterCreate-LabelFrame` art is three
-/// 64-tall slices (25 | 115 | 25) whose top rides 17 ABOVE the 32-tall frame.
+/// `AddonCharacterDropDown` at TOPLEFT (0, -38); its `CharacterCreate-LabelFrame` art is three
+/// 64-tall slices (25 | 115 | 25) whose top rides 17 above the 32-tall frame.
 const DROP_TOP: f32 = 38.0;
 const DROP_ART_TOP: f32 = DROP_TOP - 17.0;
 const DROP_ART_H: f32 = 64.0;
@@ -95,36 +63,33 @@ const DROP_TC: [[f32; 4]; 3] = [
     [0.1953125, 0.8046875, 0.0, 1.0],
     [0.8046875, 1.0, 0.0, 1.0],
 ];
-/// The open list: TOPLEFT to the dropdown frame's BOTTOMLEFT +(8, 22 up) → (8, 48) in the plate.
+/// The open list: TOPLEFT to the dropdown's BOTTOMLEFT +(8, 22 up), (8, 48) in the plate.
 const DROP_LIST_LEFT: f32 = 8.0;
 const DROP_LIST_TOP: f32 = DROP_TOP + 32.0 - 22.0;
-/// `AddonListForceLoad`: a 32² checkbox whose TOP-center sits at (+50, −42); label at LEFT +36.
+/// `AddonListForceLoad`: a 32² checkbox whose TOP-center sits at (+50, -42); label at LEFT +36.
 const FORCE_LEFT: f32 = BG_W / 2.0 + 50.0 - 16.0;
 const FORCE_TOP: f32 = 42.0;
-/// `AddonListScrollFrame`: TOPLEFT (49, −73), 510×390; its slider column and track hang right.
+/// `AddonListScrollFrame`: TOPLEFT (49, -73), 510×390; its slider column and track hang right.
 const SCROLL_TOP: f32 = 73.0;
 const SCROLL_H: f32 = 390.0;
 const SCROLL_RIGHT: f32 = 49.0 + 510.0;
-/// The slider column between the two 16² arrows — the `<Slider>` the reference's
-/// `GlueScrollBarTemplate` authors, and the surface a drag measures itself against ([`ScrollBand`]).
+/// The slider column between the two 16² arrows, `GlueScrollBarTemplate`'s `<Slider>`.
 const BAR_TOP: f32 = SCROLL_TOP + 16.0;
 const BAR_H: f32 = SCROLL_H - 32.0;
-/// The knob's extent along the track (`UI-ScrollBar-Knob`, 16²).
+/// `UI-ScrollBar-Knob`, 16².
 const KNOB: f32 = 16.0;
 /// The bottom row: 35 tall, 13 off the plate bottom.
 const BTN_TOP: f32 = BG_H - 13.0 - 35.0;
 
-/// A red that reads as "this is enabled and will not load" — `SetTextColor(1.0, 0.1, 0.1)`,
-/// AddonList.lua's own value.
+/// Enabled but will not load: `SetTextColor(1.0, 0.1, 0.1)` (`AddonList.lua:63`).
 const BROKEN: Color = Color::srgb(1.0, 0.1, 0.1);
-/// The `AddonTooltip` backdrop tint — its `OnLoad`'s `SetBackdropColor(0.09, 0.09, 0.19)`.
+/// The `AddonTooltip` backdrop tint, its `OnLoad`'s `SetBackdropColor(0.09, 0.09, 0.19)`.
 const TIP_FILL: Color = Color::srgb(0.09, 0.09, 0.19);
 /// The tooltip's authored width.
 const TIP_W: f32 = 220.0;
 
-/// One checkbox's face — the reference's `GetAddOnEnableState` values by their meaning
-/// (0 / 2 / 1 = [`Self::Off`] / [`Self::On`] / [`Self::Mixed`]). `Mixed` exists only in the
-/// All view: enabled for SOME of the characters, not all of them.
+/// One checkbox's face, `GetAddOnEnableState`'s 0 / 2 / 1; `Mixed` (enabled for some characters)
+/// exists only in the All view.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 enum BoxState {
     Off,
@@ -132,72 +97,46 @@ enum BoxState {
     Mixed,
 }
 
-/// What the cursor is over, for the two tooltips: the row strip raises the `AddonTooltip` body,
-/// the checkbox raises `ENABLED_FOR_SOME` (only when its state is MIXED) — the reference splits
-/// them the same way (the entry's `OnEnter` vs the CheckButton's).
+/// What the cursor is over: a row raises `AddonTooltip`, a mixed checkbox `ENABLED_FOR_SOME`.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum Hover {
     Row(usize),
     Check(usize),
 }
 
-/// The screen's state. Opened by the select screen's AddOns button, driven by
-/// [`drive_addons_panel`], cleared on leaving character select.
-///
-/// `staged` is the whole point of Okay/Cancel: edits go here — one column per roster character —
-/// and only Okay writes the files. The reference does the same with `SaveAddOns`/`ResetAddOns`
-/// over the client's in-memory per-character records.
+/// The screen's state; edits stage per character and only Okay writes the files.
 #[derive(Resource)]
 pub(super) struct AddonsPanel {
     pub(super) open: bool,
-    /// The installed list as read at open — never re-read while up, so a row's index is stable.
-    /// Shared **metadata**: its own `enabled` bit is the first column's read and nothing repaints
-    /// from it; the live enable state is `staged`'s.
+    /// The installed list read at open, so a row's index is stable; the enable state is `staged`'s.
     list: Vec<InstalledAddOn>,
-    /// The realm the roster belongs to — half of every enable file's key (0997's `(realm, name)`).
+    /// The roster's realm, half of every enable file's `(realm, name)` key.
     realm: String,
-    /// The roster's character names at open, the dropdown's entries after "All". Empty on a fresh
-    /// account; `staged` then holds one anonymous column so the checkboxes still work (below).
+    /// The roster's character names, the dropdown's entries after "All".
     chars: Vec<String>,
-    /// The edited enable state: `staged[c][i]` is character `c`'s bit for `list[i]`. When `chars`
-    /// is empty this is ONE anonymous column (the folder with nobody's file — everything enabled);
-    /// it has no file behind it, so Okay writes nothing, exactly what the pre-1293 single-identity
-    /// screen did with no character.
+    /// `staged[c][i]` is character `c`'s bit for `list[i]`; with no characters, one anonymous
+    /// column that Okay does not write.
     staged: Vec<Vec<bool>>,
-    /// What the files said at open, column for column — Okay writes only the columns that moved
-    /// off this ([`Self::save_staged`]).
+    /// What the files said at open; Okay writes only the columns that moved off it.
     baseline: Vec<Vec<bool>>,
-    /// The dropdown's selection: `None` = "All", `Some(c)` = `chars[c]`. Which character's enable
-    /// state the list edits — and whose staged bits feed the gate.
+    /// The dropdown's selection: `None` is "All", `Some(c)` is `chars[c]`.
     view: Option<usize>,
-    /// The dropdown's option list is up (drawn over the list area).
     dropdown_open: bool,
-    /// The live `checkAddonVersion` mirror ("1"/absent = check ON = the force-load box UNTICKED),
-    /// refreshed from the boot VM every frame by [`drive_addons_panel`] — the same live-per-query
-    /// read the gate's verbs make (1292 §2.2), which is why toggling the box repaints the statuses
-    /// with nothing rescanned.
+    /// The live `checkAddonVersion`, true meaning the force-load box is unticked; read off the
+    /// boot VM every frame.
     version_check: bool,
     /// First visible row (`AddonList.offset`).
     offset: usize,
-    /// The scroll bar's in-flight drag: the grab [`slider_grab`] returned at the press, as a
-    /// fraction of the band's own height ([`ScrollBand`]).
-    ///
-    /// Held here rather than read back off `Interaction::Pressed` because the panel **respawns
-    /// its whole tree** on any repaint — and a drag repaints it every row it crosses. A fresh
-    /// entity's `Interaction` starts at `None`, so a capture inferred from the widget would drop
-    /// the moment the drag moved the list. The button's own held state (`ButtonInput`) is the
-    /// only thing that survives a respawn, so that is what the drag rides on.
+    /// The scroll drag's grab, as a fraction of the band's height. Held here, not read off
+    /// `Interaction::Pressed`: a drag respawns the tree, and a fresh entity's `Interaction` is
+    /// `None`.
     drag: Option<f32>,
-    /// The spawned tooltip, keyed by what it describes — **the only thing hover drives, and
-    /// never a repaint trigger**. The old model set `dirty` on every hover change and respawned
-    /// the whole tree, which reset the fresh entities' `Interaction` to `None`, which flipped
-    /// the hover back, which respawned again — the "border flashing" the director reported.
+    /// The spawned tooltip, keyed by what it describes. Hover never sets `dirty`: a respawn resets
+    /// `Interaction`, which would flip the hover and respawn again.
     tip: Option<(Hover, Entity)>,
     root: Option<Entity>,
     spawned_s: f32,
-    /// Set while the spawned tree no longer matches the state — one flag rather than a diff,
-    /// because a 19-row list is cheaper to respawn than to reconcile. Hover is deliberately NOT
-    /// part of this (above).
+    /// The spawned tree no longer matches the state and is respawned whole.
     dirty: bool,
 }
 
@@ -212,9 +151,8 @@ impl Default for AddonsPanel {
             baseline: Vec::new(),
             view: None,
             dropdown_open: false,
-            // The registrar default: "1" = check ON (1292, byte-verified). Hand-written Default
-            // for this one field — a derived `false` would paint every out-of-date row loadable
-            // for the frame before the drive system's first CVar read corrects it.
+            // The registered default, "1"; a `false` would paint out-of-date rows loadable for a
+            // frame.
             version_check: true,
             offset: 0,
             drag: None,
@@ -227,22 +165,13 @@ impl Default for AddonsPanel {
 }
 
 impl AddonsPanel {
-    /// Open for this realm's roster: the folder read **once** into one metadata list, and one
-    /// staged column per character off the enable store. The reference's `AddonList_OnShow` also
-    /// re-reads (`AddonList_Update`), so a folder that changed under us is picked up.
-    ///
-    /// **The store is loaded for the whole roster, not per character** (decision 2311). A column
-    /// is not "that character's file, everything else enabled": an addon the character has no row
-    /// for takes what the realm's *other* characters agree on, and only falls to the manifest's
-    /// `## DefaultState` when they disagree or nobody has said anything. Reading it the other way
-    /// is what made a newly created character re-enable every addon in the All view — its
-    /// all-enabled column turned every disabled row Mixed, and Mixed reads as on.
+    /// Open for this realm's roster: read the folder, and one staged column per character, as
+    /// `AddonList_OnShow` re-reads. The store loads for the whole roster: an addon a character has
+    /// no row for takes what the other characters agree on, else the manifest's `## DefaultState`.
     pub(super) fn open_for(&mut self, realm: String, chars: Vec<String>) {
         self.list = addons::installed_rows();
         self.staged.clear();
         let store = addons::EnableStore::load(&realm, &chars);
-        // A fresh account stages one anonymous column: no character means no file to key, and
-        // Okay has none to write ([`Self::save_staged`] walks `chars`).
         let columns: Vec<Option<&str>> = if chars.is_empty() {
             vec![None]
         } else {
@@ -259,7 +188,7 @@ impl AddonsPanel {
         self.baseline = self.staged.clone();
         self.realm = realm;
         self.chars = chars;
-        // "All" is the reference's own default selection (AddonList.lua's dropdown initializer).
+        // "All" is the reference's default selection.
         self.view = None;
         self.dropdown_open = false;
         self.offset = 0;
@@ -280,10 +209,7 @@ impl AddonsPanel {
         self.dirty = true;
     }
 
-    /// Okay — the reference's `SaveAddOns`: write the per-character enable files, and only for
-    /// the characters whose staged column actually moved off what their file said at open (the
-    /// write is [`addons::write_enable_state`]'s merge, so an untouched character's file is not
-    /// even opened). The anonymous no-roster column has no file and writes nothing.
+    /// Okay, `SaveAddOns`: write the enable file of each character whose column changed.
     fn save_staged(&self) {
         for (c, name) in self.chars.iter().enumerate() {
             if self.staged.get(c) == self.baseline.get(c) {
@@ -300,23 +226,13 @@ impl AddonsPanel {
         }
     }
 
-    /// Are there any installed addons at all? The reference hides its button when not
-    /// (`UpdateAddonButton`), and so do we — a button that opens an empty list is worse than none.
-    ///
-    /// **Answered once per process, not per call.** The screen asks this while it is spawning its
-    /// tree, and the tree respawns on every glue-scale change — which during a window drag-resize
-    /// is *every frame*. Reading the folder there means a `read_dir` plus a `.toc` parse per addon
-    /// per frame for as long as the director holds the mouse down. Installing or removing an addon
-    /// mid-session is not a thing that happens, so the cache never needs invalidating; the panel
-    /// itself re-reads the folder on every open ([`Self::open_for`]), which is where freshness
-    /// actually matters.
+    /// Whether any addon is installed (`UpdateAddonButton` hides the button otherwise). Cached for
+    /// the process: the screen respawns every frame of a drag-resize.
     pub(super) fn any_installed() -> bool {
         static ANY: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
         *ANY.get_or_init(|| !addons::installed_rows().is_empty())
     }
 
-    /// The rows currently visible, as `(index, addon)` — enable state is the view's to answer
-    /// ([`Self::box_state`]), not the metadata's.
     fn visible(&self) -> impl Iterator<Item = (usize, &InstalledAddOn)> {
         self.list
             .iter()
@@ -325,14 +241,11 @@ impl AddonsPanel {
             .take(MAX_ROWS)
     }
 
-    /// The highest first-row index that still fills the list.
     fn max_offset(&self) -> usize {
         self.list.len().saturating_sub(MAX_ROWS)
     }
 
-    /// Where the knob sits, as a fraction of its travel — the value→pixel direction. Shared by the
-    /// spawn (which draws the knob there) and the drag (which needs to know where it grabbed), so
-    /// the two can never disagree about what the bar is showing.
+    /// Where the knob sits, as a fraction of its travel; shared by the spawn and the drag.
     fn thumb_fraction(&self) -> f32 {
         match self.max_offset() {
             0 => 0.0,
@@ -340,12 +253,8 @@ impl AddonsPanel {
         }
     }
 
-    /// The pixel→value direction: seat the first visible row at `fraction` of the way down.
-    ///
-    /// Rounded to a whole row because this list scrolls by ROWS, not pixels — the reference's
-    /// AddonList is a faux scroll frame over 19 fixed slots, so the knob rides in row-sized
-    /// detents. `dirty` only when the row actually changes: a drag inside one detent must not
-    /// respawn the tree 60 times a second.
+    /// Seat the first visible row at `fraction` of the way down, rounded to a row: the reference's
+    /// list is a faux scroll frame over 19 fixed slots.
     fn scroll_to(&mut self, fraction: f32) {
         let next = (fraction * self.max_offset() as f32).round() as usize;
         if next != self.offset {
@@ -354,9 +263,8 @@ impl AddonsPanel {
         }
     }
 
-    /// One row's checkbox state for the current view. A single character's view is plain
-    /// two-state over their column; the All view is the reference's tri-state — its
-    /// `GetAddOnEnableState(nil, i)`: enabled for all / for some (the greyed check) / for none.
+    /// One row's checkbox for the current view; the All view is `GetAddOnEnableState(nil, i)`'s
+    /// tri-state.
     fn box_state(&self, i: usize) -> BoxState {
         match self.view {
             Some(c) => {
@@ -387,21 +295,13 @@ impl AddonsPanel {
         }
     }
 
-    /// Is this addon enabled *for the current view* — the bit the gate is fed? A single character
-    /// reads their own column. The All view answers **"any staged character has it on"**, which
-    /// 1293 stated as the natural reading of an untraced mechanism and which the bytes have
-    /// since confirmed: `AddonList_Update` computes `enabled = (checkboxState > 0)` off
-    /// `GetAddOnEnableState(nil, i)`, whose `1` (enabled for some) therefore counts as on
-    /// (`0x51e470`). What 1293 got wrong was not this fold but what each column holds — see
-    /// [`Self::open_for`] and decision 2311.
+    /// The enable bit the gate is fed: in the All view, on for any character, since
+    /// `AddonList_Update` takes `enabled = (checkboxState > 0)` (`AddonList.lua:48`, `0x51e470`).
     fn effective_enabled(&self, i: usize) -> bool {
         self.box_state(i) != BoxState::Off
     }
 
-    /// The current view lowered into the gate's adapter rows (1292): the folder's one registry
-    /// with THIS view's staged enable bits. `loaded` is `false` for every row — nothing has
-    /// loaded at the glue (`load_third_party` is a world-entry step, 1191 §2), so the loaded
-    /// short-circuit can never fire here.
+    /// The current view as the gate's rows; nothing is loaded at the glue.
     fn gate_rows(&self) -> Vec<GateRow<'_>> {
         self.list
             .iter()
@@ -417,20 +317,14 @@ impl AddonsPanel {
             .collect()
     }
 
-    /// **Why a row will not load** — the one arbiter's answer (1292), which the status column
-    /// splices and the title colour keys on. `demand_only=false`: this is the glue surface
-    /// (`dl=0`) — `NOT_DEMAND_LOADED` is unreachable here. `version_check` is the live CVar
-    /// mirror, re-read per query like the reference (1292 §2.2).
+    /// Why a row will not load. The glue surface passes `demand_only=false`, so
+    /// `NOT_DEMAND_LOADED` is unreachable; the version check is re-read per query.
     fn verdict(&self, i: usize) -> Verdict {
         can_load(&self.gate_rows(), i, false, self.version_check)
     }
 
-    /// AddonList.lua's title colour, verbatim in structure: gold when loadable; red when the
-    /// player has it ON and it still will not load — **unless the reason is `DEP_DISABLED`**,
-    /// which reads grey like a disabled row (the Lua's own `reason ~= "DEP_DISABLED"` guard: the
-    /// player already made that choice one row up, and red would blame the dependent); grey
-    /// otherwise. Any `|c` markup in the title overrides this base per-span, exactly as the
-    /// reference FontString renders it ([`crate::glue::widgets::markup_spans`]).
+    /// The title colour (`AddonList.lua:60-66`): gold when loadable, red when enabled and still
+    /// not loading unless the reason is `DEP_DISABLED`, grey otherwise. `|c` markup overrides it.
     fn title_colour(&self, i: usize) -> Color {
         let verdict = self.verdict(i);
         if verdict.loadable() {
@@ -442,10 +336,8 @@ impl AddonsPanel {
         }
     }
 
-    /// A checkbox click for the current view. In a single character's view it is a plain toggle
-    /// of their bit. In the All view it is the reference's CheckButton over the tri-state: a
-    /// grey (mixed) box **counts as checked**, so clicking On *or* Mixed unchecks — disable for
-    /// every character — and only a fully-unchecked box enables for all.
+    /// A checkbox click. In the All view a mixed box counts as checked, so clicking On or Mixed
+    /// disables for every character and only an unchecked box enables for all.
     fn click_row(&mut self, i: usize) {
         match self.view {
             Some(c) => {
@@ -466,8 +358,7 @@ impl AddonsPanel {
         }
     }
 
-    /// Enable All / Disable All sweep the CURRENT VIEW: the view the player is editing is the
-    /// view the sweep edits — "All" sweeps every column, a single character's view only theirs.
+    /// Enable All and Disable All sweep the current view's columns.
     fn set_all(&mut self, on: bool) {
         match self.view {
             Some(c) => {
@@ -484,7 +375,6 @@ impl AddonsPanel {
         self.dirty = true;
     }
 
-    /// The dropdown's current value — "All" or the viewed character's name.
     fn view_name<'a>(&'a self, strings: &'a GlueStrings) -> &'a str {
         match self.view {
             None => strings.text("ALL", "All"),
@@ -493,11 +383,8 @@ impl AddonsPanel {
     }
 }
 
-/// The status column's text: the reference's `getglobal("ADDON_"..reason)` splice, run against
-/// the parsed GlueStrings table — the glue side loads no VM to splice in (1197 §3), but the
-/// string TABLE is loaded, so the lookup is the same one. The fallbacks are the shipped values
-/// of the same tokens, pinned by `the_status_labels_are_the_reference_globalstrings_values`
-/// (verified against the extracted 1.12 chain, GlueStrings.lua l.44-56).
+/// The status text, `getglobal("ADDON_"..reason)` over the parsed GlueStrings; the fallbacks are
+/// the shipped values (`GlueStrings.lua:44-56`).
 fn status_label<'a>(strings: &'a GlueStrings, token: &'a str) -> &'a str {
     let fallback = match token {
         "DISABLED" => "Disabled",
@@ -505,19 +392,14 @@ fn status_label<'a>(strings: &'a GlueStrings, token: &'a str) -> &'a str {
         "DEP_MISSING" => "Dependency missing",
         "DEP_DISABLED" => "Dependency disabled",
         "DEP_INTERFACE_VERSION" => "Dependency out of date",
-        // `BANNED`/`CORRUPT`/`INSECURE` gate on server signature state we do not model, and
-        // `NOT_DEMAND_LOADED` is the in-game surface's (`demand_only=false` here) — none is
-        // producible at the glue (addon_gate's module doc); the raw token is the honest fallback.
+        // `BANNED`, `CORRUPT`, `INSECURE` and `NOT_DEMAND_LOADED` are not produced at the glue.
         other => other,
     };
     strings.get(&format!("ADDON_{token}")).unwrap_or(fallback)
 }
 
-/// Flip the *Load out of date AddOns* box: the `checkAddonVersion` CVar **inverted** (1292 §2,
-/// byte-verified — ticked = `"0"`). A host write into the registry (2303), which is what
-/// persists it and what the VM's mirror learns — nothing else to do: the statuses repaint from
-/// [`drive_addons_panel`]'s per-frame mirror, no rescan, because the gate re-reads the flag per
-/// query (1292 §2.2).
+/// Flip the "Load out of date AddOns" box, the `checkAddonVersion` CVar inverted (ticked is
+/// `"0"`); the statuses repaint from [`drive_addons_panel`]'s per-frame read.
 fn toggle_force_load(cvars: &mut crate::cvars::Cvars) {
     let checking = cvars.addon_version_check();
     cvars.set("checkAddonVersion", if checking { "0" } else { "1" });
@@ -526,50 +408,38 @@ fn toggle_force_load(cvars: &mut crate::cvars::Cvars) {
 /// The panel's clickable parts.
 #[derive(Component, Clone, Copy, PartialEq, Eq)]
 pub(super) enum AddonsAction {
-    /// A row's CHECKBOX — the only thing on a row that clicks, as in the reference (the entry
-    /// template has no `OnClick`; `AddonList_Enable` hangs off the CheckButton alone).
+    /// A row's checkbox, the only thing on a row that clicks (`AddonList_Enable`).
     Row(usize),
-    /// The row strip itself: hover raises the `AddonTooltip`; a press does nothing.
+    /// The row strip: hover raises the `AddonTooltip`; a press does nothing.
     RowHover(usize),
     EnableAll,
     DisableAll,
     Okay,
-    /// Cancel, the ESC key, and the `GlueCloseButton` X — all `AddonList_OnCancel`.
+    /// Cancel, Escape and the `GlueCloseButton` X, all `AddonList_OnCancel`.
     Cancel,
     ScrollUp,
     ScrollDown,
-    /// The slider column — **one surface covering knob and track alike**, because the law has no
-    /// thumb hit-test to gate capture on: a press anywhere on the bar captures, and where it
-    /// *grabs* is [`slider_grab`]'s to say, from geometry rather than from picking.
+    /// The slider column, one surface for knob and track: a press anywhere captures, and
+    /// [`slider_grab`] says where it grabs.
     ScrollBar,
-    /// The dropdown control — opens/closes the option list. Also carried by the open list's
-    /// full-screen backdrop, so a click that misses every option closes it (click-away).
+    /// The dropdown control; also the open list's full-screen backdrop, so a missed click closes
+    /// it.
     DropdownToggle,
-    /// One dropdown option: `None` = "All", `Some(c)` = that roster character.
+    /// One dropdown option: `None` is "All", `Some(c)` a roster character.
     DropdownPick(Option<usize>),
-    /// The *Load out of date AddOns* checkbox ([`toggle_force_load`]).
+    /// The "Load out of date AddOns" checkbox.
     ForceLoad,
 }
 
-/// The panel root (despawned whole on close).
 #[derive(Component)]
 struct AddonsUi;
 
-/// The scroll bar's travel band — the node spanning [`BAR_TOP`]`..`[`BAR_TOP`]`+`[`BAR_H`], with
-/// the knob riding inside it as a child.
-///
-/// The drag reads its `ComputedNode`/`UiGlobalTransform` rather than re-deriving where the bar
-/// landed on screen: this panel is centered by a flex parent at a window-dependent scale, so any
-/// hand-rolled screen-rect math here would be a second copy of the layout, wrong the first time
-/// the window resizes. Normalizing the cursor into this node's own box is scale-free by
-/// construction.
+/// The scroll bar's travel band, the knob its child. The drag normalizes the cursor into this
+/// node's own box, so it is free of the window scale and centering.
 #[derive(Component)]
 pub(super) struct ScrollBand;
 
-/// Spawn/despawn the panel, run its flows, and repaint when anything it shows has changed.
-///
-/// Ordered before the select screen's own click handling so a click that lands on the panel is
-/// never also read as a click on the screen behind it.
+/// Spawn or despawn the panel, run its flows, and repaint when anything it shows changed.
 pub(super) fn drive_addons_panel(
     mut commands: Commands,
     mut panel: ResMut<AddonsPanel>,
@@ -602,10 +472,8 @@ pub(super) fn drive_addons_panel(
     let mut close_and_discard = false;
     let mut bar_pressed = false;
     for (entity, action, interaction) in &hovers {
-        // **The scroll bar warps on the PRESS**, and only it: the reference's `CSimpleSlider`
-        // OnMouseDown (`0x789ca0`, 45 bytes, zero branches) warps the value from any press inside
-        // the hit rect — there is no thumb hit-test in the class. Every *button*
-        // in this panel fires on the RELEASE, over the button that took the press (1533).
+        // The scroll bar acts on the press: `CSimpleSlider`'s OnMouseDown (`0x789ca0`) warps from
+        // any press in its hit rect, with no thumb hit-test. Every button fires on release.
         let click = if *action == AddonsAction::ScrollBar {
             interaction.is_changed() && *interaction == Interaction::Pressed
         } else {
@@ -625,8 +493,7 @@ pub(super) fn drive_addons_panel(
             AddonsAction::ScrollDown => scroll(&mut panel, 1),
             AddonsAction::ScrollBar => bar_pressed = true,
             AddonsAction::DropdownToggle => {
-                // The reference's dropdown button click (`ToggleDropDownMenu` +
-                // `PlaySound("igMainMenuOptionCheckBoxOn")`).
+                // `ToggleDropDownMenu` and `PlaySound("igMainMenuOptionCheckBoxOn")`.
                 sounds.write(GlueSound("igMainMenuOptionCheckBoxOn"));
                 panel.dropdown_open = !panel.dropdown_open;
                 panel.dirty = true;
@@ -638,13 +505,11 @@ pub(super) fn drive_addons_panel(
                 panel.dirty = true;
             }
             AddonsAction::ForceLoad => {
-                // No VM (a bare test world / a capture): nothing to write to and nothing the
-                // walk would read differently — the box is inert, honestly.
                 toggle_force_load(&mut cvars);
             }
         }
     }
-    // `AddonList_OnKeyDown`: ESCAPE cancels, ENTER accepts.
+    // `AddonList_OnKeyDown`: Escape cancels, Enter accepts.
     if keys.just_pressed(KeyCode::Escape) {
         close_and_discard = true;
     }
@@ -657,25 +522,18 @@ pub(super) fn drive_addons_panel(
         }
     }
 
-    // ── the scroll bar's drag (B274) ──────────────────────────────────────────────────────────
-    // Benilla's one slider law, reached from the glue lane: the press grabs ([`slider_grab`] —
-    // on the knob it keeps the grabbed point, off it the knob's centre warps under the cursor),
-    // and press and every move after it share the one absolute cursor→value map
-    // ([`slider_fraction`]). Absolute, so it cannot drift off the cursor over a long drag; and
-    // the capture rides the held BUTTON, not the widget, so it survives the repaint that every
-    // crossed row triggers and keeps tracking with the cursor off the bar entirely.
+    // ── the scroll bar's drag ──────────────────────────────────────────────────────────
+    // The press grabs ([`slider_grab`]), then every move maps the cursor absolutely
+    // ([`slider_fraction`]). The capture rides the held button, so it survives each respawn.
     let cursor = window
         .single()
         .ok()
         .and_then(|w| w.physical_cursor_position());
     if !mouse.pressed(MouseButton::Left) || cursor.is_none() {
-        // Release, or the cursor left the window — the widget lane abandons a capture on the
-        // same two conditions.
         panel.drag = None;
     }
     if let (Some(cursor), Ok((node, xf))) = (cursor, band.single()) {
-        // Everything below is a fraction of the band's own height, which makes it free of the
-        // window scale, the panel's centering, and the retina factor all at once.
+        // Fractions of the band's height, free of scale, centering and the retina factor.
         if let Some(local) = node.normalize_point(*xf, cursor) {
             let cursor_n = local.y + 0.5;
             let thumb_n = KNOB / BAR_H;
@@ -684,7 +542,7 @@ pub(super) fn drive_addons_panel(
                 panel.drag = Some(slider_grab(cursor_n, lead_n, thumb_n));
             }
             if let Some(grab) = panel.drag {
-                // `None` = a knob with nowhere to go; the bar is not spawned in that case.
+                // `None` is a knob with nowhere to go; the bar is not spawned then.
                 if let Some(f) = slider_fraction(cursor_n, grab, 1.0, thumb_n) {
                     panel.scroll_to(f);
                 }
@@ -692,10 +550,8 @@ pub(super) fn drive_addons_panel(
         }
     }
 
-    // The live `checkAddonVersion` mirror (1293): read per frame like the gate's own per-query
-    // read (1292 §2.2), so the ForceLoad click above — or any other writer — repaints the
-    // statuses this same frame with nothing rescanned. Absent VM or table = the registrar
-    // default: check ON.
+    // `checkAddonVersion` read per frame, as the gate reads it per query; absent, the registered
+    // default "1".
     let version_check = script
         .as_deref()
         .and_then(|s| s.cvar("checkAddonVersion"))
@@ -706,7 +562,7 @@ pub(super) fn drive_addons_panel(
     }
 
     if close_and_save {
-        // `AddonList_OnOk` / `AddonList_OnCancel` play the realm dialog's pair.
+        // `AddonList_OnOk` and `AddonList_OnCancel` play the realm dialog's pair.
         sounds.write(GlueSound("gsLoginChangeRealmOK"));
         panel.save_staged();
         panel.close();
@@ -740,13 +596,11 @@ pub(super) fn drive_addons_panel(
         ));
         panel.spawned_s = s;
         panel.dirty = false;
-        // Fresh entities — hover, tooltips and highlights reconcile against them next frame.
+        // Hover and tooltips reconcile against the fresh entities next frame.
         return;
     }
 
     // ── hover: the tooltip, with the tree left alone ──────────────────────────────────────────
-    // (The sheens are `crate::glue::glue_hilights`' — this panel used to drive its own, which is
-    // one of the four copies that let the realm list ship with none.)
 
     let hover = hovers.iter().find_map(|(_, a, i)| {
         if !matches!(*i, Interaction::Hovered | Interaction::Pressed) {
@@ -758,8 +612,7 @@ pub(super) fn drive_addons_panel(
             _ => None,
         }
     });
-    // What the tooltip should say for this hover — `None` collapses "nothing hovered" and "a
-    // checkbox that is not mixed" (the reference's CheckButton only carries a tooltip then).
+    // A checkbox carries a tooltip only when mixed.
     let want = match hover {
         Some(h @ Hover::Row(_)) => Some(h),
         Some(h @ Hover::Check(i)) if panel.box_state(i) == BoxState::Mixed => Some(h),
@@ -773,8 +626,7 @@ pub(super) fn drive_addons_panel(
             let row = match h {
                 Hover::Row(i) | Hover::Check(i) => i,
             };
-            // Anchor to the row strip — the reference's own
-            // `AddonTooltip:SetPoint("TOPRIGHT", this, "TOPLEFT", -14, 0)`.
+            // `AddonTooltip:SetPoint("TOPRIGHT", this, "TOPLEFT", -14, 0)` on the row strip.
             let strip = hovers
                 .iter()
                 .find_map(|(e, a, _)| (*a == AddonsAction::RowHover(row)).then_some(e));
@@ -792,7 +644,7 @@ pub(super) fn drive_addons_panel(
     }
 }
 
-/// Move the first visible row by `delta`, clamped — the reference's `AddonList.offset`.
+/// Move the first visible row (`AddonList.offset`) by `delta`, clamped.
 fn scroll(panel: &mut AddonsPanel, delta: i32) {
     let max = panel.max_offset();
     let next = (panel.offset as i32 + delta).clamp(0, max as i32) as usize;
@@ -802,12 +654,9 @@ fn scroll(panel: &mut AddonsPanel, delta: i32) {
     }
 }
 
-/// One checkbox as the reference `CheckButton` draws it: the `UI-CheckBox-Up` box always (the
-/// pressed swap is [`ArtSwap`]'s), the check OVERLAID — gold (`-Check`) when on, grey
-/// (`-Check-Disabled`) when mixed (`TriStateCheckbox_SetState`'s state-1 texture) — and the ADD
-/// highlight lit on hover ([`HoverLit`]). The old face swapped the box art for the check art,
-/// which is why the director's screenshot showed floating checks with no boxes. Plain-fill
-/// fallback without art.
+/// One checkbox as the `CheckButton` draws it: the `UI-CheckBox-Up` box always, the check overlaid
+/// (`-Check` when on, `-Check-Disabled` when mixed, `TriStateCheckbox_SetState`'s state 1), and the
+/// ADD highlight on hover.
 fn checkbox_button<A: Component>(
     parent: &mut ChildSpawnerCommands,
     art: &GlueArt,
@@ -859,8 +708,7 @@ fn checkbox_button<A: Component>(
         None => {
             b.insert(BackgroundColor(match state {
                 BoxState::On => GOLD,
-                // Ours: halfway between the art-less GOLD and DIM, so a mixed box still reads
-                // as its own state.
+                // Art-less only: halfway between GOLD and DIM.
                 BoxState::Mixed => Color::srgb(0.75, 0.64, 0.25),
                 BoxState::Off => DIM,
             }));
@@ -891,9 +739,8 @@ fn spawn_panel(
         .spawn((
             AddonsUi,
             GlobalZIndex(1200), // over the select screen's 1100, like the delete dialog
-            // The reference's own full-screen BACKGROUND layer: black at 0.75 over the glue
-            // scene, which is also what keeps a stray click off the screen behind (picking
-            // follows z-order).
+            // The reference's full-screen BACKGROUND layer, black at 0.75; it also keeps a stray
+            // click off the screen behind.
             BackgroundColor(Color::srgba(0.0, 0.0, 0.0, 0.75)),
             Node {
                 width: Val::Percent(100.0),
@@ -907,13 +754,11 @@ fn spawn_panel(
             let mut boxed = overlay_ui.spawn(Node {
                 width: px(BG_W),
                 height: px(BG_H),
-                // The plate's authored CENTER offset (+24, 0).
                 left: px(BG_CENTER_OFF_X),
                 ..default()
             });
             boxed.with_children(|b| {
-                // ── the HelpFrame plate: six pieces tiling 640×512, frame + top band + dark
-                // inset + bottom band all baked into the art ─────────────────────────────────
+                // ── the HelpFrame plate: six pieces tiling 640×512 ─────────────────────────
                 match &art.help_frame {
                     Some(hf) => {
                         for (img, l, t, w, h) in [
@@ -926,9 +771,8 @@ fn spawn_panel(
                         ] {
                             b.spawn((ImageNode::new(img.clone()), abs(l, t, w, h)));
                         }
-                        // The ARTWORK divider strip under the top band: the same three top
-                        // pieces' authored sub-band (TexCoords y 0.12109375–0.234375), 29 tall
-                        // at y 50.
+                        // The ARTWORK divider under the top band: the top pieces' TexCoords
+                        // y 0.12109375-0.234375, 29 tall at y 50.
                         const BAND_TC: [f32; 4] = [0.0, 1.0, 0.121_093_75, 0.234_375];
                         for (i, (img, l, w)) in [
                             (&hf.tl, 0.0, 256.0),
@@ -956,8 +800,8 @@ fn spawn_panel(
                     }
                 }
 
-                // ── the header plate + title (`UI-DialogBox-Header` 256×64 at TOP (−12, +12),
-                // `ADDON_LIST` GlueFontNormalSmall 14 under its top) ─────────────────────────
+                // ── the header plate (`UI-DialogBox-Header` 256×64 at TOP (-12, +12)) and
+                // `ADDON_LIST` ───────────────────────────────────────────────────────────────
                 if let Some((header, _)) = &art.dialog_header {
                     b.spawn((
                         ImageNode::new(header.clone()),
@@ -986,7 +830,7 @@ fn spawn_panel(
                     s,
                 );
 
-                // ── the close X (`GlueCloseButton` at TOPRIGHT (−42, −3)) — Cancel ──────────
+                // ── the close X (`GlueCloseButton` at TOPRIGHT (-42, -3)), Cancel ──────────
                 {
                     let mut x = b.spawn((
                         AddonsAction::Cancel,
@@ -1035,8 +879,7 @@ fn spawn_panel(
                     }
                 }
 
-                // ── "Configure Addons For:" + the dropdown (`AddonCharacterDropDown`,
-                // `GlueDropDownMenuTemplate`) ────────────────────────────────────────────────
+                // ── "Configure Addons For:" and `AddonCharacterDropDown` ─────────────────────
                 outlined_text(
                     b,
                     Node {
@@ -1063,8 +906,6 @@ fn spawn_panel(
                         abs(0.0, DROP_ART_TOP, DROP_W, DROP_ART_H),
                     ));
                     drop.with_children(|d| {
-                        // The three `CharacterCreate-LabelFrame` slices (25 | 115 | 25 of the
-                        // 128-wide art) — the same sheet the create screen's dial rows use.
                         if let Some((sheet, size)) = &art.label_frame {
                             let mut left = 0.0;
                             for (w, tc) in DROP_SLICE_W.iter().zip(DROP_TC) {
@@ -1084,8 +925,7 @@ fn spawn_panel(
                                 abs(10.0, 20.0, DROP_W - 20.0, 24.0),
                             ));
                         }
-                        // The selected value (white, `GlueFontHighlightSmall`) right-aligned
-                        // beside the arrow — the template's own text seat.
+                        // The selected value, `GlueFontHighlightSmall`, right-aligned by the arrow.
                         outlined_text(
                             d,
                             Node {
@@ -1109,7 +949,7 @@ fn spawn_panel(
                             &font,
                             s,
                         );
-                        // The 24² arrow (`UI-ChatIcon-ScrollDown-*` + `UI-Common-MouseHilight`).
+                        // The 24² arrow (`UI-ChatIcon-ScrollDown-*`, `UI-Common-MouseHilight`).
                         let mut arrow = d.spawn((
                             AddonsAction::DropdownToggle,
                             Button,
@@ -1157,10 +997,8 @@ fn spawn_panel(
                     });
                 }
 
-                // ── "Load out of date AddOns" (`AddonListForceLoad`: a 32² checkbox at TOP
-                // (+50, −42), label at LEFT +36) — the `checkAddonVersion` CVar INVERTED
-                // (ticked = "0"; 1292 §2.1: force-load actively ERASES the refusal, so ticking
-                // repaints every INTERFACE_VERSION row as plain loadable) ────────────────────
+                // ── "Load out of date AddOns" (`AddonListForceLoad`): ticking erases the
+                // `INTERFACE_VERSION` refusal, so those rows repaint loadable ────────────────
                 checkbox_button(
                     b,
                     art,
@@ -1198,23 +1036,17 @@ fn spawn_panel(
                 for (slot, (index, addon)) in panel.visible().enumerate() {
                     let top = ROW_TOP + slot as f32 * ROW_PITCH;
                     let state = panel.box_state(index);
-                    // The one arbiter (1292): status and colour both come from the gate over
-                    // the CURRENT VIEW's staged states.
                     let status = panel.verdict(index).token();
                     let colour = panel.title_colour(index);
 
-                    // The row strip: tooltip hover only — no click, no highlight (the
-                    // reference entry has neither; see the module doc on the flashing).
+                    // The row strip: tooltip hover only, no click and no highlight.
                     b.spawn((
                         AddonsAction::RowHover(index),
                         Button,
                         abs(ROW_LEFT, top, ROW_W, ROW_H),
                     ))
                     .with_children(|r| {
-                        // Title — `GlueFontNormal`, 220 wide, colour markup rendered
-                        // ([`crate::glue::widgets::markup_spans`], run by every `GlueText`);
-                        // clipped at the authored box so a long title
-                        // cannot run into the status column.
+                        // Title, clipped at its 220-wide box so it cannot run into the status.
                         outlined_text(
                             r,
                             Node {
@@ -1237,8 +1069,7 @@ fn spawn_panel(
                             &font,
                             s,
                         );
-                        // Status — `GlueFontNormalSmall` (gold), 30 right of the title box:
-                        // the reference's `getglobal("ADDON_"..reason)` splice.
+                        // Status, `GlueFontNormalSmall` gold, 30 right of the title box.
                         if let Some(token) = status.as_deref() {
                             outlined_text(
                                 r,
@@ -1262,8 +1093,8 @@ fn spawn_panel(
                             );
                         }
                     });
-                    // The checkbox: a 32² CheckButton at the entry's LEFT +5, spawned after
-                    // the strip so it wins the pick where they overlap.
+                    // A 32² CheckButton at the entry's LEFT +5, spawned after the strip so it
+                    // wins the pick where they overlap.
                     checkbox_button(
                         b,
                         art,
@@ -1273,14 +1104,11 @@ fn spawn_panel(
                     );
                 }
 
-                // ── the scrollbar, shown only when the list overflows (the reference's
-                // `GlueScrollFrame_Update` hides it on the same condition): the
-                // `UI-Character-ScrollBar` decorative track + the `GlueScrollBarTemplate`
-                // column (16² arrows, the knob riding the offset fraction) ──────────────────
+                // ── the scrollbar, only when the list overflows (`GlueScrollFrame_Update`) ───
                 if panel.max_offset() > 0 {
                     if let Some((track, size)) = &art.char_scrollbar {
                         for (l, t, w, h, tc) in [
-                            // Top 31×256 at scrollframe TOPRIGHT (−2, +5).
+                            // Top 31×256 at scrollframe TOPRIGHT (-2, +5).
                             (
                                 SCROLL_RIGHT - 2.0,
                                 SCROLL_TOP - 5.0,
@@ -1288,7 +1116,7 @@ fn spawn_panel(
                                 256.0,
                                 [0.0, 0.484_375, 0.0, 1.0],
                             ),
-                            // Middle, spanning to the bottom piece (TexCoords y .75–1).
+                            // Middle, spanning to the bottom piece (TexCoords y .75-1).
                             (
                                 SCROLL_RIGHT - 2.0,
                                 SCROLL_TOP - 5.0 + 256.0,
@@ -1296,7 +1124,7 @@ fn spawn_panel(
                                 (SCROLL_TOP + SCROLL_H + 2.0 - 106.0) - (SCROLL_TOP - 5.0 + 256.0),
                                 [0.0, 0.484_375, 0.75, 1.0],
                             ),
-                            // Bottom 31×106 at scrollframe BOTTOMRIGHT (−2, −2).
+                            // Bottom 31×106 at scrollframe BOTTOMRIGHT (-2, -2).
                             (
                                 SCROLL_RIGHT - 2.0,
                                 SCROLL_TOP + SCROLL_H + 2.0 - 106.0,
@@ -1315,7 +1143,7 @@ fn spawn_panel(
                             ));
                         }
                     }
-                    // The slider column: TOPLEFT at scrollframe TOPRIGHT +(6, −16).
+                    // The slider column: TOPLEFT at scrollframe TOPRIGHT +(6, -16).
                     let bar_left = SCROLL_RIGHT + 6.0;
                     let bar_top = BAR_TOP;
                     let bar_h = BAR_H;
@@ -1343,10 +1171,7 @@ fn spawn_panel(
                                 ));
                             });
                         }
-                        // The band IS the slider: pressable end to end, with the knob a
-                        // decorative child riding at the value fraction. Splitting them into two
-                        // pickable surfaces would put a thumb hit-test back into the capture
-                        // decision, which the class does not have (`slider_grab`).
+                        // The band is the slider, pressable end to end; the knob is decoration.
                         b.spawn((
                             AddonsAction::ScrollBar,
                             ScrollBand,
@@ -1355,10 +1180,8 @@ fn spawn_panel(
                         ))
                         .with_children(|band| {
                             band.spawn((
-                                // The knob must NOT capture the press it sits under: a UI node
-                                // with no `FocusPolicy` defaults to `Block`, and a blocking knob
-                                // would swallow every press aimed at it — the one gesture this
-                                // whole path exists to serve — leaving only the bare track
+                                // The knob must not block the press: a node's default
+                                // `FocusPolicy` is `Block`, which would leave only the track
                                 // draggable.
                                 bevy::ui::FocusPolicy::Pass,
                                 ImageNode {
@@ -1411,9 +1234,8 @@ fn spawn_panel(
                     }
                 }
 
-                // ── the bottom row, the reference's own order and geometry: Disable All ·
-                // Enable All (`AddonListButtonTemplate` 160×35 from BOTTOMLEFT +16) ··· Okay ·
-                // Cancel (`GlueDialogButtonTemplate` 125×35 from BOTTOMRIGHT −46) ───────────
+                // ── the bottom row: Disable All, Enable All (`AddonListButtonTemplate` 160×35
+                // from BOTTOMLEFT +16), Okay, Cancel (125×35 from BOTTOMRIGHT -46) ──────────
                 for (action, token, fallback, left, w, kind) in [
                     (
                         AddonsAction::DisableAll,
@@ -1463,10 +1285,8 @@ fn spawn_panel(
                     });
                 }
 
-                // ── the dropdown's open list (`UIDropDownListTemplate`: the DialogBox
-                // backdrop, 16-tall rows, the gold check on the current selection, the
-                // `UI-QuestTitleHighlight` hover), plus a full-screen click-away backdrop
-                // underneath it in z ────────────────────────────────────────────────────────
+                // ── the dropdown's open list (`UIDropDownListTemplate`) over a full-screen
+                // click-away backdrop ────────────────────────────────────────────────────────
                 if panel.dropdown_open {
                     b.spawn((
                         AddonsAction::DropdownToggle,
@@ -1521,8 +1341,7 @@ fn spawn_panel(
                                 Color::WHITE,
                             );
                         }
-                        // "All" first, then the roster in its own order — the reference's
-                        // `AddonListCharacterDropDown_Initialize` shape.
+                        // "All", then the roster (`AddonListCharacterDropDown_Initialize`).
                         for view in std::iter::once(None).chain((0..panel.chars.len()).map(Some)) {
                             let name = match view {
                                 None => strings.text("ALL", "All"),
@@ -1590,11 +1409,9 @@ fn spawn_panel(
         .id()
 }
 
-/// The hover tooltip — the reference's `AddonTooltip` (a 220-wide `UI-Tooltip-Border` box, fill
-/// `(0.09, 0.09, 0.19)`, title + notes + `ADDON_DEPENDENCIES` in that order) anchored TOPRIGHT to
-/// the row's TOPLEFT at (−14, 0), spawned as the row strip's child so the anchor is structural.
-/// `## URL` rides as an extra line (1197: information, not a launch button). A MIXED checkbox
-/// hover shows `ENABLED_FOR_SOME` alone — the reference's GlueTooltip split, on the same box.
+/// `AddonTooltip`: title, notes and `ADDON_DEPENDENCIES` in a 220-wide box, a child of the row
+/// strip. Deviation: `## URL` adds a line in place of the reference's launch button, because
+/// launching a browser is an outward action. A mixed checkbox shows `ENABLED_FOR_SOME` alone.
 fn spawn_tooltip(
     parent: &mut ChildSpawnerCommands,
     art: &GlueArt,
@@ -1607,7 +1424,7 @@ fn spawn_tooltip(
 ) -> Entity {
     let px = |v: f32| Val::Px(v * s);
     let font = wow_font(assets);
-    // (text, size, colour) per line; empties dropped below.
+    // (text, size, colour) per line; empties are dropped.
     let mut lines: Vec<(String, f32, Color)> = Vec::new();
     match hover {
         Hover::Row(_) => {
@@ -1714,9 +1531,7 @@ mod tests {
         }
     }
 
-    /// A panel over `chars` staged columns (each starting at the list's own `enabled` bits),
-    /// viewing All — the open-time default. Tests that want a single character's view set
-    /// `p.view = Some(c)` themselves.
+    /// A panel over `chars` staged columns, each starting at the manifest defaults, viewing All.
     fn panel_for(chars: usize, list: Vec<InstalledAddOn>) -> AddonsPanel {
         let staged: Vec<Vec<bool>> = (0..chars.max(1))
             .map(|_| list.iter().map(|a| a.default_state).collect())
@@ -1732,25 +1547,15 @@ mod tests {
         }
     }
 
-    /// The single-character convenience: one column, All view — over one column the All view IS
-    /// that column (any-on and all-on coincide), so `p.staged[0][i]` drives everything.
+    /// One column, whose All view is that column, so `p.staged[0][i]` drives everything.
     fn panel(list: Vec<InstalledAddOn>) -> AddonsPanel {
         panel_for(1, list)
     }
 
-    /// **Every label this panel can show is the value its reference token carries**.
-    ///
-    /// The splice is the reference's own (`getglobal("ADDON_"..reason)`), run against the parsed
-    /// GlueStrings table; what this pins is the FALLBACKS — the strings shown with no client
-    /// data — quoted from the extracted 1.12 chain (GlueStrings.lua l.44-56). An empty table
-    /// exercises exactly that path.
-    ///
-    /// This test exists because a comment here once named a token `INCOMPATIBLE`, **which does
-    /// not exist** — the real one is `ADDON_INTERFACE_VERSION`. A wrong token name is invisible
-    /// until somebody splices it.
+    /// Every fallback label is its token's shipped value (`GlueStrings.lua:44-56`).
     #[test]
     fn the_status_labels_are_the_reference_globalstrings_values() {
-        let strings = GlueStrings::default(); // no chain in a test — the pinned fallbacks answer
+        let strings = GlueStrings::default(); // no chain, so the fallbacks answer
         for (token, want) in [
             ("DISABLED", "Disabled"),
             ("DEP_DISABLED", "Dependency disabled"),
@@ -1766,13 +1571,8 @@ mod tests {
         }
     }
 
-    /// The status column's rule — THE GATE's verdict (1292): `AddOn_CanLoad`'s byte-verified
-    /// check order, consulted over the current view's staged states.
-    ///
-    /// The ordering is the part worth pinning: a row the player turned OFF reads `DISABLED` and
-    /// nothing else, even when its dependency is also missing — the gate's check 3 precedes the
-    /// dependency loop, and the alternative tells a player to go fix a dependency for an addon
-    /// they deliberately switched off.
+    /// The status is the gate's verdict in `AddOn_CanLoad`'s check order: a row turned off reads
+    /// `DISABLED` even with a missing dependency, since that check precedes the dependency loop.
     #[test]
     fn the_status_column_reports_the_gates_reason_in_the_references_precedence() {
         let mut p = panel(vec![
@@ -1804,29 +1604,22 @@ mod tests {
              byte-verified; supersedes 1191 §6's silent-is-current reading)"
         );
 
-        // Force-load ERASES the refusal (1292 §2.1: reason 7 written, then reset to 0) — with
-        // the box ticked an out-of-date row is byte-indistinguishable from a current one, so the
-        // screen shows nothing there, faithfully.
+        // Force-load erases the refusal (reason 7 written, then reset to 0), so a ticked box
+        // leaves an out-of-date row indistinguishable from a current one.
         p.version_check = false;
         assert_eq!(p.verdict(4).token(), None);
         assert_eq!(p.verdict(5).token(), None);
         p.version_check = true;
 
-        // Turning the library off makes its dependent unloadable, and the dependent says so.
         p.staged[0][1] = false;
         assert_eq!(p.verdict(1).token().as_deref(), Some("DISABLED"));
         assert_eq!(p.verdict(2).token().as_deref(), Some("DEP_DISABLED"));
 
-        // ...and a row the player turned off reports only that, even with a broken dependency.
         p.staged[0][3] = false;
         assert_eq!(p.verdict(3).token().as_deref(), Some("DISABLED"));
     }
 
-    /// AddonList.lua's title colour, including its one exception: an enabled row that will not
-    /// load reads RED — **unless the reason is `DEP_DISABLED`**, where the Lua's own
-    /// `reason ~= "DEP_DISABLED"` guard sends it to grey (the player already made that choice
-    /// on the dependency's row; the first build here painted it red and the director's shot
-    /// showed the mismatch).
+    /// An enabled row that will not load is red, except for `DEP_DISABLED`, which is grey.
     #[test]
     fn the_title_colour_follows_addonlist_luas_rule_with_the_dep_disabled_exception() {
         let mut p = panel(vec![
@@ -1846,14 +1639,14 @@ mod tests {
         );
     }
 
-    /// The All view's gate input is OUR reading (1293): "enabled = any staged character has it on".
+    /// The All view feeds the gate "on for any character" (`checkboxState > 0`).
     #[test]
     fn the_all_view_feeds_the_gate_any_character_on() {
         let mut p = panel_for(
             2,
             vec![addon("Lib", &[], 11200), addon("Needs", &["Lib"], 11200)],
         );
-        p.staged[0][0] = false; // Char0 turned Lib off; Char1 has not
+        p.staged[0][0] = false; // Char0 turned Lib off, Char1 has not
 
         assert_eq!(
             p.verdict(0).token(),
@@ -1870,8 +1663,6 @@ mod tests {
         assert_eq!(p.verdict(0).token(), None, "Char1's view is untouched");
     }
 
-    /// The All view's box is the reference's tri-state (`GetAddOnEnableState`: 0/1/2), computed
-    /// across every staged column; a single character's view is plain two-state over theirs.
     #[test]
     fn the_all_view_box_is_a_tri_state_over_every_character() {
         let mut p = panel_for(3, vec![addon("A", &[], 11200)]);
@@ -1888,22 +1679,19 @@ mod tests {
         p.staged[2][0] = false;
         assert_eq!(p.box_state(0), BoxState::Off, "disabled for all");
 
-        // A single character's view never shows Mixed — it is their own bit, both ways.
         p.view = Some(1);
         assert_eq!(p.box_state(0), BoxState::Off);
         p.staged[1][0] = true;
         assert_eq!(p.box_state(0), BoxState::On);
     }
 
-    /// An All-view click is the reference's CheckButton over the tri-state: a grey (mixed) box
-    /// COUNTS AS CHECKED, so clicking it — or a fully-checked one — unchecks (disable for every
-    /// character), and only a fully-unchecked box enables for all.
+    /// In the All view a mixed box counts as checked, so a click disables for every character.
     #[test]
     fn an_all_view_click_follows_the_references_checkbutton() {
         let mut p = panel_for(3, vec![addon("A", &[], 11200)]);
         p.staged[1][0] = false; // mixed
 
-        p.click_row(0); // mixed = checked → click unchecks
+        p.click_row(0);
         assert!(
             p.staged.iter().all(|col| !col[0]),
             "mixed → disabled for ALL characters"
@@ -1918,14 +1706,12 @@ mod tests {
         p.click_row(0);
         assert!(p.staged.iter().all(|col| !col[0]), "checked → back off");
 
-        // In a single character's view the same click is a plain toggle of THEIR bit.
         p.view = Some(2);
         p.click_row(0);
         assert!(p.staged[2][0] && !p.staged[0][0] && !p.staged[1][0]);
     }
 
-    /// Okay/Cancel is a **staged** edit: nothing the panel does touches an enable file until
-    /// Okay. `Cancel` is the reference's `ResetAddOns`, and `close` is what implements it.
+    /// No enable file is touched until Okay; Cancel (`ResetAddOns`) is `close`.
     #[test]
     fn edits_are_staged_and_cancel_discards_them() {
         let mut p = panel(vec![addon("A", &[], 11200), addon("B", &[], 11200)]);
@@ -1943,10 +1729,7 @@ mod tests {
         );
     }
 
-    /// **Okay fans out per character** (1293 — the reference's `SaveAddOns` over the dropdown's
-    /// roster): every character whose staged column moved off its open-time baseline gets their
-    /// own merge-write, and an untouched character's file is not even created. Hermetic under
-    /// `BENILLA_HOME` like the walk's own folder tests (`ui_script/addons.rs`).
+    /// Okay writes each changed character's file and creates none for an untouched one.
     #[test]
     fn okay_writes_every_changed_characters_file_and_only_those() {
         let _l = crate::local_state::test_env::ENV_LOCK
@@ -1975,13 +1758,11 @@ mod tests {
         assert_eq!(p.staged.len(), 3, "one staged column per roster character");
         assert_eq!(p.staged, p.baseline);
 
-        // Distinct edits: Alice loses Alpha, Bob loses Beta, Carol touches nothing.
         p.staged[0][0] = false;
         p.staged[1][1] = false;
         p.save_staged();
 
-        // Read back through the same store the world-entry walk resolves against — the two views
-        // of one folder that 1197 §3 demands can never disagree.
+        // Read back through the store world entry resolves against.
         let roster = ["Alice".to_string(), "Bob".to_string(), "Carol".to_string()];
         let store = addons::EnableStore::load("TestRealm", &roster);
         let rows = addons::installed_rows();
@@ -2001,27 +1782,15 @@ mod tests {
             !addons::enable_state_path(Some(&carol)).unwrap().exists(),
             "an unchanged column writes no file — only the diffs against the open-time baseline"
         );
-        // And Carol, who has no file at all, is NOT "everything enabled": she takes what the
-        // others agree on, which here is nothing — Alpha and Beta are each on for one and off
-        // for the other — so both fall to their manifests' `## DefaultState` (2311).
+        // Carol, with no file, takes what the others agree on; they split on both, so each falls
+        // to its manifest's `## DefaultState`.
         assert_eq!(read("Carol"), vec![true, true]);
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
-    /// **Creating a character does not re-enable everything** — the director's report,
-    /// 2026-09-17: *"after creating a new char all addons are enabled again, even after disabling
-    /// all of them just before"*.
-    ///
-    /// The walk is theirs, verbatim: Disable All in the All view, Okay, create a character, open
-    /// the list again. What used to happen is the whole bug in one line — the new character had
-    /// no `AddOns.txt`, benilla read an absent row as **enabled**, and that all-true column turned
-    /// every row in the All view from Off to Mixed, which paints a check and reads as on
-    /// (`effective_enabled`). One click there would then have written the all-enabled state back
-    /// onto every other character's file: a one-way ratchet.
-    ///
-    /// The reference does not do this: its enable query `0x51e470` counts only nodes with an
-    /// **explicit** entry, so a character with no file contributes no opinion and inherits the
-    /// aggregate — here, the unanimous `disabled` the player just saved. Decision 2311.
+    /// Disable All, Okay, then create a character: the list reopens all disabled. The reference's
+    /// enable query `0x51e470` counts only explicit entries, so a character with no file inherits
+    /// the aggregate.
     #[test]
     fn a_new_character_inherits_the_disable_it_did_not_ask_for() {
         let _l = crate::local_state::test_env::ENV_LOCK
@@ -2040,7 +1809,6 @@ mod tests {
         let _h =
             crate::local_state::test_env::EnvGuard::set("BENILLA_HOME", home.to_str().unwrap());
 
-        // The roster before the create, and the player's Disable All + Okay over it.
         let mut p = AddonsPanel::default();
         p.open_for(
             "TestRealm".into(),
@@ -2050,8 +1818,7 @@ mod tests {
         p.save_staged();
         p.close();
 
-        // …then a character is created, so the roster the panel opens over has one more name and
-        // that name has no enable file at all.
+        // A created character, with no enable file.
         p.open_for(
             "TestRealm".into(),
             vec!["Onemage".into(), "Onerogue".into(), "Freshling".into()],
@@ -2074,9 +1841,8 @@ mod tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
-    /// The other side of the same law: a new character does **not** inherit a disable the roster
-    /// never agreed on. One character off, one on, and the newcomer takes the manifest's
-    /// `## DefaultState` — so this is not "new characters copy whoever is strictest".
+    /// A new character does not inherit a disable the roster split on: it takes the manifest's
+    /// `## DefaultState`.
     #[test]
     fn a_new_character_inherits_nothing_when_the_roster_disagrees() {
         let _l = crate::local_state::test_env::ENV_LOCK
@@ -2128,10 +1894,7 @@ mod tests {
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
-    /// The force-load box IS the `checkAddonVersion` CVar inverted, and a toggle is a host
-    /// write into the registry (2303) — that is the whole persistence story (the write dirties
-    /// the config and reaches the VM's mirror through the outbox); the panel itself only
-    /// repaints from its per-frame mirror, rescanning nothing (1292 §2.2).
+    /// The force-load box is the `checkAddonVersion` CVar inverted, written into the registry.
     #[test]
     fn the_force_load_box_flips_the_cvar_in_the_registry() {
         let mut cvars = crate::cvars::Cvars::default();
@@ -2161,17 +1924,8 @@ mod tests {
         );
     }
 
-    /// **B274** — the knob is draggable, and the drag is the client's own law.
-    ///
-    /// This models the press/move arithmetic the drive system runs, in the same band-normalized
-    /// units: `cursor_n` is the cursor as a fraction of the bar's height, `thumb_n` the knob's
-    /// share of it. Only the cursor read and the `ComputedNode` lookup are left out — everything
-    /// that decides where the list lands is here.
-    ///
-    /// What it pins is the property the reporter is missing (a grab moves the list at all) plus
-    /// the two that make it feel right: **offset-preserving** on the knob (grab its bottom edge,
-    /// and the list does not jump before you have moved), and **absolute, not accumulated**, so a
-    /// long drag cannot walk away from the cursor.
+    /// The drive system's press and move arithmetic in band-normalized units: a knob grab keeps
+    /// its offset, and the drag is absolute, so it cannot walk away from the cursor.
     #[test]
     fn the_scroll_knob_drags_the_list_under_the_cursor() {
         let thumb_n = KNOB / BAR_H;
@@ -2184,35 +1938,32 @@ mod tests {
         let max = p.max_offset();
         assert_eq!(max, MAX_ROWS + 1);
 
-        // Press the knob at its BOTTOM edge, at rest (knob at the top of the track).
+        // Press the resting knob at its bottom edge.
         let grab = slider_grab(thumb_n, 0.0, thumb_n);
         assert_eq!(grab, thumb_n, "grabbing the knob's bottom keeps that point");
         let f = slider_fraction(thumb_n, grab, 1.0, thumb_n).expect("the bar has travel");
         p.scroll_to(f);
         assert_eq!(p.offset, 0, "the press alone must not jump the list");
 
-        // Drag to the middle of the track; the grabbed point stays under the cursor, so the
-        // knob's LEADING edge lands half a knob above it.
+        // Mid-track: the grabbed point stays under the cursor, the leading edge half a knob up.
         let f = slider_fraction(0.5 + thumb_n * 0.5, grab, 1.0, thumb_n).unwrap();
         p.scroll_to(f);
         assert_eq!(p.offset, max / 2, "mid-track = mid-list");
 
-        // Past the bottom end: pinned, never past it (the clamp `SetValue` does in the client).
+        // Past the bottom end: pinned, the clamp `SetValue` does.
         let f = slider_fraction(4.0, grab, 1.0, thumb_n).unwrap();
         p.scroll_to(f);
         assert_eq!(p.offset, max);
         assert_eq!(p.visible().count(), MAX_ROWS, "the last page is still full");
 
-        // Absolute, not accumulated: returning the cursor to where it pressed returns the list
-        // to where it started, however far it wandered in between.
+        // Absolute: returning the cursor to the press point returns the list to its start.
         let f = slider_fraction(thumb_n, grab, 1.0, thumb_n).unwrap();
         p.scroll_to(f);
         assert_eq!(p.offset, 0);
     }
 
-    /// A press on the TRACK — off the knob — warps the knob's centre under the cursor and drags
-    /// on from there, one gesture. 1.12 does this (`0x789ca0`, and the director's own requirement
-    /// in 0989); the glue bar runs the same law as every in-game one.
+    /// A press on the bare track warps the knob's centre under the cursor and drags on from there
+    /// (`0x789ca0`).
     #[test]
     fn a_press_on_the_bare_track_warps_the_knob_under_the_cursor() {
         let thumb_n = KNOB / BAR_H;
@@ -2236,10 +1987,8 @@ mod tests {
         assert!(p.dirty, "and the move repaints");
     }
 
-    /// The two directions are inverses at every stop: draw the knob where the offset says
-    /// ([`AddonsPanel::thumb_fraction`]), read the offset back out of that position
-    /// ([`AddonsPanel::scroll_to`]), and land on the same row. A bar that fails this creeps a row
-    /// per grab.
+    /// [`AddonsPanel::thumb_fraction`] and [`AddonsPanel::scroll_to`] are inverses at every stop,
+    /// or a bar creeps a row per grab.
     #[test]
     fn the_knob_position_and_the_row_it_means_are_inverses() {
         let mut p = panel(
diff --git a/crates/benilla-app/src/char_select/dialog.rs b/crates/benilla-app/src/char_select/dialog.rs
index 132c6c81..5a90d042 100644
--- a/crates/benilla-app/src/char_select/dialog.rs
+++ b/crates/benilla-app/src/char_select/dialog.rs
@@ -1,15 +1,6 @@
-//! The delete confirm dialog (`CharacterDeleteDialog`, decision 0465) — the ref's typed-confirm:
-//! the 512×256 `UI-DialogBox` centered over the screen, `CONFIRM_CHAR_DELETE` naming the selected
-//! character, the alert icon, an edit box where typing `DELETE_CONFIRM_STRING` ("DELETE") enables
-//! Okay, and Okay/Cancel (`GlueDialogButtonTemplate` 200×40). Esc cancels, Enter confirms when
-//! armed; Okay sends `CMSG_CHAR_DELETE` through the parked glue channel and plays
-//! `gsTitleOptionOK` (Cancel: `gsTitleOptionExit`). The target is snapshotted at open (guid +
-//! title), so a roster refresh mid-dialog can never retarget the delete.
-//!
-//! The edit box is `CharacterDeleteEditBox` verbatim (CharacterSelect.xml): 130×32, the two
-//! `UI-ChatInputBorder-Left/Right` 75×32 pieces overhanging it by 10 each side, typing in
-//! `GlueFontHighlight` (FRIZQT 15 white — outlined like every glue font), no TextInsets, and the
-//! standard drawn caret bar ([`caret_bar`]) blinking on the ref's 0.5 s clock, solid while typing.
+//! The delete confirm dialog (`CharacterDeleteDialog`): typing `DELETE_CONFIRM_STRING` ("DELETE")
+//! arms Okay, which sends `CMSG_CHAR_DELETE` (`gsTitleOptionOK`); Cancel or Escape close it
+//! (`gsTitleOptionExit`). The target is snapshotted at open, so a roster refresh cannot retarget.
 
 use benilla_ui::widget::EditBoxState;
 use bevy::input::keyboard::KeyboardInput;
@@ -29,25 +20,21 @@ use crate::sound::GlueSound;
 
 use super::wow_font;
 
-/// The dialog's state: opened by the Delete button (the target snapshotted), driven by
-/// [`drive_delete_dialog`], cleared on leave.
+/// The delete dialog's state.
 #[derive(Resource, Default)]
 pub(super) struct DeleteDialog {
     pub(super) open: bool,
-    /// The snapshotted delete target (guid) + its display line pieces (name, level, class name).
+    /// The snapshotted target: guid, name, level, class name.
     target: Option<(u64, String, u8, &'static str)>,
-    /// What's been typed into the confirm box — a real [`EditBoxState`] (decision 0704), so it
-    /// has the caret, selection, Ctrl+A and clipboard every other field has. The ref's
-    /// `letters="32"` cap is the box's own `max_letters`. (`pub(super)` for the shot instrument.)
+    /// The confirm box's text; the reference's `letters="32"` cap is its `max_letters`.
     pub(super) typed: EditBoxState,
     /// The spawned dialog root, while up.
     root: Option<Entity>,
-    /// The glue scale the spawned tree was built at — a resize rebuilds it.
+    /// The glue scale the tree was built at; a resize rebuilds it.
     spawned_s: f32,
 }
 
 impl DeleteDialog {
-    /// Open for the character (snapshot — the roster may refresh underneath).
     pub(super) fn open_for(&mut self, guid: u64, name: String, level: u8, class: &'static str) {
         self.open = true;
         self.target = Some((guid, name, level, class));
@@ -60,7 +47,8 @@ impl DeleteDialog {
         self.typed.set_text("");
     }
 
-    /// The typed text matches `DELETE_CONFIRM_STRING` (case-insensitive, the ref's `strupper`).
+    /// The typed text matches `DELETE_CONFIRM_STRING`, case-insensitive (the reference's
+    /// `strupper`).
     fn armed(&self, confirm: &str) -> bool {
         self.typed.text.eq_ignore_ascii_case(confirm)
     }
@@ -76,18 +64,15 @@ pub(super) enum DialogAction {
 /// The typed-text line inside the edit box.
 #[derive(Component)]
 pub(super) struct TypedText;
-/// The edit box's caret bar (the shared [`caret_bar`]; [`drive_delete_dialog`] blinks it — the
-/// dialog's one field always holds the focus, like the create screen's name box).
+/// The edit box's caret bar; the dialog's one field always holds the focus.
 #[derive(Component)]
 pub(super) struct DeleteCaret;
 /// The dialog root (despawned on close).
 #[derive(Component)]
 struct DialogUi;
 
-/// Spawn/despawn the dialog with [`DeleteDialog::open`], feed its typing, and run its flows:
-/// Okay (enabled only while the typed text matches) sends the delete; Cancel/Esc close; Enter
-/// confirms when armed. Runs before the list refresh so a successful delete's roster update
-/// repaints the same frame it lands.
+/// Spawn or despawn the dialog, feed its typing and run Okay, Cancel, Enter and Escape. Runs
+/// before the list refresh, so a delete's roster update repaints the frame it lands.
 #[allow(clippy::type_complexity)]
 pub(super) fn drive_delete_dialog(
     mut commands: Commands,
@@ -102,16 +87,13 @@ pub(super) fn drive_delete_dialog(
     buttons: Query<(Entity, &DialogAction)>,
     clicks: Res<crate::glue::GlueClicks>,
     mut okay: Query<(&DialogAction, &mut GlueDisabled)>,
-    // The five row items of the confirm box (segments + carets), painted by the shared
-    // `paint_glue_field`; plus the host pasteboard and the window handle its Wayland backend needs.
     mut parts: Query<(
         &crate::glue::widgets::GlueFieldPart,
         Option<&mut Text>,
         &mut Visibility,
     )>,
     mut clipboard: NonSendMut<HostClipboard>,
-    // One query: the window drives the glue scale, and its raw handle carries the `wl_display` the
-    // Wayland clipboard backend is built from (decision 0702).
+    // The window drives the glue scale; its raw handle carries the Wayland clipboard's display.
     window: Query<
         (&Window, Option<&bevy::window::RawHandleWrapper>),
         With<bevy::window::PrimaryWindow>,
@@ -122,7 +104,6 @@ pub(super) fn drive_delete_dialog(
     let strings = strings.as_deref().unwrap_or(&empty);
     let confirm = strings.text("DELETE_CONFIRM_STRING", "DELETE");
 
-    // Closed: make sure nothing is spawned, drain stray keys, done.
     if !dialog.open {
         if let Some(root) = dialog.root.take() {
             commands.entity(root).despawn();
@@ -131,8 +112,7 @@ pub(super) fn drive_delete_dialog(
         return;
     }
 
-    // Spawn on the open edge — and respawn when a window resize has changed the glue scale the
-    // tree was baked at (the typed text lives in the resource, so it survives the rebuild).
+    // Respawn on a glue-scale change; the typed text lives in the resource and survives.
     let s = crate::glue::screen_scale(window.single().ok().map(|(w, _)| w));
     if dialog.root.is_some() && dialog.spawned_s != s {
         if let Some(root) = dialog.root.take() {
@@ -151,8 +131,7 @@ pub(super) fn drive_delete_dialog(
         dialog.spawned_s = s;
     }
 
-    // Typing: the shared law (decision 0704) — editing, caret, selection and the clipboard trio.
-    // ENTER/ESCAPE come back unclaimed and are handled by the button/key block above.
+    // Enter and Escape pass through unclaimed to the key handling below.
     let mods = textinput::mods_now(&keys);
     let wl = textinput::wayland_display(window.iter().next().and_then(|(_, h)| h));
     for ev in keyboard.read() {
@@ -165,7 +144,6 @@ pub(super) fn drive_delete_dialog(
             textinput::CharFilter::Any,
         );
     }
-    // The dialog's box is always the focused one while it is up.
     textinput::tick_caret(&mut dialog.typed, true, time.delta_secs());
     paint_glue_field(&dialog.typed, true, parts.iter_mut());
 
@@ -176,10 +154,9 @@ pub(super) fn drive_delete_dialog(
         }
     }
 
-    // The flows.
     let mut do_delete = false;
     let mut do_cancel = false;
-    // Both buttons fire on the RELEASE (1533) — a confirm you can slide off and cancel.
+    // Both buttons fire on release, so a press can slide off.
     for (entity, action) in &buttons {
         if !clicks.hit(entity) {
             continue;
@@ -209,12 +186,9 @@ pub(super) fn drive_delete_dialog(
     }
 }
 
-/// Build the dialog tree (`CharacterDeleteDialog`'s shipped layout): the 512×256 DialogBox
-/// backdrop centered, the two-tone `CONFIRM_CHAR_DELETE` line (gold lead, white identity — the
-/// ref's inline `|cffffffff…|r` span, split across two stacked lines), the instructions, the
-/// alert icon, the ChatInputBorder edit box, Okay + Cancel. The vertical chain is the ref's
-/// anchor chain resolved: Text1 TOP (0,−16) → instructions 20 below → box 5 below (top 102 —
-/// which also centers it on the LEFT (12,+10) alert icon, the authored cross-check).
+/// Build `CharacterDeleteDialog`'s layout: the 512×256 DialogBox centered, the question, the
+/// instructions, the alert icon, the edit box, Okay and Cancel. The vertical positions resolve the
+/// reference's anchor chain: Text1 TOP (0,-16), instructions 20 below, the box 5 below (top 102).
 fn spawn_dialog(
     commands: &mut Commands,
     art: &GlueArt,
@@ -230,9 +204,7 @@ fn spawn_dialog(
         .as_ref()
         .map(|(_, n, l, c)| (n.clone(), *l, *c))
         .unwrap_or_default();
-    // `CONFIRM_CHAR_DELETE` = "Do you want to delete\n|cffffffff%s   Level %d   %s|r?" — the
-    // colour-span split: everything before the |c is the gold lead; the span (+ the trailing "?")
-    // is the white identity line.
+    // `CONFIRM_CHAR_DELETE`'s `|cffffffff` span splits it: gold lead above, white identity below.
     let raw = strings.text(
         "CONFIRM_CHAR_DELETE",
         "Do you want to delete\n|cffffffff%s   Level %d   %s|r?",
@@ -265,7 +237,7 @@ fn spawn_dialog(
                 ..default()
             });
             boxed.with_children(|b| {
-                // Backdrop: bg tiled at 32 inside (11,12,12,11), the 32-edge border over it.
+                // Background tiled at 32 inside insets (11,12,12,11), the 32-edge border over it.
                 if let (Some(bg), Some(border)) = (&art.dialog_bg, &art.dialog_border) {
                     b.spawn((
                         tiled_bg_node(bg.clone(), 32.0, s, Color::WHITE),
@@ -285,7 +257,7 @@ fn spawn_dialog(
                         overlay(),
                     ));
                 }
-                // The alert icon (64² at LEFT (12,10) — center 118 from the top at height 256).
+                // The 64² alert icon at LEFT (12,10): its center is 118 from the top.
                 if let Some(alert) = &art.dialog_alert {
                     b.spawn((
                         ImageNode::new(alert.clone()),
@@ -299,7 +271,7 @@ fn spawn_dialog(
                         },
                     ));
                 }
-                // The two-tone question (GlueFontNormalLarge 18): gold lead, white identity.
+                // GlueFontNormalLarge, 18.
                 for (top, text, color) in [
                     (16.0, lead.as_str(), GOLD),
                     (40.0, identity.as_str(), Color::WHITE),
@@ -325,7 +297,6 @@ fn spawn_dialog(
                         s,
                     );
                 }
-                // The instructions (`CONFIRM_CHAR_DELETE_INSTRUCTIONS`, small).
                 outlined_text(
                     b,
                     Node {
@@ -349,10 +320,8 @@ fn spawn_dialog(
                     &font,
                     s,
                 );
-                // The edit box (`CharacterDeleteEditBox`, 130×32 centered): the two
-                // `UI-ChatInputBorder-Left/Right` 75×32 pieces overhanging by 10 each side
-                // (their authored sub-rects), the typed line in `GlueFontHighlight` (FRIZQT 15
-                // white, outlined) at the box's left edge (no TextInsets), the caret bar after it.
+                // `CharacterDeleteEditBox`, 130×32: the `UI-ChatInputBorder-Left/Right` 75×32
+                // pieces overhang by 10 each side; the text has no TextInsets.
                 b.spawn((Node {
                     position_type: PositionType::Absolute,
                     top: px(102.0),
@@ -416,11 +385,8 @@ fn spawn_dialog(
                                 ..default()
                             },))
                                 .with_children(|f| {
-                                    // The same five-item row every other field uses
-                                    // (`GlueFieldPart`): segments either side of the selection,
-                                    // with a caret slot at each selection edge. Each segment is
-                                    // its own `outlined_text`, and the outline copies follow
-                                    // automatically (`glue::sync_outline_text`).
+                                    // The five-part field row: segments either side of the
+                                    // selection, a caret slot at each edge.
                                     let segment = |f: &mut ChildSpawnerCommands, part| {
                                         outlined_text(
                                             f,
@@ -450,8 +416,8 @@ fn spawn_dialog(
                                 });
                         });
                     });
-                // Okay (right edge at center −6) + Cancel (left edge at center +7), 200×40,
-                // bottom 16 — the GlueDialogButtonTemplate pair.
+                // The `GlueDialogButtonTemplate` pair, 200×40 at bottom 16: Okay's right edge at
+                // center -6, Cancel's left edge at center +7.
                 b.spawn((Node {
                     position_type: PositionType::Absolute,
                     bottom: px(16.0),
diff --git a/crates/benilla-app/src/char_select/input.rs b/crates/benilla-app/src/char_select/input.rs
index 3e92c724..64170b58 100644
--- a/crates/benilla-app/src/char_select/input.rs
+++ b/crates/benilla-app/src/char_select/input.rs
@@ -1,8 +1,7 @@
-//! The select screen's input — clicks (single selects, double enters — the ref's
-//! `CharacterSelectButton_OnClick`/`OnDoubleClick`), the bottom buttons, the keyboard (Enter =
-//! enter world, Escape = exit, arrows cycle with wrap), and the model rotation (drag anywhere at
-//! the pinned `CHARACTER_ROTATION_CONSTANT` 0.6°/px; hold the rotate pair at ±2°/frame). Sounds
-//! are the ref's exact set — a bare selection click is silent.
+//! The select screen's input: row clicks (single selects, double enters, as the reference's
+//! `CharacterSelectButton_OnClick`/`OnDoubleClick`), the bottom buttons, the keyboard, and model
+//! rotation (drag at `CHARACTER_ROTATION_CONSTANT` 0.6°/px, or hold a rotate button at ±2°/frame).
+//! A bare selection click is silent, as in the reference.
 
 use bevy::input::mouse::AccumulatedMouseMotion;
 use bevy::prelude::*;
@@ -17,13 +16,11 @@ use super::{class_name, send_pick, ClientState, Roster};
 
 use crate::glue::{drag_yaw, ROTATE_RATE};
 
-/// The double-click window (the ref rides the OS notion; this is the conventional interval).
+/// The double-click window: the conventional interval, where the reference takes the OS's.
 const DOUBLE_CLICK_SECS: f32 = 0.4;
 
-/// Button presses + the keyboard: selection, enter world, delete (opens the dialog), create,
-/// back/escape (return to the login screen — decision 0539, retiring 0465 §6's exit-the-client
-/// collapse), arrow-key cycling. Inert while the delete dialog is up (it owns the keyboard and
-/// sits over the buttons).
+/// Button presses and the keyboard: Enter enters the world, Escape and Back return to the login
+/// screen, the arrows cycle the selection with wrap.
 #[allow(clippy::type_complexity)]
 pub(super) fn select_input(
     buttons: Query<(Entity, &SelectAction)>,
@@ -42,44 +39,36 @@ pub(super) fn select_input(
     time: Res<Time>,
     mut last_click: Local<Option<(usize, f32)>>,
 ) {
-    // A modal owns the input while it is up — the delete confirm, the AddOns list, the realm
-    // list (which stands over this screen rather than replacing it), or the shared glue dialog
-    // (a refused character login is said in that one, and its Okay must not double as this
-    // screen's Enter World / Escape).
+    // A modal owns the input while it is up: the delete confirm, the AddOns list, the realm list
+    // over this screen, or the glue dialog (whose Okay must not double as Enter World or Escape).
     if dialog.open || panel.open || realms.shown || glue_dialog.is_open() {
         return;
     }
     let now = time.elapsed_secs();
     let mut enter_world = false;
     let mut back_to_login = false;
-    // Buttons fire on the RELEASE, over the button that took the press — the reference's stock
-    // `<Button>` click mask is `LeftButtonUp` alone (1533, `crate::glue::glue_clicks`).
+    // Buttons fire on release over the pressed button: the stock `<Button>` click mask is
+    // `LeftButtonUp` alone (`crate::glue::glue_clicks`).
     for (entity, action) in &buttons {
         if !clicks.hit(entity) {
             continue;
         }
         match *action {
             SelectAction::Row(i) if i < roster.chars.len() => {
-                // Single click selects (silently, like the ref); a second click on the same row
-                // within the window is the double-click → enter world.
                 let double =
                     last_click.is_some_and(|(row, at)| row == i && now - at < DOUBLE_CLICK_SECS);
                 *last_click = Some((i, now));
-                // Selecting is gated on the row actually CHANGING — the ref's own
-                // `CharacterSelectButton_OnClick` is that gate and nothing else, so the row you
-                // are already on is not re-selected and keeps the facing you dragged into it
-                // (`Roster::click_row`, decision 2194).
+                // `CharacterSelectButton_OnClick` selects only when the row changes, so the
+                // current row keeps the facing dragged into it.
                 roster.click_row(i);
-                // `OnDoubleClick` runs the same gated select and then enters the world
-                // unconditionally — it does not re-test what was selected before.
+                // `OnDoubleClick` runs the same select, then enters the world unconditionally.
                 if double {
                     enter_world = true;
                 }
             }
             SelectAction::EnterWorld => enter_world = true,
             SelectAction::Delete => {
-                // The ref plays the click and opens the typed-confirm dialog for the selection
-                // (a no-selection click just plays the sound — the ref's `selectedIndex > 0` gate).
+                // With no selection the click only plays the sound (`selectedIndex > 0` gate).
                 sounds.write(GlueSound("gsCharacterSelectionDelCharacter"));
                 if let Some(c) = roster.selected_char() {
                     dialog.open_for(c.guid, c.name.clone(), c.level, class_name(c.class));
@@ -90,13 +79,12 @@ pub(super) fn select_input(
                 next.set(ClientState::CharCreate);
             }
             SelectAction::Addons => {
-                // The reference plays `gsCharacterSelectionOpen`-family click here; ours reuses
-                // the create-screen open sound rather than inventing a name the client lacks.
+                // The stock `OnClick` plays no sound (`CharacterSelect.xml:231-233`); this plays
+                // the create-screen one.
                 sounds.write(GlueSound("gsCharacterSelectionCreateNew"));
-                // The whole roster rides along so the panel's "Configure Addons For:" dropdown
-                // can fan out over every character (decision 1293). The realm resolves exactly
-                // as `ui_macro::identity`'s does — same fallback, so the enable files the panel
-                // writes stay keyed the way the world-entry walk reads them (0997, 1191 §7).
+                // The whole roster feeds the "Configure Addons For:" dropdown. The realm must
+                // resolve as `ui_macro::identity` does, or the enable files are keyed apart from
+                // what world entry reads.
                 let realm = roster
                     .realm
                     .as_ref()
@@ -106,11 +94,9 @@ pub(super) fn select_input(
                 panel.open_for(realm, chars);
             }
             SelectAction::Back => back_to_login = true,
-            // The reference's `CHANGE_REALM`: raise the realm list **over** this screen. Nothing
-            // is torn down and nothing is disconnected — the character park serves the list in
-            // place and only leaves when a realm is picked, so Cancel puts the player back here
-            // with the session they never left. The pending pick still has to go, or the fresh
-            // roster on the OTHER realm would be auto-answered with a guid from this one.
+            // `CHANGE_REALM`: the realm list rises over this screen with the session kept, so
+            // Cancel returns here. The pending pick is cleared, or the other realm's roster would
+            // be answered with a guid from this one.
             SelectAction::ChangeRealm => {
                 sounds.write(GlueSound("gsLoginChangeRealmOK"));
                 roster.pending_pick = None;
@@ -120,7 +106,6 @@ pub(super) fn select_input(
         }
     }
 
-    // Keyboard: Enter = enter world; Escape = back to login; Up/Left + Down/Right cycle with wrap.
     if keys.just_pressed(KeyCode::Enter) || keys.just_pressed(KeyCode::NumpadEnter) {
         enter_world = true;
     }
@@ -128,9 +113,7 @@ pub(super) fn select_input(
         back_to_login = true;
     }
     if back_to_login {
-        // The ref's Back leaves select for the login screen (decision 0539): drop the parked
-        // session (the IO thread re-parks pre-logon) and forget both intents — a deliberate Back
-        // must not auto-relogin.
+        // Back drops the parked session and both intents, so it does not auto-relogin.
         sounds.write(GlueSound("gsCharacterSelectionExit"));
         roster.pending_pick = None;
         intent.clear();
@@ -162,9 +145,8 @@ pub(super) fn select_input(
     }
 }
 
-/// Rotate the selected character: drag anywhere on the scene pane (the ref's full-frame mouse
-/// rotation at the pinned 0.6°/px — dragging right increases the facing), or hold a rotate button
-/// (±2°/frame; left decrements).
+/// Rotate the selected character: drag on the scene (0.6°/px, right increases the facing) or
+/// hold a rotate button (±2°/frame, left decrements).
 pub(super) fn rotate_model(
     panes: Query<(&Interaction, &SelectAction)>,
     motion: Res<AccumulatedMouseMotion>,
diff --git a/crates/benilla-app/src/char_select/mod.rs b/crates/benilla-app/src/char_select/mod.rs
index 52540a34..52934906 100644
--- a/crates/benilla-app/src/char_select/mod.rs
+++ b/crates/benilla-app/src/char_select/mod.rs
@@ -1,27 +1,7 @@
-//! Character select — the faithful glue screen (decision 0465, superseding 0193 §4's v1 overlay).
-//!
-//! Owns [`ClientState`], the app's lifecycle state machine: `CharSelect` is the pre-world "glue"
-//! layer (the real client's GlueXML universe — login/realm/select screens), `InWorld` is the game.
-//! The IO thread parks after the world handshake and emits the account roster
-//! ([`CharListMessage`]); the **pick policy** here decides what answers it — the pending pick
-//! (seamless reconnect, decision 0065), the `WOW_CHAR` env fast path, or the director's choice on
-//! the screen, which opens on whoever they last entered the world as (`lastCharacterIndex`,
-//! decision 1622). The pick travels the [`CharPick`] channel; `Connected` flips us `InWorld`;
-//! a `/logout` round-trip ([`LoggedOutMessage`]) flips back to select with the pending pick
-//! cleared, and a **lost** session flips all the way back to the login screen (decision 1262 —
-//! the reference's `DISCONNECTED_FROM_SERVER`).
-//!
-//! The screen is the reference's own arrangement (`CharacterSelect.xml/.lua`, extracted off the
-//! patch chain — decision 0465): the fullscreen `UI_<Race>` glue scene with the **selected
-//! character standing in it, geared from its enum record** (the glue booth), the right-column
-//! character list (realm banner, ten row buttons, Create New Character), Enter World / Back /
-//! Delete Character along the bottom, the rotate pair, drag-to-rotate, arrow-key cycling,
-//! double-click-to-enter, and the typed-`DELETE` confirm dialog. Art/strings/sounds come off the
-//! player's own client data ([`crate::glue`]) — never embedded.
-//!
-//! Module split: this file (state machine + roster policy + shared display constants),
-//! [`screen`] (the authored layout), [`refresh`] (list/banner/booth-feed refresh), [`input`]
-//! (clicks, keys, rotation, the flows), [`dialog`] (the delete confirm).
+//! Character select: the app's lifecycle state ([`ClientState`]), the roster pick policy and the
+//! `CharacterSelect.xml` glue screen. The parked IO thread emits the roster ([`CharListMessage`]),
+//! answered by the pending pick (reconnect), `WOW_CHAR`, or a choice on the screen, which opens on
+//! the character last entered as (`lastCharacterIndex`).
 
 mod addons;
 mod dialog;
@@ -39,62 +19,38 @@ use crate::net::{
     EnteredWorldMessage, LoggedOutMessage,
 };
 
-/// The app's lifecycle: which screen owns the session (decision 0193).
+/// The app's lifecycle: which screen owns the session.
 #[derive(States, Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
 pub(crate) enum ClientState {
-    /// Parked pre-logon at the login screen (decision 0539): the IO thread waits for credentials;
-    /// [`crate::login`]'s policy decides what answers it (the env fast path, the reconnect
-    /// resubmit, or the director's typed submit).
-    ///
-    /// **The realm list is not one of these.** 0193 planned a `RealmList` variant and 2056 built
-    /// it; the reference has no such screen (`GlueParent.lua`'s `GlueScreenInfo` lists every glue
-    /// screen and the realm list is not among them — it is a `frameStrata="DIALOG"` frame shown
-    /// over whichever screen is up). It is [`crate::realm_select::Realms::shown`] now, and the
-    /// variant is gone rather than left unconstructed.
+    /// Parked pre-logon at the login screen, the IO thread waiting for credentials. The realm list
+    /// is no state: `GlueParent.lua`'s `GlueScreenInfo` omits it, a `DIALOG` frame over any screen
+    /// ([`crate::realm_select::Realms::shown`]).
     #[default]
     Login,
-    /// Parked at character select: the select screen is up, the IO thread waits for a pick, and
-    /// the in-world input surfaces (player controller, FrameXML keyboard) are gated off.
+    /// Parked at character select, the IO thread waiting for a pick.
     CharSelect,
-    /// The character-creation screen (decision 0423): still parked at select (the IO thread
-    /// services create/delete in place), a sibling glue screen. Entered from the select screen's
-    /// "Create New Character" button; Back returns to `CharSelect`. In-world input stays gated off
-    /// (any `in_state(InWorld)` system is off here, mechanically).
+    /// The character-creation screen, still parked at select (the IO thread serves create and
+    /// delete in place).
     CharCreate,
     /// A character is in (or entering) the world.
     InWorld,
 }
 
-/// **The one "only while in the world" gate** (decision 2265 §C3). A system that has no business
-/// at a glue screen — an input reader, a world-packet feed, a per-character file watcher — joins
-/// this set instead of carrying its own `run_if(in_state(ClientState::InWorld))`: twenty-odd
-/// copies of that condition said one thing in twenty-odd places, and the condition a set carries
-/// ANDs with a member's own, so a member keeps whatever else it needs (the controller's
-/// capture-mode gate, say) and the conversion is exact.
-///
-/// Configured once, in [`CharSelectPlugin`] — the state's home — for `Update`, the only schedule
-/// a member lives in. A member in another schedule means configuring the set *there* as well
-/// (a set's conditions are per schedule; an unconfigured set gates nothing), never a fresh
-/// `run_if` at the site.
+/// The one "only while in the world" gate; a member's own `run_if` ANDs with it. Configured for
+/// `Update` only: a set's conditions are per schedule, so a member elsewhere needs the set
+/// configured there too.
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub(crate) struct InWorldGated;
 
 /// The character-select subsystem: the state machine + the select screen.
 pub(crate) struct CharSelectPlugin {
-    /// The screen this session opens on.
-    ///
-    /// A connected boot starts at [`ClientState::Login`] (decision 0539) and the roster's arrival
-    /// flips it. A world capture starts straight at [`ClientState::InWorld`] — no net thread, no
-    /// picker — so the deterministic scene harness is untouched by the glue layer. A **glue**
-    /// capture starts on the glue screen it photographs, which is the reason this is a state and
-    /// not the bool it used to be: there turned out to be three answers, not two.
+    /// The screen this session opens on: `Login` when connected, `InWorld` for a world capture,
+    /// the photographed glue screen for a glue capture.
     pub(crate) start: ClientState,
 }
 
-/// Mirror the session's screen onto the engine's one-bit "is there a world" fact.
-///
-/// One writer, not a line at each of the dozen sites that set [`ClientState`] — a mirror a future
-/// transition can forget is worse than the coupling it replaced.
+/// Mirror the session's screen onto the engine's one-bit "is there a world" fact, in one place so
+/// no transition can forget it.
 fn publish_world_live(
     state: Res<State<ClientState>>,
     mut live: ResMut<benilla_world::schedule::WorldLive>,
@@ -108,13 +64,9 @@ fn publish_world_live(
 impl Plugin for CharSelectPlugin {
     fn build(&self, app: &mut App) {
         app.insert_state(self.start)
-            // The in-world gate, configured beside the state it reads (see [`InWorldGated`]).
             .configure_sets(Update, InWorldGated.run_if(in_state(ClientState::InWorld)))
             .init_resource::<Roster>()
-            // **The engine's world-existence bit** (1160's wire (b)): the session owner is this
-            // module, so this module tells the world whether there is one. Ordered ahead of every
-            // world stage so the fact and its falling edge are this frame's, not last frame's — which
-            // is the whole reason `WorldLive` is a resource and not a mirrored state.
+            // Ahead of every world stage, so `WorldLive` and its falling edge are this frame's.
             .add_systems(
                 Update,
                 publish_world_live.before(benilla_world::schedule::WorldStage::Net),
@@ -133,18 +85,17 @@ impl Plugin for CharSelectPlugin {
             .add_systems(
                 Update,
                 (
-                    // The policy + transitions run in BOTH states: the roster auto-answer (reconnect
-                    // relogin) happens while `InWorld`, and the logout edge arrives there too.
-                    // `back_on_disconnect` LAST: a session that died during entry queues both
-                    // edges into one frame, and the dead one has to win (decision 1262).
+                    // Runs in every state: the reconnect auto-answer and the logout edge arrive
+                    // `InWorld`. `back_on_disconnect` runs after the entry: a session that died
+                    // during entry queues both edges into one frame, and the dead one must win.
                     (
                         apply_roster_policy,
                         enter_on_connected,
                         back_on_logout,
                         back_on_login_refused,
                         back_on_disconnect,
-                        // LAST, and outside both `run_if`s: it mirrors the pick this frame ended
-                        // with, and world entry is reached from the create screen too (1622).
+                        // Last and ungated: it mirrors the pick the frame ended with, and world
+                        // entry is reached from the create screen too.
                         persist_last_character,
                     )
                         .chain(),
@@ -154,17 +105,10 @@ impl Plugin for CharSelectPlugin {
                         input::rotate_model,
                         debug_select_dialog,
                         dialog::drive_delete_dialog,
-                        // Ahead of the dialog driver, so a refused delete is on screen the frame
-                        // its answer lands rather than the next.
+                        // Ahead of the dialog driver, so a refused delete shows the frame it lands.
                         delete_result,
-                        // The reference's one `GlueDialog` (`crate::glue::dialog`), which on this
-                        // screen carries the refused character login and the refused delete. Both
-                        // glue screens run the same system over the same resource; what a press
-                        // *means* is answered per-screen, and an `Error` — the only kind reachable
-                        // here — needs no answer at all.
+                        // The one `GlueDialog`: here, the refused login and the refused delete.
                         crate::glue::dialog::drive_glue_dialog,
-                        // Before the list refresh, and before `select_input` reads a click that
-                        // landed on the panel rather than the screen (decision 1196).
                         debug_select_addons,
                         debug_select_walk,
                         addons::drive_addons_panel,
@@ -175,18 +119,15 @@ impl Plugin for CharSelectPlugin {
                     )
                         .chain()
                         .before(crate::glue::GlueVisuals)
-                        // After the UI tick: one member holds the VM (the addons panel reads
-                        // the manifest through it), and every VM holder in `Update` declares
-                        // its side of the tick (decision 2304). A glue screen has no push the
-                        // tick must see, so the whole chain takes the drain side.
+                        // After the UI tick: the addons panel holds the VM, and a glue screen
+                        // has no push the tick must see, so the chain takes the drain side.
                         .after(crate::ui_script::UiInput)
                         .run_if(in_state(ClientState::CharSelect)),
                 )
                     .chain()
                     .after(benilla_world::schedule::WorldStage::Net),
             )
-            // AFTER the cover's own stage, so the raise it reads is this frame's — see the
-            // system's doc for why the glue must yield the glass the moment the cover goes up.
+            // After the cover's stage, so the raise it reads is this frame's.
             .add_systems(
                 Update,
                 screen::hide_under_world_cover
@@ -196,56 +137,35 @@ impl Plugin for CharSelectPlugin {
     }
 }
 
-// ── State: the roster + pick policy ──────────────────────────────────────────────────────────────
+// ── The roster and pick policy ──────────────────────────────────────────────────────────────────
 
-/// The account roster + the pick policy's memory. `pending_pick` is the character we asked to log
-/// in as — kept while in-world so a reconnect's fresh roster is auto-answered with it (decision
-/// 0065's seamless relogin); cleared by a deliberate logout so the roster is *shown* instead.
+/// The account roster and the pick policy's memory.
 #[derive(Resource, Default)]
 pub(crate) struct Roster {
     pub(super) chars: Vec<Character>,
-    /// The selected row (the ref's `CharacterSelect.selectedIndex`, 0-based; `None` = empty list).
-    /// A fresh roster clamps it into range and defaults to the first row (the ref's law).
-    /// **Write it through [`Roster::select`]**, never directly — see [`Roster::select_seq`].
+    /// The selected row, `CharacterSelect.selectedIndex` 0-based. Written only through
+    /// [`Roster::select`].
     selected: Option<usize>,
-    /// Bumped by every [`Roster::select`], whether or not the row changed.
-    ///
-    /// The ref's `SelectCharacter` zeroes the select facing **unconditionally**: `0x472950`'s
-    /// `mov ds:0xb4217c, 0` sits one instruction *above* the already-built discriminator, so it
-    /// dominates both legs, and the merged tail re-applies it geometrically (1533). A counter
-    /// rather than change-detection on `selected`, because the engine re-squares on a
-    /// *re*-selection of the same index too — which is exactly what a roster refresh does, calling
-    /// it with the index it already holds.
-    ///
-    /// **The click is the one caller that does not reach it**, and the gate is in the stock Lua
-    /// rather than in the engine — see [`Roster::click_row`] and decision 2194. Of the ten Lua call
-    /// sites only the two click handlers are gated, and of `0x472740`'s four C callers two are the
-    /// roster teardown passing `-1` (so `0x472950` exits above the reset) — every ungated path
-    /// re-squares.
+    /// Bumped by every [`Roster::select`], changed row or not: the reference's `SelectCharacter`
+    /// zeroes the facing unconditionally (`0x472950` writes `0xb4217c` above its already-built
+    /// check), so a roster refresh re-selecting the same index re-squares too. Only a row click is
+    /// gated, in the stock Lua ([`Roster::click_row`]).
     pub(super) select_seq: u64,
-    /// The guid we answered the IO thread with; `Some` = a login is requested/live.
+    /// The guid picked; kept in-world so a reconnect's roster is answered with it, cleared by a
+    /// logout so the roster is shown.
     pub(super) pending_pick: Option<u64>,
-    /// `WOW_CHAR`, when explicitly set: auto-pick this name on the FIRST roster (the dev fast
-    /// path past the screen). `take()`n once — a later `/logout` shows the screen normally.
+    /// `WOW_CHAR`: auto-pick this name on the first roster only.
     env_char: Option<String>,
-    /// A just-created character's name (decision 0423): its row gets selected (the ref's
-    /// `SELECT_LAST_CHARACTER`, keyed by name so it survives the create/enum race). Armed by
-    /// [`Roster::note_created`], which consumes it against the roster **already in hand** —
-    /// [`apply_roster_policy`] only has to answer the other arrival order.
+    /// A just-created character's name, whose row gets selected (the reference's
+    /// `SELECT_LAST_CHARACTER`, keyed by name to survive the create/enum race).
     just_created: Option<String>,
-    /// The auth realm-list entry this session connected to (the screen's realm banner, 0465);
-    /// refreshed with each roster.
+    /// The realm-list entry this session connected to, refreshed with each roster.
     pub(super) realm: Option<benilla_protocol::RealmInfo>,
-    /// `WOW_CHAR` read latch (env read once at first policy run).
     env_read: bool,
 }
 
 impl Roster {
-    /// A roster with a pick already in flight — the state world entry runs in.
-    ///
-    /// `#[cfg(test)]` and `pub(crate)` because the fields are `pub(super)`: a test outside this
-    /// module cannot build one, and `ui_script`'s does exactly that to drive
-    /// `seat_from_roster` over a real row rather than a copy of its logic.
+    /// A roster with a pick in flight, for tests outside this module.
     #[cfg(test)]
     pub(crate) fn with_pending_pick(chars: Vec<Character>, guid: u64) -> Self {
         Self {
@@ -255,26 +175,16 @@ impl Roster {
         }
     }
 
-    /// Note a character the create screen just made, and select its row.
-    ///
-    /// **The consume happens here, not on the next roster message** (B119): the IO thread
-    /// re-enumerates and emits the fresh roster *before* the create result (`net::io`), so by the
-    /// time the result reaches [`crate::char_create`] the new row is normally already in
-    /// [`Self::chars`] and [`apply_roster_policy`] has already run for that list. Arming a flag for
-    /// "the next roster update" then waited for a message that never arrives again — the select
-    /// screen came back on the previously-selected row (reproduced: create a tauren on a
-    /// human-first account and the human is still standing there).
-    ///
-    /// The arm survives when the name isn't in hand yet, so the reverse arrival order (result
-    /// first) is still answered by [`apply_roster_policy`].
+    /// Note a character the create screen just made, and select its row now: `net::io` emits the
+    /// fresh roster before the create result, so no later roster comes. If the row is not in hand
+    /// yet, the arm stays for [`apply_roster_policy`].
     pub(crate) fn note_created(&mut self, name: String) {
         self.just_created = Some(name);
         self.select_created_by_name();
     }
 
-    /// Select the armed just-created row **by name**, disarming only on a hit. Case-insensitive:
-    /// vmangos normalizes a created name (`normalizePlayerName` — first letter upper, rest lower),
-    /// so a typed `ZZBULL` enumerates back as `Zzbull` and an exact compare would miss.
+    /// Select the armed just-created row by name, disarming only on a hit. Case-insensitive:
+    /// vmangos's `normalizePlayerName` turns a typed `ZZBULL` into `Zzbull`.
     fn select_created_by_name(&mut self) {
         let Some(name) = self.just_created.as_deref() else {
             return;
@@ -289,130 +199,83 @@ impl Roster {
         }
     }
 
-    /// Select a row — the ref's `SelectCharacter`. Every selection goes through here so the facing
-    /// reset it owes cannot be forgotten at one of the seven call sites (see [`Self::select_seq`]).
+    /// Select a row, the reference's `SelectCharacter`; every selection goes through here so the
+    /// facing reset is never skipped.
     pub(super) fn select(&mut self, row: Option<usize>) {
         self.selected = row;
         self.select_seq = self.select_seq.wrapping_add(1);
     }
 
-    /// A click on a character row — the ref's `CharacterSelectButton_OnClick`, whose entire body is
-    /// the gate `if ( id ~= CharacterSelect.selectedIndex ) then CharacterSelect_SelectCharacter(id)`
-    /// (shipped `CharacterSelect.lua` l.305-310; `OnDoubleClick`, l.312-318, repeats it verbatim
-    /// before entering the world, and the ten `CharSelectCharacterButtonTemplate` buttons carry
-    /// `id="1".."10"` 1:1 with the character index, so `id` *is* the row).
-    ///
-    /// So the row you are already on is never re-selected from a click, and the facing zero
-    /// [`Self::select`] owes never fires for it: the angle you dragged the character to survives
-    /// clicking it again. Decision 2194, correcting 1533 — the engine function is unconditional as
-    /// recorded (`0x472740`), but the click never reaches it: the binding has exactly one live call
-    /// site, and the two handlers that lead to it both gate.
+    /// A click on a row: `CharacterSelectButton_OnClick` selects only when `id` differs from
+    /// `selectedIndex` (`CharacterSelect.lua:305-310`, and `OnDoubleClick` at 312-318), so clicking
+    /// the current row keeps its dragged facing.
     pub(super) fn click_row(&mut self, row: usize) {
         if self.selected != Some(row) {
             self.select(Some(row));
         }
     }
 
-    /// The selected row, if any.
     pub(super) fn selected(&self) -> Option<usize> {
         self.selected
     }
 
-    /// The selected character, if any.
     pub(super) fn selected_char(&self) -> Option<&Character> {
         self.selected.and_then(|i| self.chars.get(i))
     }
 
-    /// The pending pick's map — the loading screen resolves the *destination's* art from the
-    /// roster at the entry edge, before the server's `SMSG_LOGIN_VERIFY_WORLD` snap lands
-    /// (decision 0737).
+    /// The pending pick's map, for the loading screen's art before `SMSG_LOGIN_VERIFY_WORLD`.
     pub(crate) fn pending_map(&self) -> Option<u32> {
         self.pending_row().map(|c| c.map)
     }
 
-    /// The pending pick's level — the loading screen's tip-of-the-day guard (decision 2077). The
-    /// reference keeps a synthesised flag at `[selChar+0x10a]` that `0x5b42a0` sets iff this byte
-    /// arrived as `0` in `SMSG_CHAR_ENUM`, and a set flag suppresses the tip. vmangos always sends
-    /// a real level, so the arm is unreachable against our server; it is honoured because it costs
-    /// one comparison and a different server is free to send a zero.
+    /// The pending pick's level: the reference suppresses the loading tip when it arrived as 0 in
+    /// `SMSG_CHAR_ENUM` (`0x5b42a0` sets `[selChar+0x10a]`); vmangos always sends a real level.
     pub(crate) fn pending_level(&self) -> Option<u8> {
         self.pending_row().map(|c| c.level)
     }
 
-    /// The picked character's `(map, wow xyz)` — **where the world we are about to load actually
-    /// is**, known from the roster row a whole server round-trip before `SMSG_LOGIN_VERIFY_WORLD`
-    /// says so. The streamers aim at this during world entry (decision 0777); without it the only
-    /// answer available before the snap is the hardcoded Northshire anchor
-    /// ([`crate::SPAWN_XY`]), which is a guess that is wrong for every character who isn't a fresh
-    /// human — and a wrong guess here does not merely idle, it spends the entry's IO budget
-    /// decoding tiles that are dropped a moment later.
+    /// The picked character's `(map, wow xyz)`, a round trip before `SMSG_LOGIN_VERIFY_WORLD`; the
+    /// streamers aim at it during world entry.
     pub(crate) fn pending_entry(&self) -> Option<(u32, [f32; 3])> {
         self.pending_row()
             .map(|c| (c.map, [c.position.x, c.position.y, c.position.z]))
     }
 
-    /// The roster row for the pick in flight.
-    ///
-    /// `pub(crate)` because this row is the ONLY description of the character that exists during
-    /// world entry: `Connected` flips us `InWorld` a whole server round-trip before the self
-    /// descriptor streams in, and the in-game UI — plus every addon's file scope — materializes
-    /// inside that window. `ui_script::load_ingame_ui_on_world_entry` seats
-    /// `UnitName("player")` from here for exactly that reason.
+    /// The roster row for the pick in flight: the only description of the character until the
+    /// self descriptor streams in, so the in-game UI seats `UnitName("player")` from it.
     pub(crate) fn pending_row(&self) -> Option<&Character> {
         self.pending_pick
             .and_then(|g| self.chars.iter().find(|c| c.guid == g))
     }
 
-    /// The **roster position** of the pick in flight — what the reference persists as
-    /// `lastCharacterIndex` at Enter World (decision 1622). By guid rather than by the live
-    /// selection, so the row it names is the one actually being entered even if the selection has
-    /// since moved.
+    /// The roster position of the pick in flight, by guid rather than the live selection: what
+    /// the reference persists as `lastCharacterIndex` at Enter World.
     pub(super) fn pending_index(&self) -> Option<usize> {
         let guid = self.pending_pick?;
         self.chars.iter().position(|c| c.guid == guid)
     }
 }
 
-// ── The remembered character (`lastCharacterIndex`, decision 1622) ───────────────────────────────
+// ── The remembered character (`lastCharacterIndex`) ───────────────────────────────
 
-/// The CVar the select screen remembers you by — a **real 1.12 CVar**
-/// (registered at `0x402d93`, name `0x82e8f8`, help "Last character selected", default `"0"`,
-/// pointer cached at `[0x882674]`), and written engine-side: no shipped GlueXML names it and the
-/// binary never looks it up by name.
+/// The 1.12 CVar the select screen remembers by: registered at `0x402d93` (name `0x82e8f8`,
+/// default `"0"`, pointer at `[0x882674]`), written engine-side, named by no GlueXML.
 pub(crate) const CVAR_LAST_CHARACTER: &str = "lastCharacterIndex";
 
-/// The stored index is **0-based**, and `"0"` is the FIRST character — not "nothing remembered".
-///
-/// It is the engine's own selection cell `[0x83856c]` printed with `"%d"`: `SelectCharacter`
-/// (`0x473470`) takes the glue Lua's 1-based row and `dec`s it, and the event back out
-/// (`0x472740`) re-adds the one. So the number on disk is one *less* than the row `CharacterSelect
-/// .selectedIndex` counts in, and it lines up with [`Roster::selected`] exactly.
-///
-/// The registered default being `"0"` is load-bearing rather than incidental: `CVar::SaveConfig`
-/// (`0x63d980`) skips any value equal to its default, so a player who last entered on their first
-/// character has **no such line in `Config.wtf` at all** — and reads back as row 0 anyway. Ours
-/// composes the same way (`cvars::compose_file`), so `config.toml` gets the same shape for the
-/// same reason.
+/// The stored index is 0-based, `"0"` the first character: the engine's selection cell
+/// `[0x83856c]` printed with `"%d"` (`0x473470` decrements the Lua's 1-based row).
+/// `CVar::SaveConfig` (`0x63d980`) skips a value equal to the default, so row 0 writes no line.
 fn last_character_value(row: usize) -> String {
     row.to_string()
 }
 
-/// The stored value → a row. `None` only for a value that is not a number at all (a hand edit);
-/// out-of-range is the *caller's* business, because the reference's answer to it is not a clamp.
+/// The stored value as a row; out of range is the caller's, since the reference does not clamp.
 fn last_character_row(value: &str) -> Option<usize> {
     value.trim().parse::<usize>().ok()
 }
 
-/// The remembered row for a roster of `len` characters — the reference's whole selection rule,
-/// `CGlueMgr::SetSelectedCharacter` `0x472740`:
-///
-/// ```text
-/// selected = (stored < 0 || stored >= count) ? 0 : stored
-/// ```
-///
-/// Out of range falls back to the **first** row, never to the nearest one: a character deleted
-/// since you last played, or a realm with fewer characters, puts you at the top of the list rather
-/// than beside where the old row used to be.
+/// The remembered row for a roster of `len`: out of range falls back to the first row, not the
+/// nearest (`CGlueMgr::SetSelectedCharacter`, `0x472740`).
 fn remembered_row(cvars: &crate::cvars::Cvars, len: usize) -> usize {
     cvars
         .get(CVAR_LAST_CHARACTER)
@@ -421,30 +284,17 @@ fn remembered_row(cvars: &crate::cvars::Cvars, len: usize) -> usize {
         .unwrap_or(0)
 }
 
-/// Mirror the character we are **entering the world as** into [`CVAR_LAST_CHARACTER`].
-///
-/// **At Enter World, not at every click** — which is the difference between "the last character
-/// you logged in as" and "the last row you happened to touch", and it is the reference's own
-/// seam: `CGlueMgr::EnterWorld` (`0x46b500`) formats `[0x83856c]` into the CVar at `0x46b5fa`,
-/// and clicks and arrow keys reach `0x472740` without ever going near it. [`Roster::pending_pick`]
-/// is exactly that moment for us, so [`Roster::pending_index`] is what this reads.
-///
-/// The write is a host write into the registry ([`crate::cvars::Cvars::set`]), which is what
-/// persists it and what the VM's mirror learns (2303) — the shape the AddOns panel's force-load
-/// box uses from this same screen (1293). **One divergence, stated:** the
-/// reference flushes `Config.wtf` synchronously in the same call (`0x46b6f6`), while ours reaches
-/// disk on the exit edge with every other CVar (1528) — so a crash between entering the world and
-/// quitting loses the memory, where the reference would not. That is the CVar store's shape, not
-/// this key's, and changing it is an autosave design (1528's own "what this does NOT fix").
+/// Mirror the character entering the world into [`CVAR_LAST_CHARACTER`], at Enter World, not on
+/// a click: `CGlueMgr::EnterWorld` (`0x46b500`) writes the CVar at `0x46b5fa`. The reference
+/// flushes `Config.wtf` in the same call (`0x46b6f6`); this reaches disk on exit with every CVar.
 fn persist_last_character(
     roster: Res<Roster>,
     mut cvars: ResMut<crate::cvars::Cvars>,
-    // A plain `Local` is honest here since 2303: the registry outlives every VM, so the row
-    // written once stays written — the per-VM memo this used to need was betting on the seed.
+    // The registry outlives every VM, so a row written once stays written.
     mut mirrored: Local<Option<usize>>,
 ) {
     let Some(row) = roster.pending_index() else {
-        return; // nobody is entering the world — nothing to remember
+        return;
     };
     if *mirrored == Some(row) {
         return;
@@ -453,39 +303,29 @@ fn persist_last_character(
     *mirrored = Some(row);
 }
 
-/// Ask the parked IO thread to log in as `guid` (the pick channel) and remember it as pending.
-/// `pub(crate)` for the probe rig (decision 0651), which picks a character it may have had to
-/// *create* first — going through here is what keeps `pending_pick` truthful, so 0065's reconnect
-/// re-answers with the rigged body rather than showing the roster.
+/// Ask the parked IO thread to log in as `guid` and remember it as pending; the probe rig picks
+/// through here too, so a reconnect re-answers with its character.
 pub(crate) fn send_pick(roster: &mut Roster, pick: &CharPick, guid: u64) {
     roster.pending_pick = Some(guid);
     let _ = pick.0.send(CharRequest::Enter(guid));
 }
 
-/// Drain each [`CharListMessage`] into the roster, then decide what answers it: the pending pick
-/// (reconnect), the `WOW_CHAR` fast path (first roster only), or nothing — the screen waits for
-/// the director. A shown roster clamps the selection into range and defaults it to the first row
-/// (the ref's `UpdateCharacterList`).
+/// Drain each [`CharListMessage`] into the roster, then answer it with the pending pick
+/// (reconnect), the `WOW_CHAR` fast path (first roster only), or nothing, leaving the screen up.
 fn apply_roster_policy(
     mut msgs: MessageReader<CharListMessage>,
     mut roster: ResMut<Roster>,
     pick: Res<CharPick>,
-    // The remembered row (decision 1622) — read off the registry rather than the VM's table
-    // because the registry is the store that outlives every VM (2303), and because reading it
-    // here keeps this system send-able. It is consulted exactly once per process: `selected` is
-    // `None` only before the first roster lands.
+    // The remembered row, read off the registry, the store that outlives every VM.
     cvars: Res<crate::cvars::Cvars>,
-    // Is the character pick already spoken for? Present only when a rig is driving this run
-    // (decision 1174's always-present run fact) — absent in every ordinary run, which is the
-    // player answer and the one this screen was written for.
+    // Present only when a rig drives the run and picks its own character.
     rig: Option<Res<crate::run_mode::RigCharacter>>,
     mut exit: MessageWriter<AppExit>,
 ) {
     if !roster.env_read {
         roster.env_read = true;
-        // `WOW_RIG` with a body outranks `WOW_CHAR`: the rig picks its own derived character, and
-        // it may have to CREATE it first, which this fast path (a one-shot `take()` that gives up
-        // on a name it can't find) structurally cannot wait for.
+        // `WOW_RIG` outranks `WOW_CHAR`: the rig may have to create its character first, which
+        // this one-shot fast path cannot wait for.
         roster.env_char = match rig.as_deref() {
             Some(crate::run_mode::RigCharacter(name)) => {
                 if let Ok(ignored) = std::env::var("WOW_CHAR") {
@@ -493,11 +333,7 @@ fn apply_roster_policy(
                 }
                 None
             }
-            // `WOW_CHAR`, or the login smoke's optional third field (decision 1262): the seat
-            // exists because `WOW_CHAR` *was* also an unattended marker, so using it to reach the
-            // world switched the very branch a session test was trying to exercise. 1769 severed
-            // that — `WOW_CHAR` now only means "skip the click" — and the seat stays as the
-            // smoke's own way in. Same fast path either way.
+            // `WOW_CHAR`, or the login smoke's optional third field.
             None => std::env::var("WOW_CHAR").ok().or_else(|| {
                 std::env::var("WOW_LOGIN_SMOKE")
                     .ok()
@@ -508,15 +344,10 @@ fn apply_roster_policy(
     for msg in msgs.read() {
         roster.chars = msg.characters.clone();
         roster.realm = msg.realm.clone();
-        // A still-armed create (the result hasn't landed yet — the reverse of the order `net::io`
-        // actually sends in) selects its row here: by name first, else the LAST row, which is the
-        // ref's literal `SELECT_LAST_CHARACTER` → `SelectCharacter(numChars)` and lands on the same
-        // character regardless — vmangos enumerates `ORDER BY create_time, guid`, so the new one is
-        // last. Otherwise clamp into range, first row default.
-        // **`SELECT_LAST_CHARACTER` outranks the remembered row** — the reference's own
-        // precedence, and the order is why: the C side restores the CVar and pushes it into Lua
-        // (`0x472563` → `UPDATE_SELECTED_CHARACTER`) *before* firing `CHARACTER_LIST_UPDATE`, and
-        // `UpdateCharacterList`'s deferred `selectLast` flag then overwrites it.
+        // A still-armed create selects by name, else the last row: the reference's
+        // `SELECT_LAST_CHARACTER` is `SelectCharacter(numChars)`, and vmangos enumerates
+        // `ORDER BY create_time, guid`. It outranks the remembered row: the reference pushes the
+        // CVar's row (`0x472563`) before `CHARACTER_LIST_UPDATE`, whose `selectLast` overwrites it.
         let created = roster.just_created.is_some();
         if created {
             roster.select_created_by_name();
@@ -531,23 +362,14 @@ fn apply_roster_policy(
         if roster.chars.is_empty() {
             roster.select(None);
         } else if !created {
-            // The remembered character (decision 1622), re-applied on **every** roster — the
-            // reference reads the CVar in the char-list rebuild itself (`0x4724d0` → `0x472740`),
-            // not once at startup, so the screen always opens on whoever you last entered the
-            // world as. Out of range falls back to the first row; see `remembered_row`.
+            // Re-applied on every roster: the reference reads the CVar in the list rebuild
+            // (`0x4724d0` to `0x472740`), not once at startup.
             let row = remembered_row(&cvars, roster.chars.len());
-            // Greppable, and it names the character rather than only the index: "the first row
-            // happened to be right" and "the memory worked" are the same picture on screen, and
-            // this line is the only thing that tells them apart in a log.
             let who = roster.chars[row].name.clone();
             info!("char select: {CVAR_LAST_CHARACTER} selects row {row} ({who})");
             roster.select(Some(row));
         }
-        // `WOW_CHARSELECT_PICK=<name>` — **select** that row and stay on the screen, the
-        // deliberate opposite of `WOW_CHAR`'s enter-the-world fast path. Without it the screen is
-        // only ever reachable on its default first row, which makes every "what does this
-        // character look like at select?" check hostage to the account's create order (it cost
-        // this session's item-glow verification a run). An unknown name leaves the default.
+        // `WOW_CHARSELECT_PICK=<name>` selects that row and stays on the screen.
         if let Ok(name) = std::env::var("WOW_CHARSELECT_PICK") {
             match roster
                 .chars
@@ -562,8 +384,7 @@ fn apply_roster_policy(
             }
         }
         if let Some(guid) = roster.pending_pick {
-            // We already chose this session (in-world reconnect, or a pick raced a dying socket):
-            // re-answer without showing the screen.
+            // A reconnect, or a pick that raced a dying socket: re-answer without the screen.
             send_pick(&mut roster, &pick, guid);
         } else if let Some(name) = roster.env_char.take() {
             match roster
@@ -578,9 +399,7 @@ fn apply_roster_policy(
                 }
                 None => {
                     warn!("char select: WOW_CHAR={name} not on this account — showing roster");
-                    // A driverless run can never pick a different row itself — parked here it
-                    // burns its whole wall-clock. Same home as the login arm's verdict, so the
-                    // marker a leg runner greps for is written in exactly one place (1371, 1769).
+                    // A driverless run cannot pick another row, so it fails rather than idles.
                     if std::env::var_os("WOW_LOGIN_SMOKE").is_none()
                         && crate::run_mode::fatal_when_driverless(&format!(
                             "WOW_CHAR={name} is not on this account"
@@ -594,7 +413,7 @@ fn apply_roster_policy(
     }
 }
 
-/// `Connected` (bridged as [`EnteredWorldMessage`]) → the world owns the session.
+/// `Connected` ([`EnteredWorldMessage`]): the world owns the session.
 fn enter_on_connected(
     mut msgs: MessageReader<EnteredWorldMessage>,
     mut next: ResMut<NextState<ClientState>>,
@@ -604,16 +423,9 @@ fn enter_on_connected(
     }
 }
 
-/// **The session died** → all the way back to the login screen (decision 1262), which is where the
-/// reference's `GlueParent.lua` puts it: `SetGlueScreen("login")` on `DISCONNECTED_FROM_SERVER`,
-/// with [`crate::login`] raising the "Disconnected from server" dialog over it.
-///
-/// Chained **after** [`enter_on_connected`] on purpose. Both edges can land in the same frame — the
-/// IO thread emits `Connected` before its read loop starts, so a stream that dies during entry
-/// queues `Connected` and `Disconnected` back to back and the app drains both at once. That is the
-/// race the report caught: the entry half won, and the client walked into a world whose session had
-/// already been torn down — a camera with no avatar, `SelfGuid` set, an entry awaiting a snap that
-/// could never arrive. Ordering it last makes the dead session the last word by construction.
+/// The session died: back to the login screen, as `GlueParent.lua`'s `DISCONNECTED_FROM_SERVER`
+/// does. Chained after [`enter_on_connected`]: a stream dying during entry drains `Connected` and
+/// `Disconnected` in one frame, and the dead session must be the last word.
 fn back_on_disconnect(
     mut msgs: MessageReader<crate::net::DisconnectedMessage>,
     mut roster: ResMut<Roster>,
@@ -622,26 +434,14 @@ fn back_on_disconnect(
     if !msgs.read().any(|m| m.session_over) {
         return;
     }
-    // The pending pick is the reconnect's memory (0065). With no reconnect coming it would only
-    // auto-answer the *next* roster — sending the player straight back into the world they were
-    // just thrown out of, without ever seeing the screen.
+    // With no reconnect coming, a kept pick would auto-answer the next roster.
     roster.pending_pick = None;
     next.set(ClientState::Login);
 }
 
-/// The server **refused** the character we picked (`SMSG_CHARACTER_LOGIN_FAILED`) → back to the
-/// glue layer, pick cleared, and the refusal said out loud.
-///
-/// The entry it undoes was optimistic: the IO thread announces the connection in the same breath
-/// as the pick (so the destination's tiles start streaming a round-trip early, decision 0777), and
-/// the refusal arrives after. So this runs the logout's transition on a world that was only ever
-/// half-built — the cover comes down with it ([`crate::loading_screen`]), and the IO thread's
-/// relist puts the roster back underneath.
-///
-/// **Clearing the pick is the load-bearing half.** `pending_pick` is 0065's reconnect memory, and
-/// the relist behind this refusal produces exactly the roster it auto-answers: left set, the
-/// client would re-enter the character the server just refused, be refused again, and loop — from
-/// behind a black screen, since each pass raises the cover afresh.
+/// `SMSG_CHARACTER_LOGIN_FAILED`: back to select with the refusal in the glue dialog. The IO
+/// thread announces the entry with the pick, so this undoes a half-built one. The pick must be
+/// cleared, or the relist behind the refusal is auto-answered and the refused login loops.
 fn back_on_login_refused(
     mut msgs: MessageReader<CharacterLoginFailedMessage>,
     mut roster: ResMut<Roster>,
@@ -659,25 +459,10 @@ fn back_on_login_refused(
     dialog.open_error(char_login_refusal_text(strings, msg.result));
 }
 
-/// The refusal byte, in the client's own words — the reference's jump table `0x5aae08`,
-/// transcribed.
-///
-/// **The byte is a 1-based reason index, not a status code**, and that is the whole reason this
-/// table exists rather than an offset. `ClientServices::OnCharLoginResult 0x5aad70` reads it as
-/// `movzx eax,byte[ebp+8]; dec eax; cmp eax,5; ja <default>` and jumps through a six-entry table,
-/// which maps `1..=6` onto the `CHAR_LOGIN_*` status codes `0x3e, 0x3f, 0x40, 0x42, 0x43, 0x44` —
-/// **skipping `0x41`**, `CHAR_LOGIN_FAILED`, which is reachable only as the default. So the
-/// tempting `0x3d + byte` is right for four rows and wrong for the rest, and `0` and anything past
-/// `6` are "Login failed" rather than an out-of-bounds read: the `ja` guard precedes the table.
-/// (The strings are the shipped `GlueStrings.lua:158-166`, quoted here only as the
-/// graceful-absence fallback.)
-///
-/// Both emulators speak this dialect. vmangos sends a bare `1` for all three of its refusal
-/// guards (`PlayerLoading() || GetPlayer() || !guid.IsPlayer()`), so **every** refusal from our
-/// own local server reads "World server is down" — the reference would say exactly that too, and
-/// saying anything better here would be benilla inventing a diagnosis the client cannot make.
-/// mangos-classic's live enum is `CharLoginFailReasons` `0x01..=0x08`; its `ResponseCodes`
-/// `CHAR_LOGIN_*` block, whose values would NOT survive this table, is commented out.
+/// The refusal byte as the reference's words, its jump table `0x5aae08`: the byte is a 1-based
+/// reason index (`0x5aad70` does `dec eax; cmp eax,5; ja <default>`), mapping `1..=6` onto status
+/// codes `0x3e 0x3f 0x40 0x42 0x43 0x44`, skipping `CHAR_LOGIN_FAILED` (`0x41`), the default arm.
+/// vmangos sends `1` for all its refusal guards, so it always reads "World server is down".
 pub(crate) fn char_login_refusal_text(strings: &GlueStrings, result: u8) -> &str {
     let (key, fallback): (&str, &str) = match result {
         1 => ("CHAR_LOGIN_NO_WORLD", "World server is down"),
@@ -698,20 +483,13 @@ pub(crate) fn char_login_refusal_text(strings: &GlueStrings, result: u8) -> &str
             "CHAR_LOGIN_LOCKED_FOR_TRANSFER",
             "Your character is currently locked as part of the paid character transfer process.",
         ),
-        // `0`, and `7` up (mangos-classic's `LOCKED_BY_BILLING` and `FAILED` among them): the
-        // switch's default arm, which is the only way `CHAR_LOGIN_FAILED` is ever reached.
+        // `0` and `7` up: the default arm, the only way to `CHAR_LOGIN_FAILED`.
         _ => ("CHAR_LOGIN_FAILED", "Login failed"),
     };
     strings.text(key, fallback)
 }
 
-/// A confirmed `/logout` → back to the glue layer, pick cleared (the follow-up roster must be
-/// shown, not auto-answered).
-///
-/// The in-world UI's input latches are released by [`crate::ui_script::end_ui_session`], on the
-/// `OnExit(InWorld)` edge this transition causes: they stick because `feed_ui_input` stops running
-/// outside `InWorld`, which is a fact about the edge and not about *why* we left it — so both this
-/// path and the disconnect above get it from one place (1290).
+/// A confirmed `/logout`: back to select, the pick cleared so the next roster is shown.
 fn back_on_logout(
     mut msgs: MessageReader<LoggedOutMessage>,
     mut roster: ResMut<Roster>,
@@ -723,20 +501,11 @@ fn back_on_logout(
     }
 }
 
-/// Surface a refused delete in the glue dialog; a success needs nothing here, since `net::io`
-/// re-enumerates before the result and the row is already gone.
-///
-/// **A refusal is reachable, and was silent.** vmangos refuses to delete a guild master
-/// (`HandleCharDeleteOpcode`: `GetGuildByLeader` → `CHAR_DELETE_FAILED`), and this used to be a
-/// `warn!` under a comment calling the refusal unreachable — so the player pressed Delete, typed
-/// DELETE, and watched nothing happen.
-///
-/// The reference's shape, read off `WoW.exe`: `SMSG_CHAR_DELETE 0x5b45c0` hands the result byte to
-/// `0x5ab0e0`, which passes it **straight through** as the operation status
-/// (`SetStatus(byte == 0x39, byte)`); `CGlueMgr::Update`'s `screenState == 6` arm (`0x46c14e`)
-/// then, on a completed-and-failed operation, fires `OPEN_STATUS_DIALOG("OKAY", text)`
-/// (`0x46c177` pushes `"OKAY"` `0x837084`) with the status text the key table `0x85cae8` names —
-/// the one-button dialog [`crate::glue::dialog::GlueDialog::open_error`] is.
+/// Surface a refused delete in the glue dialog (vmangos refuses a guild master). The reference's
+/// `SMSG_CHAR_DELETE` handler (`0x5b45c0`) passes the byte through as the status (`0x5ab0e0`), and
+/// on failure `CGlueMgr::Update` (`0x46c14e`) opens the one-button `OKAY` dialog (`0x46c177`
+/// pushes `"OKAY"`, `0x837084`) with the key table `0x85cae8`'s text. A success needs nothing:
+/// `net::io` re-enumerates first.
 fn delete_result(
     mut msgs: MessageReader<CharActionResultMessage>,
     mut dialog: ResMut<crate::glue::dialog::GlueDialog>,
@@ -758,18 +527,11 @@ fn delete_result(
     }
 }
 
-/// A `SMSG_CHAR_DELETE` result byte → the sentence the refusal dialog says, or `None` for the
-/// success (`0x39`), which the refreshed roster says instead.
-///
-/// The keys are the `CHAR_DELETE_*` block of the reference's status-key table `0x85cae8`
-/// (`0x38..=0x3b`), numbered exactly as vmangos's `ResponseCodes` (`SharedDefines.h`). vmangos
-/// sends only two of them: `0x39` on success and `0x3a` for a guild master; its three other
-/// refusals (a character still loaded, one not found, one on another account) send nothing at all.
-///
-/// **The default arm is benilla's, not the reference's.** The reference indexes the whole 83-row
-/// table with the byte, so an out-of-block byte would read some other family's sentence (and one
-/// past `0x52` would read `"(%i)"`); that table is not transcribed here, and no server we speak to
-/// sends such a byte, so anything unnamed says the block's own generic failure.
+/// A `SMSG_CHAR_DELETE` result byte as the refusal sentence, `None` for success (`0x39`). The keys
+/// are the `CHAR_DELETE_*` block (`0x38..=0x3b`) of the status-key table `0x85cae8`, numbered as
+/// vmangos's `ResponseCodes`; vmangos sends only `0x39` and `0x3a` (guild master). Any other byte
+/// reads `CHAR_DELETE_FAILED`; the reference indexes its whole 83-row table with it, which is not
+/// transcribed here, and no server sends one.
 pub(crate) fn char_delete_refusal_text(strings: &GlueStrings, code: u8) -> Option<&str> {
     let (key, fallback): (&str, &str) = match code {
         benilla_protocol::messages::CHAR_DELETE_SUCCESS => return None,
@@ -778,15 +540,14 @@ pub(crate) fn char_delete_refusal_text(strings: &GlueStrings, code: u8) -> Optio
             "CHAR_DELETE_FAILED_LOCKED_FOR_TRANSFER",
             "Your character is currently locked as part of the paid character transfer process.",
         ),
-        // `0x3a` — the guild-master refusal — and the default arm above.
+        // `0x3a`, the guild-master refusal, and every unnamed byte.
         _ => ("CHAR_DELETE_FAILED", "Character deletion failed"),
     };
     Some(strings.text(key, fallback))
 }
 
-/// Glue-flow smoke (`WOW_GLUE_ROUNDTRIP=1`, decision 0423): once a real roster is up, bounce
-/// CharSelect → CharCreate → **Back** → CharSelect and exit — so the return-to-select rebuild is
-/// provable headlessly from the logs. Runs ungated (it crosses states); inert without the env.
+/// Glue-flow smoke (`WOW_GLUE_ROUNDTRIP=1`): once a roster is up, go to CharCreate, Back to
+/// CharSelect, and exit. Ungated, since it crosses states.
 fn debug_glue_roundtrip(
     roster: Res<Roster>,
     state: Res<State<ClientState>>,
@@ -826,24 +587,10 @@ fn debug_glue_roundtrip(
     }
 }
 
-/// The logout-boundary smoke (`WOW_LOGOUT_SMOKE=1`, meant with the `WOW_CHAR` fast path): once
-/// seated in the world, linger, request the `/logout` round-trip, confirm the return to
-/// CharSelect, linger again (the glue theme should be the only thing audible over the logs'
-/// world-teardown lines), **enter the world a second time**, and exit. Inert without the env.
-///
-/// The re-entry leg is not decoration. Since decision 0777 the world is *released* on the way out
-/// (`terrain_stream::release_world`), so the second entry is a materially different code path from
-/// the first — it streams a map the streamer has already torn down once — and a teardown that
-/// forgets to reset its own bookkeeping fails exactly here and nowhere else. The world-audio
-/// boundary this smoke was written for is still checked on the way through.
-///
-/// **It ends the way a player ends a session** — by closing the window, not by writing an
-/// `AppExit` of its own (decision 1528). That is not cosmetic: the close is the *latest*
-/// announcement Bevy makes (`exit_on_all_closed` in `PostUpdate`, a frame after the request), so
-/// it is the only exit that actually tests whether the shutdown tail is reachable. Exiting by a
-/// hand-written `AppExit` from `Update` skipped that question for this smoke's whole life, and the
-/// bug it would have caught — every saved variable, every addon file and the camera pose lost on
-/// every window close — shipped underneath it.
+/// The logout smoke (`WOW_LOGOUT_SMOKE=1`, with `WOW_CHAR`): once in the world, `/logout`, return
+/// to CharSelect, enter the world again and close the window. The second entry streams a map
+/// `terrain_stream::release_world` tore down. It ends by a window close, not an `AppExit`, since
+/// only the close reaches the shutdown tail that saves variables and addon files.
 fn debug_logout_smoke(
     state: Res<State<ClientState>>,
     player: Res<crate::player::Player>,
@@ -876,17 +623,8 @@ fn debug_logout_smoke(
             info!("logout-smoke: back at character select — lingering");
             (*phase, *mark) = (3, now);
         }
-        // **The residency reading belongs HERE, not on arrival.** It used to print on the first
-        // frame at CharSelect and report "25 tiles resident (must be 0)" every single run — a
-        // permanent, alarming, wrong number. `release_world` runs ~150 ms later (it hangs off the
-        // world-live falling edge, not the state edge), so the probe was reading the count before
-        // the thing it is checking had happened, and reporting the world it had just left.
-        //
-        // It cost more than a wrong line: 2277 wrote the reading up as a live contradiction of
-        // 0777's release-world claim, on the strength of it reproducing identically on an older
-        // commit — which it did, because an instrument that measures too early does that reliably.
-        // A number that is always wrong teaches everyone to skip the line (0777's own lesson about
-        // tripwires nobody trips, from the other end).
+        // Residency is read here, not on arrival: `release_world` runs about 150 ms after the
+        // state edge, on the world-live falling edge.
         3 if now - *mark > 4.0 => match roster.chars.first().map(|c| (c.guid, c.name.clone())) {
             Some((guid, name)) => {
                 info!(
@@ -903,13 +641,9 @@ fn debug_logout_smoke(
             }
         },
         4 if *state.get() == ClientState::InWorld && player.active && now - *mark > 3.0 => {
-            // **The suppressor reading is the point of the second entry, not a decoration on it**
-            // (B306, decision 1542). This leg has crossed the boundary on every run since 2277 and
-            // could only ever report that it *happened* — tiles, UI rebuilds, error counts — none
-            // of which a character who re-entered unable to move would disturb. `scripts/smoke.sh`
-            // fails on anything but `none`, and separately reports whether the run's logout was
-            // the rooted kind at all: a GM probe gets vmangos's instant path, which is B306's
-            // precondition missing, so a green here is not a B306 regression on its own.
+            // The suppressor reading catches a character that re-entered unable to move;
+            // `scripts/smoke.sh` fails on anything but `none`. A GM account's logout is instant,
+            // not rooted, so it does not exercise the rooted path.
             info!(
                 "logout-smoke: re-entered — {} tiles resident, suppressors: {}, done",
                 streamer.residency().1,
@@ -919,9 +653,7 @@ fn debug_logout_smoke(
         }
         5 => {
             info!("logout-smoke: done");
-            // The player's exit: request the window close and let `bevy_window` take it from
-            // there. A run with no window (there is none in the headless harness) has no such
-            // path, so it says so and falls back rather than hanging until the timeout.
+            // Close the window as a player does; a headless run has none and exits directly.
             match windows.single() {
                 Ok(window) => {
                     close.write(bevy::window::WindowCloseRequested { window });
@@ -937,18 +669,9 @@ fn debug_logout_smoke(
     }
 }
 
-/// The select-screen **walk** instrument (`WOW_CHARSELECT_WALK=<period_s>[:<enter_after_s>]`) —
-/// the thing a headless run had no way to do at all: *click a row*. It steps the selection one row
-/// per `period_s` through the whole roster (the ref's arrow-key cycle, in code), starting from the
-/// row the screen opened on, and logs each step with its elapsed stamp — so a booth/scene timeline
-/// (`WOW_BOOTH_LOG=1`, `WOW_STREAM_TRACE`) is attributable to the selection that caused it. With
-/// `enter_after_s`, it then presses **Enter World** that long after the last step, which is the
-/// only headless way to land on the world-entry edge from a screen that was actually *used*
-/// (`WOW_CHAR`'s fast path answers the first roster and never renders a second selection).
-///
-/// Built for the two reports this file's booth feed owns — the cold-selection model swap and the
-/// entry-edge stall — and kept, because every future "what does the screen do when you click"
-/// question needs exactly this and nothing more. Inert without the env.
+/// The select walk (`WOW_CHARSELECT_WALK=<period_s>[:<enter_after_s>]`): select each row in turn,
+/// one per `period_s`, logging each step with its time; with `enter_after_s`, press Enter World
+/// that long after the last step.
 fn debug_select_walk(
     mut roster: ResMut<Roster>,
     pick: Res<CharPick>,
@@ -976,7 +699,7 @@ fn debug_select_walk(
         return;
     }
     if roster.chars.is_empty() {
-        return; // roster not in yet — the walk starts at the first real screen
+        return;
     }
     let now = time.elapsed_secs();
     let at = *next_at.get_or_insert(now + period);
@@ -992,8 +715,7 @@ fn debug_select_walk(
             c.name, c.race, c.class
         );
         roster.select(Some(i));
-        // The last row waits `enter_after` (not `period`) before the entry, so the screen the
-        // stall is measured from is a settled one.
+        // The last row waits `enter_after`, so the entry starts from a settled screen.
         *next_at = Some(
             now + if *row == roster.chars.len() {
                 enter_after.unwrap_or(period)
@@ -1003,7 +725,6 @@ fn debug_select_walk(
         );
         return;
     }
-    // The roster is walked. Either enter the world on the last selection, or stop.
     *done = true;
     if enter_after.is_none() {
         return;
@@ -1014,36 +735,27 @@ fn debug_select_walk(
     }
 }
 
-/// When the select screen came up: `Time::elapsed_secs()` at `OnEnter(CharSelect)`, gone again
-/// at `OnExit`. The one clock the screen's "a few seconds after the screen is up" instruments
-/// ([`debug_select_dialog`], [`debug_select_addons`], [`debug_select_shot`]) measure from, in
-/// place of a `Local` each stamped on its own first run (decision 2265 §C3). Those three run
-/// under `in_state(CharSelect)` in `Update`, so the resource is always there when they read it.
+/// When the select screen came up, present only while it is; the screen's timed instruments
+/// measure from it.
 #[derive(Resource, Clone, Copy)]
 struct CharSelectEnteredAt(f32);
 
 impl CharSelectEnteredAt {
-    /// Seconds the screen has been up.
     fn elapsed(&self, time: &Time) -> f32 {
         time.elapsed_secs() - self.0
     }
 }
 
-/// `OnEnter(CharSelect)`: stamp the screen's entry.
 fn stamp_select_entry(mut commands: Commands, time: Res<Time>) {
     commands.insert_resource(CharSelectEnteredAt(time.elapsed_secs()));
 }
 
-/// `OnExit(CharSelect)`: the screen is down, so is its clock.
 fn clear_select_entry(mut commands: Commands) {
     commands.remove_resource::<CharSelectEnteredAt>();
 }
 
-/// The shot instrument's delete-dialog dial (`WOW_CHARSELECT_DIALOG=<typed>`): open the
-/// typed-confirm dialog for the selected character a few seconds after the screen is up, with
-/// `<typed>` pre-typed (may be empty) — so the dialog's geometry (the ChatInputBorder edit box,
-/// the caret bar) is capturable headlessly. Pair with `WOW_CHARSELECT_SHOT_OUT`; inert without
-/// the env; fires once.
+/// `WOW_CHARSELECT_DIALOG=<typed>`: open the delete dialog for the selection 4 s after the screen
+/// is up, with `<typed>` pre-typed, for a shot.
 fn debug_select_dialog(
     roster: Res<Roster>,
     mut dialog: ResMut<dialog::DeleteDialog>,
@@ -1062,7 +774,7 @@ fn debug_select_dialog(
         return;
     }
     let Some(c) = roster.selected_char() else {
-        return; // roster not in yet — keep waiting
+        return;
     };
     let (guid, name, level, class) = (c.guid, c.name.clone(), c.level, class_name(c.class));
     dialog.open_for(guid, name, level, class);
@@ -1071,10 +783,8 @@ fn debug_select_dialog(
     *done = true;
 }
 
-/// The shot instrument's AddOns dial (`WOW_CHARSELECT_ADDONS=1`): open the AddOns panel a few
-/// seconds after the screen is up, exactly as the screen's own button would — so the reference
-/// AddonList layout is exercised and capturable headlessly (pair with
-/// `WOW_CHARSELECT_SHOT_OUT`). Inert without the env; fires once.
+/// `WOW_CHARSELECT_ADDONS=1`: open the AddOns panel 4 s after the screen is up, as its button
+/// does, for a shot.
 fn debug_select_addons(
     roster: Res<Roster>,
     mut panel: ResMut<addons::AddonsPanel>,
@@ -1093,9 +803,8 @@ fn debug_select_addons(
         return;
     }
     if roster.chars.is_empty() {
-        return; // roster not in yet — keep waiting
+        return;
     }
-    // The same open the AddOns button performs (`input::select_input`): realm + full roster.
     let realm = roster
         .realm
         .as_ref()
@@ -1107,20 +816,11 @@ fn debug_select_addons(
     *done = true;
 }
 
-/// Default delay before the select-screen shot fires (seconds from the screen coming up) — long
-/// enough for the art, the glue scene and the geared model to settle.
+/// Default delay of the select shot, seconds from the screen coming up.
 const SELECT_SHOT_AT: f32 = 8.0;
 
-/// The select-screen shot instrument (`WOW_CHARSELECT_SHOT_OUT=<path>`, decision 0465): once the
-/// screen has been up a few seconds (art + scene + model settled), write one PNG of the window via
-/// Bevy's own framebuffer readback — machine-checkable geometry without macOS screen-recording
-/// permission. Inert without the env.
-///
-/// `WOW_CHARSELECT_SHOT_AT=<secs>` moves the shot (default [`SELECT_SHOT_AT`], measured from the
-/// first frame the screen is up). The knob exists because the fixed 8 s lands *inside* the
-/// create round-trip when the run is `WOW_CHARCREATE_SHOT` + `WOW_CHARCREATE_NAME`: the B119 retest
-/// wants the screen a few seconds AFTER the new character lands, and it captured the frame 19 ms
-/// after the create result — before the booth had re-baked the new selection.
+/// The select shot (`WOW_CHARSELECT_SHOT_OUT=<path>`): one PNG of the window by framebuffer
+/// readback, [`SELECT_SHOT_AT`] seconds after the screen is up, or `WOW_CHARSELECT_SHOT_AT`.
 fn debug_select_shot(
     mut commands: Commands,
     time: Res<Time>,
@@ -1154,7 +854,7 @@ pub(crate) fn wow_font(assets: &AssetServer) -> Handle<Font> {
     assets.load("mpq://Fonts/FRIZQT__.ttf")
 }
 
-// ── 1.12 display constants (frozen facts of the build; display only) ────────────────────────────
+// ── 1.12 display names ──────────────────────────────────────────────────────────────────────────
 
 pub(crate) fn race_name(race: u8) -> &'static str {
     match race {
@@ -1185,9 +885,7 @@ pub(crate) fn class_name(class: u8) -> &'static str {
     }
 }
 
-/// A `Character` with only its identity filled in — enough for any test that cares about *which*
-/// row, not what stands on the stage. `pub(crate)` so [`crate::cvars`]'s end-to-end round trip can
-/// build a roster without a second copy of this list drifting from the real one.
+/// A `Character` with only its identity filled in.
 #[cfg(test)]
 pub(crate) fn test_character(guid: u64, name: &str) -> Character {
     Character {
@@ -1217,14 +915,7 @@ pub(crate) fn test_character(guid: u64, name: &str) -> Character {
     }
 }
 
-/// The roster policy and its CVar mirror, with none of the screen they normally run under — the
-/// two systems the remembered selection is made of ([`apply_roster_policy`] reads it,
-/// [`persist_last_character`] writes it), wired into a test app.
-///
-/// `pub(crate)` so [`crate::cvars`] can drive them over a **real** CVar host: the seam where a
-/// queued engine write becomes a line in `config.toml` lives entirely in that module, and this
-/// module's own tests stub it. `CharSelectPlugin` itself is not usable there — it wants the whole
-/// glue screen, its art and its sounds.
+/// The roster policy and its CVar mirror without the screen, for tests over a real CVar host.
 #[cfg(test)]
 pub(crate) fn add_test_systems(app: &mut App, pick: crossbeam_channel::Sender<CharRequest>) {
     app.insert_state(ClientState::CharSelect)
@@ -1243,19 +934,8 @@ mod tests {
 
     use super::test_character as character;
 
-    /// **A session that dies during world entry does not leave the client in the world**
-    /// (decision 1262).
-    ///
-    /// The IO thread emits `Connected` *before* its read loop starts, so a socket that dies mid-
-    /// entry — which is exactly what a displacement kick looks like, a bare EOF and nothing else —
-    /// queues `Connected` and `Disconnected` back to back, and the drain (`try_iter`) hands the app
-    /// both in one frame. Both edges then fire in the same `Update`. Whichever writes `NextState`
-    /// last wins, and before this the entry did: the client flipped `InWorld` against a world the
-    /// same frame's teardown had already emptied, and stood there in a camera with no avatar.
-    ///
-    /// The guard is the *ordering*, which nothing else can catch: each system is correct alone, the
-    /// build is green either way, and the failure needs two logins racing on one account to
-    /// reproduce by hand.
+    /// A socket dying mid-entry (a displacement kick) drains `Connected` and `Disconnected` in one
+    /// frame; the ordering alone makes the disconnect win.
     #[test]
     fn a_session_lost_during_entry_beats_the_entry() {
         let mut app = App::new();
@@ -1269,7 +949,6 @@ mod tests {
             .add_systems(Update, (enter_on_connected, back_on_disconnect).chain());
         app.world_mut().resource_mut::<Roster>().pending_pick = Some(7);
 
-        // One frame carrying both halves of the race, in the order the drain produces them.
         app.world_mut().write_message(EnteredWorldMessage {
             billing_time_rested: 0,
             tutorial_flags: None,
@@ -1297,9 +976,7 @@ mod tests {
         );
     }
 
-    /// The same frame with the session *not* over (a clean logout's teardown, or an unattended run
-    /// keeping 0065's seamless reconnect) still enters the world — the guard above must not have
-    /// turned every disconnect into a bounce to the login screen.
+    /// A teardown whose session is not over (a logout, or a reconnect) still enters the world.
     #[test]
     fn a_teardown_that_is_not_the_end_leaves_the_entry_alone() {
         let mut app = App::new();
@@ -1331,19 +1008,8 @@ mod tests {
         );
     }
 
-    /// **A refused character login takes the entry back** — and does it in the same frame the
-    /// entry was announced in.
-    ///
-    /// The IO thread sends `CMSG_PLAYER_LOGIN` and emits `Connected` in the same breath (the
-    /// entry's head start, decision 0777), so when the server refuses immediately — which is the
-    /// vmangos guard's whole shape: `PlayerLoading() || GetPlayer() || !guid.IsPlayer()` answers
-    /// before it touches the database — `Connected` and `SMSG_CHARACTER_LOGIN_FAILED` reach the
-    /// app in ONE drain. Both edges then fire in one `Update`, and the refusal has to be the last
-    /// word, exactly as a lost session does one test up.
-    ///
-    /// Without this the client flips `InWorld` against a world the server has just declined to
-    /// give it: no snap, no objects, and a loading cover armed for a snap that will never come —
-    /// which is the shape the whole fix exists to end.
+    /// `Connected` is emitted with `CMSG_PLAYER_LOGIN`, and vmangos refuses before touching the
+    /// database, so the refusal lands in the same drain and must be the last word.
     #[test]
     fn a_refused_login_beats_the_entry_it_revokes() {
         let mut app = App::new();
@@ -1379,8 +1045,7 @@ mod tests {
             "and the pick goes with it: the relist behind the refusal is auto-answered with \
              `pending_pick`, so keeping it would re-enter the character just refused, forever",
         );
-        // And the player is told. No GlueStrings in this App, so this is the fallback literal —
-        // the shipped sentence for vmangos's `1` is asserted against the real chain below.
+        // No GlueStrings here, so the fallback literal; the shipped one is checked below.
         assert_eq!(
             app.world()
                 .resource::<crate::glue::dialog::GlueDialog>()
@@ -1390,15 +1055,8 @@ mod tests {
         );
     }
 
-    /// **Every refusal byte resolves to the sentence 1.12 actually ships**, read off the player's
-    /// own chain — the char-create screen's regression (2045/2052) applied to the table this
-    /// screen owns. Skips without client data.
-    ///
-    /// The two rows worth writing down. `1` is the only byte vmangos ever sends, and it reads
-    /// "World server is down" — not the "duplicate character" its own guard actually means, which
-    /// is the server's dialect and not ours to improve on. And `4` is where the tempting
-    /// `0x3d + byte` arithmetic breaks: the reference's table skips `CHAR_LOGIN_FAILED` (0x41),
-    /// so `4` is `CHAR_LOGIN_DISABLED` and not the "Login failed" an offset would give.
+    /// Every refusal byte resolves to the sentence 1.12 ships, off the player's chain. `4` is
+    /// `CHAR_LOGIN_DISABLED`: the reference's table skips `CHAR_LOGIN_FAILED` (0x41).
     #[test]
     fn every_refusal_byte_resolves_in_the_real_glue_strings() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -1412,16 +1070,14 @@ mod tests {
         );
         assert_eq!(char_login_refusal_text(&strings, 5), "Character not found");
 
-        // The default arm, from both ends of the guard the reference's `dec eax; cmp eax,5; ja`
-        // draws — and it must be the same sentence, since there is only one default.
+        // Both ends of the reference's `dec eax; cmp eax,5; ja` guard reach the one default.
         let default = char_login_refusal_text(&strings, 0);
         assert_eq!(default, "Login failed");
         for byte in [7u8, 8, 0x3f, 0x43, 0xff] {
             assert_eq!(char_login_refusal_text(&strings, byte), default);
         }
 
-        // Every named byte must resolve to a REAL key — a fallback that happens to match would
-        // hide a missing key forever.
+        // Every named byte must resolve to a real key, or a matching fallback hides a missing one.
         let map = crate::glue_strings::table_from_chain(&mut chain).into_map();
         for key in [
             "CHAR_LOGIN_NO_WORLD",
@@ -1436,11 +1092,8 @@ mod tests {
         }
     }
 
-    /// **A refused delete is said, not swallowed.** vmangos refuses to delete a guild master with
-    /// `CHAR_DELETE_FAILED` (0x3a); the screen used to `warn!` into the log and show nothing, so
-    /// the confirmed delete just silently did not happen. The reference raises its one-button
-    /// glue dialog with the `CHAR_DELETE_*` status text (`CGlueMgr::Update`'s `screenState == 6`
-    /// arm). A success raises nothing — the refreshed roster is the answer.
+    /// A refused delete (vmangos's guild-master `CHAR_DELETE_FAILED`, 0x3a) opens the one-button
+    /// glue dialog; a success opens nothing.
     #[test]
     fn a_refused_delete_raises_the_glue_dialog() {
         use crate::glue::dialog::{DialogKind, GlueDialog};
@@ -1467,14 +1120,11 @@ mod tests {
         app.update();
         let dialog = app.world().resource::<GlueDialog>();
         assert_eq!(dialog.kind, Some(DialogKind::Error), "the OKAY dialog");
-        // No GlueStrings in this App: the fallback literal. The shipped sentence is asserted
-        // against the real chain below.
+        // No GlueStrings here, so the fallback literal; the shipped one is checked below.
         assert_eq!(dialog.text, "Character deletion failed");
     }
 
-    /// The delete refusals resolve to the sentences 1.12 ships, off the player's own chain — and
-    /// every key named is a REAL key, so a matching fallback cannot hide a missing one. Skips
-    /// without client data.
+    /// The delete refusals resolve to the sentences 1.12 ships, each off a real key.
     #[test]
     fn every_delete_result_resolves_in_the_real_glue_strings() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -1503,18 +1153,15 @@ mod tests {
         }
     }
 
-    /// B119 — a created character is selected against the roster **already in hand**. `net::io`
-    /// re-enumerates and emits the fresh roster BEFORE the create result, so by the time
-    /// `note_created` runs the row exists and the roster message is spent; a version that only armed
-    /// a flag for "the next roster update" left the previously-selected row standing (reproduced
-    /// live: create a tauren on a human-first account, the human stays on the stage).
+    /// A created character is selected against the roster already in hand: `net::io` emits the
+    /// fresh roster before the create result.
     #[test]
     fn a_created_character_is_selected_from_the_roster_in_hand() {
         let mut roster = Roster {
             chars: vec![
                 character(1, "Kerwind"),
                 character(2, "Xero"),
-                character(3, "Zzbullone"), // the fresh row, appended by the re-enum
+                character(3, "Zzbullone"), // appended by the re-enum
             ],
             selected: Some(0),
             ..default()
@@ -1524,9 +1171,7 @@ mod tests {
         assert!(roster.just_created.is_none(), "and the arm consumed");
     }
 
-    /// The name key is case-insensitive: vmangos normalizes a created name
-    /// (`normalizePlayerName` — first letter upper, rest lower), so the string the create screen
-    /// typed is NOT what the enum sends back.
+    /// The name key is case-insensitive: vmangos's `normalizePlayerName` recases a created name.
     #[test]
     fn the_created_name_matches_the_servers_normalized_spelling() {
         let mut roster = Roster {
@@ -1538,11 +1183,10 @@ mod tests {
         assert_eq!(roster.selected, Some(1));
     }
 
-    // ── The remembered character (`lastCharacterIndex`, decision 1622) ───────────────────────────
+    // ── The remembered character (`lastCharacterIndex`) ───────────────────────────
 
-    /// Drive the REAL [`apply_roster_policy`] over one roster message, with `config.toml` already
-    /// holding `stored` for `lastCharacterIndex` (`None` = a launch that has never entered a
-    /// world). Returns the row the screen opens on.
+    /// Run [`apply_roster_policy`] over one roster with `stored` as `lastCharacterIndex` (`None`
+    /// for never set); returns the row the screen opens on.
     fn roster_policy_over(
         stored: Option<&str>,
         names: &[&str],
@@ -1575,9 +1219,7 @@ mod tests {
         app.world().resource::<Roster>().selected()
     }
 
-    /// **The report**: the screen must open on the character you last logged in as, as the
-    /// reference does. The stored value is 0-based — the engine's own selection cell, one less
-    /// than the row the glue Lua counts in — so `"2"` IS row 2.
+    /// The screen opens on the character last logged in as; the stored value is 0-based.
     #[test]
     fn the_roster_opens_on_the_remembered_character() {
         assert_eq!(
@@ -1591,10 +1233,8 @@ mod tests {
         );
     }
 
-    /// A client that has never entered a world stores nothing — and `"0"` is not "nothing", it is
-    /// the FIRST character (the registrar default, which is exactly why the key is absent from a
-    /// `Config.wtf` whose player last played their first character). Both land on row 0, and it
-    /// matters that they land there for the reference's reason.
+    /// Nothing stored and `"0"`, the registered default and the first character, both land on
+    /// row 0.
     #[test]
     fn nothing_remembered_and_a_stored_zero_are_both_the_first_row() {
         assert_eq!(
@@ -1607,8 +1247,7 @@ mod tests {
         );
     }
 
-    /// The remembered character was deleted (or this realm simply has fewer): the reference's
-    /// `0x472740` sends an out-of-range index to the **first** row — never to the nearest one.
+    /// An out-of-range index goes to the first row, not the nearest (`0x472740`).
     #[test]
     fn a_remembered_row_past_the_end_falls_back_to_the_first() {
         assert_eq!(
@@ -1618,7 +1257,7 @@ mod tests {
         );
     }
 
-    /// A hand-edited or corrupt value is not a crash and not a wrong row: the first row.
+    /// A corrupt value selects the first row.
     #[test]
     fn an_unparseable_remembered_value_is_the_first_row() {
         assert_eq!(
@@ -1627,10 +1266,8 @@ mod tests {
         );
     }
 
-    /// **Every** roster re-applies the stored row, not just the session's first — the reference
-    /// reads the CVar inside the char-list rebuild (`0x4724d0`), so a live selection that was
-    /// never entered as does not survive a re-enum. This is the half that makes the memory mean
-    /// "who you last **logged in** as" rather than "the last row you clicked".
+    /// Every roster re-applies the stored row (the reference reads it in the list rebuild,
+    /// `0x4724d0`), so a selection never entered as does not survive a re-enum.
     #[test]
     fn a_re_enumerated_roster_returns_to_the_remembered_character() {
         assert_eq!(
@@ -1640,12 +1277,8 @@ mod tests {
         );
     }
 
-    /// **The report**: drag the character round on the select screen, then click the row it is
-    /// already standing on, and it snapped square again — the reference keeps the angle.
-    /// `CharacterSelectButton_OnClick`'s whole body is `if ( id ~= CharacterSelect.selectedIndex )`,
-    /// so that click never reaches the engine's unconditional facing zero at all (2194, correcting
-    /// 1533 — which verified the engine function and never asked what calls it). The facing reset
-    /// rides `select_seq`, so "did it re-square" is exactly "did the counter move".
+    /// Clicking the current row keeps the dragged facing (`CharacterSelectButton_OnClick` gates on
+    /// `id ~= selectedIndex`); the facing reset rides `select_seq`.
     #[test]
     fn re_clicking_the_selected_row_keeps_the_facing() {
         let mut roster = Roster {
@@ -1667,9 +1300,8 @@ mod tests {
         );
     }
 
-    /// …but a just-created character still wins, which is the reference's precedence and the
-    /// order it comes in: the C side pushes the restored index into Lua first, and
-    /// `UpdateCharacterList`'s deferred `selectLast` flag overwrites it (B119 stays fixed).
+    /// A just-created character outranks the remembered row: `UpdateCharacterList`'s deferred
+    /// `selectLast` overwrites the restored index.
     #[test]
     fn a_created_character_outranks_the_remembered_one() {
         let (tx, _rx) = crossbeam_channel::unbounded();
@@ -1681,8 +1313,7 @@ mod tests {
             .add_message::<CharListMessage>()
             .add_message::<AppExit>()
             .add_systems(Update, apply_roster_policy);
-        // The create result landed before the fresh roster (the order `net::io` does NOT use —
-        // the one `apply_roster_policy` exists to answer).
+        // The create result lands before the fresh roster, the order `apply_roster_policy` answers.
         app.world_mut()
             .resource_mut::<Roster>()
             .note_created("Zzbullone".into());
@@ -1702,7 +1333,7 @@ mod tests {
         );
     }
 
-    /// The base, in the one place it lives, and the value's own spelling for the first character.
+    /// The stored value is 0-based.
     #[test]
     fn the_stored_index_is_zero_based_and_round_trips() {
         for row in [0usize, 1, 4, 9] {
@@ -1721,9 +1352,7 @@ mod tests {
         assert_eq!(last_character_row(""), None);
     }
 
-    /// **The write is at Enter World, not at selection** — the reference's `0x46b500` formats the
-    /// CVar from the index it is about to enter as, while clicks and arrow keys reach `0x472740`
-    /// and never touch it. So "last logged in", exactly as reported.
+    /// The write is at Enter World, not at selection (`0x46b500`).
     #[test]
     fn only_entering_the_world_writes_the_cvar() {
         let (tx, _rx) = crossbeam_channel::unbounded();
@@ -1740,7 +1369,7 @@ mod tests {
                 character(2, "Xero"),
                 character(3, "Zz"),
             ];
-            roster.select(Some(2)); // clicked around the list…
+            roster.select(Some(2));
             roster.select(Some(1));
         }
         app.update();
@@ -1749,7 +1378,6 @@ mod tests {
             "a selection alone must NOT be remembered — the reference writes nothing here",
         );
 
-        // …and now Enter World, on the row that was selected.
         app.world_mut().resource_mut::<Roster>().pending_pick = Some(2);
         app.update();
         let moved: Vec<(String, String)> = app
@@ -1764,9 +1392,7 @@ mod tests {
             vec![(CVAR_LAST_CHARACTER.to_string(), "1".to_string())],
             "guid 2 sits at row 1, and the row is what the registry took",
         );
-        // Steady frames stay quiet, and the next VM is seeded from the registry — which is what
-        // replaced the per-VM memo this system used to carry (1290's property, now held by the
-        // store outliving the VM, 2303).
+        // Steady frames stay quiet; the next VM is seeded from the registry.
         app.update();
         let cvars = app.world().resource::<crate::cvars::Cvars>();
         assert!(!cvars.has_events());
@@ -1776,10 +1402,8 @@ mod tests {
             .any(|r| r.name == CVAR_LAST_CHARACTER && r.value == "1"));
     }
 
-    /// The reverse arrival order (result first, roster after) stays armed and is answered by the
-    /// roster policy — and a name that still can't be found falls back to the LAST row, which is the
-    /// ref's literal `SELECT_LAST_CHARACTER` → `SelectCharacter(numChars)` and the same character
-    /// anyway (vmangos enumerates `ORDER BY create_time, guid`).
+    /// Result first, roster after: the arm is answered by the roster policy, and a name not found
+    /// falls back to the last row (`SELECT_LAST_CHARACTER`).
     #[test]
     fn an_unanswerable_create_stays_armed() {
         let mut roster = Roster {
diff --git a/crates/benilla-app/src/char_select/refresh.rs b/crates/benilla-app/src/char_select/refresh.rs
index 3d60f2d4..e2987cb0 100644
--- a/crates/benilla-app/src/char_select/refresh.rs
+++ b/crates/benilla-app/src/char_select/refresh.rs
@@ -1,8 +1,5 @@
-//! The select screen's live refresh — everything that follows the roster or the pointer after
-//! [`super::screen`] spawns the tree: the row texts + visibility, the row highlight (hover, and
-//! LOCKED on the selected row — the ref's `LockHighlight`), the realm banner, the selected name
-//! over the model, the buttons' enabled states, and the glue-booth feed (scene by the selected
-//! character's race, the geared look).
+//! The select screen's live refresh after [`super::screen`] spawns the tree: row texts, the
+//! locked row highlight, the realm banner, the selected name, button states and the glue booth.
 
 use bevy::prelude::*;
 
@@ -15,9 +12,8 @@ use crate::portrait::{GlueLook, GluePreview, SelectLook};
 use super::screen::{RealmBanner, RowText, SelectAction, SelectedName, MAX_ROWS};
 use super::{class_name, Roster};
 
-/// Refill the row texts + visibility, the selected name, and the realm banner whenever the roster
-/// changes (a fresh enum, a selection move) — or when the screen was just (re)spawned (returning
-/// from the create screen finds an unchanged roster; the fresh, empty tree must still fill).
+/// Refill the rows, the selected name and the realm banner when the roster changes or the screen
+/// was just spawned (a return from the create screen finds the roster unchanged).
 #[allow(clippy::type_complexity)]
 pub(super) fn refresh_list(
     roster: Res<Roster>,
@@ -37,7 +33,6 @@ pub(super) fn refresh_list(
     let empty = GlueStrings::default();
     let strings = strings.as_deref().unwrap_or(&empty);
 
-    // Row visibility: rows with a character show; the rest hide (the ref's enumerate-then-hide).
     for (action, mut vis) in &mut rows {
         if let SelectAction::Row(i) = action {
             *vis = if *i < roster.chars.len() {
@@ -47,8 +42,8 @@ pub(super) fn refresh_list(
             };
         }
     }
-    // Row texts: Name; Info = `CHARACTER_SELECT_INFO` "Level %d %s" (class only — the ghost
-    // variant appends "(Ghost)"); Location = the zone name off AreaTable.
+    // Info is `CHARACTER_SELECT_INFO` "Level %d %s" (class only; the ghost variant appends
+    // "(Ghost)"); Location is the AreaTable zone name.
     for (text, mut t) in &mut texts {
         let (i, kind) = match text {
             RowText::Name(i) => (*i, 0),
@@ -81,8 +76,6 @@ pub(super) fn refresh_list(
             t.0 = new;
         }
     }
-    // The selected character's name over the model (empty list → empty, the ref's
-    // UPDATE_SELECTED_CHARACTER arg 0).
     if let Ok(mut t) = name.single_mut() {
         let new = roster
             .selected_char()
@@ -95,9 +88,8 @@ pub(super) fn refresh_list(
     if let Ok(mut t) = banner.single_mut() {
         let new = match &roster.realm {
             Some(realm) => {
-                // `GetServerName`'s own `isPVP, isRP` pair, from the one table that owns it.
-                // The banner's normal-realm arm is EMPTY, unlike the realm list's `Normal` — the
-                // reference leaves `serverType = ""` when neither flag is set.
+                // `GetServerName`'s `isPVP, isRP` pair. A normal realm has no suffix, unlike
+                // the realm list's `Normal`: the reference leaves `serverType = ""`.
                 let suffix = match crate::realm_select::pvp_rp(realm.realm_type) {
                     (true, true) => strings.text("RPPVP_PARENTHESES", "(RPPVP)"),
                     (false, true) => strings.text("RP_PARENTHESES", "(RP)"),
@@ -108,13 +100,8 @@ pub(super) fn refresh_list(
                     .then(|| strings.text("SERVER_DOWN", "Server down"));
                 realm_banner(&realm.name, suffix, down)
             }
-            // **`CharSelectRealmName:Hide()`** (`CharacterSelect.lua` l.66): with no server name
-            // the reference hides the FontString outright — it has no string for this case, and
-            // ours used to invent one (`"Connecting…"`). Empty text is our Hide.
-            //
-            // It is also all but unreachable now. The realm is chosen *before* the world dial, so
-            // by the time this screen exists the session has one; what is left here is the
-            // no-network harness, which is exactly the case the reference draws nothing for.
+            // With no server name the reference hides the banner (`CharSelectRealmName:Hide()`,
+            // `CharacterSelect.lua:67`); empty text is that Hide.
             None => String::new(),
         };
         if t.0 != new {
@@ -123,34 +110,19 @@ pub(super) fn refresh_list(
     }
 }
 
-/// The realm banner, composed the way `CharacterSelect_OnShow` composes it (`CharacterSelect.lua`
-/// l.48-62): the down note is appended to the **name**, and the realm-type suffix goes after that
-/// whole thing.
-///
-/// ```text
-/// serverName = serverName.."\n("..TEXT(SERVER_DOWN)..")";   -- only while disconnected
-/// CharSelectRealmName:SetText(serverName.." "..serverType);
-/// ```
-///
-/// A separate function because the order is exactly what drifted: ours put the suffix first and the
-/// down note last, under a comment claiming the reference's shape. Nothing showed while the suffix
-/// was `"(PVP)"` — parentheses read plausibly at either end. Decision 2052 made the suffix the enGB
-/// patch's `"PVP"`, a bare word, and the order became legible. A comment could not fail; this can.
+/// The realm banner as `CharacterSelect_OnShow` composes it (`CharacterSelect.lua:48-64`): the
+/// down note is appended to the name, and the realm-type suffix follows the whole.
 fn realm_banner(name: &str, suffix: &str, down: Option<&str>) -> String {
     let name = match down {
         Some(reason) => format!("{name}\n({reason})"),
         None => name.to_string(),
     };
-    // The reference appends `" "..serverType` unconditionally, leaving a trailing space on a realm
-    // with no type; we trim it, since ours is a laid-out node rather than a Lua string.
+    // The reference appends `" "..serverType` unconditionally; the trailing space is trimmed.
     format!("{name} {suffix}").trim_end().to_string()
 }
 
-/// Per-frame interaction visuals + button states: the row highlight (hover ∪ selected — the ref's
-/// `LockHighlight` on the selected row), and the enabled states — Enter World / Delete disable on
-/// an empty list (the ref's `UpdateCharacterList`), Create hides at the 10-cap or disconnected.
-/// (Change Realm was drawn deliberately dead under 0465 §6, until 2056 gave it something to do and
-/// 2072 made it work.)
+/// Per-frame button states: `LockHighlight` on the selected row, Enter World and Delete disabled
+/// on an empty list (`UpdateCharacterList`), Create hidden at the 10-cap or disconnected.
 #[allow(clippy::type_complexity)]
 pub(super) fn refresh_banner_and_buttons(
     roster: Res<Roster>,
@@ -161,8 +133,7 @@ pub(super) fn refresh_banner_and_buttons(
         (With<crate::glue::widgets::GlueBtn>, Without<Hilight>),
     >,
 ) {
-    // `LockHighlight` on the chosen row and nothing about *visibility*: hovering is
-    // `crate::glue::glue_hilights`' question, and the two used to be one expression here.
+    // Only the lock: hover is `crate::glue::glue_hilights`'.
     for (action, mut locked) in &mut rows {
         let SelectAction::Row(i) = action else {
             continue;
@@ -182,8 +153,7 @@ pub(super) fn refresh_banner_and_buttons(
             disabled.0 = want;
         }
     }
-    // Create New Character shows while the realm answered and a slot is free (the ref hides it
-    // disconnected or at MAX_CHARACTERS_PER_REALM = 10).
+    // The reference hides Create disconnected or at `MAX_CHARACTERS_PER_REALM` (10).
     let show_create = roster.realm.is_some() && roster.chars.len() < MAX_ROWS;
     for (action, mut vis) in &mut create_vis {
         if matches!(action, SelectAction::CreateChar) {
@@ -196,32 +166,23 @@ pub(super) fn refresh_banner_and_buttons(
     }
 }
 
-/// Feed the glue booth from the roster (decision 0465): the scene is the SELECTED character's
-/// race's (the ref's `SetBackgroundModel` on the enum fileString — Orc before a list arrives or
-/// with an empty account, the ref's OnLoad default), the look its geared enum record. Runs every
-/// frame (cheap compares inside `GluePreview` writers — the builder keys on value change).
+/// Feed the glue booth: the scene is the selected character's race (`SetBackgroundModel`; Orc
+/// with no character, the reference's OnLoad default), the look its geared enum record.
 pub(super) fn feed_glue_preview(
     roster: Res<Roster>,
     mut preview: ResMut<GluePreview>,
     mut showing: Local<Option<u64>>,
 ) {
-    // **The facing belongs to the displayed character, not to the screen** (1533): turning one
-    // character must not hand its angle to the next one you click, and a fresh character faces the
-    // stage's own forward until you turn it. `GluePreview::yaw` is one resource shared by all three
-    // glue screens, so the reset lives at the selection edge rather than in the resource.
-    //
-    // Keyed on the selection **counter**, not on who is shown: the ref's `SelectCharacter` zeroes
-    // the facing unconditionally (`0x472950`, above the already-built discriminator), so selecting
-    // the same index again — what a roster refresh does — re-squares the character too. A *click*
-    // on the selected row is gated out one level up and never gets here (`Roster::click_row`,
-    // 2194). See `Roster::select_seq`.
+    // Each select zeroes the facing, even of the same index (`SelectCharacter`, `0x472950`),
+    // so this keys on the selection counter, not on who is shown. `GluePreview::yaw` is shared
+    // by all three glue screens, so the reset lives here.
     if *showing != Some(roster.select_seq) {
         *showing = Some(roster.select_seq);
         preview.yaw = 0.0;
     }
     let (race, look) = match roster.selected_char() {
         Some(c) => (c.race, Some(GlueLook::Select(SelectLook::from(c)))),
-        None => (2, None), // UI_Orc — the ref's initial/empty-account scene
+        None => (2, None), // UI_Orc, the reference's empty-account scene
     };
     let scene = Some(crate::portrait::GlueScene::Race(race));
     if preview.scene != scene {
@@ -236,7 +197,7 @@ pub(super) fn feed_glue_preview(
 mod tests {
     use super::*;
 
-    /// The composition order, pinned against `CharacterSelect.lua` l.48-62.
+    /// The composition order of `CharacterSelect.lua:48-64`.
     #[test]
     fn the_down_note_hangs_off_the_name_and_the_type_suffix_follows_it() {
         assert_eq!(realm_banner("Kalimdor", "PVP", None), "Kalimdor PVP");
@@ -245,8 +206,6 @@ mod tests {
             "Kalimdor\n(Server down) PVP",
             "the suffix follows the whole name+note, not the name alone"
         );
-        // No realm type: the reference's unconditional " " is all that would be left, and a banner
-        // does not end in whitespace.
         assert_eq!(realm_banner("Kalimdor", "", None), "Kalimdor");
         assert_eq!(
             realm_banner("Kalimdor", "", Some("Server down")),
diff --git a/crates/benilla-app/src/char_select/screen.rs b/crates/benilla-app/src/char_select/screen.rs
index 7a8f64c7..354ce27f 100644
--- a/crates/benilla-app/src/char_select/screen.rs
+++ b/crates/benilla-app/src/char_select/screen.rs
@@ -1,17 +1,5 @@
-//! The select screen's **layout** — the reference `CharacterSelect.xml` arrangement rebuilt in
-//! Bevy UI (decision 0465), full-bleed and scaled to the window: the glue engine renders a
-//! 1024×768 virtual screen scaled to the display, so every authored offset/size below is the
-//! ref's number times `height / 768`.
-//!
-//! Bottom layer: the glue booth's fullscreen render (the `UI_<Race>` scene + the geared selected
-//! character), drag-anywhere to rotate. Over it: the WoW logo (TOPLEFT), the selected character's
-//! name (`GlueFontNormalHuge` at BOTTOM (0,100)), Enter World (200×60 at BOTTOM (0,30)) with the
-//! rotate pair tucked under it, Back (BOTTOMRIGHT (−30,25)) and Delete Character to its left, and
-//! the right-column character frame: 260×642 at TOPRIGHT (−5,−15), `Glue-Tooltip` backdrop tinted
-//! `DEFAULT_TOOLTIP_COLOR` at 0.85 alpha, holding the realm banner, the Change Realm
-//! button (back to [`crate::realm_select`]'s list), ten 256×70 row buttons from TOPLEFT
-//! (24,−65) at the authored 57 px pitch (13 px overlap, hit-inset 15), and Create New Character at
-//! the frame's BOTTOM (0,15). The delete dialog is [`super::dialog`]'s.
+//! The select screen's layout, `CharacterSelect.xml` rebuilt in Bevy UI. The glue screen is a
+//! 1024×768 virtual screen, so every authored offset and size is scaled by `height / 768`.
 
 use bevy::prelude::*;
 use bevy::ui_render::ui_material::MaterialNode;
@@ -28,30 +16,28 @@ use benilla_assets::WorldAssets;
 
 use super::wow_font;
 
-/// One clickable control on the screen — a single component so one query dispatches every button.
+/// One clickable control on the screen.
 #[derive(Component, Clone, Copy, PartialEq, Eq)]
 pub(super) enum SelectAction {
-    /// The fullscreen scene pane (drag to rotate — no click action).
+    /// The fullscreen scene pane, dragged to rotate.
     Scene,
-    /// A character-list row (0-based roster index; single click selects, double click enters).
+    /// A character-list row by 0-based roster index.
     Row(usize),
     EnterWorld,
-    /// Back to the login screen (the ref's flow — decision 0539 retired 0465 §6's
-    /// exit-the-client collapse).
+    /// Back to the login screen.
     Back,
     Delete,
     CreateChar,
-    /// Back to the realm list — drops the parked session, keeps the logon.
+    /// Raise the realm list over this screen, keeping the session.
     ChangeRealm,
-    /// Open the AddOns list (decision 1197) — the reference's `CharacterSelectAddonsButton`.
+    /// Open the AddOns list (`CharacterSelectAddonsButton`).
     Addons,
     RotateLeft,
     RotateRight,
 }
 
-/// Root of the select screen (despawned whole on exit). `with_art` records whether the tree was
-/// built with the client art present — an artless early spawn upgrades once the art lands; `s`
-/// records the glue scale it was built at, so a window resize (mac fullscreen) rebuilds it too.
+/// Root of the select screen. `with_art` and the glue scale `s` it was built at let an artless
+/// spawn or a resize rebuild it.
 #[derive(Component)]
 pub(super) struct CharSelectUi {
     pub(super) with_art: bool,
@@ -72,32 +58,26 @@ pub(super) enum RowText {
 }
 
 const SCREEN_Z: i32 = 1100;
-/// `DEFAULT_TOOLTIP_COLOR` (AccountLogin.lua): border rgb + bg rgb; the frame applies bg at 0.85.
+/// `DEFAULT_TOOLTIP_COLOR` (`AccountLogin.lua`): border and background rgb, background at 0.85.
 const FRAME_BORDER: Color = Color::srgb(0.8, 0.8, 0.8);
 const FRAME_FILL: Color = Color::srgb(0.09, 0.09, 0.09);
 const FRAME_FILL_ALPHA: f32 = 0.85;
-/// The list's row geometry (`CharSelectCharacterButtonTemplate` + the button anchors): 256×70
-/// buttons whose next TOP anchors 13 above the previous BOTTOM — net pitch 57; the hit rect drops
-/// the bottom 15 (the visible/clickable row is 55 tall).
+/// Row geometry (`CharSelectCharacterButtonTemplate`): 256×70 buttons, each TOP 13 above the
+/// previous BOTTOM (pitch 57), the hit rect dropping the bottom 15 (55 tall).
 pub(super) const MAX_ROWS: usize = 10;
 const ROW_W: f32 = 256.0;
 const ROW_HIT_H: f32 = 55.0;
 const ROW_PITCH: f32 = 57.0;
 
-/// Entry is a cheap state reset only — the tree spawns via [`materialize_screen`], because the
-/// INITIAL state's `OnEnter` fires during app startup, before the MPQ chain / booth slots exist
-/// (a one-shot spawn here came up artless with no scene pane — the boot-order trap the create
-/// screen never sees, entered seconds later).
+/// Entry only resets state: the initial state's `OnEnter` fires at startup, before the MPQ chain
+/// and booth slots exist, so the tree spawns in [`materialize_screen`].
 pub(super) fn enter_select(mut preview: ResMut<GluePreview>) {
-    // The model faces the camera on entry (the C-side facing global's zero default; the create
-    // screen's −15° is its own reset). The booth feed (`refresh::feed_glue_preview`) establishes
-    // the scene + look from the roster each frame.
+    // The model faces the camera on entry: the reference's facing global defaults to zero.
     preview.yaw = 0.0;
 }
 
-/// Spawn the screen tree once its prerequisites exist — and upgrade an artless early spawn the
-/// moment the client art lands (despawn + respawn; the tree is cheap and static). With no client
-/// data at all the artless tree still spawns after a short grace (the graceful-absence posture).
+/// Spawn the screen tree once the art is loaded, respawn it when art lands after an artless spawn
+/// or the glue scale changes; with no client data it spawns artless after a second.
 pub(super) fn materialize_screen(
     mut commands: Commands,
     existing: Query<(Entity, &CharSelectUi)>,
@@ -118,8 +98,6 @@ pub(super) fn materialize_screen(
     let s = crate::glue::screen_scale(window.single().ok());
     match existing.single() {
         Ok((root, ui)) => {
-            // Rebuild when the art lands after an early artless spawn, or when a window resize
-            // (mac fullscreen, a drag) has changed the glue scale the tree was baked at.
             if (!ui.with_art && with_art) || ui.s != s {
                 commands.entity(root).despawn();
                 spawn_screen(
@@ -180,13 +158,8 @@ fn spawn_screen(
             BackgroundColor(BACKDROP),
         ))
         .with_children(|ui| {
-            // The 3D scene, full-bleed and first (everything else draws over it) — the ref's
-            // screen IS the fullscreen ModelFFX: the selected race's scene with the geared
-            // character standing in it. The whole pane drags to rotate (the ref's full-frame mouse
-            // rotation); the page tint behind it is the no-art fallback. It keeps the WINDOW while
-            // the chrome below does not: a pillarbox's bars are the booth camera's own output
-            // clear inside this window-sized target (1619 §3), so the pane that samples it covers
-            // the window and brings the bars with it.
+            // The fullscreen ModelFFX scene, first so everything draws over it. It covers the
+            // window, not the canvas: a pillarbox's bars are the booth camera's own clear.
             let mut pane = ui.spawn((
                 SelectAction::Scene,
                 Button,
@@ -205,18 +178,15 @@ fn spawn_screen(
         })
         .id();
 
-    // ...and every piece of chrome hangs off the CANVAS — the boxed scene's own rect (decision
-    // 2091). Anchored to the window instead, the logo and the whole right-hand character frame
-    // (with Delete Character and Back) stood out in the bars at 21:9 (B377).
+    // The chrome hangs off the canvas, the boxed scene's rect, so none of it sits in the bars.
     let mut canvas = commands.spawn((crate::glue::glue_canvas(), ChildOf(root)));
     canvas.with_children(|ui| {
-        // The WoW logo (`CharacterSelectLogo`, 256×128 at TOPLEFT (3,−7)).
+        // `CharacterSelectLogo`, 256×128 at TOPLEFT (3,-7).
         if let Some(logo) = &art.logo {
             ui.spawn((ImageNode::new(logo.clone()), abs(s, 3.0, 7.0, 256.0, 128.0)));
         }
 
-        // The selected character's name (`CharSelectCharacterName`, GlueFontNormalHuge 22 gold,
-        // BOTTOM (0,100)).
+        // `CharSelectCharacterName`, GlueFontNormalHuge gold at BOTTOM (0,100).
         ui.spawn((Node {
             position_type: PositionType::Absolute,
             bottom: px(100.0),
@@ -241,7 +211,7 @@ fn spawn_screen(
                 );
             });
 
-        // Enter World (`CharSelectEnterWorldButton`, GlueButtonTemplate 200×60 at BOTTOM (0,30)).
+        // `CharSelectEnterWorldButton`, GlueButtonTemplate 200×60 at BOTTOM (0,30).
         ui.spawn((Node {
             position_type: PositionType::Absolute,
             bottom: px(30.0),
@@ -265,11 +235,7 @@ fn spawn_screen(
 
         rotate_cluster(ui, art, &font, s);
 
-        // **AddOns** (decision 1197) — the reference's `CharacterSelectAddonsButton`, which 1191
-        // §5 recorded as never built because there was no list behind it. There is now. Bottom
-        // LEFT, out of the way of the Enter World / Back cluster; the reference sits it in the
-        // same lower band. Shown only when something is installed, exactly as the reference's
-        // `UpdateAddonButton` hides it on `GetNumAddOns() == 0`.
+        // `CharacterSelectAddonsButton`, hidden on `GetNumAddOns() == 0` (`UpdateAddonButton`).
         if super::addons::AddonsPanel::any_installed() {
             ui.spawn((Node {
                 position_type: PositionType::Absolute,
@@ -293,7 +259,7 @@ fn spawn_screen(
                 });
         }
 
-        // Back (100×35 at BOTTOMRIGHT (−30,25)) and Delete Character (165×35 at its LEFT).
+        // Back (100×35 at BOTTOMRIGHT (-30,25)) and Delete Character (165×35 at its LEFT).
         ui.spawn((Node {
             position_type: PositionType::Absolute,
             right: px(30.0),
@@ -330,9 +296,7 @@ fn spawn_screen(
     });
 }
 
-/// The right-column character frame (`CharacterSelectCharacterFrame`, 260×642 at TOPRIGHT
-/// (−5,−15)): the `Glue-Tooltip` backdrop, the realm banner + disabled Change Realm, the ten row
-/// buttons, and Create New Character at the bottom.
+/// The right-column `CharacterSelectCharacterFrame`, 260×642 at TOPRIGHT (-5,-15).
 fn character_frame(
     ui: &mut ChildSpawnerCommands,
     art: &GlueArt,
@@ -350,8 +314,8 @@ fn character_frame(
         ..default()
     },))
         .with_children(|frame| {
-            // The backdrop: bg inset (10,5,4,9) tiled at 16, the 16-edge border over it — both
-            // tinted with DEFAULT_TOOLTIP_COLOR (border rgb / bg rgb at 0.85), the ref's OnLoad.
+            // Background inset (10,5,4,9) tiled at 16 under the 16-edge border, both tinted with
+            // `DEFAULT_TOOLTIP_COLOR` in the reference's OnLoad.
             if let (Some(bg), Some(border)) = (&art.tooltip_bg, &art.name_border) {
                 frame.spawn((
                     tiled_bg_node(
@@ -376,7 +340,7 @@ fn character_frame(
                     overlay(),
                 ));
             }
-            // The realm banner (`CharSelectRealmName`, GlueFontDisableLarge 18 at TOP (0,−10)).
+            // `CharSelectRealmName`, GlueFontDisableLarge at TOP (0,-10).
             outlined_text(
                 frame,
                 Node {
@@ -397,9 +361,6 @@ fn character_frame(
                 font,
                 s,
             );
-            // Change Realm (below the banner) — live. It was drawn permanently disabled for as
-            // long as there was no realm list behind it to go back to; there is now, and it
-            // costs a world dial rather than a re-login (`crate::realm_select`).
             frame
                 .spawn((Node {
                     position_type: PositionType::Absolute,
@@ -421,13 +382,12 @@ fn character_frame(
                         s,
                     );
                 });
-            // The ten row buttons (256×70 from TOPLEFT (24,−65), net pitch 57 — the 13 px overlap
-            // is the hit-rect's dropped bottom 15; our nodes ARE the hit shape, 55 tall).
+            // From TOPLEFT (24,-65); the nodes are the 55-tall hit shape.
             for row in 0..MAX_ROWS {
                 row_button(frame, art, font, row, s);
             }
-            // Create New Character (width ≈ text+50 ×45 at the frame BOTTOM (0,15) — the ref's
-            // shipped client always shows it here; the per-free-row anchor is commented out).
+            // Create New Character at the frame's BOTTOM (0,15); the reference's per-free-row
+            // anchor is commented out.
             frame
                 .spawn((Node {
                     position_type: PositionType::Absolute,
@@ -452,10 +412,8 @@ fn character_frame(
         });
 }
 
-/// One character-list row (`CharSelectCharacterButtonTemplate`): Name (GlueFontNormal 15 gold at
-/// TOPLEFT (0,−5)), Info (GlueFontHighlightSmall 12 white below), Location (GlueFontDisableSmall
-/// 12 gray below), and the ADD-mode `Glue-CharacterSelect-Highlight` card (256×74 at (−20,+8)) —
-/// lit on hover and LOCKED on the selected row.
+/// One `CharSelectCharacterButtonTemplate` row: Name, Info and Location lines and the ADD-mode
+/// `Glue-CharacterSelect-Highlight` card (256×74 at (-20,+8)), lit on hover, locked when selected.
 fn row_button(
     frame: &mut ChildSpawnerCommands,
     art: &GlueArt,
@@ -468,8 +426,8 @@ fn row_button(
         .spawn((
             SelectAction::Row(row),
             Button,
-            LockHighlight::default(), // `LockHighlight` on the selected row (refresh.rs)
-            Visibility::Hidden,       // shown by the refresh while the roster has this row
+            LockHighlight::default(),
+            Visibility::Hidden,
             Node {
                 position_type: PositionType::Absolute,
                 left: px(24.0),
@@ -548,10 +506,8 @@ fn row_button(
         });
 }
 
-/// The rotate pair (`CharacterSelectRotateLeft/Right`, 50² each): the left button's TOP anchors to
-/// Enter World's BOTTOM at (−15,+19) — the pair sits flush with the screen's bottom edge, tucked
-/// under the button — the right overlapping −19; `UI-RotationRight-Big` art with the left mirrored,
-/// `UI-Common-MouseHilight` ADD on hover.
+/// The rotate pair (`CharacterSelectRotateLeft/Right`, 50² each): the left's TOP anchors to Enter
+/// World's BOTTOM at (-15,+19), the right overlaps it by 19; the left mirrors the right's art.
 fn rotate_cluster(ui: &mut ChildSpawnerCommands, art: &GlueArt, font: &Handle<Font>, s: f32) {
     let px = |v: f32| Val::Px(v * s);
     ui.spawn((Node {
@@ -625,26 +581,10 @@ fn rotate_cluster(ui: &mut ChildSpawnerCommands, art: &GlueArt, font: &Handle<Fo
         });
 }
 
-/// **A world loading cover outranks the glue screen.**
-///
-/// The glue screens sit at [`SCREEN_Z`] = 1100 and the loading screen at 1000, so the glue draws
-/// *over* the cover. That is right for the logout direction — the world→glue swap must show the
-/// glue — and wrong for the entry one: the cover is raised in `WorldStage::Present` while we are
-/// still `CharSelect`, so the raise frame renders the character screen on top of it and the FIRST
-/// frame that can show the cover is the **state-flip** frame, which is also the frame the whole
-/// world arrives on. Measured this round: click → cover on the glass was ~100 ms, of which the
-/// flip frame alone was 60 — the character screen held, frozen, for every millisecond of it. That
-/// is the director's *"the char freezes briefly before the loading screen appears"*; 1345 fixed
-/// the same shape for the FrameXML burst and left this half standing, because nothing had ever
-/// asked which frame the cover first *drew* on.
-///
-/// Hiding the root moves the cover onto the raise frame's own render, a whole frame earlier and —
-/// far more importantly — **off** the flip frame's critical path: the cover is already drawn and
-/// presenting while that frame churns. Registered after `WorldStage::Present` so it reads *this*
-/// frame's raise; visibility propagates in `PostUpdate` and renders the same frame, exactly like
-/// the loading screen's own show/hide. Read from [`LoadingScreen::covering`] and not from
-/// [`crate::loading_screen::EntryCover`]: this is the one consumer that must react while still
-/// `CharSelect`, which is precisely the frame `EntryCover` cannot count.
+/// Hide the screen under a world loading cover. The glue at z 1100 draws over the loading screen
+/// at z 1000, and on world entry the cover rises while still `CharSelect`; hiding the root shows it
+/// on that frame, not the state-flip frame the world loads on. Runs after `WorldStage::Present` and
+/// reads `LoadingScreen::covering`, since `EntryCover` does not count this frame.
 pub(super) fn hide_under_world_cover(
     loading: Res<crate::loading_screen::LoadingScreen>,
     mut roots: Query<&mut Visibility, With<CharSelectUi>>,
@@ -671,15 +611,10 @@ pub(super) fn exit_select(
     for e in &roots {
         commands.entity(e).despawn();
     }
-    // Clear the booth + scene (entering the world or the create screen; the latter re-establishes
-    // its own the same frame) and drop any open dialog state.
     preview.look = None;
     preview.scene = None;
     dialog.close();
-    // The shared glue dialog is this screen's too while it is up (a refused character login), and
-    // it must not follow us into the world or onto the create screen — the login screen's own
-    // `exit_login` closes it on the same edge for the same reason. The tree goes with it **here**
-    // rather than being left to the driver: the driver runs on the glue screens only, so on the
-    // edges out of the glue layer there would be nobody left to despawn the root.
+    // The glue dialog must not follow into the world or the create screen. Its tree is despawned
+    // here, since its driver runs on the glue screens only.
     glue_dialog.dismiss(&mut commands);
 }
diff --git a/crates/benilla-app/src/chat_bubble.rs b/crates/benilla-app/src/chat_bubble.rs
index 0542093f..2ad3a8f7 100644
--- a/crates/benilla-app/src/chat_bubble.rs
+++ b/crates/benilla-app/src/chat_bubble.rs
@@ -1,71 +1,24 @@
-//! **Chat bubbles** — `CGChatBubbleFrame` (decision 0288's phase-9 tail, landed by decision
-//! 0598): the over-the-head speech bubble a chat line spawns, a **2-D overlay** like the V-plate
-//! ([`crate::vplates`]) and unlike the world-pass overhead *names* ([`crate::nameplates`]).
+//! Chat bubbles, `CGChatBubbleFrame`: the speech bubble a chat line spawns over the speaker, a
+//! 2-D overlay like the V-plate ([`crate::vplates`]).
 //!
-//! The pinned law, transcribed:
-//! - **Spawn** (`0x608ac0`, one caller — the SMSG_MESSAGECHAT display path): the sender GUID
-//!   typed-looks-up to a live unit or no bubble; CVar select `ChatBubbles` (party lines:
-//!   `ChatBubblesParty`); non-empty text; **no active V-plate on the unit** (`0x608adc` —
-//!   mutual exclusion both ways: a live bubble in turn suppresses the floating overhead name,
-//!   [`BubblesActive`]); the local player resolves; 3-D dist² ≤ 400 (20 yd). Self is NOT
-//!   excluded. **Replace, never queue**: a new line tears the old bubble down first.
-//! - **Lifetime** (`0x4b1810`): word-count-scaled, self-vs-other asymmetric —
-//!   `2750 + 750·(words−1)` ms for others, `1500 + 500·(words−1)` for the local player
-//!   (your own bubbles are shorter-lived); words = space/tab-run count. 250 ms linear fade-in;
-//!   at `create + duration + 250` a permanent 250 ms fade-out, then the frame recycles. The
-//!   20 yd gate re-tests **every frame**: out of range fades out *recoverable*, back in range
-//!   fades back in.
-//! - **Geometry** (`0x4b0940`/`0x4b1600`): the classic `Backdrop` construct —
-//!   `ChatBubble-Background` flat fill, `ChatBubble-Backdrop` 8-piece edge
-//!   ([`benilla_ui::script::backdrop::pieces`], the same engine geometry FrameXML backdrops
-//!   use), `ChatBubble-Tail` a separate square of side = the border-unit, TOPRIGHT on the
-//!   frame's BOTTOM + (0, border/4). Border-unit = insets = edge-size = **16/1024 of the
-//!   screen width** (`G44·16/(S·1024)`); text = `NAMEPLATE_FONT` at 0.01 gx, wrap hard-capped
-//!   at **0.2 gx**, floor 2·border-unit; the frame hugs the text layout ± **0.01 gx** on all
-//!   four sides; text colored by chatType (the 94-entry table ≡ [`default_color`]), rendered
-//!   PLAIN (`||`→`|`, color/hyperlink escapes stripped — [`sanitize`]).
-//! - **Anchor** (`0x4b0c30`): `worldZ = unit.z + attachmentHeight·modelScale + 0.7`, projected
-//!   by the plate/name projector, seated **BOTTOM at the point, growing upward** (the mirror
-//!   of the plate, which hangs down). `attachmentHeight` is `0x4b0e38 call 0x711a20` — a read of
-//!   the **MD20 header image**, i.e. the **Stand sequence CAaBox's Z extent**, a file constant
-//!   with no bone matrix anywhere in its call tree — and the scaled product is **latched** at
-//!   `bubble+0x354` behind a parity guard, so it is queried exactly **once per chat line**
-//!   ([`crate::entities::StandBoxHeight`], 1406).
-//! - **Stacking** (`0x4b1060`, the per-frame pass over ALL live bubbles — one caller, `0x4817a3`):
-//!   each bubble is its own frame and its frame LEVEL is restamped every frame from the CAMERA's
-//!   distance to the speaker. The list re-sorts farthest-first (`0x4b1360`, comparing
-//!   `[bubble+0x350]` = |cam − unit|², written at `0x4b12c0`), then a head→tail walk stamps
-//!   `SetFrameLevel(2), (3), (4)…` (`0x4b1309`). Level outranks draw layer in the client's total
-//!   order, so overlapping bubbles stack as WHOLE cards with the nearest speaker's on top —
-//!   nothing interleaves. ([`level_z`]; benilla read the bytes for this one, 1504.)
+//! - Spawn (`0x608ac0`, from the `SMSG_MESSAGECHAT` display path): the sender resolves to a live
+//!   unit, its CVar is on, the text is non-empty, the unit carries no V-plate (`0x608adc`; a live
+//!   bubble in turn hides the overhead name, [`BubblesActive`]), and the local player is within
+//!   20 yd (3-D). Self is not excluded. A new line replaces the old bubble, never queues.
+//! - Anchor (`0x4b0c30`): unit z + height × model scale + 0.7, bottom-seated, growing upward. The
+//!   height is the Stand sequence box's Z extent from the model header (`0x711a20`), not the posed
+//!   attachment the overhead name reads (`0x608640`), latched once per chat line.
+//! - Stacking (`0x4b1060`): every frame the bubbles sort farthest-first by camera distance and
+//!   take frame levels 2, 3, 4…, so whole cards stack with the nearest speaker's on top.
 //!
-//! Named divergences (all deliberate):
-//! - ~~**`ChatBubblesParty` defaults ON**~~ — **no longer a divergence (1804).** It shipped `"1"`
-//!   against the binary's `"0"` from 0598, on the director's `/p` ask; both CVars now boot at the
-//!   registrar's own values and the Chat page's row is the way back on. Same walk-back as
-//!   [`crate::vplates::VPlateMode`], whose enemy plates were the same shape of pin.
-//! - **The v1 kind set is SAY/YELL/PARTY + monster say/yell.** The byte gate is
-//!   "sender resolves", not a type whitelist, which *implies* guild/officer/whisper/emote
-//!   bubbles too — but that category claim is inferred, resting on an open wire-type remap
-//!   (`0x49a870`), and contradicts the remembered reference look, so the uncontested
-//!   set ships and a capture can widen it ([`bubble_cvar`]).
-//! - ~~**The anchor height is the posed overhead attachment**~~ — **REFUTED and removed (1406).**
-//!   This shipped as an INFERRED equivalence ("both are the head-region attachment height,
-//!   model-scaled") between the overhead-name chain `0x608640` and the bubble's `0x711a20`. They
-//!   are not equivalent, and they differ on exactly the axis that mattered: `0x608640` reads the
-//!   live posed palette and tracks the pose, `0x711a20` reads file bytes. The overhead *name*
-//!   keeps `0x608640`; the bubble now takes the Stand-box constant the bytes actually specify. It
-//!   sits **0.199 model units lower** on a human male (2.0128 vs the attachment's 2.2120) — a
-//!   deliberate, measured move toward the reference, not a regression.
-//! - **Sizes ride the plates' damped diagonal basis** ([`plate_basis`], decisions 0185/0186)
-//!   so bubble text and plate text stay the same em at every window — the same director-pinned
-//!   deviation from the unbounded byte law.
-//! - **No per-frame occlusion fade**: the client also fades a bubble whose speaker model isn't
-//!   render-visible (`0x7103d0`/`0x6704c0`); v1 re-tests distance only. Residual named in 0598.
+//! Only say, yell, party and monster say/yell bubble: the reference's gate is "sender resolves",
+//! but the wire-type remap (`0x49a870`) that would admit other kinds is untraced.
 //!
-//! (0598 briefly shipped the plate-blocks-bubble gate UN-transcribed — bubbles stacked over our
-//! then-always-on plates. 0599 restored the faithful gate and booted friendly plates OFF
-//! instead, so friendly/party bubbles have room the reference way.)
+//! Deviation: sizes ride the plates' damped diagonal basis ([`plate_basis`]), not the unbounded
+//! reference law, so bubble text and plate text keep one em at every window size.
+//!
+//! Not built: the reference also fades a bubble whose speaker's model data is not resident or whose
+//! scene-entity flag is clear (`0x7103d0`/`0x6704c0`); only distance is re-tested here.
 
 use std::collections::HashMap;
 
@@ -85,18 +38,12 @@ use crate::vplates::{device_snap, gx_px, plate_basis, text_px, VPlateSet, VPlate
 use benilla_assets::{AssetSet, WorldAssets};
 use benilla_world::view::WorldCamera;
 
-/// The two CVars (registrar `0x603280`), host side. **Registered knobs since decision 1139** —
-/// they were a pair of `const bool` from 0598 until the options window had a page to put
-/// them on, which is exactly the shape 1134 calls a row over a frozen gate.
-///
-/// **Both defaults are the binary's own** (`ChatBubbles` `"1"`, `ChatBubblesParty` `"0"`).
-/// `party` shipped ON from 0598 to 1804 on the director's `/p` ask; the row is on the Chat page,
-/// one click from where it was.
+/// The two bubble CVars (registrar `0x603280`), booting at the reference's defaults.
 #[derive(Resource)]
 pub(crate) struct BubbleConfig {
-    /// `ChatBubbles` — say/yell and their monster variants.
+    /// `ChatBubbles`: say, yell and their monster variants.
     pub(crate) all: bool,
-    /// `ChatBubblesParty` — party lines, which the client gates separately.
+    /// `ChatBubblesParty`: party lines, which the reference gates separately.
     pub(crate) party: bool,
 }
 
@@ -109,50 +56,41 @@ impl Default for BubbleConfig {
     }
 }
 
-/// The bubble art (`0x4b0940` ctor) — the shared tooltip-family textures.
+/// The bubble art (`0x4b0940`).
 const BG_TEXTURE: &str = "Interface\\Tooltips\\ChatBubble-Background";
 const EDGE_TEXTURE: &str = "Interface\\Tooltips\\ChatBubble-Backdrop";
 const TAIL_TEXTURE: &str = "Interface\\Tooltips\\ChatBubble-Tail";
 
-/// The 0.7 yd lift over the attachment height (`[0x7ffd7c]` = 0.699999988).
+/// The 0.7 yd lift over the anchor height (`[0x7ffd7c]`).
 const LIFT: f32 = 0.7;
-/// The spawn + per-frame range gate: dist² ≤ 400 (20 yd, `[0x806798]` — same as the plates).
+/// The spawn and per-frame range gate, 20 yd squared (`[0x806798]`, the plates' too).
 const MAX_DIST_SQ: f32 = 400.0;
-/// The fade ramps: 250 ms linear, in and out (`0x4b0ea0`/`0x4b0ee0`).
+/// The 250 ms linear fade, in and out (`0x4b0ea0`/`0x4b0ee0`).
 const FADE_SECS: f32 = 0.25;
-/// `NAMEPLATE_FONT` at 0.01 gx — the same em law as the plate name.
+/// `NAMEPLATE_FONT` at 0.01 gx, the plate name's em.
 const TEXT_H: f32 = 0.01;
-/// The auto-fit body margin: text layout ± 0.01 gx on all four sides (`0x3c23d70a`).
+/// The body margin around the text layout, all four sides (`0x3c23d70a`).
 const MARGIN: f32 = 0.01;
 /// The text wrap hard cap, gx (`[0x80679c]` = 0.2).
 const WRAP_W: f32 = 0.2;
-/// Border-unit = edge-size = insets = tail side: 16/1024 of the screen WIDTH
-/// (`G44·16.0/(S·1024.0)` — G44/S nets the width in the diagonal gx basis).
+/// The border unit (edge size, insets, tail side): 16/1024 of the screen width.
 const BORDER_FRAC: f32 = 16.0 / 1024.0;
 
-/// Paint order **inside one bubble's frame level** — the four pieces, back→front. The tail draws
-/// over the frame's bottom edge piece: its art carries the border lines that make the seam read
-/// continuous, and the reference gets the same result from its own layer key (the tail is an
-/// ARTWORK texture, the text an ARTWORK font string, and a batch drains every texture before
-/// every font string — `0x76fb00`).
+/// Paint order inside one bubble's level: the tail covers the bottom edge piece and the text draws
+/// last, as the reference's batch drains textures before font strings (`0x76fb00`).
 const Z_BG: u64 = 0;
 const Z_EDGE: u64 = 1;
 const Z_TAIL: u64 = 2;
 const Z_TEXT: u64 = 3;
 
-/// The z base for the bubble at `rank` in this frame's farthest→nearest order — the port of the
-/// reference's per-frame `SetFrameLevel(2 + i)` walk (`0x4b12d5`–`0x4b1312`, decision 1504). One
-/// LEVEL per bubble, [`overlay_z::BUBBLE_STRIDE`] keys wide, so a whole bubble stacks over a whole
-/// bubble; the whole band stays under the V-plates ([`crate::ui_pass::overlay_z`]).
+/// The z base for the bubble at `rank`, farthest first: the reference's per-frame
+/// `SetFrameLevel(2 + i)` walk (`0x4b12d5`-`0x4b1312`), one level per bubble, under the V-plates.
 fn level_z(rank: usize) -> u64 {
     let level = (rank as u64).min(overlay_z::BUBBLE_MAX_LEVEL);
     overlay_z::BUBBLE + level * overlay_z::BUBBLE_STRIDE
 }
 
-/// Which CVar gates this chat kind's bubble — `None` = the kind never bubbles in v1.
-/// PARTY selects `ChatBubblesParty`, every other bubbling kind `ChatBubbles` (`0x608b0d`).
-/// Guild/officer/whisper/emote are structurally implied by the byte gate but INFERRED on an
-/// OPEN remap (module doc) — out until a capture confirms.
+/// The CVar gating this kind's bubble (`0x608b0d`); `None` for a kind that does not bubble.
 fn bubble_cvar(kind: ChatEventKind, cfg: &BubbleConfig) -> Option<bool> {
     use ChatEventKind as K;
     match kind {
@@ -162,7 +100,7 @@ fn bubble_cvar(kind: ChatEventKind, cfg: &BubbleConfig) -> Option<bool> {
     }
 }
 
-/// The space/tab-run word counter (`0x4b1810`): maximal runs of non-space/tab characters.
+/// The word count (`0x4b1810`): maximal runs of characters other than space and tab.
 fn word_count(text: &str) -> u32 {
     let mut words = 0u32;
     let mut in_word = false;
@@ -176,8 +114,8 @@ fn word_count(text: &str) -> u32 {
     words
 }
 
-/// The duration law (`0x4b1810`): `base + perWord·(words−1)` ms — 2750/750 for someone else,
-/// 1500/500 for the local player (your own bubbles are shorter-lived). Empty → 0.
+/// The lifetime (`0x4b1810`): `base + perWord·(words−1)` ms, 2750/750 for others and 1500/500
+/// for the local player.
 fn duration_secs(words: u32, is_self: bool) -> f32 {
     if words == 0 {
         return 0.0;
@@ -186,10 +124,8 @@ fn duration_secs(words: u32, is_self: bool) -> f32 {
     (base + per * (words - 1)) as f32 / 1000.0
 }
 
-/// The bubble-text sanitize: `||` stays an escaped literal pipe, `|cAARRGGBB`/`|r` color
-/// escapes and the `|H…|h`/`|h` hyperlink wrappers strip (their display text stays) — bubble
-/// text is always plain, colored solely by chatType. Output remains in ESCAPED form (literal
-/// pipes as `||`) because the glyph layout's own markup parser consumes it downstream.
+/// Bubble text is plain, coloured only by chat type: colour escapes and hyperlink wrappers strip
+/// (their display text stays), and `||` stays escaped for the glyph layout's markup parser.
 fn sanitize(text: &str) -> String {
     let b = text.as_bytes();
     let mut out = String::with_capacity(text.len());
@@ -212,8 +148,7 @@ fn sanitize(text: &str) -> String {
             Some(b'c') | Some(b'C') if i + 10 <= b.len() => i += 10,
             Some(b'r') | Some(b'R') => i += 2,
             Some(b'H') => {
-                // Skip the opener through its `|h`; the display text then flows until the
-                // closing `|h`, which the arm below drops.
+                // Skip the opener through its `|h`; the closing `|h` drops in the arm below.
                 i += 2;
                 while i < b.len() && !(b[i] == b'|' && b.get(i + 1) == Some(&b'h')) {
                     i += 1;
@@ -221,7 +156,7 @@ fn sanitize(text: &str) -> String {
                 i += 2;
             }
             Some(b'h') => i += 2,
-            // A dangling or unknown escape renders as a literal pipe + the rest.
+            // A dangling or unknown escape renders as a literal pipe.
             _ => {
                 out.push_str("||");
                 i += 1;
@@ -231,8 +166,7 @@ fn sanitize(text: &str) -> String {
     out
 }
 
-/// The bleed inset for one border piece, `Vec2::ZERO` texels meaning "art size unknown, leave the
-/// UVs alone" (a bare test app with no patch chain).
+/// The bleed inset for one border piece; zero texels (no patch chain) leaves the UVs alone.
 fn pieces_inset(uvs: [[f32; 2]; 4], texels: Vec2) -> [[f32; 2]; 4] {
     if texels.x <= 0.0 || texels.y <= 0.0 {
         return uvs;
@@ -240,15 +174,8 @@ fn pieces_inset(uvs: [[f32; 2]; 4], texels: Vec2) -> [[f32; 2]; 4] {
     inset_atlas_bleed(uvs, texels.x, texels.y)
 }
 
-/// The frame's bottom-left origin for a projected seat: BOTTOM-CENTER on the seat, then both
-/// coordinates snapped onto the **device** pixel grid ([`device_snap`], the plate's law).
-///
-/// Split out so the snap law is nameable and pinned. It shipped as a plain logical `round()`,
-/// which is 1 device pixel only at scale 1: on the 2× display we play on it stepped the bubble
-/// two physical pixels per axis over a continuously-sliding world, and at a fractional scale
-/// (1.25/1.5) it never landed on a texel boundary at all — so it paid the stepping without even
-/// buying the crispness it exists for. Same bug, same fix as the plate (0188's snap → the plate's
-/// device grid); the bubble was the site that never got it (1398).
+/// The frame's bottom-left origin, bottom-center on the seat. Deviation: snapped onto the device
+/// pixel grid ([`device_snap`]) so the border art blits 1:1; the reference seats it fractionally.
 fn seat_origin(seat: Vec2, w: f32, scale: f32) -> Vec2 {
     Vec2::new(
         device_snap(seat.x - w * 0.5, scale),
@@ -256,23 +183,18 @@ fn seat_origin(seat: Vec2, w: f32, scale: f32) -> Vec2 {
     )
 }
 
-/// The border-unit in logical px for this viewport: 16/1024 of the screen width, carried
-/// through the damped size basis (so it shrinks in step with plate/text sizes past the knee).
+/// The border unit in logical px: 16/1024 of the screen width, in the damped size basis.
 fn border_px(viewport: Vec2, basis: f32) -> f32 {
     let width_gx = viewport.x / viewport.length();
     gx_px(width_gx * BORDER_FRAC, basis).max(1.0)
 }
 
-/// The bubble-spawn requests this frame — fed by the chat feed's wire arm (the reference
-/// spawns in the SMSG display path, the same moment the line routes) and drained by
-/// [`drive_bubbles`]. Push-side filtered so guild/system spam never queues strings.
+/// This frame's bubble-spawn requests, pushed as the chat line routes.
 #[derive(Resource, Default)]
 pub(crate) struct BubbleQueue(Vec<(u64, ChatEventKind, String)>);
 
 impl BubbleQueue {
-    /// Queue a routed wire line for a bubble. Drops non-bubbling kinds, disabled CVars, and
-    /// senderless lines here; the live-unit/range/plate gates run in the driver. The switch is
-    /// read at PUSH time, so a Chat-page click takes the very next line either way.
+    /// Queue a routed line; kind, CVar and sender filter here, unit, plate and range in the driver.
     pub(crate) fn push(
         &mut self,
         cfg: &BubbleConfig,
@@ -299,45 +221,37 @@ impl BubbleQueue {
     }
 }
 
-/// One live bubble (the `CGChatBubbleFrame` + its `CGUnit+0xe64` handle, folded together).
+/// One live bubble: the `CGChatBubbleFrame` and its `CGUnit+0xe64` handle.
 struct Bubble {
-    /// Sanitized display text ([`sanitize`] — plain, escapes stripped).
+    /// The [`sanitize`]d display text.
     text: String,
-    /// The chatType color (the 94-entry table), client-space sRGB 0..1.
+    /// The chat-type colour (the 94-entry table), sRGB 0..1.
     color: [f32; 3],
     /// `Time::elapsed_secs` at spawn.
     born: f32,
-    /// The steady window past the fade-in ([`duration_secs`]).
+    /// The steady window after the fade-in ([`duration_secs`]).
     duration: f32,
-    /// The **latched** anchor height above the speaker's feet: the Stand box's Z extent
-    /// ([`crate::entities::StandBoxHeight`]) already multiplied by the unit's model scale, queried
-    /// ONCE here and never re-read — the reference caches exactly this product at `bubble+0x354`
-    /// behind a parity guard, so it is one query per chat line (1406).
+    /// Stand-box height × model scale, latched at spawn as the reference does (`bubble+0x354`).
     lift: f32,
-    /// Current fade alpha 0..1 — ramped 250 ms linear toward the eligibility verdict.
+    /// Fade alpha 0..1, ramped toward the eligibility verdict.
     alpha: f32,
 }
 
-/// The live bubbles, keyed by speaker guid (a unit carries at most one — replace, never queue).
+/// The live bubbles by speaker guid, at most one per unit.
 #[derive(Resource, Default)]
 struct Bubbles(HashMap<u64, Bubble>);
 
-/// The units carrying a live bubble this frame — the `ShouldShowName` exclusivity verdict the
-/// overhead-name driver reads (`+0xe64` ≠ 0 suppresses the floating name), the mirror of
-/// [`VPlates`].
+/// Units with a live bubble this frame, whose overhead name is suppressed (`+0xe64` ≠ 0).
 #[derive(Resource, Default)]
 pub(crate) struct BubblesActive(pub(crate) EntityHashSet);
 
-/// The bubble art, warmed at boot like the plate art (a first bubble must not draw texture-less).
-/// The edge strip needs REPEAT addressing (its runs tile UVs past 1); bg and tail clamp.
+/// The bubble art, loaded at boot. The edge strip tiles UVs past 1 (repeat); bg and tail clamp.
 #[derive(Resource)]
 struct BubbleArt {
     bg: Handle<Image>,
     edge: Handle<Image>,
     tail: Handle<Image>,
-    /// The edge atlas's size in texels, for the half-texel bleed inset
-    /// ([`benilla_ui::script::backdrop::inset_atlas_bleed`] — 1402). Stamped at load because the
-    /// draw has no `Assets<Image>` and this never changes.
+    /// The edge atlas's size in texels, for the half-texel bleed inset.
     edge_texels: Vec2,
 }
 
@@ -347,7 +261,7 @@ fn load_bubble_art(
     mut images: ResMut<Assets<Image>>,
 ) {
     let Some(mut assets) = assets else {
-        return; // no game data (bare test app) — drive_bubbles tolerates the missing resource
+        return; // no game data (a bare test app); `drive_bubbles` tolerates the missing art
     };
     let bg = assets.sprite_texture(BG_TEXTURE, &mut images);
     let edge = assets.sprite_texture_tiled(EDGE_TEXTURE, &mut images);
@@ -368,12 +282,8 @@ fn load_bubble_art(
     });
 }
 
-/// Spawn, tick, and draw, every frame: drain the queue through the spawn gate (`0x608ac0`),
-/// ramp each live bubble's fade against its lifetime + the per-frame 20 yd re-test
-/// (`0x4b0c30`), publish the name-suppression verdict, and append the draw list — backdrop
-/// pieces, tail, wrapped chatType-colored text — bottom-seated on the projected anchor.
-/// Runs after [`VPlateSet`] (the spawn gate reads this frame's plate verdict), inside the
-/// [`UiQuadAppend`] window.
+/// Every frame: drain the queue through the spawn gate (`0x608ac0`), ramp each bubble's fade
+/// against its lifetime and the 20 yd re-test (`0x4b0c30`), publish [`BubblesActive`], and draw.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 fn drive_bubbles(
     mut queue: ResMut<BubbleQueue>,
@@ -387,26 +297,20 @@ fn drive_bubbles(
     mut atlas: Option<ResMut<UiFontAtlas>>,
     mut quads: ResMut<UiQuads>,
     art: Option<Res<BubbleArt>>,
-    // The latched anchor height, read once per bubble at spawn ([`StandBoxHeight`]).
     heights: Query<&StandBoxHeight>,
     time: Res<Time>,
-    // The device scale, for the seat's pixel snap ([`device_snap`]).
+    // The device scale, for the seat's pixel snap.
     window: Query<&Window, With<bevy::window::PrimaryWindow>>,
 ) {
     active.0.clear();
     let now = time.elapsed_secs();
     let step = time.delta_secs() / FADE_SECS;
     let self_tf = self_q.single().ok();
-    // The typed sender lookup (`0x468460`): guid → live unit. Linear over the streamed set,
-    // like the plate walk — both populations are 20 yd-bounded and small.
+    // The typed sender lookup (`0x468460`), a linear scan of the small streamed set.
     let find = |guid: u64| units.iter().find(|(_, g, _)| g.0 == guid);
 
     // ── The spawn/replace gate (`0x608ac0`) ─────────────────────────────────────────────────
-    // Every arm below reports its REFUSAL under the `bub` tag. A bubble that never appears used to
-    // be a silent five-way question — no text, no unit, a plate in the way, no local player, out of
-    // range — with nothing in any log to separate them, and the draw trace beside it says nothing
-    // because the draw never runs. One line per refusal is the difference between reading the
-    // answer and bisecting for it.
+    // Every refusal is traced under the `bub` tag.
     let refuse = |why: &str, guid: u64| {
         if benilla_assets::trace::enabled_for("bub") {
             benilla_assets::trace::line("bub", &format!("refuse guid={guid:#x} {why}"));
@@ -417,37 +321,32 @@ fn drive_bubbles(
         let words = word_count(&text);
         if words == 0 {
             refuse("empty-text", guid);
-            continue; // empty text → duration 0 → no bubble
+            continue; // no words, no lifetime, no bubble
         }
         let Some((entity, _, tf)) = find(guid) else {
             refuse("sender-not-a-live-unit", guid);
-            continue; // sender not resolvable to a live unit → NO bubble
+            continue;
         };
-        // An active V-plate blocks bubble creation (`0x608adc` — the mutual exclusion,
-        // faithful; restored by 0599 after 0598 briefly stacked them). Friendly plates boot
-        // OFF (0599's other half), so friendly/party bubbles have room; a plated hostile
-        // yelling shows no bubble, exactly like the reference with plates toggled on.
+        // An active V-plate blocks the bubble (`0x608adc`): a plated hostile's yell shows none.
         if vplates.0.contains(&entity) {
             refuse("v-plate-on-speaker", guid);
             continue;
         }
         let Some(self_tf) = self_tf else {
             refuse("no-local-player", guid);
-            continue; // the local player must resolve
+            continue;
         };
         let d2 = (tf.translation - self_tf.translation).length_squared();
         if d2 > MAX_DIST_SQ {
             refuse(&format!("out-of-range dist={:.1}yd", d2.sqrt()), guid);
-            continue; // 20 yd at spawn
+            continue;
         }
         let is_self = self_guid.0 == Some(guid);
         let c = default_color(kind);
-        // The one-time attachment query (`0x4b0e38 call 0x711a20`, scaled by `[unit+0x90]`): a file
-        // constant × this unit's model scale. A speaker with no bounds reads 0 and the bubble sits
-        // at the feet + 0.7, which is the reference's own degenerate for a bounds-less model.
+        // The one-time height query (`0x4b0e38` calling `0x711a20`, scaled by `[unit+0x90]`). A
+        // model with no bounds reads 0 and the bubble sits 0.7 above the feet, as in the reference.
         let lift = heights.get(entity).map_or(0.0, |h| h.0) * tf.scale.y;
-        // Replace, never queue: the insert tears the old bubble down (`0x608c00`) and the
-        // fresh one fades in from 0.
+        // Replace, never queue (`0x608c00`): the fresh bubble fades in from 0.
         bubbles.0.insert(
             guid,
             Bubble {
@@ -477,20 +376,18 @@ fn drive_bubbles(
     let mut pending: Vec<Pending> = Vec::new();
     for (guid, b) in bubbles.0.iter_mut() {
         let Some((entity, _, tf)) = find(*guid) else {
-            dead.push(*guid); // the speaker despawned — the unit teardown takes its bubble
+            dead.push(*guid); // the speaker despawned, and its bubble with it
             continue;
         };
         if now >= b.born + b.duration + FADE_SECS {
-            // The permanent fade-out (`0x4b0ee0(1)`) — at 0 the frame recycles.
+            // The permanent fade-out (`0x4b0ee0(1)`); at 0 the frame recycles.
             b.alpha -= step;
             if b.alpha <= 0.0 {
                 dead.push(*guid);
                 continue;
             }
         } else {
-            // Per-frame re-eligibility: the same 20 yd gate, recoverable — out of range fades
-            // out, back in range fades back in. (The client also fades on the speaker model's
-            // render visibility — the v1 residual, module doc.)
+            // The 20 yd gate, re-tested every frame: out of range fades out, back in fades in.
             let eligible = self_tf
                 .is_some_and(|s| (tf.translation - s.translation).length_squared() <= MAX_DIST_SQ);
             b.alpha = if eligible {
@@ -499,28 +396,19 @@ fn drive_bubbles(
                 (b.alpha - step).max(0.0)
             };
         }
-        // The live handle (`+0xe64` ≠ 0): the name suppression holds while the bubble EXISTS,
-        // faded or not.
+        // The name stays suppressed while the bubble exists, faded or not (`+0xe64` ≠ 0).
         active.0.insert(entity);
         if b.alpha <= 0.0 {
             continue;
         }
-        // No camera/atlas/art — lifetimes still tick, nothing draws.
+        // No camera, atlas or art: lifetimes tick, nothing draws.
         let (Some((cam, cam_pose)), true) = (cam, atlas.is_some() && art.is_some()) else {
             continue;
         };
-        // World anchor (`0x4b0c30`): the unit's position, Z lifted by the LATCHED Stand-box height
-        // + 0.7 yd — seated BOTTOM at the projected point, growing upward. Every term is this
-        // frame's `Transform` or a constant, so there is no pose to read and no clock to get wrong.
-        // A point behind the camera draws nothing (state kept — it fades back the moment it
-        // projects again).
+        // The anchor (`0x4b0c30`), from this frame's `Transform` and constants only. A seat behind
+        // the camera draws nothing and keeps its state.
         let seat_world = tf.translation + Vec3::Y * (b.lift + LIFT);
         let cam_tf = GlobalTransform::from(*cam_pose);
-        // The SEVENTH silent cause, and the one that cost the most to find: a seat behind the
-        // camera fails to project and the bubble draws nothing — alive, ticking, invisible, and
-        // (before this) invisible to the trace too, because every `bub` line is written by the
-        // draw. A probe whose camera had been restored pitched into the ground therefore read as
-        // "bubbles are broken" for six runs (1402). Reported like the spawn gate's refusals.
         let Ok(seat) = cam.world_to_viewport(&cam_tf, seat_world) else {
             refuse("not-on-screen (behind the camera)", *guid);
             continue;
@@ -529,15 +417,13 @@ fn drive_bubbles(
             refuse("no-viewport", *guid);
             continue;
         };
-        // Seated and projected here, DRAWN below: the level a bubble draws at is a property of
-        // the whole live set, not of this bubble ([`level_z`]), so the draw waits for the sort.
+        // Drawn after the sort: a bubble's level depends on the whole live set ([`level_z`]).
         pending.push(Pending {
             guid: *guid,
             entity,
             seat,
             viewport,
-            // The sort key (`0x4b1251`–`0x4b12c0`): |camera − speaker|², the CAMERA's distance,
-            // not the local player's (which is the eligibility gate's, above).
+            // The sort key (`0x4b1251`-`0x4b12c0`): the camera's distance, not the player's.
             cam_dist_sq: cam_pose.translation.distance_squared(tf.translation),
             anchor: seat_world,
             unit_pos: tf.translation,
@@ -548,15 +434,11 @@ fn drive_bubbles(
     }
 
     // ── The frame-level pass (`0x4b12d5`–`0x4b1312`) ─────────────────────────────────────────
-    // The reference re-sorts its live-bubble list by camera distance, FARTHEST at the head, and
-    // then walks head→tail stamping `SetFrameLevel(2), (3), (4)…` — so every bubble owns a frame
-    // level of its own and the NEAREST speaker's bubble ends up on top. (It only re-sorts when
-    // the camera moved or a bubble is dirty; the stamping walk runs unconditionally. Sorting
-    // every frame is the same list with no state to keep.) Ties break on guid so an exact
-    // distance tie can't flip the stack frame to frame.
+    // Sorted farthest first (`0x4b1360`), levels stamped head to tail (`0x4b1309`). The reference
+    // re-sorts only on a change; sorting every frame gives the same list.
     stack_sort(&mut pending);
     let (Some((_, cam_pose)), Some(atlas), Some(art)) = (cam, atlas.as_deref_mut(), art) else {
-        return; // nothing reached `pending` either — the same gate refused it in the tick
+        return; // the tick's same gate kept `pending` empty
     };
     for (rank, p) in pending.iter().enumerate() {
         let Some(b) = bubbles.0.get(&p.guid) else {
@@ -580,10 +462,8 @@ fn drive_bubbles(
     }
 }
 
-/// The stack order: **farthest camera distance first**, so the enumeration index that follows is
-/// the reference's frame level and the nearest speaker's bubble draws last (on top). Ties break on
-/// guid — the reference's list keeps its previous order across an exact tie because it re-inserts
-/// only ahead of a *strictly* closer node, and a `HashMap` walk has no such memory.
+/// Farthest camera distance first, so the index is the frame level. Ties break on guid, as the
+/// reference keeps its order across an exact tie and a `HashMap` walk cannot.
 fn stack_sort(pending: &mut [Pending]) {
     pending.sort_by(|a, b| {
         b.cam_dist_sq
@@ -592,21 +472,20 @@ fn stack_sort(pending: &mut [Pending]) {
     });
 }
 
-/// One bubble that passed the tick and projected on screen, waiting for the frame-level sort.
+/// One projected bubble awaiting the frame-level sort.
 struct Pending {
     guid: u64,
     entity: Entity,
     seat: Vec2,
     viewport: Vec2,
-    /// |camera − speaker|², the reference's own sort key (`[bubble+0x350]`).
+    /// |camera − speaker|², the reference's sort key (`[bubble+0x350]`).
     cam_dist_sq: f32,
-    /// The world seat and the speaker's position — the `bub` jitter trace's decomposition.
+    /// The world seat and the speaker's position, for the `bub` trace.
     anchor: Vec3,
     unit_pos: Vec3,
 }
 
-/// Append one bubble's draw list: the Backdrop pieces (bg fill inset by the border-unit +
-/// the 8-piece edge), the tail square, and the wrapped, centered, chatType-colored text.
+/// Append one bubble's draw list: the backdrop pieces, the tail and the wrapped, centered text.
 fn draw_bubble(
     atlas: &mut UiFontAtlas,
     quads: &mut UiQuads,
@@ -616,35 +495,31 @@ fn draw_bubble(
     viewport: Vec2,
     scale: f32,
     trace: bool,
-    // The `bub` jitter-decomposition trace's inputs — see the tail of this function.
+    // The `bub` trace's inputs.
     entity: Entity,
     anchor: Vec3,
     unit_pos: Vec3,
     cam_pose: &Transform,
-    // This bubble's frame level, flattened to a z base ([`level_z`]).
+    // This bubble's frame level as a z base.
     z: u64,
 ) {
     let basis = plate_basis(viewport);
     let border = border_px(viewport, basis);
     let margin = gx_px(MARGIN, basis);
 
-    // The exact window-derived em, laid out AT that em. This used to shape at the nearest baked
-    // ladder size and rescale the finished quads by `px/shaped` around the box centre — a bubble's
-    // size is derived from the viewport and so lands on nothing round, which meant every bubble on
-    // screen was a resampled bitmap. Since decision 1342 the raster follows the request.
+    // Shaped at the exact window-derived em, so the glyphs are never a rescaled bitmap.
     let px = text_px(TEXT_H, basis);
     if px <= 0.0 {
         return;
     }
     let mut e = atlas.lock();
     let spec = FontSpec {
-        path: None, // NAMEPLATE_FONT — Friz Quadrata, the engine's default face
+        path: None, // `NAMEPLATE_FONT`: Friz Quadrata, the engine's default face
         height: Some(px),
         outline: Outline::None,
         alpha_gradient: None,
     };
-    // The wrap law (`0x4b1600` tail): single-line width > 0.2 gx → hard-cap (forces wrap);
-    // else max(measured, 2·border-unit).
+    // The wrap law (`0x4b1600`): wider than 0.2 gx wraps at the cap, else max(width, 2 borders).
     let cap = gx_px(WRAP_W, basis);
     let floor = 2.0 * border;
     let (line_w, _) = measure_text(&mut e, &b.text, None, spec);
@@ -652,14 +527,7 @@ fn draw_bubble(
     let (_, box_h) = measure_text(&mut e, &b.text, Some(box_w), spec);
     let (text_w, text_h) = (box_w.ceil(), box_h.ceil());
 
-    // The auto-fit body: the frame hugs the text layout ± the flat margin; BOTTOM-center on
-    // the seat, growing upward. Snapped onto the **device** pixel grid (the plate divergence —
-    // a fractional corner bilinear-smears the border art), which is [`device_snap`], the plate's
-    // own law, not the plain logical `round()` this shipped with: the quad lane is logical px, so
-    // rounding there quantized the bubble to `scale_factor` PHYSICAL pixels — two pixels of
-    // stepping per axis on the 2× display we play on, against a world sliding continuously
-    // underneath, and no texel alignment at all at a fractional scale. It is the same bug the
-    // plate was carrying and the same fix; the bubble is simply the site that never got it (1398).
+    // The frame hugs the text layout plus the margin, bottom-center on the seat, growing upward.
     let w = text_w + 2.0 * margin;
     let h = text_h + 2.0 * margin;
     let origin = seat_origin(seat, w, scale);
@@ -667,8 +535,8 @@ fn draw_bubble(
     let frame = Rect::new(left, bottom - h, left + w, bottom);
     let alpha = b.alpha;
 
-    // The Backdrop construct (`0x4b0a35 → 0x76a5d0`): one value feeds the 4 insets and both
-    // edge-size fields. The engine's `pieces` speaks y-up — negate y across the seam.
+    // The backdrop (`0x4b0a35` into `0x76a5d0`): one value feeds the four insets and both
+    // edge-size fields. `pieces` is y-up, so y negates across the seam.
     let bd = Backdrop {
         bg_file: Some(BG_TEXTURE.to_string()),
         edge_file: Some(EDGE_TEXTURE.to_string()),
@@ -686,18 +554,15 @@ fn draw_bubble(
     };
     let up = GxRect::new(-frame.max.y, frame.min.x, -frame.min.y, frame.max.x);
     for p in pieces(up, &bd) {
-        // Every bubble piece is axis-aligned (equal insets make the BR-inset quirk vacuous):
-        // corners [TL,TR,BR,BL] y-up → a y-down rect from TL/BR, UVs riding their corners.
+        // Equal insets keep every piece axis-aligned: a y-down rect from its TL and BR corners.
         let rect = Rect::new(
             p.corners[0][0],
             -p.corners[0][1],
             p.corners[2][0],
             -p.corners[2][1],
         );
-        // The border pieces share one 256×32 atlas; without the half-texel inset, bilinear at each
-        // piece's own edge blends in the neighbour's first column — and the column beside the TOP
-        // slice is WHITE at alpha 0, which is the pale line that ran through the bubble (1402). The
-        // bg is its own texture and keeps its UVs.
+        // The border pieces share one 256×32 atlas: without the half-texel inset, bilinear blends
+        // in the neighbour's column, white at alpha 0 beside the top slice, a pale line.
         let uvs = if p.is_bg {
             p.uvs
         } else {
@@ -716,8 +581,7 @@ fn draw_bubble(
             ..default()
         });
     }
-    // The tail (`0x4b0af1`): a border-unit square, TOPRIGHT on the frame's BOTTOM lifted
-    // border/4 INTO the body — the overlap that makes the seam read continuous.
+    // The tail (`0x4b0af1`): a border-unit square, TOPRIGHT on the bottom lifted border/4.
     let tail_top = frame.max.y - border * 0.25;
     let cx = (frame.min.x + frame.max.x) * 0.5;
     quads.overlays.push(UiQuad {
@@ -728,8 +592,7 @@ fn draw_bubble(
         color: [1.0, 1.0, 1.0, alpha],
         ..default()
     });
-    // The text: centered in the margin box, wrapped at the cap. No rescale pass — the glyphs came
-    // out of the cache at this em.
+    // The text, centered in the margin box and wrapped at the cap.
     let center = Vec2::new(cx, (frame.min.y + frame.max.y) * 0.5);
     let mut text_quads = layout_text_quads(
         &mut e,
@@ -742,12 +605,7 @@ fn draw_bubble(
         },
         z + Z_TEXT,
         spec,
-        // The bubble frame seats on the DEVICE pixel grid ([`device_snap`], 1398) and slides with
-        // the speaker; its text must be rigid against it. Snapping the block top on the UI's
-        // logical grid instead made the text pop a whole px every second step the frame took —
-        // the V-plate's defect at the sibling site, exactly as 1398 found the snap itself missing
-        // here. Unlike the plate this rect is real (a margin box), so the degenerate-rect
-        // carve-out never covered it.
+        // Exact, so the text stays rigid against the device-snapped frame.
         TextSeat::Exact,
     );
     drop(e);
@@ -757,19 +615,9 @@ fn draw_bubble(
             frame.min.x, frame.min.y, frame.max.x, frame.max.y, b.text
         );
     }
-    // **The jitter decomposition** (`WOW_MOVE_TRACE` tag `bub`, one line per bubble per frame) —
-    // the plate's `vpl` line ([`crate::vplates`]) for the bubble: the seat's world point, the
-    // camera pose that projected it, the raw projected seat, and the snapped frame origin. "The
-    // bubble is jittery when running" is then attributed from numbers rather than from the eye —
-    // a moving anchor, a noisy camera, or the pixel snap. Since 1406 `anchor=` and `pos=` differ by
-    // a LATCHED constant on Y and by nothing at all on X/Z, so any wobble between them is a defect
-    // by construction. (Through 1398 they were read on different clocks — the anchor computed
-    // through a `GlobalTransform` Bevy propagates in `PostUpdate`, i.e. last frame's — and their
-    // difference measured exactly that lag: the term 1341 cleared for the plate by measuring a unit
-    // that was STANDING STILL, where it is identically zero. Dropping the pose read removes the
-    // seam rather than correcting it.) It rides the shared tag-filtered trace and NOT the `WOW_BUBBLE_TRACE`
-    // eprintln beside it, whose unbuffered writes would distort the frame pacing the question is
-    // about (the 0880 lesson, the same reason `vpl` lives there).
+    // The jitter decomposition (`WOW_MOVE_TRACE` tag `bub`): `anchor=` and `pos=` differ by a
+    // latched constant on Y only, so a wobble between them is a defect. Not the eprintln above,
+    // whose unbuffered writes would distort frame pacing.
     if benilla_assets::trace::enabled_for("bub") {
         let (cp, cf) = (cam_pose.translation, cam_pose.forward());
         benilla_assets::trace::line(
@@ -803,14 +651,13 @@ fn draw_bubble(
     quads.overlays.append(&mut text_quads);
 }
 
-/// The bubble stage — [`crate::nameplates`] orders after it (the bubble/name exclusion reads
-/// [`BubblesActive`]), exactly as it orders after [`VPlateSet`] for the plate verdict.
+/// The bubble stage; [`crate::nameplates`] orders after it to read [`BubblesActive`].
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub(crate) struct BubbleSet;
 
 pub(crate) struct ChatBubblePlugin;
 
-/// The two bubble switches' change callback (1139, 2303): flags, like every other pair.
+/// The two bubble CVars' change callback.
 pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut bubbles: ResMut<BubbleConfig>) {
     match ev.key().as_str() {
         "chatbubbles" => bubbles.all = ev.flag(),
@@ -827,9 +674,7 @@ impl Plugin for ChatBubblePlugin {
             .init_resource::<Bubbles>()
             .init_resource::<BubblesActive>()
             .add_systems(Startup, load_bubble_art.after(AssetSet::Open))
-            // After the V-plate drive (the spawn gate reads this frame's plate verdict),
-            // inside the UI-quad append window; the name driver orders after [`BubbleSet`]
-            // (the bubble/name exclusion reads this frame's verdict).
+            // After the V-plate drive, whose verdict the spawn gate reads.
             .add_systems(
                 Update,
                 drive_bubbles
@@ -844,7 +689,7 @@ impl Plugin for ChatBubblePlugin {
 mod tests {
     use super::*;
 
-    /// The word counter is a space/tab-run law — not Unicode whitespace, not collapse-free.
+    /// Space and tab runs only, not Unicode whitespace.
     #[test]
     fn word_count_is_the_space_tab_run_law() {
         assert_eq!(word_count(""), 0);
@@ -854,7 +699,6 @@ mod tests {
         assert_eq!(word_count("a\u{a0}b"), 1, "NBSP is not a separator");
     }
 
-    /// The duration bytes: others 2750 + 750·(n−1), self 1500 + 500·(n−1), empty 0.
     #[test]
     fn duration_matches_the_byte_law() {
         assert_eq!(duration_secs(0, false), 0.0);
@@ -864,8 +708,6 @@ mod tests {
         assert_eq!(duration_secs(3, true), 2.5);
     }
 
-    /// Bubble text is plain: color/hyperlink escapes strip (display text stays), `||` stays
-    /// escaped for the downstream markup parser, a dangling pipe renders literally.
     #[test]
     fn sanitize_strips_escapes_keeps_display_text() {
         assert_eq!(sanitize("hello"), "hello");
@@ -879,17 +721,7 @@ mod tests {
         assert_eq!(sanitize("|x odd"), "||x odd");
     }
 
-    /// The v1 kind set: say/yell + monster say/yell on `ChatBubbles`, party on
-    /// `ChatBubblesParty`; everything else out pending the OPEN remap capture. And the two
-    /// switches are genuinely separate: the client gates party lines on their own CVar, so
-    /// turning one off leaves the other bubbling.
-    ///
-    /// The sweep runs on a config with **both switches planted on**, which is not what a fresh
-    /// client boots at: `ChatBubblesParty` shipped `"1"` from 0598's `/p` ask until 1804 put both
-    /// defaults back on the binary's (`ChatBubbles` `"1"`, `ChatBubblesParty` `"0"`). Planted,
-    /// because the question here is which *kinds* the gate admits, and a kind whose switch is off
-    /// cannot answer it. The shipped pair is asserted below, where it is exactly the
-    /// party-off half of the independence check.
+    /// Both switches on, since a kind whose switch is off cannot show whether the gate admits it.
     #[test]
     fn the_kind_set_is_the_uncontested_v1() {
         use ChatEventKind as K;
@@ -918,8 +750,7 @@ mod tests {
             assert_eq!(bubble_cvar(k, &on), None, "{k:?} must not bubble in v1");
         }
 
-        // Party off with say on — which is the SHIPPED pair since 1804, so this half of the
-        // independence check is [`BubbleConfig::default`] itself and pins the boot state too.
+        // Party off with say on is the default pair, so this also pins the boot state.
         let no_party = BubbleConfig::default();
         assert!(no_party.all && !no_party.party, "the shipped pair");
         assert_eq!(
@@ -944,11 +775,7 @@ mod tests {
         );
     }
 
-    /// The seat snaps on the DEVICE grid, not the logical one — the plate's law
-    /// ([`device_snap`]), which the bubble shipped without. At the 2× display we play on, a
-    /// logical `round()` moved the bubble two physical pixels per axis against a world that
-    /// slides continuously; this moves it one, the smallest step that still lands the border
-    /// blit on a texel boundary. Pinned so `scale` can't be "simplified" back out into `round()`.
+    /// A logical `round()` would step two physical pixels per axis at 2×.
     #[test]
     fn the_bubble_seat_snaps_on_the_device_grid() {
         // 2×: the grid is every half logical pixel, and every snapped edge is a whole physical px.
@@ -962,15 +789,14 @@ mod tests {
                 o.y
             );
         }
-        // The x half is the same law applied to the CENTERED left edge (seat − w/2), so an odd
-        // width still lands the left edge — the one the border blit starts from — on the grid.
+        // The x half snaps the centered left edge (seat − w/2), where the border blit starts.
         let o = seat_origin(Vec2::new(100.4, 0.0), 41.0, 2.0);
         assert_eq!(o.x, 80.0);
         assert_eq!(((100.4_f32 - 20.5) * 2.0).round() / 2.0, o.x);
-        // 1×: identical to the logical round() it replaces — the fix costs nothing at scale 1.
+        // 1×: identical to a logical round().
         assert_eq!(seat_origin(Vec2::new(0.0, 10.4), 0.0, 1.0).y, 10.0);
         assert_eq!(seat_origin(Vec2::new(0.0, 10.6), 0.0, 1.0).y, 11.0);
-        // 1.5× (the Windows norm), where a logical round() was never texel-aligned at all.
+        // 1.5×, where a logical round() is never texel-aligned.
         for v in [10.4, 10.9, 11.2] {
             let o = seat_origin(Vec2::new(0.0, v), 0.0, 1.5);
             assert_eq!(
@@ -981,10 +807,7 @@ mod tests {
         }
     }
 
-    /// The snap must not be a *quantizer with a large step*: over a continuous glide, the extra
-    /// displacement it adds to any one frame is bounded by half a device pixel. This is the
-    /// property the jitter report is about — at 2× the old logical round() allowed a whole
-    /// logical pixel (two physical) of extra step, which is what read as judder.
+    /// Over a continuous glide the snap displaces any one frame by at most half a device pixel.
     #[test]
     fn the_snap_adds_at_most_half_a_device_pixel_of_step() {
         let scale = 2.0;
@@ -1001,24 +824,20 @@ mod tests {
         );
     }
 
-    /// Every bubble owns a frame LEVEL: its four pieces are one contiguous band, bands ascend
-    /// with rank, and no two bubbles can interleave. This is the whole 1504 fix — with a flat
-    /// per-piece key, every bubble's background painted under every bubble's text, so a speaker's
-    /// line bled across a neighbour's card.
+    /// One contiguous band per bubble, ascending with rank, so no two bubbles interleave.
     #[test]
     fn each_bubble_gets_its_own_level_band() {
         // The four pieces of one bubble, in paint order, all inside one level.
         const { assert!(Z_BG < Z_EDGE && Z_EDGE < Z_TAIL && Z_TAIL < Z_TEXT) };
         const { assert!(Z_TEXT < overlay_z::BUBBLE_STRIDE) };
         for rank in 0..8usize {
-            // ...and every piece strictly below the NEXT bubble's background.
+            // ...and every piece strictly below the next bubble's background.
             assert!(level_z(rank) + Z_TEXT < level_z(rank + 1) + Z_BG);
         }
         assert!(level_z(1) > level_z(0), "later rank draws later");
     }
 
-    /// The band is bounded: however many bubbles are live, none of them can reach the V-plates'
-    /// band above ([`crate::ui_pass::overlay_z`]) or the floating combat text's below.
+    /// However many bubbles are live, none reaches the V-plates above or the combat text below.
     #[test]
     fn the_bubble_band_stays_between_its_neighbours() {
         for rank in [0, 1, 1_000, usize::MAX] {
@@ -1028,8 +847,7 @@ mod tests {
         }
     }
 
-    /// The stack order is the reference's: farthest camera distance first (so the nearest
-    /// speaker's bubble ends up on top), guid breaking an exact tie deterministically.
+    /// Farthest camera distance first, guid breaking an exact tie.
     #[test]
     fn the_stack_is_sorted_farthest_first() {
         let at = |guid: u64, d2: f32| Pending {
@@ -1048,12 +866,11 @@ mod tests {
             vec![2, 3, 7, 9],
             "farthest first; the 400-yd² pair ordered by guid"
         );
-        // The rank the draw uses IS the frame level: the nearest speaker draws last.
+        // The rank the draw uses is the frame level: the nearest speaker draws last.
         assert!(level_z(0) < level_z(p.len() - 1));
     }
 
-    /// The border-unit lands the byte constants: 16 px at 1024-wide 4:3 (G44·16/(S·1024)
-    /// nets width/64), damped past the plate knee like every other size.
+    /// 16 px at 1024-wide 4:3 (width/64), damped past the plate knee.
     #[test]
     fn border_unit_is_a_64th_of_the_width() {
         let vp = Vec2::new(1024.0, 768.0);
diff --git a/crates/benilla-app/src/chr_classes.rs b/crates/benilla-app/src/chr_classes.rs
index c04dc721..97613a37 100644
--- a/crates/benilla-app/src/chr_classes.rs
+++ b/crates/benilla-app/src/chr_classes.rs
@@ -1,25 +1,14 @@
-//! `ChrClasses.dbc`, loaded once and read by everything that asks the client a question about a
-//! class.
-//!
-//! Three consumers today and they are unrelated to each other — [`crate::ui_pet_book`] wants field
-//! 4's pet name token, `UnitHasRelicSlot` wants field 16's relic flag, and
-//! `crate::spell::mods` wants field 15's class spell-family — which is exactly why the
-//! table does not live inside any of them. It used to live in the pet book, back when the pet
-//! token was the only column anyone read.
-//!
-//! The resource is **absent**, not empty, when the load fails. Every reader then falls to the
-//! reference's own degraded answer (`"PET"` for the token, no relic slot for any class, family 0
-//! — which the modifier gate's first conjunct refuses), so a missing table costs a warlock the
-//! word "Demon", a paladin their relic branches and everyone their talent modifiers rather than
-//! taking the client down.
+//! `ChrClasses.dbc`, loaded once for its unrelated readers: the pet book (field 4, pet name token),
+//! `UnitHasRelicSlot` (field 16) and `crate::spell::mods` (field 15, spell family). Absent when the
+//! load fails; each reader then takes the reference's degraded answer: `"PET"`, no relic slot,
+//! family 0.
 
 use bevy::prelude::*;
 
 use benilla_assets::{AssetSet, LockRecover, WorldAssets};
 use benilla_formats::ChrClasses;
 
-/// The parsed table — see [`benilla_formats::ChrClasses`] for what each column is and which bytes
-/// say so.
+/// The parsed table; [`benilla_formats::ChrClasses`] documents the columns.
 #[derive(Resource)]
 pub(crate) struct ChrClassTable(pub(crate) ChrClasses);
 
diff --git a/crates/benilla-app/src/cinematic.rs b/crates/benilla-app/src/cinematic.rs
index e0c3bcd1..bfa3519a 100644
--- a/crates/benilla-app/src/cinematic.rs
+++ b/crates/benilla-app/src/cinematic.rs
@@ -1,70 +1,28 @@
-//! **Cinematic playback** — the race-intro fly-by, and every other `SMSG_TRIGGER_CINEMATIC`.
+//! Cinematic playback: the race-intro fly-by and every other `SMSG_TRIGGER_CINEMATIC`.
 //!
-//! A cinematic is an in-engine camera flight, not a movie: the trigger carries a
-//! `CinematicSequences.dbc` id, the row names its `CinematicCamera.dbc` shots, and each shot is an
-//! authored eye/target/roll path in a `Cameras\*.m2` planted at a world origin and facing. The
-//! parsing, the world transform and the Bézier evaluation all live in
-//! [`benilla_formats::CinematicPath`]; this module is the *playback* — when it starts, what it
-//! takes over while it runs, and how it ends.
+//! A cinematic is an in-engine camera flight: the trigger's `CinematicSequences.dbc` row names its
+//! `CinematicCamera.dbc` shots, each an eye/target/roll path in a `Cameras\*.m2`, evaluated by
+//! [`benilla_formats::CinematicPath`]. This module is the playback.
 //!
-//! # What the reference does, and what we match
+//! - A trigger before the world is up waits in a single-slot latch (`0xc4d75c`), last write wins,
+//!   and starts when the world-load gate opens (`0x5deb78`); here the gate is the loading screen.
+//! - The path plays as an M2 animation (`0x7121a0`, sequence 0, rate 1.0), and a shot ends at its
+//!   sequence band's end ([`CinematicPath::duration_ms`]); shipped fly-bys clamp and play once.
+//! - Every shot, the first included, is announced with `CMSG_NEXT_CINEMATIC_CAMERA` from the shot
+//!   arm (`0x48edf0`, sent at `0x48ef11`). A camera id of 0 ends the cinematic (`0x48efe0`).
+//! - ESC is no engine binding: `StopCinematic` has no native caller, and the only skip is
+//!   `CinematicFrame.xml`'s `OnKeyDown`, whose Lua queues
+//!   [`SessionRequest::StopCinematic`](benilla_ui::script::SessionRequest).
+//! - `CMSG_COMPLETE_CINEMATIC` goes out once, on a natural end and on a skip alike (`0x48f080`).
+//!   Unacked, vmangos keeps object visibility on its own copy of the flying camera
+//!   (`Player.cpp:1448`), and everything around the body stays despawned until relog.
+//! - Every boundary (start, shot advance, end) cuts through black: a 0.25 s fade-out
+//!   (`[0x804550]`, `0x4c0d10`) whose completion runs the step, then a fade-in (`0x4c1280`). There
+//!   is no audio fade on this path.
 //!
-//! The reason each piece here is shaped the way it is:
-//!
-//! - **A trigger that arrives before the world is up is deferred, not dropped.** The reference
-//!   stashes the sequence id in a single-slot latch (`0xc4d75c`) whenever its world-load gate is
-//!   still closed, and starts it the instant the gate opens (`0x5deb78`). Last write wins; there
-//!   is no queue. [`Cinematic::pending`] is that latch, and the gate here is the loading screen —
-//!   a first login's intro would otherwise play its opening seconds behind the cover, with no UI
-//!   to ESC out of.
-//! - **The camera path is armed as an ordinary M2 animation** (`0x7121a0`, sequence 0, rate 1.0)
-//!   and the shot ends when the scene clock reaches the sequence band's end — `M2Sequence.end −
-//!   .start`, which is [`CinematicPath::duration_ms`]. Every shipped fly-by is `flags` bit 0 =
-//!   clamp, i.e. plays **once and freezes**; it does not loop. (`Scry_cam`, which is not a race
-//!   intro, is the one file authored to loop — a difference we inherit for free by ending on the
-//!   band rather than on the flag.)
-//! - **The client announces every shot with `CMSG_NEXT_CINEMATIC_CAMERA` — including the first.**
-//!   The send sits inside the *shot arm* `0x48edf0`, not the shot advance: `0x48ef11 push 0xfb`
-//!   → `0x418190` (the packet builder) → `0x48ef24 call 0x5ab630` (flush), immediately before
-//!   `0x48ef29` starts that shot's narration and `0x48ef43` fades it in — the same builder/flush
-//!   pair `0x48f154 push 0xfc` uses for the completion ack. Since every shot goes through the arm,
-//!   a shipped single-camera race intro sends exactly one of these, at the start. benilla used to
-//!   read this as "between the shots of a multi-camera row" and cite `0x48efe0`, which sent none
-//!   at all on every shot the game actually ships. A camera id of `0` still **ends** the cinematic
-//!   rather than being skipped (`0x48efe0`).
-//! - **ESC is not an engine binding.** `StopCinematic` has zero native callers in the reference:
-//!   the only skip path is `CinematicFrame.xml`'s own `OnKeyDown`, which is why benilla's copy of
-//!   that frame (stock `Interface\FrameXML\CinematicFrame.xml`) carries the same handler and why
-//!   the Lua binding queues [`SessionRequest::StopCinematic`](benilla_ui::script::SessionRequest)
-//!   rather than reaching in here.
-//! - **The ack ends the run, once.** `CMSG_COMPLETE_CINEMATIC` goes out on a natural end and on an
-//!   ESC skip alike (`0x48f080`). Decision 0196 is why it can never be dropped: unacked, vmangos
-//!   re-anchors object visibility to its own copy of the flying camera and everything around the
-//!   body despawns until relog.
-//!
-//! # What we deliberately do differently
-//!
-//! **Every cinematic boundary in the reference cuts through black, and benilla cuts hard.** The
-//! `0.25 s` at `[0x804550]` is not a scheduled delay — it is a screen fade, and the next step is
-//! its *completion callback*: `0x4c0d10` builds a fullscreen opaque-black quad (`0xff000000`) and
-//! latches what to run when it is fully up, so `CINEMATIC_START`, each shot advance and
-//! `EndCinematic` all execute at full black and `0x4c1280` fades back in. Six sites, both edges,
-//! always black, always 0.25 s. There is **no audio fade anywhere on this path**.
-//!
-//! benilla plays and acks immediately. Building the picture is what would let the timing be
-//! faithful too, so the two go together and neither is faked without the other — decision 1724
-//! leaves both standing rather than adding latency with nothing on screen to justify it.
-//!
-//! # What playback takes over
-//!
-//! Three things, all released on the way out. The **camera** — its *pose* only; the projection is
-//! left alone, because a fly-by is framed by the world camera's own optics and the M2 record's
-//! `fov` reaches nothing on this path (decision 1711). Written after `control` has seated it, the
-//! same slot `apply_camera_shake` uses. The **streaming focus**, which has to follow the camera
-//! rather than the body, because a Tauren's shot opens 1741 yards from where the body stands and would
-//! otherwise fly over unstreamed terrain; and the **UI's cinematic flag**, which drives
-//! `CinematicFrame`'s letterbox and makes `InCinematic()` answer truthfully so `StaticPopup`
-//! suppresses dialogs the way the reference's does.
+//! Playback takes over, and releases, the camera pose, the streaming focus (which follows the
+//! camera, so the flight is over streamed terrain) and the UI's cinematic flag, which drives
+//! `CinematicFrame` and makes `InCinematic()` true so `StaticPopup` suppresses dialogs.
 
 use std::time::Duration;
 
@@ -87,45 +45,27 @@ pub(crate) struct Cinematics(pub(crate) CinematicCatalog);
 /// The shot being played, plus the deferred-start latch.
 #[derive(Resource, Default)]
 pub(crate) struct Cinematic {
-    /// The sequence a trigger asked for but the world was not ready to show — the reference's
-    /// single-slot latch (`0xc4d75c`), last write wins, no queue.
+    /// The reference's single-slot latch (`0xc4d75c`): a sequence the world was not ready to show.
     pending: Option<u32>,
     playing: Option<Playing>,
-    /// The end boundary is still settling: the shot is over, the teardown has run, and the screen
-    /// is **holding at black** until the world around the body is presentable again.
-    ///
-    /// This is the reference's `0x48f080` — EndCinematic's forced terrain load back around the
-    /// followed unit, which runs at full black and *blocks* (no loading cover is raised anywhere on
-    /// this path: its raise, `0x406800`, has no caller there). benilla streams asynchronously and
-    /// cannot block, so it holds the black the reference was already showing for as long as that
-    /// load would have taken. Same thing on screen; ours keeps rendering.
-    ///
-    /// The value is the seconds of black left to spend waiting. **Black is never held forever:**
-    /// if the world does not come back inside the budget the fade comes in anyway, and the loading
-    /// cover — which sits below it — does the job it was always going to do. A stuck black screen
-    /// would be worse than the cover this exists to avoid.
+    /// Seconds of black left while the world comes back after the end. The reference's
+    /// EndCinematic (`0x48f080`) blocks on a terrain load at full black and raises no loading cover
+    /// (`0x406800` has no caller there); streaming cannot block, so the black holds instead, for
+    /// at most [`SETTLE_BUDGET`].
     settling: Option<f32>,
-    /// The player asked to skip (ESC), and it has not been paid yet.
-    ///
-    /// A skip is **not** settled where it is asked for. The reference's `StopCinematic` fades out
-    /// and hands EndCinematic to the fade as its completion callback (`0x48f067` →`0x48f080`), so
-    /// the ack and the teardown land at full black like every other boundary. [`stop`] sets this;
-    /// [`drive`] pays it.
+    /// A skip not yet paid: `StopCinematic` runs EndCinematic as its fade-out's completion
+    /// (`0x48f067`, `0x48f080`), so [`stop`] sets this and [`drive`] pays it at full black.
     skip: bool,
 }
 
 /// One cinematic in flight.
 struct Playing {
-    /// Which *run* this is, counted from process start. The `CinematicSequences.dbc` id alone is
-    /// not an identity: re-triggering the same sequence while it plays produces the same
-    /// `(sequence, shot)` pair, and the narration follower reads that pair to tell "still the same
-    /// shot" from "a new one" — so without this the picture restarted at t=0 while the voice kept
-    /// running from wherever it had got to.
+    /// The run's number since process start: a re-trigger of the playing sequence is a new run,
+    /// which the narration follower must see as a new shot.
     run: u64,
     /// The `CinematicSequences.dbc` id, for logging.
     sequence_id: u32,
-    /// The row's shots, in order. Non-empty (a sequence that resolves to nothing is acked at the
-    /// trigger and never becomes a `Playing`).
+    /// The row's shots in order, never empty.
     shots: Vec<CinematicPath>,
     /// Which shot is on screen.
     index: usize,
@@ -145,10 +85,8 @@ impl Cinematic {
         self.playing.is_some()
     }
 
-    /// The shot on screen: `(run, shot index, narration sound id)`. The identity pair is what lets
-    /// a follower tell "still the same shot" from "the next one", which is the question the
-    /// narration channel actually asks — and it is keyed on [`Playing::run`] rather than the
-    /// sequence id so that re-triggering the sequence already playing counts as a new shot.
+    /// The shot on screen: `(run, shot index, narration sound id)`, keyed on [`Playing::run`] so a
+    /// re-trigger counts as a new shot.
     pub(crate) fn playing_shot(&self) -> Option<(u64, usize, u32)> {
         let play = self.playing.as_ref()?;
         Some((play.run, play.index, play.shot().sound_id))
@@ -157,12 +95,8 @@ impl Cinematic {
 
 #[cfg(test)]
 impl Cinematic {
-    /// A cinematic that answers [`Cinematic::is_playing`] — for the neighbours that only ask that
-    /// one question (the streaming focus's hold, the HUD hide). **Shot-less on purpose:** there is
-    /// no way to build a [`CinematicPath`] without a real `Cameras\*.m2`, and a fixture that
-    /// faked one would let a test assert about a shot that does not exist. Anything that reads a
-    /// shot must be tested against the real corpus instead, and will panic loudly here if it is
-    /// not.
+    /// A shot-less cinematic for tests that only ask [`Cinematic::is_playing`]; a [`CinematicPath`]
+    /// needs a real `Cameras\*.m2`, so anything that reads a shot panics here.
     pub(crate) fn playing_for_test() -> Self {
         Self {
             pending: None,
@@ -179,29 +113,13 @@ impl Cinematic {
     }
 }
 
-/// One of the two letterbox bars — full-width, black, top or bottom.
-///
-/// **Bevy UI nodes rather than the reference's FrameXML textures — and as of decision 1734 that is
-/// a choice, not a constraint.** It was a constraint: 1699 had to move the bars out of
-/// `CinematicFrame.xml` because the HUD was hidden through [`UiHidden`](crate::ui_hide::UiHidden),
-/// which kills both of `ui_pass`'s quad lanes wholesale, so bars drawn as FrameXML textures went
-/// dark along with the action bars they exist to replace. That is no longer how the HUD is hidden.
-/// `UIParent:Hide()` cascades along the frame tree, and `CinematicFrame` has no parent — the
-/// reference declares it that way precisely so it survives the hide it triggers — so the
-/// reference's own arrangement would now work.
-///
-/// It stays here for now because it earns its place on its own terms: computed per frame, a window
-/// resized mid-cinematic stays correctly letterboxed, where the reference (whose resolution changed
-/// only across a restart) would not. Moving it back into `CinematicFrame.xml` is a real option that
-/// 1734 unblocked and did not take; it is a fidelity question, not a bug.
-///
-/// `CinematicFrame` still exists and still shows — it is what makes `InCinematic()` true, fires
-/// the events, owns the ESC handler, and is now what hides the HUD.
+/// One of the two letterbox bars, full-width black, top or bottom.
+/// Deviation: Bevy UI nodes computed per frame, not `CinematicFrame.xml`'s textures, so a window
+/// resized mid-cinematic stays letterboxed. `CinematicFrame` still shows and owns ESC.
 #[derive(Component)]
 struct LetterboxBar;
 
-/// What [`drive_letterbox`] switched off when the shot started, so it puts back only what it took.
-/// A player who was already in a mouse-look session keeps their state.
+/// What [`drive_letterbox`] switched off at the start, so it puts back only what it took.
 #[derive(Default)]
 struct Takeover {
     cursor: bool,
@@ -218,19 +136,15 @@ impl Plugin for CinematicPlugin {
             )
             .add_systems(
                 Update,
-                // One chain, all three steps in the same frame: the net drain has already run
-                // (`WorldStage::Net` precedes `Input`), so a trigger can arrive, start and be
-                // driven without ever showing a frame of the follow camera in between. And they
-                // run *after* `control` has seated that camera, so the pose written here is the
-                // last word on it — the same slot `apply_camera_shake` takes.
+                // One chain in one frame, after the net drain and after `control` seats the
+                // camera: no follow-camera frame shows, and this pose is the last word on it.
                 (take_trigger, start_pending, drive)
                     .chain()
                     .in_set(WorldStage::Input)
                     .after(PlayerControlSet),
             )
-            // The UI edge runs after the driver settled this frame's state, and only once there
-            // IS a UI: firing CINEMATIC_START into a VM with no `CinematicFrame` yet would raise
-            // no letterbox and leave nothing listening for the ESC that ends the shot.
+            // Only once the in-game UI is up: `CINEMATIC_START` into a VM with no `CinematicFrame`
+            // would leave nothing listening for ESC.
             .add_systems(
                 Update,
                 feed_ui
@@ -238,21 +152,18 @@ impl Plugin for CinematicPlugin {
                     .after(drive)
                     .run_if(crate::ui_script::ingame_ui_up),
             )
-            // A cinematic cannot outlive the world it was flying over: leaving drops it silently,
-            // with no ack, exactly as the reference's own leave-world teardown does (`0x490a80`
-            // clears the in-cinematic flag and sends no `CMSG_COMPLETE_CINEMATIC` — the socket is
-            // going away anyway).
-            // The screen's two takeovers — the HUD going dark and the bars coming in — ride the
-            // same edge as everything else, after the driver has settled this frame's state.
+            // The cursor and the bars, after the driver settled this frame's state.
             .add_systems(
                 Update,
                 drive_letterbox.in_set(WorldStage::Input).after(drive),
             )
+            // Leaving the world drops a cinematic with no ack, as the reference's teardown does
+            // (`0x490a80` clears the flag and sends no `CMSG_COMPLETE_CINEMATIC`).
             .add_systems(OnExit(ClientState::InWorld), abandon_on_leaving_world);
     }
 }
 
-/// The two bars, spawned once and parked hidden — the loading cover's own shape.
+/// The two bars, spawned once and parked hidden.
 fn spawn_letterbox(mut commands: Commands) {
     for top in [true, false] {
         commands.spawn((
@@ -267,42 +178,25 @@ fn spawn_letterbox(mut commands: Commands) {
                 ..default()
             },
             BackgroundColor(Color::BLACK),
-            // Above the world and the UI quads, below the loading cover (1000): a cinematic that
-            // runs into a zone load should be covered by the load, not paint over it.
+            // Above the world and the UI quads, below the loading cover's `GlobalZIndex` of 1000.
             GlobalZIndex(900),
             Visibility::Hidden,
         ));
     }
 }
 
-/// The height of **one** letterbox bar, in the same units as the screen it is measured against.
-///
-/// The reference's law in one expression — see [`drive_letterbox`] for where each term comes from.
-/// Pure and unit-agnostic, so it is testable against the reference's own numbers without a window.
+/// The height of one letterbox bar, in the screen's units ([`drive_letterbox`] has the law).
 fn letterbox_bar(width: f32, screen: f32) -> f32 {
     let two_to_one = (screen - (width / 2.0).min(screen)) / 2.0;
     two_to_one.min(screen / 6.0).max(0.0)
 }
 
-/// Raise the letterbox and darken the HUD while a shot is on screen; put both back after.
+/// Hide the cursor and raise the letterbox while a shot is on screen; put both back after.
 ///
-/// The bar height is the reference's own law, and it is **two** halves of one formula. The Lua in
-/// `CinematicFrame.lua` crops the picture to **2:1** — `width/2`, capped at the screen height,
-/// remainder split evenly — but only `if width/height > 4/3`; below that it recomputes nothing and
-/// the bars stand at the size `CinematicFrame.xml` declares them, `1024 x 128`. That is not a
-/// separate rule: the frame is authored on the client's native `1024 x 768` sheet (`WorldMapFrame`
-/// authors its fullscreen backdrop at exactly that, and `SetupFullscreenScale` grows it), so `128`
-/// is `height/6` — which is the 2:1 formula evaluated at exactly 4:3. The `if` is a guard around a
-/// recompute, not a gate on whether there are bars.
-///
-/// So the whole law is one line: **`min((height - min(width/2, height))/2, height/6)`**. Wider than
-/// 4:3 the first term wins and the picture is 2:1; at 4:3 they are equal; narrower, the cap holds
-/// the bars at a sixth apiece exactly as the reference's un-recomputed textures do. Reading it as
-/// "only a wide screen gets bars" left benilla un-letterboxed at 4:3 and below, which is the
-/// reference's *native* aspect.
-///
-/// Computed here per frame rather than once in `OnLoad`: a window resized mid-cinematic stays
-/// letterboxed, where the reference (whose resolution changed only across a restart) would not.
+/// `CinematicFrame.lua:9` crops to 2:1 (`width/2` capped at the height) only when wider than 4:3;
+/// otherwise the bars keep the XML's `1024 x 128` on the native `1024 x 768` sheet, a sixth of the
+/// height, which is the 2:1 formula at exactly 4:3. The whole law is
+/// `min((height - min(width/2, height))/2, height/6)`, so 4:3 and narrower still get bars.
 fn drive_letterbox(
     cine: Res<Cinematic>,
     mut bars: Query<(&mut Node, &mut Visibility), With<LetterboxBar>>,
@@ -312,22 +206,13 @@ fn drive_letterbox(
     mut logged: Local<f32>,
 ) {
     let playing = cine.is_playing();
-    // **The HUD is no longer hidden from here.** It is Lua's, exactly as it is in the reference:
-    // `CinematicFrame`'s `CINEMATIC_START` arm calls `ShowUIPanel`, its `area = "full"` row routes
-    // to `SetFullScreenFrame`, and that hides `UIParent` — which now reaches the whole HUD,
-    // because decision 1734 restored the 72 `parent=` declarations the transcription had dropped.
-    // `UiHidden` goes back to meaning only what ALT-Z means.
+    // The HUD is Lua's, as in the reference: `CINEMATIC_START` runs `ShowUIPanel`, whose
+    // `area = "full"` routes to `SetFullScreenFrame`, which hides `UIParent`.
 
-    // **The hardware cursor goes with it** — `0x58b590(0)` at StartCinematic, `(1)` at
-    // EndCinematic and at the leave-world teardown. Nothing else in benilla
-    // would: this flag is otherwise written only by the mouse-look session in `player::camera`,
-    // and `control` skips that whole branch while the view is detached, so the pointer the player
-    // arrived at character-select with simply sat on top of the fly-by.
-    //
-    // Same restore-only-what-we-hid discipline as the HUD above, and the same **write only on a
-    // real change**: `CursorOptions` is what `bevy_winit`'s `changed_cursor_options` watches, and
-    // re-applying cursor state to AppKit every frame intermittently stalls the main thread
-    // (`player::control`'s shadow-copy note, the 0366 frame-tail hunt).
+    // The hardware cursor hides at StartCinematic and returns at EndCinematic and the leave-world
+    // teardown (`0x58b590(0)`/`(1)`); nothing else hides it while the view is detached. Written
+    // only on a real change: `bevy_winit` re-applies `CursorOptions` to AppKit on every change,
+    // which can stall the main thread.
     if let Ok(mut opts) = cursor.single_mut() {
         if playing && opts.visible {
             opts.visible = false;
@@ -347,10 +232,7 @@ fn drive_letterbox(
             let (width, screen) = (w.width(), w.height().max(1.0));
             letterbox_bar(width, screen)
         });
-    // On the edges and on a resize, never every frame: the measured crop, so the letterbox is a
-    // number in the log rather than something only an eye can confirm. `info!` on purpose — the
-    // default filter stops at that level, and a number nobody's ordinary run prints is a number
-    // nobody checks (it fires once per cinematic, plus once per resize during one).
+    // The measured crop, logged at `info!` on the edges and on a resize, never every frame.
     if height != *logged {
         *logged = height;
         if height > 0.0 {
@@ -384,8 +266,7 @@ fn load_catalog(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
             );
             commands.insert_resource(Cinematics(cat));
         }
-        // Graceful absence, the standing posture: with no catalog every trigger falls through to
-        // the immediate ack, which is exactly the pre-playback behaviour decision 0196 shipped.
+        // With no catalog every trigger falls through to the immediate ack.
         Err(e) => warn!("cinematic: tables failed to load: {e:#}"),
     }
 }
@@ -403,14 +284,12 @@ fn take_trigger(
             .as_deref()
             .is_some_and(|c| !c.0.shots(id).is_empty());
         if !playable {
-            // Nothing to play — ack on the spot rather than leaving the server flying a path
-            // nobody is watching (decision 0196).
+            // Nothing to play: ack at once rather than leave the server flying a path unwatched.
             warn!("cinematic: {id} names no shot we can play — acking it");
             ack(net.as_deref());
             continue;
         }
-        // Last write wins, the reference's single-slot latch — but the id it displaces still owes
-        // the server its ack (see [`relinquish`]).
+        // Last write wins, but the displaced id is still owed its ack ([`relinquish`]).
         if let Some(dropped) = cine.pending.replace(id) {
             warn!("cinematic: {dropped} displaced by {id} before it started — acking it");
             ack(net.as_deref());
@@ -418,14 +297,8 @@ fn take_trigger(
     }
 }
 
-/// Give up whatever is in flight, paying its ack.
-///
-/// **The invariant this exists to keep: one `CMSG_COMPLETE_CINEMATIC` for every trigger we
-/// accepted.** Decision 0196 is why the direction matters — an unacked cinematic leaves vmangos
-/// anchoring object visibility to its own copy of the flying camera, and everything around the
-/// body stays despawned until relog. An *extra* ack is discarded by a server that is not watching
-/// one; a missing one is not recoverable in-session. So when two triggers are live at once, both
-/// are acked: they are two cinematics the server started, not one.
+/// Give up whatever is in flight, paying one `CMSG_COMPLETE_CINEMATIC` per accepted trigger: an
+/// extra ack is harmless, a missing one costs a relog (module doc), so two live triggers pay two.
 fn relinquish(cine: &mut Cinematic, net: Option<&NetCommands>, why: &str) {
     if let Some(play) = cine.playing.take() {
         info!("cinematic: {} {why}", play.sequence_id);
@@ -448,20 +321,17 @@ fn start_pending(
     mut fade: ResMut<crate::screen_fade::ScreenFade>,
 ) {
     let Some(id) = cine.pending else { return };
-    // The reference's world-load gate. Ours is the loading cover plus being in the world at all:
-    // starting under the cover would burn the opening seconds behind black, and `CinematicFrame`
-    // (the letterbox, and the only ESC route out) does not exist until the in-game UI has loaded.
+    // The world-load gate: in the world, where `CinematicFrame` (the only ESC route) exists, and
+    // not under the loading cover, which would hide the opening seconds.
     if *state.get() != ClientState::InWorld || screen.is_some_and(|s| s.covering()) {
         return;
     }
     let (Some(catalog), Some(assets)) = (catalog, assets) else {
         return;
     };
-    // **The reference does not arm the shot here — it fades out, and the arm is the fade's
-    // completion callback** (`0x48edc5` arms `0x4c0d10(0x48edd0, 0, 0.25)`). So the world's last
-    // frame darkens first and everything below runs at full black: the chain read, the camera
-    // load, `CINEMATIC_START`. Gated last, after every "we cannot play this" return above, so a
-    // start that fails its preconditions never darkens the screen on the way to doing nothing.
+    // The shot is armed as the fade-out's completion (`0x48edc5` arms `0x4c0d10(0x48edd0, 0,
+    // 0.25)`), so all below runs at full black. Gated after every can't-play return, so a failed
+    // start never darkens the screen.
     if !fade.is_black() {
         fade.fade_out(crate::screen_fade::CINEMATIC);
         return;
@@ -474,14 +344,14 @@ fn start_pending(
     for row in &rows {
         match CinematicPath::load(&mut chain, row) {
             Ok(p) => shots.push(p),
-            // One unreadable shot does not have to sink the whole cinematic: play what parses.
+            // One unreadable shot does not sink the cinematic: play what parses.
             Err(e) => warn!("cinematic: camera {} failed to load: {e:#}", row.id),
         }
     }
     if shots.is_empty() {
         warn!("cinematic: {id} had no loadable shot — acking it");
         ack(net.as_deref());
-        // Nothing is going to be shown under this black, so give the world back.
+        // Nothing will show under this black, so give the world back.
         fade.fade_in(crate::screen_fade::CINEMATIC);
         return;
     }
@@ -490,9 +360,8 @@ fn start_pending(
         shots.len(),
         shots.iter().map(|s| s.duration_ms).sum::<u32>()
     );
-    // A trigger that lands on top of a running cinematic replaces it — and the one it replaces
-    // is acked here rather than dropped ([`relinquish`]'s invariant). No stock server does this;
-    // a GM `.debug play cinematic` during an intro does.
+    // A trigger on top of a running cinematic replaces it and acks the old one; a GM
+    // `.debug play cinematic` during an intro does this.
     if let Some(old) = cine.playing.take() {
         warn!(
             "cinematic: {} replaced by {id} while playing — acking it",
@@ -513,38 +382,23 @@ fn start_pending(
     fade.fade_in(crate::screen_fade::CINEMATIC);
 }
 
-/// `CMSG_NEXT_CINEMATIC_CAMERA` — sent as each shot is armed, the first one included (module doc:
-/// `0x48ef11`, inside the shot arm). It is how the server learns which camera is flying, which is
-/// the other half of decision 0196's visibility re-anchor.
+/// `CMSG_NEXT_CINEMATIC_CAMERA`, sent as each shot is armed, the first included (`0x48ef11`).
+/// vmangos ignores it (`MiscHandler.cpp:919`) and flies its camera copy on its own clock.
 fn announce_shot(net: Option<&NetCommands>) {
     if let Some(net) = net {
         let _ = net.0.send(ClientCommand::NextCinematicCamera);
     }
 }
 
-/// How long the end boundary will hold the screen black waiting for the world to come back.
-///
-/// Generous, because the alternative it is trading against is mild (a loading cover for a moment)
-/// and the cost of being too tight is the cover this exists to remove. Measured, the wait is
-/// 0.4-0.9 s on a warm slot. It is a **budget, not a timeout to rely on**: exhausting it logs.
+/// The most seconds the end boundary holds black for the world, which usually takes under one;
+/// running out logs and reveals anyway.
 const SETTLE_BUDGET: f32 = 8.0;
 
 /// Advance the shot and seat the camera on it; hand over to the next shot, or end the cinematic.
 ///
-/// Runs **after** `control` has seated the follow camera, the same slot `apply_camera_shake` uses:
-/// the pose written here is this frame's, over a base the controller rewrote from scratch, so
-/// nothing accumulates and the *pose* needs no restore — the next frame's `control` simply seats
-/// it again.
-///
-/// **The FOV is not touched at all**, and that is the correction decision 1711 landed. A fly-by is
-/// rendered through the world camera's own optics, re-stamped every frame — the M2 camera record's
-/// `fov` is written at model load (`0x70f336`) and read by nothing on this path (its one raw
-/// reader, `0x7ac640`, is reachable only
-/// from the portrait and `<Model>` frames). Feeding the authored 45 degrees through the reference's
-/// own `theta_v = F / sqrt(aspect^2 + 1)` builder — which is otherwise right, and angle-space
-/// division really is what `0x5c3cc0` does — rendered fifteen of the sixteen shipped shots at
-/// **half** the intended vertical FOV, i.e. visibly over-zoomed. Nothing to write means nothing to
-/// release.
+/// Runs after `control` seats the follow camera, which it re-seats every frame, so the pose needs
+/// no restore. The FOV is left alone: the M2 camera's `fov` (written at `0x70f336`) is read by
+/// nothing on this path, its one reader `0x7ac640` serving only portraits and `<Model>` frames.
 fn drive(
     mut cine: ResMut<Cinematic>,
     time: Res<Time>,
@@ -555,11 +409,7 @@ fn drive(
     mut camera: Query<&mut Transform, With<WorldCamera>>,
 ) {
     // --- The end boundary's tail: hold the black while the world comes back around the body.
-    //
-    // Both terms, because each has a one-frame race the other covers: residency can still read
-    // "presentable" for the frame before the focus moves off the camera, and the cover has not
-    // raised yet on the frame the shot ends. Either being false keeps the screen black, so the
-    // worst a race costs is one extra black frame.
+    // Both terms, as each covers the other's one-frame race; either false keeps the black.
     if let Some(left) = cine.settling {
         let home = progress
             .as_deref()
@@ -581,28 +431,23 @@ fn drive(
         return;
     }
 
-    // A skip with only a latch in flight is settled by [`stop`] itself, so by here every skip has
-    // something on screen to fade.
+    // A skip with only a latch in flight is settled by [`stop`], so here a skip has a shot to fade.
     let skip = cine.skip;
     let Some(play) = cine.playing.as_mut() else {
         return;
     };
     play.elapsed += time.delta();
 
-    // --- Every boundary cuts through black. A shot that has run out and a skip the player asked
-    // for are the same event to the screen: fade out, and land the step at **full black**. The
-    // reference does not schedule the step after a delay — it hands it to the fade as the
-    // completion callback (`0x48efd7` → `0x48efe0` for an advance, `0x48f067` → `0x48f080` for a
-    // stop), which is what keeps the cut invisible when the boundary itself hitches.
+    // --- Every boundary cuts through black: a run-out shot or a skip fades out and steps at full
+    // black, as the fade's completion (`0x48efd7` to `0x48efe0` to advance, `0x48f067` to
+    // `0x48f080` to stop), which keeps the cut invisible under a hitch.
     if skip || play.elapsed.as_millis() as u32 >= play.shot().duration_ms {
         if !fade.is_black() {
             fade.fade_out(crate::screen_fade::CINEMATIC);
-            // …and fall through to seat the camera, so what darkens is the shot's own last pose.
+            // Fall through to seat the camera: what darkens is the shot's own last pose.
         } else {
-            // Walk past every shot this frame's delta ran clean through (a long stall, a debugger
-            // pause) — each still owes the server its `CMSG_NEXT_CINEMATIC_CAMERA`. They are
-            // walked inside **one** black rather than a fade each: the fade marks the boundary the
-            // player sees, not every row crossed behind it.
+            // Walk past every shot this frame's delta ran through, each owed its
+            // `CMSG_NEXT_CINEMATIC_CAMERA`, inside one black.
             let mut ended = skip;
             while !ended {
                 let play = cine.playing.as_mut().expect("checked above");
@@ -621,22 +466,18 @@ fn drive(
             if ended {
                 cine.skip = false;
                 if skip {
-                    // A skip takes a latched trigger with it — the player said "not this", and
-                    // the one still waiting on the world is owed its ack all the same.
+                    // A skip takes a latched trigger with it, acked all the same.
                     relinquish(&mut cine, net.as_deref(), "stopped");
                 } else if let Some(play) = cine.playing.take() {
-                    // A **natural end** is not [`relinquish`]: a trigger that arrived while this
-                    // one was flying is a cinematic still owed its *playback*, not an ack, and
-                    // `start_pending` will pick it up on the next pass.
+                    // A natural end is not [`relinquish`]: a latched trigger is owed its playback,
+                    // which `start_pending` picks up next.
                     info!("cinematic: {} finished", play.sequence_id);
                     ack(net.as_deref());
                 }
             }
             if ended {
-                // **Do not fade in yet.** The world around the body was streamed away while the
-                // camera flew, and revealing it now is what put a loading cover on screen for
-                // half a second at the end of every fly-by. Hold the black instead, which is what
-                // the reference is already showing while its own forced load blocks.
+                // Not faded in yet: the world around the body streamed away during the flight, so
+                // hold the black the reference shows while its own load blocks.
                 cine.settling = Some(SETTLE_BUDGET);
                 return;
             }
@@ -650,25 +491,19 @@ fn drive(
     };
     let play = cine.playing.as_ref().expect("checked above");
     let shot = play.shot();
-    // Clamped: while a boundary darkens, `elapsed` has already run past the shot's end and the
-    // pose held under the fade is the shot's last authored one, not an extrapolation past it.
+    // Clamped: under a boundary's fade the pose holds at the shot's last authored one.
     let view = shot.sample((play.elapsed.as_millis() as u32).min(shot.duration_ms));
     let eye = benilla_assets::coords::wow_to_bevy(view.eye);
     let target = benilla_assets::coords::wow_to_bevy(view.target);
 
-    // The roll is authored about the view axis, and around whole turns rather than around zero —
-    // `FlyByDwarf` holds a constant 2π — so it is applied as an angle and never tested for zero.
-    // The WoW→Bevy basis is a proper rotation (determinant +1), so the sign carries across
-    // unchanged.
+    // The roll is about the view axis and authored around whole turns (`FlyByDwarf` holds 2π), so
+    // it is applied as an angle, never tested for zero. The WoW-to-Bevy basis is a proper rotation,
+    // so its sign carries.
     let forward = (target - eye).normalize_or_zero();
     let up = if forward == Vec3::ZERO {
         Vec3::Y
     } else if forward.cross(Vec3::Y).length_squared() < 1e-6 {
-        // Looking straight up or down: rotating `Y` about a `forward` that *is* `Y` is the
-        // identity, so the authored roll would vanish and `look_at` would fall back to an
-        // arbitrary (if deterministic) horizon. Roll the one basis vector that is guaranteed not
-        // to be parallel to the view instead — same angle, about the same axis, just a seed that
-        // survives. No shipped shot holds a vertical view, which is why this never showed.
+        // Looking straight up or down, rolling `Y` about `Y` is the identity: roll `Z` instead.
         Quat::from_axis_angle(forward, view.roll) * Vec3::Z
     } else {
         Quat::from_axis_angle(forward, view.roll) * Vec3::Y
@@ -679,27 +514,20 @@ fn drive(
     }
 }
 
-/// ESC, or anything else that asks for the skip: end the cinematic and ack it.
-///
-/// The reference sends the same `CMSG_COMPLETE_CINEMATIC` here as it does on a natural end — a
-/// skip is indistinguishable from a completion on the wire, which is what made decision 0196's
-/// instant-ack legitimate in the first place.
+/// ESC, or anything else asking for the skip: end the cinematic and ack it. On the wire a skip is
+/// a completion.
 pub(crate) fn stop(cine: &mut Cinematic, net: Option<&NetCommands>) {
     if cine.playing.is_some() {
-        // Something is on screen, so the skip takes the same route every other boundary takes:
-        // fade to black, and settle at full black. [`drive`] pays the ack there. This is the
-        // reference's own shape — `StopCinematic` (`0x48f050`) does not end anything itself, it
-        // arms a 0.25 s fade-out with EndCinematic (`0x48f080`) as the completion callback.
+        // Something is on screen: [`drive`] pays at full black, as `StopCinematic` (`0x48f050`)
+        // arms a 0.25 s fade-out with EndCinematic (`0x48f080`) as its completion.
         cine.skip = true;
         return;
     }
-    // A trigger still waiting on the world goes with it: the player has said "not this". Nothing
-    // is on screen to fade, so this is paid on the spot — and it must be, because a latch that is
-    // never started has no [`drive`] pass coming to settle it.
+    // A latch still waiting on the world goes too, paid now: no [`drive`] pass will settle it.
     relinquish(cine, net, "stopped");
 }
 
-/// Leaving the world drops a cinematic without acking — the socket is going away with it.
+/// Leaving the world drops a cinematic without acking; the socket goes with it.
 fn abandon_on_leaving_world(
     mut cine: ResMut<Cinematic>,
     mut fade: ResMut<crate::screen_fade::ScreenFade>,
@@ -710,16 +538,12 @@ fn abandon_on_leaving_world(
     cine.pending = None;
     cine.skip = false;
     cine.settling = None;
-    // Whatever was mid-fade goes with it. A graceful fade-in has no frames left to run in here —
-    // the next thing on screen is the glue, and it must not come up behind our black.
+    // Clear any fade: the glue comes up next and must not sit behind our black.
     fade.clear();
 }
 
-/// Fire the `CINEMATIC_START`/`CINEMATIC_STOP` edges and keep `InCinematic()` honest.
-///
-/// Edge-fired off what **this VM** has heard, the `death.rs` posture: a fresh VM's memo is empty,
-/// so a `/reload` mid-cinematic re-fires `CINEMATIC_START` into the rebuilt frame tree and the
-/// letterbox comes back up rather than staying lost for the rest of the shot.
+/// Fire the `CINEMATIC_START`/`CINEMATIC_STOP` edges and keep `InCinematic()` current. The memo
+/// is per VM, so a `/reload` mid-cinematic re-fires `CINEMATIC_START` into the rebuilt tree.
 fn feed_ui(
     cine: Res<Cinematic>,
     script: Option<NonSendMut<UiScript>>,
@@ -729,20 +553,13 @@ fn feed_ui(
         return;
     };
     let playing = cine.is_playing();
-    // VM-scoped (decision 1290): the memo is memory *about a VM*, so a `/reload` mid-cinematic
-    // resets it and the edge re-fires into the rebuilt frame tree — which is the whole point,
-    // because the new tree's `CinematicFrame` is hidden and knows nothing about the shot still on
-    // screen. A plain `Local` here would leave the letterbox down and ESC dead for the rest of a
-    // 102-second intro.
+    // VM-scoped: a plain `Local` would leave ESC dead after a mid-cinematic `/reload`.
     let published = published.get(&script);
     if *published == Some(playing) {
         return;
     }
-    // **A fresh VM is already not in a cinematic, so there is no edge to announce.** The memo
-    // starts `None`, and `None != Some(false)` — which fired a `CINEMATIC_STOP` into every login
-    // and every `/reload`, an event the reference never sends unedged. Seed the state instead of
-    // announcing it; the `/reload`-mid-cinematic case (`playing == true`) still falls through and
-    // re-fires `CINEMATIC_START` into the rebuilt tree, which is what the memo is here for.
+    // A fresh VM is already out of a cinematic: seed the memo rather than fire a `CINEMATIC_STOP`
+    // the reference never sends unedged.
     if published.is_none() && !playing {
         *published = Some(false);
         return;
@@ -769,22 +586,16 @@ fn ack(net: Option<&NetCommands>) {
 mod tests {
     use super::letterbox_bar;
 
-    /// The reference computes the bars on its native `1024 x 768` sheet, so that sheet is where its
-    /// own numbers are quotable — and both of its cases have to come out of the one expression.
+    /// Both of the reference's cases, on its native `1024 x 768` sheet, from the one expression.
     #[test]
     fn the_letterbox_matches_the_reference_on_its_own_sheet() {
-        // Exactly 4:3 — the branch `CinematicFrame.lua` does NOT take, so the bars stand at the
-        // size `CinematicFrame.xml` declares: 128 of 768. The formula has to agree there, because
-        // that agreement is the proof the XML default *is* the formula at the boundary.
+        // Exactly 4:3, the branch the Lua does not take: the XML's 128 of 768.
         assert_eq!(letterbox_bar(1024.0, 768.0), 128.0);
 
-        // Wider: the Lua recomputes, `desiredHeight = width/2`, remainder split evenly. 16:10 on
-        // the same sheet is 1229 x 768 -> picture 614.5, bars 76.75 apiece.
+        // Wider, the Lua's `desiredHeight = width/2`: 16:10 on the sheet leaves bars of 76.8.
         assert!((letterbox_bar(1228.8, 768.0) - 76.8).abs() < 0.05);
     }
 
-    /// The wide case is a **2:1 picture**, whatever the screen: that is the whole point of
-    /// `desiredHeight = width/2`, and it is the number a player can measure off a screenshot.
     #[test]
     fn a_widescreen_picture_is_cropped_to_two_to_one() {
         for (w, h) in [(1920.0, 1080.0), (2560.0, 1440.0), (1600.0, 900.0)] {
@@ -798,21 +609,16 @@ mod tests {
         }
     }
 
-    /// The regression this function exists for: benilla read the Lua's `if` as "only a wide screen
-    /// gets bars" and drew none at or below 4:3 — the reference's *native* aspect, and the one a
-    /// windowed player lands on most easily.
     #[test]
     fn four_three_and_narrower_are_still_letterboxed() {
         // 4:3 at a real resolution.
         assert!((letterbox_bar(1024.0, 768.0) / 768.0 - 1.0 / 6.0).abs() < 1e-6);
         assert!((letterbox_bar(1600.0, 1200.0) / 1200.0 - 1.0 / 6.0).abs() < 1e-6);
-        // 5:4 and square: the reference leaves its textures alone, so the cap holds at a sixth
-        // rather than following `width/2` down to a taller bar.
+        // 5:4 and square: the reference's textures stay put, so the cap holds at a sixth.
         assert!((letterbox_bar(1280.0, 1024.0) / 1024.0 - 1.0 / 6.0).abs() < 1e-6);
         assert!((letterbox_bar(768.0, 768.0) / 768.0 - 1.0 / 6.0).abs() < 1e-6);
     }
 
-    /// A window can be any shape; none of them may produce a negative or a screen-swallowing bar.
     #[test]
     fn no_window_shape_produces_a_nonsense_bar() {
         for (w, h) in [(1.0, 1.0), (4000.0, 100.0), (100.0, 4000.0), (0.0, 720.0)] {
@@ -823,11 +629,7 @@ mod tests {
     }
 }
 
-/// **The ack ledger.** Decision 0196's invariant is the one thing on this path that cannot be
-/// checked by looking at the screen: an unacked cinematic leaves vmangos anchoring object
-/// visibility to its own copy of the flying camera, and everything around the body stays
-/// despawned until relog. It had no test at all, and that is precisely why a second trigger could
-/// silently displace a playing cinematic and pay nothing — the bug these cases now pin.
+/// The ack ledger: one `CMSG_COMPLETE_CINEMATIC` per accepted trigger, which no screen shows.
 #[cfg(test)]
 mod ack_ledger {
     use super::*;
@@ -844,9 +646,7 @@ mod ack_ledger {
             .count()
     }
 
-    /// Run `drive` once with the screen **already at full black** — the frame on which a boundary
-    /// settles. The ramp that gets it there is `screen_fade`'s own business and is tested there;
-    /// what these cases are about is what is paid when it arrives.
+    /// Run `drive` once with the screen already at full black, the frame a boundary settles on.
     fn settle_at_black(cine: Cinematic, net: NetCommands) -> App {
         let mut fade = crate::screen_fade::ScreenFade::default();
         fade.fade_out(0.0);
@@ -861,13 +661,7 @@ mod ack_ledger {
         app
     }
 
-    /// One trigger in flight, one ack out — the ordinary ESC skip.
-    ///
-    /// **The ack is paid at full black, not where ESC was pressed.** `stop` only latches the skip:
-    /// the reference's `StopCinematic` (`0x48f050`) ends nothing itself, it arms a fade-out and
-    /// hands EndCinematic (`0x48f080`) to it as the completion callback. The invariant is
-    /// unchanged — one ack per accepted trigger — it is simply paid one boundary later, and this
-    /// pins both halves so the deferral can never quietly become a *dropped* ack.
+    /// The ESC skip's one ack is paid at full black, not at the key press (`0x48f050`).
     #[test]
     fn stopping_a_playing_cinematic_acks_it_once() {
         let (net, rx) = wire();
@@ -881,9 +675,7 @@ mod ack_ledger {
         assert!(!app.world().resource::<Cinematic>().is_playing());
     }
 
-    /// Two triggers accepted, two acks owed. Over-acking is discarded by a server that is not
-    /// watching a cinematic; under-acking is the failure that costs a relog, so this direction is
-    /// deliberate and not a duplicate to squash.
+    /// Two triggers accepted, two acks owed: not a duplicate to squash.
     #[test]
     fn a_playing_cinematic_and_a_latched_one_each_pay() {
         let (net, rx) = wire();
@@ -895,16 +687,12 @@ mod ack_ledger {
         assert!(app.world().resource::<Cinematic>().pending.is_none());
     }
 
-    /// The other side of that line: a cinematic that ends **on its own** leaves a latched trigger
-    /// alone. It is owed its playback, not an ack — `start_pending` picks it up on the next pass.
-    /// Only a skip says "not this" about the one still waiting.
+    /// A natural end leaves a latched trigger to be played, not acked.
     #[test]
     fn a_natural_end_does_not_pay_off_a_latched_trigger() {
         let (net, rx) = wire();
-        // `playing_for_test` is shot-less, so the natural-end path cannot be reached through
-        // `drive`'s duration test without a real `Cameras\*.m2`. The skip flag reaches the same
-        // settle point; what this pins is the branch *inside* it, so the latch is set and the
-        // end is taken as a completion rather than a stop.
+        // A shot-less `playing_for_test` cannot run out through `drive`, so this runs the
+        // natural-end branch itself.
         let mut cine = Cinematic::playing_for_test();
         cine.pending = Some(41);
         let net_ref = &net;
@@ -916,7 +704,6 @@ mod ack_ledger {
         assert_eq!(cine.pending, Some(41), "the latch survives to be played");
     }
 
-    /// Nothing in flight owes nothing — ESC with no cinematic must not ack into the void.
     #[test]
     fn stopping_nothing_acks_nothing() {
         let (net, rx) = wire();
@@ -925,9 +712,7 @@ mod ack_ledger {
         assert_eq!(acks(&rx), 0);
     }
 
-    /// **The regression.** A trigger that displaces a latched one pays for the one it displaced —
-    /// the latch is last-write-wins (the reference's single slot), but the server still started
-    /// the cinematic it dropped.
+    /// A displaced latch is acked: the server still started the cinematic it dropped.
     #[test]
     fn a_displaced_latch_is_acked() {
         let (net, rx) = wire();
@@ -943,9 +728,7 @@ mod ack_ledger {
         assert_eq!(cine.pending, Some(81));
     }
 
-    /// Leaving the world is the one path that deliberately pays **nothing**: the socket is going
-    /// away with the cinematic, exactly as the reference's own teardown does (`0x490a80` clears
-    /// the flag and sends no `CMSG_COMPLETE_CINEMATIC`).
+    /// Leaving the world pays nothing, as the reference's teardown (`0x490a80`).
     #[test]
     fn abandoning_the_world_acks_nothing() {
         let (net, rx) = wire();
@@ -960,13 +743,8 @@ mod ack_ledger {
     }
 }
 
-/// **The end boundary holds the black until the world is back around the body.**
-///
-/// The reference's EndCinematic does a *blocking* terrain load at full black (`0x48f080`) and
-/// raises no loading cover anywhere on the cinematic path (its raise, `0x406800`, has no caller
-/// there). benilla streams asynchronously, so "block" is not available — but "keep showing the
-/// black the fade already put up" is, and it produces the same thing on screen. Without it the
-/// fly-by ends into a loading cover for half a second, measured, every time.
+/// The end boundary holds the black until the world is back around the body, where the
+/// reference blocks on its terrain load (`0x48f080`).
 #[cfg(test)]
 mod settling_under_black {
     use super::*;
@@ -1043,9 +821,6 @@ mod settling_under_black {
         );
     }
 
-    /// **The black is a budget, not a wait.** A world that never comes back must not leave the
-    /// player staring at a black screen — that would be strictly worse than the cover this
-    /// removes. The budget runs out and the fade comes in regardless.
     #[test]
     fn a_world_that_never_returns_still_gets_the_screen_back() {
         let mut app = ended_at_black();
diff --git a/crates/benilla-app/src/combat_log/chat.rs b/crates/benilla-app/src/combat_log/chat.rs
index 1fbbf2f4..350443b9 100644
--- a/crates/benilla-app/src/combat_log/chat.rs
+++ b/crates/benilla-app/src/combat_log/chat.rs
@@ -1,17 +1,11 @@
-//! The combat log's **chat line** leg (B297) — one of the two consumers of every combat packet;
-//! the floating number is [`super::text`]'s, and [`super`]'s handlers call this leg first.
-//!
-//! The split is the reference's own. `0x629b60` is the display dispatcher: one classification of
-//! both endpoints, then a branch per outcome into a formatter that emits *text*. The floating
-//! number comes off a different path entirely (`0x629d30`, which fires `COMBAT_TEXT_UPDATE`), gated by
-//! different CVars, with a different source law — which is why our two live in different files
-//! rather than in one arm with two tails. Everything here composes; the law it composes with is
+//! The combat log's chat-line leg. The reference's display dispatcher `0x629b60` classifies both
+//! endpoints, then branches per outcome into a text formatter; the floating number is a separate
+//! path (`0x629d30`, [`super::text`]) with its own CVars and source law. The wording law is
 //! [`crate::ui_chat::combat`].
 //!
-//! **Every arm has the same three steps**: classify both endpoints, pick the family and the chat
-//! type, queue the line for its names. What differs between them is only which packet field is the
-//! sentence's subject, which is not always the packet's own `attacker`
-//! (`SMSG_SPELLDAMAGESHIELD` is the standing counter-example).
+//! Every arm classifies both endpoints, picks the family and chat type, and queues the line for
+//! its names. The sentence's subject is not always the packet's `attacker`
+//! (`SMSG_SPELLDAMAGESHIELD`).
 
 use bevy::prelude::*;
 
@@ -27,8 +21,7 @@ use crate::ui_chat::ChatLog;
 
 use crate::net::{GuidIndex, ObjectStore, Reputations, SelfGuid};
 
-/// The classification inputs every line needs, bundled so seven legs do not each grow six
-/// parameters. Assembled per packet by [`super`]'s handlers from [`super::Log`].
+/// The classification inputs every line needs, built per packet from `super::Ctx`.
 pub(crate) struct ChatCtx<'a> {
     pub self_guid: &'a SelfGuid,
     pub group: Option<&'a crate::ui_party::GroupState>,
@@ -36,10 +29,10 @@ pub(crate) struct ChatCtx<'a> {
     pub factions: Option<&'a crate::target::ring::Factions>,
     pub reputations: &'a Reputations,
     pub spells: Option<&'a crate::ui_action::Spells>,
-    /// The live display ranges — the reference's `0x8629e0` table, now CVar-backed.
+    /// The display ranges: the reference's `0x8629e0` table, CVar-backed.
     pub ranges: &'a combat::CombatLogRanges,
-    /// `CombatLogPeriodicSpells`. The whole-packet gate lives at the `PeriodicAuraLog` dispatch
-    /// arm (it suppresses the floats too); this carries the two *chat-only* read sites.
+    /// `CombatLogPeriodicSpells`, for its two chat-only read sites; the whole-packet gate is in
+    /// the `PeriodicAuraLog` handler.
     pub periodic: bool,
 }
 
@@ -56,8 +49,7 @@ impl ChatCtx<'_> {
         )
     }
 
-    /// One endpoint's half of the display-range gate — the law is
-    /// [`combat::in_range`]; this only supplies the context it reads.
+    /// One endpoint's half of the display-range gate, [`combat::in_range`].
     fn in_range(&self, guid: u64, class: UnitClass, poses: &Query<&mut Transform>) -> bool {
         combat::in_range(
             guid,
@@ -68,19 +60,15 @@ impl ChatCtx<'_> {
         )
     }
 
-    /// A spell's display name, or `None` when the reference would emit **no line at all** for this
-    /// spell (`0x62cd80`, like every spell formatter). Two gates, both of which 1571 was missing:
+    /// A spell's display name, or `None` when the reference emits no line for it (`0x62cd80`, like
+    /// every spell formatter):
+    /// - `Attributes & 0x180` at `SpellRec+0x18`, `SPELL_ATTR_DO_NOT_DISPLAY` and
+    ///   `SPELL_ATTR_DO_NOT_LOG` (vmangos `SpellDefines.h:799-800`), keeping proc triggers and
+    ///   aura tickers out;
+    /// - an empty localized name.
     ///
-    /// - **`Attributes & 0x180`** — `SPELL_ATTR_DO_NOT_DISPLAY | SPELL_ATTR_DO_NOT_LOG` (the mask
-    ///   and the `SpellRec+0x18` offset are the binary's; the enum names are inferred from vmangos
-    ///   `SpellDefines.h:799-800`). This is what keeps the invisible book-keeping spells every
-    ///   server casts constantly — proc triggers, aura tickers — out of the log entirely.
-    /// - **An empty localized name.** The reference gates on the name it is about to print, so a
-    ///   row with no text in this locale produces silence rather than a sentence with a hole in it.
-    ///
-    /// A spell id the catalog cannot answer at all is *not* gated: that is our own missing data,
-    /// not the server's intent, and a nameless sentence still carries the numbers a damage meter
-    /// needs. The reference degrades the same way through `GetObjectName`'s `"UKNOWNOBJECT"` tail.
+    /// A spell the catalog does not know is not gated: the line still carries its numbers, as the
+    /// reference degrades through `GetObjectName`'s `"UKNOWNOBJECT"` tail.
     fn spell_name(&self, spell_id: u32) -> Option<String> {
         let Some(display) = self.spells.and_then(|s| s.catalog.get(spell_id)) else {
             return Some(String::new());
@@ -92,17 +80,9 @@ impl ChatCtx<'_> {
         Some(display.name.clone())
     }
 
-    /// `0x6ea280 == 2` — **"this spell targets enemies"**, the predicate the chat-type stubs
-    /// `0x627d30`/`0x627d60` run to choose between a family's `…_DAMAGE` and `…_BUFF` rows.
-    /// It reads the row, never the endpoints, which is why it lives beside
-    /// [`Self::spell_name`] and not beside the classifier.
-    ///
-    /// A row the catalog cannot answer reads as **harmful**, which is not a claim about the
-    /// spell — it is our own data gap, and the reference never reaches the question (it has
-    /// already bailed on a missing record at the `SpellRec+0x18` gate above, where we deliberately
-    /// carry on: see [`Self::spell_name`]). Harmful is chosen because it is the `…_DAMAGE` row
-    /// every one of these sites used unconditionally before the consult existed, so a missing row
-    /// keeps the behaviour it had rather than acquiring a new one.
+    /// `0x6ea280 == 2`, "this spell targets enemies": the predicate the chat-type stubs
+    /// `0x627d30`/`0x627d60` use to choose a family's `…_DAMAGE` or `…_BUFF` row. A spell the
+    /// catalog does not know reads as harmful, keeping the `…_DAMAGE` row.
     fn spell_harmful(&self, spell_id: u32) -> bool {
         self.spells
             .and_then(|s| s.catalog.get(spell_id))
@@ -110,11 +90,8 @@ impl ChatCtx<'_> {
     }
 }
 
-/// `SMSG_ATTACKERSTATEUPDATE` → the melee line. The whole `COMBAT_*` half of the block comes from
-/// this one packet.
-///
-/// `school` is the swing's first sub-damage school, which is what selects the `…SCHOOL` template
-/// ("You hit X for 5 fire damage." against "You hit X for 5."). Physical (0) takes the plain form.
+/// `SMSG_ATTACKERSTATEUPDATE`: the melee line, every `COMBAT_*` family. `school`, the first
+/// sub-damage's, selects the `…SCHOOL` template; physical (0) takes the plain one.
 pub(super) fn attacker_state(
     s: AttackerState,
     ctx: &ChatCtx,
@@ -122,23 +99,18 @@ pub(super) fn attacker_state(
     poses: &Query<&mut Transform>,
     log: &mut ChatLog,
 ) {
-    // `0x625e40`, the first of the packet's two whole-display gates and the one that runs before
-    // the dispatcher is even entered (`0x629b3e` → `0x629b45 je`): a swing that came from a spell
-    // and did not land plainly emits **no line at all**. The floating number is gated by the same
-    // predicate at its own site.
+    // `0x625e40`, checked before the dispatcher (`0x629b3e`, `0x629b45`): a swing from a spell
+    // that did not land plainly emits no line; the floating number has the same gate.
     if !s.displayed() {
         return;
     }
     let attacker = ctx.classify(s.attacker, stores);
     let victim = ctx.classify(s.victim, stores);
-    // `0x62a710`'s else-arm declines for VictimState 0/1/4/9 — the reference emits nothing at all
-    // for a swing that landed in one of those states, so neither does the packet.
+    // `0x62a710` emits nothing for VictimState 0, 1, 4 or 9.
     let Some(family) = combat::melee_family(s.hit_info, s.victim_state, s.damage, s.school) else {
         return;
     };
-    // A swing is a MISS line only for the outcomes the reference words as one; everything the
-    // victim did about it (dodge, parry, block, …) is still a "misses" chat TYPE, because the type
-    // pair is hits/misses and only a landed hit is "hits".
+    // The chat type pair is hits/misses: only a landed hit is "hits", a dodge or parry "misses".
     let landed = family.stem.starts_with("COMBATHIT");
     let Some(kind) = combat::combat_kind(attacker, victim, !landed) else {
         return;
@@ -147,10 +119,8 @@ pub(super) fn attacker_state(
         spell: String::new(),
         school: (s.school != 0).then_some(s.school),
         amount: i64::from(s.damage),
-        // **Only the landed-hit family grows a trailer**, and it is the only family in the whole
-        // block that can show GLANCING/CRUSHING/BLOCK: `0x628410`'s four call sites, and this is
-        // the one that passes a real `blocked` and a real `HitInfo` (`0x629ee7`). A dodge or a full
-        // absorb prints no amount at all — the reference does not append to those lines.
+        // Only a landed hit grows a trailer, and only here can it say GLANCING, CRUSHING or BLOCK:
+        // of `0x628410`'s call sites, this one passes a real `blocked` and `HitInfo` (`0x629ee7`).
         trailers: landed.then_some(combat::Trailers {
             absorbed: s.absorb,
             resisted: s.resist,
@@ -171,12 +141,9 @@ pub(super) fn attacker_state(
     );
 }
 
-/// `SMSG_SPELLNONMELEEDAMAGELOG` → a spell's damage line, or the fully-absorbed / fully-resisted
-/// wording when nothing got through.
-///
-/// The packet's own `periodic` flag routes the line to the `SPELL_PERIODIC_*` types and the
-/// `PERIODICAURADAMAGE` wording — a DoT tick the server chose to report here rather than through
-/// `SMSG_PERIODICAURALOG` is still a periodic tick, and the reference tells them apart the same way.
+/// `SMSG_SPELLNONMELEEDAMAGELOG`: a spell's damage line, or the absorbed, blocked or resisted
+/// wording when nothing got through. The `periodic` flag routes it to the `SPELL_PERIODIC_*`
+/// types and the `PERIODICAURADAMAGE` wording, as the reference does.
 pub(super) fn spell_damage_log(
     s: SpellDamageLog,
     ctx: &ChatCtx,
@@ -186,16 +153,14 @@ pub(super) fn spell_damage_log(
 ) {
     let attacker = ctx.classify(s.attacker, stores);
     let victim = ctx.classify(s.target, stores);
-    // `SPELL_HIT_TYPE_CRIT` (vmangos `SpellDefines.h:179`) — the same bit the floating text reads.
+    // `SPELL_HIT_TYPE_CRIT` (vmangos `SpellDefines.h:179`), the bit the floating text reads.
     let crit = s.hit_info & 0x2 != 0;
     let Some(spell) = ctx.spell_name(s.spell_id) else {
         return;
     };
 
-    // **Split damage takes the packet before anything else does** (`hit_info & 8` → `0x62de60`,
-    // the handler's FIRST test at `0x5e8...`, before the periodic split): a Soul Link-style share reads "%s's
-    // %s causes %s %d damage.", never "hits %s for %d". It has no `…SELFSELF` key and it grows no
-    // trailers.
+    // Split damage (`hit_info & 8`, to `0x62de60`) is tested first, before the periodic split: it
+    // reads "%s's %s causes %s %d damage.", has no `…SELFSELF` key and no trailers.
     const SPELL_HIT_TYPE_SPLIT: u32 = 0x8;
     if s.hit_info & SPELL_HIT_TYPE_SPLIT != 0 {
         let Some(kind) = combat::spell_kind(attacker, victim, false) else {
@@ -217,15 +182,13 @@ pub(super) fn spell_damage_log(
         );
     }
     if s.periodic {
-        // The second of `CombatLogPeriodicSpells`' two chat-only read sites: `0x62d9ae` inside
-        // `0x62d9a0` skips the `call 0x628100` line emit and nothing else — both branches converge
-        // and still reach the float emitters, which is why this returns instead of gating the arm.
+        // A chat-only `CombatLogPeriodicSpells` read (`0x62d9ae` in `0x62d9a0`): it skips the line
+        // emit `0x628100` and nothing else, so the floats still fire.
         if !ctx.periodic {
             return;
         }
-        // **The TARGET's class, not the caster's** (decision 2127): this leg lands in the shared
-        // `PERIODICAURADAMAGE` formatter `0x628100`, whose msg-id selector takes `outClassB`
-        // (`0x628235`), and B is the victim at every call site.
+        // The target's class, not the caster's: the formatter `0x628100` selects on the victim
+        // (`0x628235`).
         let Some(kind) = combat::periodic_kind(victim, false) else {
             return;
         };
@@ -233,9 +196,7 @@ pub(super) fn spell_damage_log(
             spell,
             school: Some(s.school),
             amount: i64::from(s.damage),
-            // `0x628341`, the periodic call site: absorb and resist only — it passes zero for
-            // blocked and for HitInfo, so a periodic line can never say "(blocked)" or
-            // "(crushing)".
+            // `0x628341` passes zero for blocked and HitInfo: absorb and resist trailers only.
             trailers: Some(combat::Trailers {
                 absorbed: s.absorb,
                 resisted: s.resist,
@@ -259,8 +220,7 @@ pub(super) fn spell_damage_log(
     let Some(kind) = combat::spell_kind(attacker, victim, false) else {
         return;
     };
-    // Nothing through: the reference words it as the reason rather than as a zero, and the order
-    // of the three tests is its own — absorb, then BLOCK, then resist (`0x62cd80`).
+    // Nothing through: worded as the reason, tested absorb, block, then resist (`0x62cd80`).
     let family = if s.damage == 0 && s.absorb > 0 {
         combat::SPELLLOGABSORB
     } else if s.damage == 0 && s.blocked > 0 {
@@ -275,10 +235,8 @@ pub(super) fn spell_damage_log(
             (true, true) => combat::SPELLLOGCRITSCHOOL,
         }
     };
-    // `0x62d03c`, the spell call site: it passes a real `blocked` but **HitInfo 0**, so a spell
-    // line can show RESIST/VULNERABLE/BLOCK/ABSORB and never GLANCING or CRUSHING. Only the
-    // families that actually print a damage number take one — the reference appends nothing to
-    // the "was absorbed / was blocked / was resisted" wordings, which name the reason instead.
+    // `0x62d03c` passes a real `blocked` but HitInfo 0, so never GLANCING or CRUSHING; the
+    // absorbed, blocked and resisted wordings take no trailer.
     let landed = family.stem.starts_with("SPELLLOG") && family.stem != "SPELLLOGABSORB";
     let fills = Fills {
         spell,
@@ -304,11 +262,7 @@ pub(super) fn spell_damage_log(
     );
 }
 
-/// `SMSG_SPELLLOGMISS` → one line per target a cast failed to land on, each worded by its own
-/// `SpellMissInfo`.
-///
-/// The packet is a *list*, and each entry is its own sentence with its own victim — so the chat
-/// type is recomputed per entry, not once for the cast.
+/// `SMSG_SPELLLOGMISS`: one line per missed target, worded by its own `SpellMissInfo`.
 pub(super) fn spell_log_miss(
     s: &SpellLogMiss,
     ctx: &ChatCtx,
@@ -320,16 +274,9 @@ pub(super) fn spell_log_miss(
     let Some(spell) = ctx.spell_name(s.spell_id) else {
         return;
     };
-    // **Every line off this packet is typed as a DAMAGE-SHIELD line**, and that is not a guess:
-    // the `SMSG_SPELLLOGMISS` caller passes the formatter's 5th argument as 1 (`0x5e7f31 push 1`),
-    // which routes `0x62bc5a` to `0x62c140` — the damage-shield two-way selector — instead of the
-    // usual eight-row spell matrix. Its five other callers pass 0 and take the normal path.
-    //
-    // Whether that is deliberate or a 1.12 bug is **not derivable from the binary**. We reproduce
-    // the behaviour, because an addon filtering on
-    // chat type has to see what the reference shows; the discriminator, if anyone wants it, is a
-    // live cast that misses and a look at which ChatFrame filter catches the line. 1571 sent these
-    // through `spell_kind` and had them land in `SPELL_*_DAMAGE`.
+    // Every line off this packet is typed as a damage-shield line: its caller passes the
+    // formatter's 5th argument as 1 (`0x5e7f31`), routing `0x62bc5a` to the damage-shield selector
+    // `0x62c140` instead of the spell matrix. Addons filter on the chat type the reference shows.
     let kind = combat::damage_shield_kind(attacker);
     for &(target, miss_info) in &s.misses {
         let family = combat::miss_family(miss_info);
@@ -351,7 +298,7 @@ pub(super) fn spell_log_miss(
     }
 }
 
-/// `SMSG_SPELLHEALLOG` → a heal line. A heal is a **BUFF** type, not a damage one.
+/// `SMSG_SPELLHEALLOG`: a heal line, a BUFF type.
 pub(super) fn spell_heal_log(
     s: SpellHealLog,
     ctx: &ChatCtx,
@@ -389,12 +336,8 @@ pub(super) fn spell_heal_log(
     );
 }
 
-/// `SMSG_SPELLENERGIZELOG` → a power-gain line, also a BUFF type.
-///
-/// **The wire amount is RAW and the sentence wants the displayed figure** (decision 2117): the
-/// reference's own handler `0x5e8a90` divides by `0x6e7130(powerType)` at `0x5e8af3` before it
-/// hands the number to anything, so a warrior's one point of Unbridled Wrath rage — 10 on the
-/// wire — words as *"You gain 1 Rage from …"*, not 10.
+/// `SMSG_SPELLENERGIZELOG`: a power-gain line, a BUFF type, in the displayed figure: `0x5e8a90`
+/// divides by `0x6e7130(powerType)` at `0x5e8af3`, so 10 rage on the wire words as 1.
 pub(super) fn spell_energize_log(
     s: SpellEnergizeLog,
     ctx: &ChatCtx,
@@ -428,10 +371,8 @@ pub(super) fn spell_energize_log(
     );
 }
 
-/// `SMSG_PERIODICAURALOG` → one line per tick, worded by the tick's aura type.
-///
-/// The periodic chat types split DAMAGE from BUFFS and **ignore the victim entirely** (their two
-/// selectors take one argument), which is why the kind is picked from `caster` alone here.
+/// `SMSG_PERIODICAURALOG`: one line per tick, worded by its aura type. The periodic chat-type
+/// selectors take one class, not a pair.
 pub(super) fn periodic_aura_log(
     s: &PeriodicAuraLog,
     ctx: &ChatCtx,
@@ -451,8 +392,7 @@ pub(super) fn periodic_aura_log(
                 false,
                 Fills {
                     spell: spell.clone(),
-                    // The periodic packet's school is a full u32; the template's slot is the same
-                    // `SPELL_SCHOOL<n>_NAME` index the direct-damage one takes.
+                    // A u32 on this packet, the same `SPELL_SCHOOL<n>_NAME` index as direct damage.
                     school: u8::try_from(school).ok(),
                     amount: i64::from(amount),
                     ..Default::default()
@@ -467,8 +407,7 @@ pub(super) fn periodic_aura_log(
                     ..Default::default()
                 },
             ),
-            // The same divide as the direct packet, from the same law and the same table — the
-            // reference's periodic handler `0x626dd0` applies it at `0x627087` before wording.
+            // The same displayed-figure divide, at `0x627087` in `0x626dd0`.
             PeriodicTick::Energize { power, amount } => (
                 combat::POWERGAIN,
                 true,
@@ -479,13 +418,8 @@ pub(super) fn periodic_aura_log(
                     ..Default::default()
                 },
             ),
-            // **Aura 64 is not an arm of this match at all.** It reaches the very same function
-            // the execute-log's `POWER_DRAIN` effect does — `0x627910` → `0x627930`, with the
-            // periodic flag set — so every choice that function makes (the LEECH/DRAIN fork, the
-            // happiness arm and its fall-through, the out-of-range drop, the chat-type stub)
-            // belongs to it and not to a constant written out here. This arm used to word
-            // `SPELLPOWERLEECH` unconditionally against an execute-log arm that forked three ways:
-            // one formatter, two call sites that disagreed (2117's named residue, closed by 2157).
+            // Aura 64 goes to the same formatter as the execute log's `POWER_DRAIN` (`0x627910`
+            // to `0x627930`, periodic flag set), which makes every wording choice.
             PeriodicTick::ManaLeech {
                 power,
                 amount,
@@ -524,17 +458,11 @@ pub(super) fn periodic_aura_log(
     }
 }
 
-/// `SMSG_SPELLDAMAGESHIELD` → the Thorns-style return hit.
-///
-/// **The sentence's subject is the packet's `victim`.** The wire names the fields from the original
-/// swing's point of view — `victim` wears the shield, `attacker` struck them and now takes the
-/// damage back — while `DAMAGESHIELDSELFOTHER` is "You reflect %d %s damage to %s.", whose subject
-/// is the reflector. Getting this backwards would name both endpoints in the wrong halves of every
-/// line, and nothing downstream would notice.
-///
-/// The chat type is a plain two-way split on the **bearer**, not the usual eight-row matrix:
-/// `0x62c140` returns `0x3f` (`SPELL_DAMAGESHIELDS_ON_SELF`) for class 0 or 1 and `0x40`
-/// (`…ON_OTHERS`) for everything else — "damage shields on self" meaning the shield that is on you.
+/// `SMSG_SPELLDAMAGESHIELD`: the Thorns-style return hit. The sentence's subject is the packet's
+/// `victim`, who wears the shield; `attacker` struck it and takes the damage
+/// (`DAMAGESHIELDSELFOTHER` is "You reflect %d %s damage to %s."). The chat type is a two-way on
+/// the bearer: `0x62c140` returns `0x3f` `SPELL_DAMAGESHIELDS_ON_SELF` for class 0 or 1, else
+/// `0x40` `…ON_OTHERS`.
 pub(super) fn damage_shield(
     s: DamageShield,
     ctx: &ChatCtx,
@@ -562,14 +490,9 @@ pub(super) fn damage_shield(
     );
 }
 
-/// `SMSG_PARTYKILLLOG` → "You have slain %s!" / "%s is slain by %s!".
-///
-/// **Only two killer classes produce a line at all** (`0x628890`, which has no selector): class 0
-/// is `SELFKILLOTHER`, class 2 (a party member) is `PARTYKILLOTHER`, and **everything else —
-/// including your own pet at class 1 — emits nothing**. That is the reference's own shape, not a
-/// simplification: a pet's kill is announced by the plain `UNITDIES*` line instead.
-///
-/// The chat type comes off the **victim**, through the death selector.
+/// `SMSG_PARTYKILLLOG`: "You have slain %s!" or "%s is slain by %s!". Only killer class 0
+/// (`SELFKILLOTHER`) and 2, a party member (`PARTYKILLOTHER`), produce a line (`0x628890`); a
+/// pet's kill gets the plain `UNITDIES*` line instead. The chat type comes off the victim.
 pub(super) fn party_kill_log(
     s: PartyKillLog,
     ctx: &ChatCtx,
@@ -596,10 +519,8 @@ pub(super) fn party_kill_log(
     );
 }
 
-/// `SMSG_SPELLINSTAKILLLOG` → "You are killed by %s." / "%s is killed by %s."
-///
-/// `0x62cbe0` calls the spell-damage selector with the victim's class in **both** positions
-/// (`0x626be0(class, class)`), so the type never splits on a second endpoint — there isn't one.
+/// `SMSG_SPELLINSTAKILLLOG`: "You are killed by %s." or "%s is killed by %s.". `0x62cbe0` passes
+/// the victim's class in both selector positions (`0x626be0(class, class)`).
 pub(super) fn spell_insta_kill_log(
     s: SpellInstaKillLog,
     ctx: &ChatCtx,
@@ -629,18 +550,11 @@ pub(super) fn spell_insta_kill_log(
     );
 }
 
-/// `SMSG_PROCRESIST` → "%s resists %s's %s." and `SMSG_SPELLORDAMAGE_IMMUNE` → "%s is immune to
-/// %s's %s." — one body, two sentences.
+/// `SMSG_PROCRESIST` ("%s resists %s's %s.") and `SMSG_SPELLORDAMAGE_IMMUNE` ("%s is immune to
+/// %s's %s."), both worded target first and typed off the (caster, target) pair.
 ///
-/// Both word the TARGET first (the reference's convention B), and both take their chat type from
-/// the (caster, target) pair — `PROCRESIST` always through the damage/buff stub `0x627d30`, and
-/// `IMMUNESPELL` through the plain damage selector `0x626be0`. The difference is real: an immunity
-/// to a *helpful* spell still files under `…_DAMAGE`.
-///
-/// **`IMMUNESPELL`'s `log_format` byte is the reference's "is periodic" flag, and it is now read.**
-/// `0x62d25f` inside `0x62d240` gates *this formatter only*, and only when that byte is set — so a
-/// direct immunity still prints with `CombatLogPeriodicSpells` off, and a periodic one does not.
-/// `PROCRESIST` is not gated at all: the read site is in the `SPELLORDAMAGE_IMMUNE` arm.
+/// `IMMUNESPELL`'s `log_format` byte is the periodic flag: `0x62d25f` in `0x62d240` gates that
+/// formatter alone on `CombatLogPeriodicSpells` when the byte is set; `PROCRESIST` is ungated.
 pub(super) fn spell_outcome_log(
     s: SpellOutcomeLog,
     immune: bool,
@@ -649,8 +563,7 @@ pub(super) fn spell_outcome_log(
     poses: &Query<&mut Transform>,
     log: &mut ChatLog,
 ) {
-    // The periodic gate, on the one arm that has it: `IMMUNESPELL` with the packet's periodic
-    // byte set. `PROCRESIST` shares this body but not the gate — its formatter has no read site.
+    // The periodic gate, on `IMMUNESPELL` alone.
     if immune && s.log_format != 0 && !ctx.periodic {
         return;
     }
@@ -659,10 +572,8 @@ pub(super) fn spell_outcome_log(
     let Some(spell) = ctx.spell_name(s.spell_id) else {
         return;
     };
-    // The two sentences do not share a selector, and this is where that bites: `PROCRESIST` goes
-    // through the damage/buff stub `0x627d30`, which asks the SPELL (`0x6ea280 == 2`), while
-    // `IMMUNESPELL` goes straight to the plain damage selector `0x626be0`. So an immunity to a
-    // *helpful* spell still files under `…_DAMAGE`, and a resisted helpful proc does not.
+    // `PROCRESIST` goes through the damage/buff stub `0x627d30`, which asks the spell;
+    // `IMMUNESPELL` through the damage selector `0x626be0`, so an immunity is always `…_DAMAGE`.
     let buff = !immune && !ctx.spell_harmful(s.spell_id);
     let Some(kind) = combat::spell_kind(caster, target, buff) else {
         return;
@@ -686,11 +597,9 @@ pub(super) fn spell_outcome_log(
     );
 }
 
-/// `SMSG_SPELLDISPELLOG` → "Your %s is removed." / "%s's %s is removed.", one line per aura.
-///
-/// The chat type is **hard-coded `0x45` `SPELL_BREAK_AURA`** (`0x62d480`) — it consults no class at
-/// all, which is why this is the one arm that never calls a selector. The dispeller is classified
-/// only for the range gate; the sentence names the bearer and the aura and nothing else.
+/// `SMSG_SPELLDISPELLOG`: "Your %s is removed." or "%s's %s is removed.", one line per aura. The
+/// chat type is the literal `0x45` `SPELL_BREAK_AURA` (`0x62d480`); the dispeller is classified
+/// only for the range gate.
 pub(super) fn spell_dispel_log(
     s: &SpellDispelLog,
     ctx: &ChatCtx,
@@ -720,12 +629,8 @@ pub(super) fn spell_dispel_log(
     }
 }
 
-/// `SMSG_DISPEL_FAILED` → "You fail to dispel %s's %s.", one line per aura that would not come off.
-///
-/// **The reference picks the format-string variant ONCE, before the loop** (`0x628c20`), so every
-/// line in a packet shares it — which is the same answer ours reaches, since both endpoints are the
-/// same for the whole packet. The chat type is re-derived per line only because the msg-id stub
-/// `0x627d30` consults the spell, and the spells differ.
+/// `SMSG_DISPEL_FAILED`: "You fail to dispel %s's %s.", one line per aura. The format variant is
+/// picked once per packet (`0x628c20`); the chat type per line, since `0x627d30` asks the spell.
 pub(super) fn dispel_failed(
     s: &DispelFailed,
     ctx: &ChatCtx,
@@ -739,8 +644,7 @@ pub(super) fn dispel_failed(
         let Some(spell) = ctx.spell_name(spell_id) else {
             continue;
         };
-        // Per line, because `0x627d30` consults the spell and the spells differ — which is what
-        // this arm's doc has said since it was written, over a `false` hoisted out of the loop.
+        // Per line: `0x627d30` asks the spell.
         let Some(kind) = combat::spell_kind(caster, victim, !ctx.spell_harmful(spell_id)) else {
             continue;
         };
@@ -760,17 +664,12 @@ pub(super) fn dispel_failed(
     }
 }
 
-/// `SMSG_ENCHANTMENTLOG` → "You cast %s on your %s." / "%s has faded from your %s."
+/// `SMSG_ENCHANTMENTLOG`: "You cast %s on your %s." or "%s has faded from your %s.". An empty
+/// caster guid means the enchant faded (`0x628f40`); the fade names only the owner. The item name,
+/// the last `%s`, comes from the item cache, so an uncached entry waits.
 ///
-/// **An empty caster guid is how the server says the enchant FADED** (vmangos's own comment on the
-/// field, and the reference's two-way at `0x628f40`); the fade names only the owner, which is why
-/// it drops from four keys to two. The item name is the last `%s` in every variant and comes from
-/// the item cache, so a line whose entry is not cached yet waits rather than printing a hole.
-///
-/// The chat type is the literal `0x44` `SPELL_ITEM_ENCHANTMENTS` on the fade leg and on the ADD leg
-/// when `show_affiliation` is clear — the copy the server sends to the item's own owner. The
-/// broadcast copy (affiliation set) takes the BUFF selector instead, which is what puts a
-/// bystander's enchant into their `SPELL_*_BUFF` bucket rather than the item block.
+/// The chat type is the literal `0x44` `SPELL_ITEM_ENCHANTMENTS` for a fade and for the owner's
+/// copy (`show_affiliation` clear); the broadcast copy takes the BUFF selector.
 pub(super) fn enchantment_log(
     s: EnchantmentLog,
     ctx: &ChatCtx,
@@ -823,21 +722,12 @@ pub(super) fn enchantment_log(
     );
 }
 
-/// `SMSG_SPELLLOGEXECUTE` → the lines a cast's *effects* produce, as opposed to the damage it
-/// dealt: what it created, fed, interrupted, drained, dismissed or damaged.
+/// `SMSG_SPELLLOGEXECUTE`: the lines a cast's effects produce, one formatter per effect id via
+/// the reference's jump table `0x5e8074`.
 ///
-/// **One packet, many formatters.** The wire is a list of groups keyed by spell-effect id, and the
-/// reference's own per-effect jump table (`0x5e8074`) sends each to a different formatter with a
-/// different family, a different chat type and a different argument convention. So this arm is a
-/// switch, not a sentence — the seven effects below are the ones that word themselves.
-///
-/// **Deliberately not wired, and named rather than dropped** (decision 1703): effects 33/59
-/// `OPEN_LOCK` (`OPEN_LOCK_{SELF,OTHER}` — its trailing `%s` is a *gameobject* name, and benilla
-/// has no GO-name cache to resolve one from a guid), and the `SIMPLECAST*`/`SIMPLEPERFORM*`/
-/// `SPELLTERSE_*` catch-all the reference falls back to for the guid-only tail of the switch (its
-/// bail conditions read `AttributesEx4` and the spell's three `Effect` columns, and `Spell.dbc`
-/// column 10 is not parsed into `SpellDisplay` yet). Both are additions, not corrections: nothing
-/// below changes when they land.
+/// Not built: effects 33 and 59 `OPEN_LOCK` (its `%s` is a gameobject name, and there is no
+/// gameobject-name cache), and the `SIMPLECAST*`/`SIMPLEPERFORM*`/`SPELLTERSE_*` fallback, whose
+/// bail reads `AttributesEx4` and `Spell.dbc` column 10, not parsed into `SpellDisplay`.
 pub(super) fn spell_log_execute(
     s: &SpellLogExecute,
     ctx: &ChatCtx,
@@ -858,10 +748,7 @@ pub(super) fn spell_log_execute(
     for (_effect, rows) in &s.effects {
         for row in rows {
             match *row {
-                // Effect 8 POWER_DRAIN — the non-periodic entry to the shared formatter
-                // [`power_drain_line`] (`0x627930` with the periodic flag clear). Every family
-                // choice this row can make lives there, because the periodic packet makes the
-                // same ones through the same function.
+                // Effect 8 POWER_DRAIN: [`power_drain_line`] (`0x627930`), periodic flag clear.
                 E::PowerDrain {
                     target,
                     amount,
@@ -884,9 +771,8 @@ pub(super) fn spell_log_execute(
                         false,
                     );
                 }
-                // Effect 19 ADD_EXTRA_ATTACKS. **The caster guid is never passed** (`0x62d9f0`):
-                // the sentence's only endpoint is the unit that gained the attacks, and the
-                // singular form is the same key with `_SINGULAR` appended.
+                // Effect 19 ADD_EXTRA_ATTACKS: no caster in the sentence (`0x62d9f0`), only the
+                // unit that gained the attacks.
                 E::ExtraAttacks { target, count } => {
                     let victim = ctx.classify(target, stores);
                     let Some(kind) = combat::spell_kind(victim, victim, false) else {
@@ -911,8 +797,8 @@ pub(super) fn spell_log_execute(
                         },
                     );
                 }
-                // Effect 24 CREATE_ITEM — the tradeskill line, at the literal `0x3e`. No target
-                // guid on the wire: the two-way is on the CASTER being you.
+                // Effect 24 CREATE_ITEM: the tradeskill line, literal type `0x3e`, split on the
+                // caster being you; no target on the wire.
                 E::CreateItem { item_entry } => queue_named(
                     log,
                     ctx,
@@ -924,7 +810,7 @@ pub(super) fn spell_log_execute(
                     Fills::default(),
                     combat::Named::Item(item_entry),
                 ),
-                // Effect 101 FEED_PET — the same shape as CREATE_ITEM, a different sentence.
+                // Effect 101 FEED_PET: CREATE_ITEM's shape, a different sentence.
                 E::FeedPet { item_entry } => queue_named(
                     log,
                     ctx,
@@ -936,9 +822,8 @@ pub(super) fn spell_log_execute(
                     Fills::default(),
                     combat::Named::Item(item_entry),
                 ),
-                // Effect 68 INTERRUPT_CAST. **The spell the sentence names is the INTERRUPTED
-                // one**, off the row, not the interrupting cast off the packet header — which is
-                // the whole point of the line.
+                // Effect 68 INTERRUPT_CAST: the sentence names the interrupted spell, off the row,
+                // not the packet's own.
                 E::InterruptCast { target, spell_id } => {
                     let victim = ctx.classify(target, stores);
                     let Some(interrupted) = ctx.spell_name(spell_id) else {
@@ -961,8 +846,7 @@ pub(super) fn spell_log_execute(
                         },
                     );
                 }
-                // Effect 111 DURABILITY_DAMAGE. Both fields `-1` is the "all items" form, which
-                // has its own family and names no item at all.
+                // Effect 111 DURABILITY_DAMAGE: both fields `-1` is the "all items" form.
                 E::DurabilityDamage {
                     target,
                     item_entry,
@@ -1000,9 +884,8 @@ pub(super) fn spell_log_execute(
                         combat::Named::Item(entry),
                     );
                 }
-                // Effect 102 DISMISS_PET arrives in the guid-only tail; the reference's two-way is
-                // on the caster being you, at the literal misc-info type, and the named thing is
-                // the pet.
+                // Effect 102 DISMISS_PET, in the guid-only tail: split on the caster being you, at
+                // the literal misc-info type, naming the pet.
                 E::Target { target } if *_effect == EFFECT_DISMISS_PET => {
                     let pet = ctx.classify(target, stores);
                     queue_named(
@@ -1017,60 +900,40 @@ pub(super) fn spell_log_execute(
                         combat::Named::Unit(target),
                     );
                 }
-                // Heals and energizes off this packet are the floating text's business, not the
-                // chat log's: the reference words them from SMSG_SPELLHEALLOG / SPELLENERGIZELOG,
-                // which arrive separately and already have arms. The rest of the guid-only tail is
-                // the SIMPLECAST catch-all named in this function's docs.
+                // Heals and energizes are worded from their own packets; the rest of the guid-only
+                // tail is the unbuilt SIMPLECAST fallback.
                 E::Heal { .. } | E::Energize { .. } | E::Target { .. } => {}
             }
         }
     }
 }
 
-/// vmangos `Powers`: happiness, the one power with no `…_POINTS` GlobalString — `0x6278f0` returns
-/// NULL for it, which is why it takes its own family instead of a `POWERGAIN` row.
+/// vmangos `Powers` happiness, the one power with no `…_POINTS` GlobalString (`0x6278f0` returns
+/// NULL), so it takes its own family.
 const POWER_HAPPINESS: u32 = 4;
 
 /// vmangos `SpellEffects::SPELL_EFFECT_DISMISS_PET`.
 const EFFECT_DISMISS_PET: u32 = 102;
 
-/// `|multiplier| >= 2^-22` — the reference's own leech/drain discriminator (`[0x8029d4]`).
+/// `|multiplier| >= 2^-22`: the reference's leech/drain discriminator (`[0x8029d4]`).
 const LEECH_EPSILON: f32 = 1.0 / 4_194_304.0;
 
-/// `0x6e7130(powerType)` as the log formatters take it — [`power_display_scale`]'s table, widened
-/// for the `i64` arithmetic every power line does.
-///
-/// It delegates rather than re-tabulating: this file used to carry its own copy of `{1, 10, 1, 1,
-/// 1000}`, and the copy was applied at exactly one of the four sites that need it (decision 2117).
+/// `0x6e7130(powerType)`: [`power_display_scale`]'s table, widened to `i64`.
 fn power_divisor(power: u32) -> i64 {
     i64::from(power_display_scale(power))
 }
 
-/// The figure a `POWERGAIN` line words: the wire amount on the display scale.
-///
-/// The reference does this **in the packet handler**, once per packet — `0x5e8af3` for
-/// `SMSG_SPELLENERGIZELOG`, `0x627087` for an energize tick — so the chat line and the
-/// `COMBAT_TEXT_UPDATE` push can never disagree. We have two consumers instead of one call, so the
-/// law is a named function rather than a local (decision 2117).
+/// The figure a `POWERGAIN` line words: the wire amount on the display scale, as the reference's
+/// handlers divide it once for both chat and `COMBAT_TEXT_UPDATE` (`0x5e8af3`, `0x627087`).
 fn power_gain(power: u32, amount: u32) -> i64 {
     i64::from(amount) / power_divisor(power)
 }
 
-/// Which endpoint a periodic tick's formatter hands its **msg-id selector** — the choice that
-/// decides whether a line types as `SPELL_PERIODIC_SELF_*` or `SPELL_PERIODIC_CREATURE_*`
-/// (decision 2127).
-///
-/// It is a function, exhaustive over the wire enum, because the four periodic formatters disagree
-/// and one shared `periodic_kind(caster, …)` was wrong for half of them: `0x628100`
-/// (`PERIODICAURADAMAGE`) and `0x627240` (`PERIODICAURAHEAL`) hand the selector `outClassB`, the
-/// **target** (`0x628235`, `0x62732c`); `0x627520` (`POWERGAIN`) and `0x627930`
-/// (`SPELLPOWERLEECH`/`…DRAIN`) hand it `outClassA`, the **caster** (`0x6275fb`,
-/// `0x627a0f`/`0x627a3a`). A new tick kind has to answer this question rather than inherit an
-/// answer.
-///
-/// The `ManaLeech` row is the table's record of the fourth formatter and is what the test pins;
-/// the tick itself is worded by [`power_drain_line`], which applies the same row directly (it is
-/// handed the caster and the target, not the tick, because its other call site has no tick).
+/// Which endpoint a periodic tick's formatter hands its msg-id selector, choosing
+/// `SPELL_PERIODIC_SELF_*` or `…_CREATURE_*`. `0x628100` (`PERIODICAURADAMAGE`) and `0x627240`
+/// (`PERIODICAURAHEAL`) hand the target (`0x628235`, `0x62732c`); `0x627520` (`POWERGAIN`) and
+/// `0x627930` (`SPELLPOWERLEECH`/`…DRAIN`) the caster (`0x6275fb`, `0x627a0f`/`0x627a3a`).
+/// [`power_drain_line`] applies the `ManaLeech` row directly.
 fn periodic_subject(tick: &PeriodicTick, caster: UnitClass, target: UnitClass) -> UnitClass {
     match tick {
         PeriodicTick::Damage { .. } | PeriodicTick::Heal { .. } => target,
@@ -1078,12 +941,8 @@ fn periodic_subject(tick: &PeriodicTick, caster: UnitClass, target: UnitClass) -
     }
 }
 
-/// Arm 5 of `0x627930`: **a real multiplier says the caster gained what the target lost**.
-///
-/// `6279ff fcomp dword ptr [0x8029d4]` against `|multiplier|`, and `[0x8029d4]` is `2^-22`
-/// (`00 00 80 34`) — the reference's own epsilon, not a round number of ours. The compare's `jp`
-/// takes the greater-or-equal side, so **equality is a leech**; only a strictly smaller magnitude
-/// is the plain `SPELLPOWERDRAIN`.
+/// Arm 5 of `0x627930`: a real multiplier means the caster gained what the target lost.
+/// `0x6279ff` compares `|multiplier|` with `[0x8029d4]` = `2^-22`, and equality is a leech.
 fn leech_family(multiplier: f32) -> Family {
     if multiplier.abs() >= LEECH_EPSILON {
         combat::SPELLPOWERLEECH
@@ -1092,21 +951,9 @@ fn leech_family(multiplier: f32) -> Family {
     }
 }
 
-/// The `(drained, gained)` pair a leech/drain sentence words, or `None` when the line is dropped.
-///
-/// One function because the reference has one formatter: `0x627930` serves both
-/// `SMSG_SPELLLOGEXECUTE` effect 8 `POWER_DRAIN` and `SMSG_PERIODICAURALOG` aura 64, and the three
-/// rules are its own — `drained = amount / div`, `gained = round(amount·multiplier) / div` (the
-/// product is reduced to an integer *before* the divide, which is why this is arithmetic and not
-/// two divides), and **`drained == 0` drops the line** (`627ae3 test esi,esi`).
-///
-/// **The two figures do not share their arithmetic**, which 2117 recorded as one `trunc`.
-/// `drained` is a plain signed integer divide of the wire amount (`627ad9 idiv`), no FPU at all.
-/// `gained` goes through the x87: the product is doubled, biased by ∓0.5 on its own sign,
-/// `fistp`-ed under the default round-half-to-even, and arithmetic-shifted back down
-/// (`627a8f`..`627ac9`) — a hand-rolled rounding that, for the non-negative products a leech
-/// actually produces, lands on exactly `floor(p)`, i.e. the truncation the record claimed. So the
-/// figures are unchanged and the *mechanism* named here is the byte's, not a paraphrase of it.
+/// The `(drained, gained)` pair a leech or drain sentence words, or `None` when the line drops.
+/// `drained` is an integer divide of the wire amount (`0x627ad9 idiv`), and zero drops the line
+/// (`0x627ae3`); `gained` is [`rounded_product`] divided the same way.
 fn leech_figures(power: u32, amount: u32, multiplier: f32) -> Option<(i64, i64)> {
     let div = power_divisor(power);
     let drained = i64::from(amount) / div;
@@ -1118,73 +965,38 @@ fn leech_figures(power: u32, amount: u32, multiplier: f32) -> Option<(i64, i64)>
     })
 }
 
-/// `627a8f`..`627ac9` — the product `amount · multiplier`, reduced to an integer the way the
-/// reference reduces it, which is not `as i64` and not `__ftol`.
-///
-/// `fild` the amount, `fmul` the f32 multiplier, then **`fst dword [ebp-0x10]` rounds the product
-/// to f32** (`0x627a95`) — that narrowing is real and is why this is not done in `f64`. The
-/// reduction is then a hand-rolled round-half-away-from-zero: double it, bias by ∓0.5 on the
-/// product's own sign (`0x627aa5`/`0x627ab5`, against `[0x8628f4] = 0.5`), `fistp` under the
-/// default round-half-to-even, and `sar 1` back down (`0x627ac9`).
-///
-/// For the non-negative products a leech actually produces this lands on `floor(p)` — the
-/// truncation 2117 recorded — so the figures are the same and only the edges differ. The edges
-/// are the point: at f32 precision an `f64` product can round to the other side of an integer,
-/// and the whole family exists so an addon reads the same number off our log as off the
-/// reference's.
+/// `amount * multiplier` reduced to an integer as `0x627a8f`..`0x627ac9` does it: the product is
+/// narrowed to f32 (`fst`, `0x627a95`), doubled, biased by -0.5 or +0.5 on its sign
+/// (`0x627aa5`/`0x627ab5`, `[0x8628f4] = 0.5`), `fistp`-ed half-to-even and shifted right one
+/// (`0x627ac9`). For a non-negative product that is `floor`; the f32 narrowing shows at the
+/// edges.
 fn rounded_product(amount: u32, multiplier: f32) -> i32 {
     let product = (f64::from(amount) * f64::from(multiplier)) as f32; // the `fst` narrowing
     let biased = f64::from(product).mul_add(2.0, if product < 0.0 { 0.5 } else { -0.5 });
-    // `fistp` truncates to i32 under the default control word: round half to even.
+    // `fistp` under the default control word: round half to even.
     (biased.round_ties_even() as i32) >> 1
 }
 
-/// The periodic handler's **pre-divide** — `0x627126`/`0x627138` scales the tick's amount by
-/// `0x6e7130(powerType)` *before* handing it to `0x627930`, which then divides by the very same
-/// table again.
-///
-/// It is a reference bug, and we reproduce it deliberately. The positive control is its own
-/// sibling: the energize tick pre-divides identically at `0x627087` and `0x627520` contains no
-/// divide at all, so the double is specific to aura 64. Reproduced because this family exists to
-/// be *read* — MikScrollingBattleText parses these sentences, and a number that disagrees with the
-/// reference's is the bug, whichever client is arithmetically right. It is the same posture
-/// [`spell_log_miss`] already takes toward `0x5e7f31`'s chat type.
-///
-/// Mana is unaffected by construction (divisor 1, so the second divide is the identity), which is
-/// every leech anyone has looked at; a periodic rage leech would come out at a hundredth. Whether
-/// any 1.12 aura-64 row names a non-mana power is **not measured here**.
+/// The periodic handler's pre-divide: `0x627126`/`0x627138` scales the tick by
+/// `0x6e7130(powerType)` before `0x627930` divides by the same table again. A reference bug,
+/// reproduced so the sentence's number matches (addons parse these lines). Mana's divisor is 1,
+/// so only a non-mana leech is affected.
 fn periodic_leech_amount(power: u32, amount: u32) -> u32 {
     (i64::from(amount) / power_divisor(power)) as u32
 }
 
-/// `0x627930` — **the** power leech/drain formatter, for both of its call sites.
+/// `0x627930`, the power leech and drain formatter: `SMSG_PERIODICAURALOG` aura 64 enters through
+/// `0x627910` with the periodic flag set, `SMSG_SPELLLOGEXECUTE` effect 8 with it clear.
 ///
-/// One function because the reference has one function. `SMSG_PERIODICAURALOG` aura 64 enters it
-/// through `0x627910` with the periodic flag **set**; `SMSG_SPELLLOGEXECUTE` effect 8
-/// `POWER_DRAIN` enters it with the flag **clear**; everything between the two entries is shared.
-/// Ours were two arms that had drifted apart — the execute-log one forked three ways and the
-/// periodic one worded `SPELLPOWERLEECH` unconditionally, which 2117 named as residue and 2157
-/// closes.
-///
-/// The arms, in the order the bytes test them (read off `0x627930` this session):
-///
-/// 1. **`powerType == 4` → `0x627de0`**, the *first* test in the function (`62793c cmp edi,4`).
-///    It is a **fall-through, not a diversion**: `627953 test al,al` / `627955 jne` leaves only
-///    when `0x627de0` actually emitted, so a happiness drain whose pet→owner chain does not
-///    resolve carries on down the generic path and words `SPELLPOWERLEECH`/`…DRAIN` with the
-///    `HAPPINESS_POINTS` noun.
-/// 2. **`powerType >= 5` → no line**, and the gate is `0x6278f0`'s own `cmp ecx,5; jae` answering
-///    NULL for the power noun (`627964 test edi,edi` / `627966 je`) — *not* the four `0x64a4c0`
-///    name compares much further down, which run after the emit. The compare is **unsigned**, so
-///    a negative tag drops here too. Ours is [`combat::power_word`] answering `None`.
-/// 3. the spell gates — `SpellRec+0x18 & 0x180` and an empty localized name — which are the
-///    caller's [`ChatCtx::spell_name`], already run before we get here.
-/// 4. the shared resolve + range gate `0x626630`, which is [`queue`]'s.
-/// 5. **the LEECH/DRAIN fork** on `|multiplier| >= 2^-22` (`6279ff fcomp [0x8029d4]`; the `jp`
-///    takes greater-or-equal, so equality is a leech).
-/// 6. **the periodic flag picks the chat-type stub** — `0x627d60` periodic, `0x627d30` direct —
-///    and only here, *after* the fork.
-/// 7. **`drained == 0` drops the line** (`627ae3 test esi,esi` / `627ae5 je`), after the divide.
+/// The arms, in the order the bytes test them:
+/// 1. `powerType == 4` tries `0x627de0` first (`0x62793c`), and leaves only if it emitted
+///    (`0x627955`); otherwise a happiness drain words the generic line with `HAPPINESS_POINTS`.
+/// 2. `powerType >= 5`, unsigned, has no power noun (`0x6278f0`, `0x627966`): no line.
+/// 3. The spell gates, the caller's [`ChatCtx::spell_name`].
+/// 4. The resolve and range gate `0x626630`, [`queue`]'s.
+/// 5. The leech/drain fork, [`leech_family`].
+/// 6. The periodic flag picks the chat-type stub, `0x627d60` periodic or `0x627d30` direct.
+/// 7. `drained == 0` drops the line (`0x627ae5`), after the divide.
 fn power_drain_line(
     log: &mut ChatLog,
     ctx: &ChatCtx,
@@ -1199,11 +1011,11 @@ fn power_drain_line(
     multiplier: f32,
     periodic: bool,
 ) {
-    // Arm 1. The happiness sentence is tried first and only *consumes* the packet when it emits.
+    // Arm 1: the happiness sentence consumes the packet only when it emits.
     if power == POWER_HAPPINESS && happiness_drain_line(log, ctx, stores, poses, target, amount) {
         return;
     }
-    // Arm 2. `0x6278f0`'s bound, expressed where the noun is: no noun, no line.
+    // Arm 2: no noun, no line.
     if !combat::power_has_word(power) {
         return;
     }
@@ -1212,15 +1024,10 @@ fn power_drain_line(
         return;
     };
     let family = leech_family(multiplier);
-    // Arm 6. Both stubs ask the SPELL, not the family: `0x627d30` is
-    // `call 0x6ea280; cmp eax,2; je -> 0x626be0 (damage) else 0x627820 (buff)` and `0x627d60` is
-    // its periodic twin over `0x627d80`/`0x6274a0`. So a
-    // helpful drain files under `…_BUFF` and a harmful one under `…_DAMAGE`, which is a property
-    // of the row in `Spell.dbc` and not something either call site may hardcode — both of ours
-    // did, in opposite directions.
+    // Arm 6: both stubs ask the spell, `0x6ea280 == 2` (`0x627d30` to `0x626be0` damage or
+    // `0x627820` buff; `0x627d60` over `0x627d80`/`0x6274a0`), so a helpful drain is `…_BUFF`.
     let buff = !ctx.spell_harmful(spell_id);
-    // The periodic stub hands its selector `outClassA`, the **caster** (`0x627a0f`/`0x627a3a`) —
-    // the row [`periodic_subject`] records for this tick kind.
+    // The periodic stub hands its selector the caster (`0x627a0f`/`0x627a3a`).
     let kind = if periodic {
         combat::periodic_kind(caster.1, buff)
     } else {
@@ -1248,17 +1055,9 @@ fn power_drain_line(
     );
 }
 
-/// `0x627de0` — the happiness sentence, and the one arm of `0x627930` that is not about a power
-/// noun at all: the subject is the pet's **owner**, the named thing is the **pet**, and the chat
-/// type is the literal `0x19` misc-info rather than anything a selector picks.
-///
-/// **Answers whether it emitted**, because that is the byte's own contract: `0x627930` tests the
-/// returned `al` and only stops when it is set, so a pet whose owner chain does not resolve is not
-/// a dropped line — it is a line that comes out of the generic leech/drain path instead.
-///
-/// The divisor is unconditionally happiness's own 1000 (`627f45 mov ecx,4`), which is what
-/// [`power_divisor`] answers for tag 4, so the figure is [`leech_figures`]'s `drained` by another
-/// route.
+/// `0x627de0`, the happiness sentence: the subject is the pet's owner, the named thing the pet,
+/// the chat type the literal `0x19` misc-info. Returns whether it emitted, since `0x627930` falls
+/// through to the generic path when it did not. The divisor is happiness's 1000 (`0x627f45`).
 fn happiness_drain_line(
     log: &mut ChatLog,
     ctx: &ChatCtx,
@@ -1268,7 +1067,7 @@ fn happiness_drain_line(
     amount: u32,
 ) -> bool {
     let Some(owner) = unit_owner(pet.0, ctx, stores) else {
-        return false; // the `+0x110` pet→owner chain did not resolve — fall through, not drop
+        return false; // the `+0x110` pet-to-owner chain did not resolve: fall through
     };
     let owner_class = ctx.classify(owner, stores);
     queue_reported(
@@ -1287,8 +1086,7 @@ fn happiness_drain_line(
     )
 }
 
-/// A unit's owner guid — `CHARMEDBY` first, then `CREATEDBY`, the same pair
-/// [`combat::classify`] reads. `None` when the unit is not streamed or owns itself.
+/// A unit's owner guid, `CHARMEDBY` then `CREATEDBY`, the pair [`combat::classify`] reads.
 fn unit_owner(guid: u64, ctx: &ChatCtx, stores: &Query<&mut ObjectStore>) -> Option<u64> {
     let entity = ctx.index.0.get(&guid).copied()?;
     let store = stores.get(entity).ok()?;
@@ -1298,14 +1096,11 @@ fn unit_owner(guid: u64, ctx: &ChatCtx, stores: &Query<&mut ObjectStore>) -> Opt
         .or_else(|| store.0.unit_created_by())
 }
 
-/// `SMSG_ENVIRONMENTALDAMAGELOG` → "You fall and lose %d health." and its five siblings.
-///
-/// **The only family with no selector at all.** `0x62aac0` builds the key by `snprintf` over a
-/// 6-entry damage-type table and a plain SELF/OTHER, and calls the melee HITS msg-id selector with
-/// **`ecx = edx = victimClass`** — so a fall on a party member types as `HOSTILEPLAYER_HITS`
-/// through that selector's tgt<=3 override, which looks wrong and is what the reference does.
-///
-/// It grows trailers (absorb/resist/vulnerability), which is how a resisted fire tick reads.
+/// `SMSG_ENVIRONMENTALDAMAGELOG`: "You fall and lose %d health." and its five siblings.
+/// `0x62aac0` builds the key from a six-entry damage-type table and SELF/OTHER, and calls the
+/// melee HITS selector with the victim's class in both positions, so a party member's fall types
+/// as `HOSTILEPLAYER_HITS` through the selector's tgt<=3 override, as in the reference. It takes
+/// absorb and resist trailers.
 pub(super) fn environmental_damage_log(
     e: EnvironmentalDamageLog,
     ctx: &ChatCtx,
@@ -1333,8 +1128,7 @@ pub(super) fn environmental_damage_log(
             trailers: Some(combat::Trailers {
                 absorbed: e.absorb,
                 resisted: e.resist,
-                // The environmental call site passes zero for both — it has no wire source for a
-                // block or a HitInfo, so GLANCING/CRUSHING/BLOCK can never appear on these lines.
+                // The environmental call site passes zero for both.
                 blocked: 0,
                 hit_info: 0,
             }),
@@ -1343,18 +1137,10 @@ pub(super) fn environmental_damage_log(
     );
 }
 
-/// `SMSG_SET_FACTION_STANDING` → "Your %s reputation has increased by %d."
-///
-/// **The wire carries the new TOTAL, and the sentence wants the DELTA** — so this runs before the
-/// store is overwritten, and a slot whose value did not actually move prints nothing (the
-/// reference's own `0x62c5f0` guard: "only when the stored value actually changed").
-///
-/// It is one of the twelve formatters with **no range gate and no classifier** — the chat type is
-/// the literal `0x55` `COMBAT_FACTION_CHANGE`, and the only participant is you — so it builds its
-/// line directly rather than going through [`queue`], which exists to gate on two endpoints.
-///
-/// The wire's `reputationListId` is `Faction.dbc`'s `rep_index`, not a faction id; the name comes
-/// off the row that carries that index.
+/// `SMSG_SET_FACTION_STANDING`: "Your %s reputation has increased by %d.". The wire carries the
+/// new total and the sentence the delta, so this runs before the store is overwritten, and an
+/// unchanged value prints nothing (`0x62c5f0`). No range gate or classifier: the chat type is the
+/// literal `0x55` `COMBAT_FACTION_CHANGE`. The wire's list id is `Faction.dbc`'s `rep_index`.
 pub(crate) fn faction_standing(
     deltas: &[(u32, i32)],
     reputations: &Reputations,
@@ -1390,8 +1176,7 @@ pub(crate) fn faction_standing(
             } else {
                 combat::FACTION_STANDING_DECREASED
             },
-            // A `Single` family reads no variant, but the field is not optional; `OtherOther` is
-            // the one `tests::variants_of` sweeps such a family with.
+            // A `Single` family reads no variant; `OtherOther` is what `tests::variants_of` sweeps.
             variant: combat::Variant::OtherOther,
             subject: 0,
             object: 0,
@@ -1406,9 +1191,8 @@ pub(crate) fn faction_standing(
     }
 }
 
-/// The one tail every arm ends in: build the queued line (dropping a class-9 endpoint) and park it
+/// The tail every arm ends in: build the queued line (dropping a class-9 endpoint) and park it
 /// for its names.
-// facts a queued line is made of. Bundling any of them would only move the list somewhere else.
 fn queue(
     log: &mut ChatLog,
     ctx: &ChatCtx,
@@ -1432,8 +1216,8 @@ fn queue(
     );
 }
 
-/// [`queue`] for a family whose `Named` slot still has to be looked up — an item entry or a unit
-/// guid rides along and the drain resolves it, holding the line until it lands (`0x6294b0`).
+/// [`queue`] for a family whose `Named` slot (an item entry or unit guid) the drain resolves,
+/// holding the line until it lands (`0x6294b0`).
 fn queue_named(
     log: &mut ChatLog,
     ctx: &ChatCtx,
@@ -1448,13 +1232,9 @@ fn queue_named(
     queue_reported(log, ctx, poses, kind, family, subject, object, fills, named);
 }
 
-/// [`queue_named`], answering **whether a line was actually queued**.
-///
-/// One caller reads the verdict and has to: `0x627de0` reports its success to `0x627930` in `al`
-/// (`mov al,1` at `0x627fb0`/`0x627fe2`/`0x627ff4` against `0x628006 xor al,al`), and a false
-/// there is a **fall-through** to the generic leech/drain path, not a dropped line. Both failure
-/// shapes below are among the ones the reference reports: its own range gate, and an empty
-/// template.
+/// [`queue_named`], answering whether a line was queued: `0x627de0` reports it to `0x627930` in
+/// `al` (set at `0x627fb0`/`0x627fe2`/`0x627ff4`, cleared at `0x628006`), and a failed range gate
+/// or empty template is a fall-through there.
 fn queue_reported(
     log: &mut ChatLog,
     ctx: &ChatCtx,
@@ -1466,10 +1246,7 @@ fn queue_reported(
     fills: Fills,
     named: combat::Named,
 ) -> bool {
-    // **The gate is an OR over the two endpoints, not an AND** — `0x626630`'s own test:
-    // `dist²(player, src) < range(srcClass)²` **OR** `dist²(player, tgt) < range(tgtClass)²`. 1571
-    // required both and therefore dropped lines the client shows: your own pet (range 100000)
-    // fighting something 80 yards away is logged by the reference and was silent here.
+    // An OR, not an AND (`0x626630`): either endpoint within its class's range shows the line.
     if !ctx.in_range(subject.0, subject.1, poses) && !ctx.in_range(object.0, object.1, poses) {
         return false;
     }
@@ -1487,14 +1264,8 @@ mod tests {
         rounded_product, PeriodicTick, UnitClass,
     };
 
-    /// **A periodic line is typed off the endpoint its own formatter reads** (decision 2127).
-    ///
-    /// The report: MikScrollingBattleText showed no DoT lines at all, in either direction. Every
-    /// periodic tick took `periodic_kind(caster, …)`, so a creature's poison ticking you came out
-    /// as `CHAT_MSG_SPELL_PERIODIC_CREATURE_DAMAGE` where the reference sends
-    /// `…_PERIODIC_SELF_DAMAGE`, and your own DoT on a creature came out the other way round —
-    /// the two swapped. MSBT matches a different GlobalString pattern per event name, so with
-    /// both events swapped neither line matched anything and both were dropped.
+    /// A periodic line is typed off the endpoint its own formatter reads: a creature's DoT on you
+    /// is `…_PERIODIC_SELF_DAMAGE`, yours on a creature `…_PERIODIC_CREATURE_DAMAGE`.
     #[test]
     fn a_periodic_damage_or_heal_tick_is_typed_off_the_target() {
         let dmg = PeriodicTick::Damage {
@@ -1504,12 +1275,12 @@ mod tests {
             resist: 0,
         };
         let heal = PeriodicTick::Heal { amount: 12 };
-        // A creature's DoT ticking me: the subject is ME, so the line types SELF.
+        // A creature's DoT ticking me types SELF.
         assert_eq!(
             periodic_subject(&dmg, UnitClass::Creature, UnitClass::Me),
             UnitClass::Me
         );
-        // My DoT ticking a creature: the subject is the CREATURE.
+        // My DoT ticking a creature types CREATURE.
         assert_eq!(
             periodic_subject(&dmg, UnitClass::Me, UnitClass::Creature),
             UnitClass::Creature
@@ -1518,7 +1289,7 @@ mod tests {
             periodic_subject(&heal, UnitClass::Creature, UnitClass::Me),
             UnitClass::Me
         );
-        // The other two formatters read the CASTER, which is why this is a table and not a rule.
+        // The other two formatters read the caster.
         let gain = PeriodicTick::Energize {
             power: 1,
             amount: 10,
@@ -1538,21 +1309,14 @@ mod tests {
         );
     }
 
-    /// The report this arithmetic was written for: MSBT read `+10 Rage` off our combat log where
-    /// the reference reads `+1 Rage`, for the same swing against the same server.
-    ///
-    /// The wire number really is ten. `Unbridled Wrath Effect` (12964) is
-    /// `effect1 = 30 SPELL_EFFECT_ENERGIZE`, `effectMiscValue1 = 1 POWER_RAGE`,
-    /// `effectBasePoints1 = 9` — base points are *n − 1*, so vmangos energizes by **10** and
-    /// `SendEnergizeSpellLog` ships that same 10 (`SpellCaster.cpp:796-813`, it logs exactly what
-    /// it hands `ModifyPower`, and the stored rage field is the ×10 one). Rage is the only power a
-    /// player can gain where raw and displayed differ, which is why it is the one that was seen.
+    /// A rage gain words the displayed figure. `Unbridled Wrath Effect` (12964) energizes rage by
+    /// base points 9 + 1 = 10 on the rage field's ×10 scale, and `SendEnergizeSpellLog` sends that
+    /// 10 (`SpellCaster.cpp:796-813`); the line reads 1.
     #[test]
     fn a_rage_gain_words_the_displayed_figure_not_the_wire_one() {
         assert_eq!(power_gain(1, 10), 1, "Unbridled Wrath: one point of rage");
         assert_eq!(power_gain(1, 100), 10, "Bloodrage: ten");
-        // Every other power a POWERGAIN line can name is one-to-one, so the divide has to be a
-        // table lookup and not an `if rage` — mana, focus and energy must come through untouched.
+        // Mana, focus and energy are one-to-one.
         assert_eq!(power_gain(0, 300), 300);
         assert_eq!(power_gain(2, 20), 20);
         assert_eq!(power_gain(3, 20), 20);
@@ -1563,24 +1327,16 @@ mod tests {
     fn a_leech_divides_both_figures_and_drops_a_zero_drained_line() {
         // Mana leeches one-to-one: 120 drained, half of it gained.
         assert_eq!(leech_figures(0, 120, 0.5), Some((120, 60)));
-        // The truncation ORDER is observable, and only on a scaled power: the reference truncates
-        // the product and divides after (`trunc(25 · 0.9) = 22`, `22 / 10 = 2`). Dividing first
-        // would give `(25 / 10) · 0.9 = 1`, and nothing downstream would notice the off-by-one.
+        // The product is truncated, then divided: `trunc(25 * 0.9) = 22`, `22 / 10 = 2`, not 1.
         assert_eq!(leech_figures(1, 25, 0.9), Some((2, 2)));
-        // Below one displayed point there is no line at all — the reference's own `drained == 0`
-        // test, which only a scaled power can reach with a nonzero wire amount.
+        // Below one displayed point, `drained == 0` drops the line.
         assert_eq!(leech_figures(1, 9, 1.0), None);
         assert_eq!(leech_figures(0, 0, 1.0), None);
-        // Happiness is the ×1000 arm; a pet's 1500 raw is one displayed point.
+        // Happiness is ×1000: 1500 raw is one displayed point.
         assert_eq!(leech_figures(4, 1500, 0.0), Some((1, 0)));
     }
 
-    /// The LEECH/DRAIN fork the periodic arm did not have — one formatter, and until 2157 its two
-    /// call sites disagreed about every choice it makes.
-    ///
-    /// The epsilon is the reference's own `[0x8029d4] = 2^-22`, and the compare's `jp` takes the
-    /// greater-or-equal side, so a multiplier sitting exactly on it is a **leech**. That boundary
-    /// is the whole reason this is a named function and not an `if multiplier != 0.0`.
+    /// The leech/drain fork on `[0x8029d4] = 2^-22`: a multiplier exactly on it is a leech.
     #[test]
     fn the_leech_drain_fork_is_the_references_own_epsilon() {
         const EPS: f32 = 1.0 / 4_194_304.0;
@@ -1592,17 +1348,13 @@ mod tests {
         );
         assert_eq!(leech_family(EPS / 2.0).stem, "SPELLPOWERDRAIN");
         assert_eq!(leech_family(0.0).stem, "SPELLPOWERDRAIN");
-        // `fabs` first: the sign is not the question the reference asks.
+        // `fabs` first: the sign does not matter.
         assert_eq!(leech_family(-1.0).stem, "SPELLPOWERLEECH");
     }
 
-    /// `0x6278f0`'s table is five entries, not four — **happiness has a noun**.
-    ///
-    /// `cmp ecx,5; jae` is the bound, and it is unsigned. We stopped the table at energy and
-    /// called happiness "no GlobalString", which silently dropped every line the reference words
-    /// with `HAPPINESS_POINTS = "Happiness"` (shipped enUS `GlobalStrings.lua:2117`): the generic
-    /// leech/drain fall-through out of `0x627de0`, and a happiness `POWERGAIN` tick. What
-    /// happiness actually lacks is a `COMBAT_TEXT_UPDATE` tag, which is a different table.
+    /// `0x6278f0`'s table has five entries, happiness included (`HAPPINESS_POINTS`,
+    /// `GlobalStrings.lua:2117`), bounded by an unsigned `cmp ecx,5; jae`. Happiness lacks only a
+    /// `COMBAT_TEXT_UPDATE` tag.
     #[test]
     fn every_wire_power_tag_has_a_noun_and_nothing_past_the_table_does() {
         for power in 0..=4 {
@@ -1613,15 +1365,8 @@ mod tests {
         }
     }
 
-    /// The gained figure is reduced to an integer the way `0x627930` reduces it — through an
-    /// **f32** product, not an `f64` one.
-    ///
-    /// The first two cases are the arithmetic anyone would write anyway. The third is the
-    /// mechanism: `fst dword [ebp-0x10]` at `0x627a95` narrows the product to f32 before the
-    /// rounding, and 2^24+1 is the smallest amount where that narrowing is visible — the f64
-    /// product is exact and the f32 one rounds to even, one below. No leech ships an amount that
-    /// large; the case is here because it is the only thing that can tell the two implementations
-    /// apart, and an `as i64` over f64 silently passes everything else.
+    /// The gained figure goes through an f32 product (`0x627a95`); 2^24+1 is the smallest amount
+    /// where the narrowing shows, rounding to even one below.
     #[test]
     fn the_gained_figure_goes_through_the_references_f32_product() {
         assert_eq!(rounded_product(25, 0.9), 22, "floor, not round");
@@ -1633,17 +1378,13 @@ mod tests {
         );
     }
 
-    /// **The periodic leg divides twice, and we reproduce it.** `0x627126`/`0x627138` scales the
-    /// tick's amount by `0x6e7130(powerType)` before `0x627930` divides by the same table again.
-    ///
-    /// Mana cannot show it — divisor 1, so the second divide is the identity, and that is every
-    /// leech anyone has looked at. Rage can: a wire 100 is 10 through the pre-divide and 1 by the
-    /// time the sentence is written.
+    /// The periodic leg divides twice, as the reference does (`0x627126`/`0x627138`, then
+    /// `0x627930`): mana is unchanged, a wire 100 rage words as 1.
     #[test]
     fn a_periodic_leech_is_pre_divided_before_the_formatter_divides_again() {
         assert_eq!(periodic_leech_amount(0, 400), 400, "mana: the identity");
         assert_eq!(periodic_leech_amount(1, 100), 10, "rage: the first divide");
-        // End to end on the rage case: 100 on the wire words as 1, not 10 and not 100.
+        // End to end: 100 rage on the wire words as 1.
         assert_eq!(
             leech_figures(1, periodic_leech_amount(1, 100), 1.0),
             Some((1, 1))
diff --git a/crates/benilla-app/src/combat_log/mod.rs b/crates/benilla-app/src/combat_log/mod.rs
index 71576b1d..a9f6c30a 100644
--- a/crates/benilla-app/src/combat_log/mod.rs
+++ b/crates/benilla-app/src/combat_log/mod.rs
@@ -1,15 +1,11 @@
-//! **The combat log** — the reference's own handler cluster for the combat packets (in the net
-//! handler table since 2323, moved out of the drain's `combat_chat` and `combat_log` arm files).
-//! Every combat packet has two consumers, and the reference emits both from one handler: the
-//! **chat line** ([`chat`], the `0x629b60` display dispatcher's text) and the **floating
-//! number** with the portrait's `UNIT_COMBAT` flash ([`text`], `0x629d30` →
-//! `COMBAT_TEXT_UPDATE`; `0x625010` is the melee blood spurt, not this). They are gated by different CVars and classify by different laws, which is why the
-//! legs are two files; they answer one packet, which is why the handler is one — the line first,
-//! the number second, as the drain's match ran them.
+//! The combat log: the handlers for the combat packets. The reference answers each packet from one
+//! handler with two consumers, the chat line ([`chat`], the display dispatcher `0x629b60`) and the
+//! floating number with the portrait's `UNIT_COMBAT` flash ([`text`]; `0x629d30` fires
+//! `COMBAT_TEXT_UPDATE`); they run in that order. The two legs have different CVar gates and
+//! classification rules.
 //!
-//! Two packets have a third consumer: the completed swing and the environmental-damage log also
-//! drive the animation layer, whose handlers ([`crate::creature_anim::net`]) are registered after
-//! these, so a kind with two handlers runs the line, then the animation.
+//! The completed swing and the environmental-damage log also drive animation; those handlers
+//! ([`crate::creature_anim::net`]) register after these, so the line runs before the animation.
 
 use benilla_protocol::messages::SpellOutcomeLog;
 use benilla_protocol::{SessionEvent, SessionEventKind};
@@ -28,8 +24,7 @@ use crate::ui_unit::{CombatTextEvent, UnitCombatFeedback};
 pub(crate) mod chat;
 pub(crate) mod text;
 
-/// What the chat line classifies against — [`chat::ChatCtx`]'s inputs, built per packet by
-/// [`Ctx::ctx`]. Read-only, so a handler can hold it beside the mutable [`Sinks`].
+/// The chat line's read-only inputs, built into a [`chat::ChatCtx`] per packet.
 #[derive(SystemParam)]
 pub(crate) struct Ctx<'w> {
     self_guid: Res<'w, SelfGuid>,
@@ -59,11 +54,10 @@ impl Ctx<'_> {
     }
 }
 
-/// What the two legs read from the world and write to: the object stores and poses both legs
-/// resolve endpoints through, the chat log, the number's gates and its three sinks.
+/// What the two legs resolve endpoints through and write to.
 #[derive(SystemParam)]
 pub(crate) struct Sinks<'w, 's> {
-    /// `CombatDamage` + the two `Pet*` sub-gates.
+    /// `CombatDamage` and the two `Pet*` sub-gates.
     damage_text: Res<'w, DamageTextGates>,
     stores: Query<'w, 's, &'static mut ObjectStore>,
     poses: Query<'w, 's, &'static mut Transform>,
@@ -75,9 +69,8 @@ pub(crate) struct Sinks<'w, 's> {
     center: MessageWriter<'w, CombatTextEvent>,
 }
 
-/// The combat log's plugin — registration only; the two legs' state is the chat window's and the
-/// combat text's. Added ahead of [`crate::creature_anim::CreatureAnimPlugin`] so the two kinds
-/// both answer run the line before the animation.
+/// The combat log's handler registration. Added ahead of
+/// [`crate::creature_anim::CreatureAnimPlugin`], so a shared kind runs the line first.
 pub(crate) struct CombatLogPlugin;
 
 impl Plugin for CombatLogPlugin {
@@ -131,11 +124,8 @@ fn on_spell_damage_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
     }
 }
 
-/// **`CombatLogPeriodicSpells` gates the WHOLE packet body, and this handler is where that is
-/// expressible.** The reference's read site `0x626dee` is the first thing the handler `0x626dd0`
-/// does, and a zero jumps to the bare epilogue `0x6271b4`: no chat line, no floating tick number,
-/// no periodic miss word. Gating inside either leg would model it as two filters; it is one gate
-/// over both.
+/// `CombatLogPeriodicSpells` gates the whole packet: the handler `0x626dd0` reads it first
+/// (`0x626dee`) and a zero jumps to the epilogue `0x6271b4`, so no line, number or word.
 fn on_periodic_aura_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
     if let SessionEvent::PeriodicAuraLog(s) = ev {
         if !c.periodic.0 {
@@ -217,8 +207,7 @@ fn on_spell_log_miss(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
     }
 }
 
-// ── the combat log's completeness block (1703): every one of these is chat-only — they carry
-// no damage number, so unlike their neighbours above they have no floating-text leg to call ──
+// ── Chat-only packets: no damage number, so no floating-text leg ──
 
 fn on_party_kill_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
     if let SessionEvent::PartyKillLog(k) = ev {
@@ -313,12 +302,9 @@ fn on_level_up(In(ev): In<SessionEvent>, mut l: Sinks) {
     }
 }
 
-/// An honor award (decision 1512 — the arc's other inbound message, the inspect reply, is
-/// `ui_honor`'s own handler): the combat-log line (name-resolved, so it queues) and the floating
-/// number, which are two different surfaces of one packet and are both the reference's. A
-/// DISHONORABLE kill arrives here too, carrying NEGATIVE honor — the floating text takes it
-/// signed, because the shipped `COMBAT_TEXT_HONOR_GAINED` handler prefixes a "+" only when the
-/// number is positive and therefore already expects the other case.
+/// An honor award: the combat-log line (name-resolved, so it queues) and the `HONOR_GAINED`
+/// number. A dishonorable kill carries negative honor, passed signed: the stock handler prefixes
+/// "+" only to a positive number (`Blizzard_CombatText.lua:234`).
 fn on_pvp_credit(In(ev): In<SessionEvent>, mut l: Sinks) {
     if let SessionEvent::PvpCredit(credit) = ev {
         l.log.push_pvp_credit(
diff --git a/crates/benilla-app/src/combat_log/text.rs b/crates/benilla-app/src/combat_log/text.rs
index 6f0ee238..6933d626 100644
--- a/crates/benilla-app/src/combat_log/text.rs
+++ b/crates/benilla-app/src/combat_log/text.rs
@@ -1,18 +1,12 @@
-//! The combat log's **floating number** leg — the combat-text **spawn table** (decision 0137
-//! phase 2; the callers of `SubmitWorldText 0x6c7840`). One fn per packet, mirroring the client's
-//! handler → emitter structure; [`super`]'s handlers call it after the chat line: each classifies
-//! the damage **source** (the color law's `K` — self / owned-by-me / anything else SUPPRESSED),
-//! resolves the outcome **recipient**, applies Gate A (self-anchored damage text is
-//! unconditionally suppressed — outgoing damage floats over the victim, incoming never floats
-//! over you), picks the category + the effective color override, and writes a
-//! [`CombatTextSpawn`]. The XP emitter is the one exception (self-anchored, no gates, its own
-//! row color — by the client's design). The law itself — categories, words, colors, cap,
-//! timing — lives in [`crate::combat_text`].
+//! The combat log's floating-number leg: the callers of `SubmitWorldText` (`0x6c7840`), one fn
+//! per packet. Each classifies the damage source (self, owned by me, or anything else, which is
+//! never drawn), resolves the recipient, applies Gate A (no damage text over self), picks the
+//! category and colour and writes a [`CombatTextSpawn`]. XP is the exception: over self, no gates,
+//! its own row colour. The law itself lives in [`crate::combat_text`].
 //!
-//! Each spell arm ALSO feeds the **`UNIT_COMBAT` event** ([`UnitCombatFeedback`] — the portrait
-//! hit indicator, decision 0576) — that channel is the worldtext's inverse: **ungated** (no
-//! Gate A, no source class; it exists to show what anyone does to you), fired at packet receive.
-//! The melee arm's twin rides the swing impact keyframe instead (`ui_unit::melee_unit_combat`).
+//! Each spell arm also feeds `UNIT_COMBAT` ([`UnitCombatFeedback`], the portrait hit indicator),
+//! ungated and fired at packet receive; the melee arm's rides the swing impact keyframe instead
+//! (`ui_unit::melee_unit_combat`).
 
 use bevy::prelude::*;
 
@@ -30,8 +24,8 @@ use crate::ui_unit::{CombatTextEvent, UnitCombatFeedback};
 
 use crate::net::{GuidIndex, NetCommands, ObjectStore, SelfGuid};
 
-/// Gate A + anchor resolution: the recipient's entity, unless the recipient is us (`0x607140`/
-/// `0x6128b0` compare the anchor guid to the active-player cache and return before submitting).
+/// Gate A: the recipient's entity, unless the recipient is us (`0x607140` and `0x6128b0` compare
+/// the anchor guid to the active player and return before submitting).
 fn gated_anchor(guid: u64, index: &GuidIndex, self_guid: &SelfGuid) -> Option<Entity> {
     if self_guid.0 == Some(guid) {
         return None;
@@ -39,10 +33,9 @@ fn gated_anchor(guid: u64, index: &GuidIndex, self_guid: &SelfGuid) -> Option<En
     index.0.get(&guid).copied()
 }
 
-/// The `0x5efea0` source-ownership classifier (the color law's `K`): the damage SOURCE resolved
-/// against the active player — `Player` (me), `Pet` (a unit whose Summoned/CreatedBy guid is me:
-/// pet, guardian, totem), or `None` = every other class, which SUPPRESSES the emit entirely
-/// (another unit's damage is never drawn; the real emitter returns before submitting).
+/// The source-ownership classifier `0x5efea0` (the colour law's `K`): `Player` for me, `Pet` for a
+/// unit whose SummonedBy or CreatedBy is me (pet, guardian, totem), `None` for anything else,
+/// whose damage is never drawn.
 pub(crate) fn classify_source(
     guid: u64,
     index: &GuidIndex,
@@ -59,22 +52,18 @@ pub(crate) fn classify_source(
         .then_some(DamageSource::Pet)
 }
 
-// NOTE: the MELEE number/word (`SMSG_ATTACKERSTATEUPDATE`) does not spawn here — it defers to the
-// attacker swing clip's impact keyframe with the rest of the victim feedback
-// (`crate::combat_text::melee_impact_text`, fed by `creature_anim::impact`).
+// The melee number and word (`SMSG_ATTACKERSTATEUPDATE`) spawn at the swing's impact keyframe
+// (`crate::combat_text::melee_impact_text`), not here.
 
-/// The color law's `B` bit for a spell-packet emit, over the catalog the arms carry: resolve the
-/// spell's record and hand it to [`crate::combat_text::melee_styled`] (which owns the law and its
-/// NULL-record degradation). This is how a ranged basic shot's `SMSG_SPELLNONMELEEDAMAGELOG`
-/// floats white (decision 0376) while an ordinary spell floats gold.
+/// The colour law's `B` bit for a spell-packet emit, from the spell's record via
+/// [`crate::combat_text::melee_styled`]: a ranged basic shot floats white, a spell gold.
 pub(super) fn melee_styled(spells: Option<&crate::ui_action::Spells>, spell_id: u32) -> bool {
     crate::combat_text::melee_styled(spells.and_then(|s| s.catalog.get(spell_id)))
 }
 
-/// The spell arms' shared `UNIT_COMBAT` split: a landed amount is `WOUND` (`CRITICAL` descriptor
-/// on crit), zero damage degrades to the full-`ABSORB`/`RESIST` descriptor, else nothing (a clean
-/// spell miss arrives via `SMSG_SPELLLOGMISS` instead). PROVISIONAL string mapping until the
-/// reference's UNIT_COMBAT emission is pinned down (decision 0576).
+/// The spell arms' `UNIT_COMBAT` action and descriptor: a landed amount is `WOUND` (`CRITICAL` on
+/// a crit); zero damage takes `ABSORB` before `RESIST`, the order the reference's emitter
+/// `0x494600` tests them (`0x49463b`); a clean miss arrives via `SMSG_SPELLLOGMISS` instead.
 fn spell_feedback(
     damage: u32,
     absorb: u32,
@@ -92,11 +81,9 @@ fn spell_feedback(
     }
 }
 
-/// Spell packet → the center text's messageType: landed damage is ALWAYS `SPELL_DAMAGE` — **a spell
-/// crit does NOT fire DAMAGE_CRIT** (no crit-distinct type exists for spell damage; the `0x62cd80`
-/// emitter fires 29 regardless, crit changes only the chat template) — zero damage the
-/// `SPELL_ABSORBED`/`SPELL_RESISTED` word. Spell-side partial trailers stay a named residual (the
-/// melee partials go through helper B `0x6268f0`; the spell emitter's partial path is unread).
+/// Spell packet to the centre text's messageType: landed damage is always `SPELL_DAMAGE`, crit or
+/// not (`0x62cd80` has no crit type); zero damage is the `SPELL_ABSORBED`/`SPELL_RESISTED` word.
+/// The reference's partial words on a landed spell hit are not built here.
 fn spell_center_text(
     damage: u32,
     absorb: u32,
@@ -113,12 +100,9 @@ fn spell_center_text(
     }
 }
 
-/// Melee packet → the center text's messageType + args (`0x629d30`; fired **synchronously at
-/// packet receive** — the impact-keyframe deferral belongs to the worldtext/UNIT_COMBAT victim
-/// dispatch, NOT this Lua event). Helper-B partials CONFIRMED: a landed hit with a partial
-/// block/absorb/resist fires the word type with `(damage, partial)` — the addon renders
-/// `"25 (10 blocked)"`. The partial-vs-crit precedence when both apply is unpinned — partials
-/// win here, flagged in 0580.
+/// Melee packet to the centre text's messageType and args (`0x629d30`), fired at packet receive,
+/// not at the impact keyframe. A landed hit with a partial block, absorb or resist fires that
+/// word with `(damage, partial)`, tested ahead of the crit.
 pub(crate) fn melee_center_text(
     hit_info: u32,
     victim_state: u32,
@@ -158,8 +142,7 @@ pub(crate) fn melee_center_text(
     }
 }
 
-/// vmangos `Powers` id → the center text's power-gain messageType (`MANA`/`RAGE`/`FOCUS`/
-/// `ENERGY`; happiness has no message type — the addon shows nothing for it).
+/// vmangos `Powers` id to the centre text's power-gain messageType; happiness has none.
 fn power_message_type(power: u32) -> Option<&'static str> {
     Some(match power {
         0 => "MANA",
@@ -170,10 +153,9 @@ fn power_message_type(power: u32) -> Option<&'static str> {
     })
 }
 
-/// `SMSG_SPELLNONMELEEDAMAGELOG` → the spell-damage number (crit on `SPELL_HIT_TYPE_CRIT 0x2`) or
-/// the zero-damage ABSORB/RESIST word, over the target (`0x5e85e0`). Source-classified: only my
-/// (gold) or my pet's (gold, PetSpellDamage-gated) spells draw. The handler pushes the same
-/// record/source to number and word twin alike, so the override colors both.
+/// `SMSG_SPELLNONMELEEDAMAGELOG`: the spell-damage number (crit on `SPELL_HIT_TYPE_CRIT` `0x2`) or
+/// the zero-damage absorb or resist word over the target (`0x5e85e0`); only my spells and my
+/// pet's (`PetSpellDamage`-gated) draw, number and word coloured alike.
 pub(super) fn spell_damage_log(
     s: SpellDamageLog,
     index: &GuidIndex,
@@ -197,8 +179,7 @@ pub(super) fn spell_damage_log(
             ),
         );
     }
-    // The ungated UNIT_COMBAT feed (portrait hit indicator): any source, any recipient — self
-    // included — before the worldtext path's source/Gate-A returns below.
+    // UNIT_COMBAT: any source, any recipient including self, before the returns below.
     if let (Some(&unit), Some((action, flags))) = (
         index.0.get(&s.target),
         spell_feedback(s.damage, s.absorb, s.resist, s.hit_info & 0x2 != 0),
@@ -211,7 +192,7 @@ pub(super) fn spell_damage_log(
             school: u32::from(s.school),
         });
     }
-    // The center combat text (decision 0578): self recipient only.
+    // The center combat text: self recipient only.
     if self_guid.0 == Some(s.target) {
         if let Some((message_type, data)) = spell_center_text(s.damage, s.absorb, s.resist) {
             center.write(CombatTextEvent {
@@ -224,8 +205,7 @@ pub(super) fn spell_damage_log(
     let Some(source) = classify_source(s.attacker, index, self_guid, stores) else {
         return; // K = other: never drawn
     };
-    // B = the melee-styled bit: a ranged basic shot (Throw/Auto Shot — AttributesEx3 & 0x8000)
-    // floats WHITE off this spell packet, exactly like the client (decision 0376).
+    // A ranged basic shot (Throw, Auto Shot: `AttributesEx3 & 0x8000`) floats white.
     let Some(color) = damage_color(gates, source, melee_styled(spells, s.spell_id)) else {
         return; // the CombatDamage / PetSpellDamage gates
     };
@@ -242,8 +222,8 @@ pub(super) fn spell_damage_log(
     }
 }
 
-/// `SMSG_PERIODICAURALOG` → DoT ticks float like direct damage (`0x626dd0`, never crit-category);
-/// heal/energize/leech ticks float **nothing** (heals never float in 5875).
+/// `SMSG_PERIODICAURALOG`: damage ticks float like direct damage, never as a crit (`0x626dd0`);
+/// heal, energize and leech ticks float nothing, as heals never float in the 1.12 client.
 pub(super) fn periodic_aura_log(
     s: PeriodicAuraLog,
     index: &GuidIndex,
@@ -268,9 +248,8 @@ pub(super) fn periodic_aura_log(
             ),
         );
     }
-    // The center combat text (decision 0578): self recipient only — damage ticks like direct
-    // damage, heal ticks PERIODIC_HEAL (arg2 = the caster's name, arg3 = amount; the name only
-    // displays under COMBAT_TEXT_SHOW_FRIENDLY_NAMES), energize ticks the power-gain family.
+    // Centre text, self recipient only: damage ticks as direct damage, heal ticks `PERIODIC_HEAL`
+    // (arg2 the caster's name, arg3 the amount), energize ticks the power-gain family.
     if self_guid.0 == Some(s.target) {
         for tick in &s.ticks {
             let ev = match *tick {
@@ -296,10 +275,8 @@ pub(super) fn periodic_aura_log(
                     ),
                     extra: Some(amount.to_string()),
                 }),
-                // The displayed figure, not the wire's — `0x626dd0` divides by
-                // `0x6e7130(powerType)` at `0x627087` **before** it pushes the COMBAT_TEXT tag
-                // (`0x494770`) and before it words the chat line, so both consumers see the same
-                // number (decision 2117).
+                // The displayed figure: `0x626dd0` divides by `0x6e7130(powerType)` at `0x627087`
+                // before both the COMBAT_TEXT push (`0x494770`) and the chat line.
                 PeriodicTick::Energize { power, amount } => {
                     power_message_type(power).map(|message_type| CombatTextEvent {
                         message_type,
@@ -314,9 +291,8 @@ pub(super) fn periodic_aura_log(
             }
         }
     }
-    // The ungated UNIT_COMBAT feed: every tick, any source. Damage WOUNDs; heal/energize fire
-    // their own actions — they never float as worldtext in 5875, but the portrait indicator is
-    // exactly where the green/blue numbers live (CombatFeedback.lua's HEAL/ENERGIZE arms).
+    // UNIT_COMBAT: every tick, any source; damage is `WOUND`, a heal `HEAL`, which shows on the
+    // portrait though heals never float as worldtext.
     if let Some(&unit) = index.0.get(&s.target) {
         for tick in &s.ticks {
             let (action, flags, amount, school) = match *tick {
@@ -333,8 +309,8 @@ pub(super) fn periodic_aura_log(
                     (action, flags, amount, school)
                 }
                 PeriodicTick::Heal { amount } => ("HEAL", "", amount, 0),
-                // NO ENERGIZE: 5875 never emits it (the string is absent binary-wide); the power
-                // gain reaches the center text only.
+                // No ENERGIZE: the string is absent from the 1.12 client; power reaches the centre
+                // text only.
                 PeriodicTick::Energize { .. } | PeriodicTick::ManaLeech { .. } => continue,
             };
             feedback.write(UnitCombatFeedback {
@@ -349,8 +325,7 @@ pub(super) fn periodic_aura_log(
     let Some(source) = classify_source(s.caster, index, self_guid, stores) else {
         return; // K = other: never drawn
     };
-    // Same B computation as the direct-damage emit (the periodic emitter `0x626dd0` pushes the
-    // resolved record to the same `0x6128b0` law).
+    // `0x626dd0` pushes the spell's record to the same `0x6128b0` law as direct damage.
     let Some(color) = damage_color(gates, source, melee_styled(spells, s.spell_id)) else {
         return;
     };
@@ -378,10 +353,9 @@ pub(super) fn periodic_aura_log(
     }
 }
 
-/// `SMSG_SPELLDAMAGESHIELD` → the reflected damage lands on the **attacker** (the unit that struck
-/// the shield bearer) — that's the recipient the number floats over (`0x5e84e0`). The damage
-/// SOURCE is the shield bearer (the victim field); the site pushes record NULL, so it colors
-/// melee-styled: my shield → white, my pet's → orange.
+/// `SMSG_SPELLDAMAGESHIELD`: the number floats over the attacker, who struck the shield; the
+/// source is the shield bearer (the victim field). The site pushes a NULL record, so it colours
+/// melee-styled: my shield white, my pet's orange (`0x5e84e0`).
 pub(super) fn damage_shield(
     s: DamageShield,
     index: &GuidIndex,
@@ -394,8 +368,7 @@ pub(super) fn damage_shield(
     if s.damage == 0 {
         return;
     }
-    // The ungated UNIT_COMBAT feed: the reflected damage is damage TAKEN by the attacker —
-    // striking a thorns bearer wounds your own portrait.
+    // UNIT_COMBAT: the attacker takes the damage, so striking thorns wounds your own portrait.
     if let Some(&unit) = index.0.get(&s.attacker) {
         feedback.write(UnitCombatFeedback {
             unit,
@@ -421,10 +394,9 @@ pub(super) fn damage_shield(
     }
 }
 
-/// `SMSG_SPELLHEALLOG` → the direct-heal feeds: the portrait indicator's `HEAL` (green number)
-/// and the center text's `HEAL`/`HEAL_CRIT` (arg2 = the healer's name, arg3 = amount). Heals
-/// never float as worldtext in 5875 — no [`CombatTextSpawn`] here. Center text is self-only;
-/// the UNIT_COMBAT feed fires for any streamed recipient (the target frame's API surface).
+/// `SMSG_SPELLHEALLOG`: `UNIT_COMBAT` `HEAL` for any streamed recipient, and the centre text's
+/// `HEAL`/`HEAL_CRIT` (arg2 the healer's name, arg3 the amount) for self. No worldtext: heals
+/// never float in the 1.12 client.
 pub(super) fn spell_heal_log(
     s: SpellHealLog,
     index: &GuidIndex,
@@ -457,13 +429,10 @@ pub(super) fn spell_heal_log(
     }
 }
 
-/// `SMSG_SPELLENERGIZELOG` → the center text's `MANA`/`RAGE`/`FOCUS`/`ENERGY` line (self-only).
-/// NO `UNIT_COMBAT` fires here: the 5875 engine has no ENERGIZE emission — the string is absent
-/// from the whole binary (the shipped CombatFeedback.lua ENERGIZE arm is dead code in 1.12).
-///
-/// The amount is the **displayed** figure: the handler `0x5e8a90` divides by
-/// `0x6e7130(powerType)` at `0x5e8af3` and hands that one number to the COMBAT_TEXT push
-/// (`0x494770`) and to the chat formatter (`0x62ca00`) alike (decision 2117).
+/// `SMSG_SPELLENERGIZELOG`: the centre text's power-gain line, self only. No `UNIT_COMBAT`: the
+/// ENERGIZE string is absent from the 1.12 client, so `CombatFeedback.lua`'s ENERGIZE arm is dead.
+/// The amount is the displayed figure: `0x5e8a90` divides by `0x6e7130(powerType)` at
+/// `0x5e8af3` before the COMBAT_TEXT push (`0x494770`) and the chat formatter (`0x62ca00`).
 pub(super) fn spell_energize_log(
     s: SpellEnergizeLog,
     self_guid: &SelfGuid,
@@ -480,8 +449,8 @@ pub(super) fn spell_energize_log(
     }
 }
 
-/// Miss code (vmangos `SpellMissInfo`, 1–11) → the center text's spell-outcome messageType (the
-/// `SPELL_*` word family — decision 0578, PROVISIONAL).
+/// Miss code (vmangos `SpellMissInfo`, 1 to 11) to the centre text's `SPELL_*` outcome word. The
+/// reference's miss-word emitter `0x62bab0` has no `SPELL_ABSORBED`; code 10's word is untraced.
 fn miss_center_type(code: u8) -> Option<&'static str> {
     Some(match code {
         1 => "SPELL_MISSED",
@@ -498,8 +467,8 @@ fn miss_center_type(code: u8) -> Option<&'static str> {
     })
 }
 
-/// Miss code (vmangos `SpellMissInfo`, 1–11) → the `UNIT_COMBAT` action word — the same table the
-/// worldtext WORDS index, on the event's uppercase key vocabulary (`CombatFeedbackText`).
+/// Miss code (vmangos `SpellMissInfo`, 1 to 11) to the `UNIT_COMBAT` action word, the worldtext
+/// words' table in the event's uppercase keys (`CombatFeedbackText`).
 fn miss_action(code: u8) -> Option<&'static str> {
     Some(match code {
         1 => "MISS",
@@ -516,11 +485,9 @@ fn miss_action(code: u8) -> Option<&'static str> {
     })
 }
 
-/// `SMSG_SPELLLOGMISS` → one outcome word per missed target (`0x5e7e00`). Disjoint from the
-/// SPELL_GO miss list in practice: vmangos routes only impact-time outcomes (immune, evade) here.
-/// Source-classified like every emitter (the classifier lives inside the word twin too), and
-/// **coloured by the same B/K law as a number** — `0x5e7f63 mov ecx,[ebp-0x8]; 0x5e7f66 push ecx`
-/// pushes the resolved SpellRec, not NULL, so this site's words are spell-GOLD (decision 2229).
+/// `SMSG_SPELLLOGMISS`: one outcome word per missed target (`0x5e7e00`); vmangos sends only
+/// impact-time outcomes (immune, evade) here. Coloured by the same law as a number: `0x5e7f66`
+/// pushes the resolved spell record, not NULL, so the words are spell gold.
 pub(super) fn spell_log_miss(
     s: SpellLogMiss,
     index: &GuidIndex,
@@ -532,9 +499,8 @@ pub(super) fn spell_log_miss(
     feedback: &mut MessageWriter<UnitCombatFeedback>,
     center: &mut MessageWriter<CombatTextEvent>,
 ) {
-    // The ungated UNIT_COMBAT feed: the outcome word over each missed target, any source — a
-    // mob's bolt you resist is YOUR portrait's "Resist". A self target also feeds the center
-    // text's SPELL_* word family (decision 0578).
+    // UNIT_COMBAT for each missed target, any source; a self target also gets the centre text's
+    // `SPELL_*` word.
     for &(target, code) in &s.misses {
         if let (Some(&unit), Some(action)) = (index.0.get(&target), miss_action(code)) {
             feedback.write(UnitCombatFeedback {
@@ -555,11 +521,8 @@ pub(super) fn spell_log_miss(
             }
         }
     }
-    // **The WORD emitter carries the same three CVar gates as the number emitter.** `0x607140`
-    // reads `CombatDamage` (`0x60718f`), `PetSpellDamage` (`0x6071a6`) and `PetMeleeDamage`
-    // (`0x6071c5`) exactly as `0x6128b0` does, and each failure jumps to the epilogue — so a miss
-    // word is suppressed by the same settings that suppress a number. It made no difference while
-    // the three were `const bool` = true; it does now.
+    // The word emitter `0x607140` checks the same three CVars as the number emitter `0x6128b0`:
+    // `CombatDamage` (`0x60718f`), `PetSpellDamage` (`0x6071a6`), `PetMeleeDamage` (`0x6071c5`).
     let Some(source) = classify_source(s.caster, index, self_guid, stores) else {
         return; // K = other: never drawn
     };
@@ -580,9 +543,8 @@ pub(super) fn spell_log_miss(
     }
 }
 
-/// `SMSG_LOG_XPGAIN` → `"XP: %d"` over **self**, category 4 — the one emitter that is
-/// self-anchored by design and skips Gate A (`0x607260`). Fires for kill and quest XP alike. The
-/// same packet also writes the combat log's own chat line.
+/// `SMSG_LOG_XPGAIN`: `"XP: %d"` over self, category 4, the one emitter that skips Gate A
+/// (`0x607260`), for kill and quest XP alike; the packet also writes the chat line.
 pub(super) fn xp_gain(
     x: XpGain,
     index: &GuidIndex,
@@ -595,24 +557,19 @@ pub(super) fn xp_gain(
             anchor: me,
             text: format!("XP: {}", x.total),
             category: 4,
-            color: None, // row 4's own purple — XP skips the damage color law entirely
+            color: None, // row 4's own purple: XP skips the damage colour law
         });
     }
     chat_log.push_xp_gain(&x);
 }
 
-/// `SMSG_EXPLORATION_EXPERIENCE` → the discovery announcement (decision 0828; surfaces and
-/// sound from the reference, 0829). Three legs, mirroring the real handler's case body
-/// `[0x5e41d2, 0x5e42bb]`:
-/// - the ERR_ZONE_EXPLORED toast + (xp > 0) the ERR_ZONE_EXPLORED_XP chat line, queued via
-///   [`ChatLog::push_exploration`] — the area name is the packet's `AreaTable.dbc` row id
-///   resolved through the shared catalog; a miss (no catalog, or an id the DBC doesn't know)
-///   shows no message, faithfully;
-/// - the race-keyed discovery jingle (`ChrRaces.dbc` col 3 → SoundEntries), played
-///   **unconditionally** — even when the area id resolves to nothing — through the same 2D-kit
-///   path as `SMSG_PLAY_SOUND`.
+/// `SMSG_EXPLORATION_EXPERIENCE`, as the reference's case body `[0x5e41d2, 0x5e42bb]`:
+/// - the ERR_ZONE_EXPLORED toast and, when xp > 0, the ERR_ZONE_EXPLORED_XP chat line, via
+///   [`ChatLog::push_exploration`]; an `AreaTable.dbc` id with no name shows no message;
+/// - the race's discovery jingle (`ChrRaces.dbc` col 3 to SoundEntries), played even when the
+///   area resolves to nothing, through the same 2D path as `SMSG_PLAY_SOUND`.
 ///
-/// No floating text (the XP itself still arrives via the non-kill `SMSG_LOG_XPGAIN`).
+/// No floating text: the XP arrives separately as `SMSG_LOG_XPGAIN`.
 pub(super) fn exploration_xp(
     x: ExplorationXp,
     area_table: Option<&crate::area::AreaTableRes>,
@@ -654,22 +611,13 @@ pub(super) fn exploration_xp(
     }
 }
 
-/// `SMSG_LEVELUP_INFO` → the ding's chat lines (decision 0304). The talent-count arg is not on the
-/// wire — the client computes `(newLevel >= 10) ? 1 : 0` (`0x5e407c`, the 0305 fold-back), exactly
-/// this. The ding's VISUAL is deliberately absent here: it rides the UNIT_FIELD_LEVEL
-/// change-watcher (`entities` spell_fx::level_up_flash), never this packet.
+/// `SMSG_LEVELUP_INFO`: the ding's chat lines. The talent-point arg is not on the wire; the client
+/// computes `(newLevel >= 10) ? 1 : 0` (`0x5e407c`). The ding's visual rides the
+/// `UNIT_FIELD_LEVEL` change watcher, not this packet.
 pub(super) fn level_up(l: LevelUpInfo, chat_log: &mut ChatLog) {
     let talent_points = u32::from(l.level >= 10);
-    // Park the raw tuple for `ui_unit`'s `PLAYER_LEVEL_UP`, whose nine args the reference's own
-    // `ChatFrame_OnEvent` reads (1884). **That is the whole of the ding's chat output.**
-    //
-    // This used to compose and print the five-line block in Rust as well, under a comment saying
-    // the Rust lines would stay "until that window migrates and can take over printing them".
-    // The window migrated — `benilla.toc` sources `Interface\FrameXML\ChatFrame.xml` and our own
-    // transcription is gone (1948) — and nobody came back to the condition, so the block was on
-    // screen **twice** (`ui_chat::tests::the_ding_block_is_printed_once` reproduces it: four lines
-    // from each side). A deliberate temporary that outlives its trigger is indistinguishable from
-    // a permanent one; this is what one looks like when it is found.
+    // Parked for `ui_unit`'s `PLAYER_LEVEL_UP`, whose args the stock `ChatFrame_OnEvent` prints;
+    // nothing here prints the block itself, or it shows twice.
     chat_log.push_level_up_gains(&l, talent_points);
 }
 
@@ -680,14 +628,8 @@ mod tests {
     use crate::net::{Guid, SelfPlayer};
     use bevy::ecs::system::RunSystemOnce;
 
-    /// **`SMSG_SPELLLOGMISS`'s word is spell GOLD** (decision 2229) — the third and last of the
-    /// three word paths this client had drawing white on a hardcoded `color: None`.
-    ///
-    /// `0x5e7f63 mov ecx,[ebp-0x8]` / `0x5e7f66 push ecx` hands `0x607140` the resolved SpellRec,
-    /// not the literal NULL the melee swing site pushes — so the emitter's `B` bit comes from the
-    /// spell's own `AttributesEx3` and an ordinary spell's word is gold, exactly like its number.
-    /// Unlike the GO's inline emit there is **no Speed test** at this site: the word prints on
-    /// receipt whatever the spell's travel time.
+    /// `SMSG_SPELLLOGMISS`'s word is spell gold: `0x5e7f66` pushes the resolved spell record, not
+    /// the melee site's NULL, and unlike the GO's inline emit there is no speed test here.
     #[test]
     fn the_spell_log_miss_word_is_spell_gold() {
         const IMMOLATE: u32 = 348;
@@ -698,7 +640,7 @@ mod tests {
                     IMMOLATE,
                     benilla_formats::SpellDisplay {
                         name: "Immolate".into(),
-                        speed: 24.0, // travels, and it still prints here
+                        speed: 24.0, // travels, and still prints here
                         ..Default::default()
                     },
                 )]
@@ -745,7 +687,7 @@ mod tests {
                         SpellLogMiss {
                             spell_id: IMMOLATE,
                             caster: 10,
-                            misses: vec![(20, 7)], // IMMUNE — the outcome vmangos routes here
+                            misses: vec![(20, 7)], // IMMUNE, an outcome vmangos sends here
                         },
                         &index,
                         &self_guid,
diff --git a/crates/benilla-app/src/combat_text/law.rs b/crates/benilla-app/src/combat_text/law.rs
index f76658cc..18da1862 100644
--- a/crates/benilla-app/src/combat_text/law.rs
+++ b/crates/benilla-app/src/combat_text/law.rs
@@ -1,12 +1,11 @@
-//! The transcribed WORLDTEXTSTRING law — tables, fade, scale, colors, emitter splits; the
-//! knowledge index is the parent module doc (`combat_text`).
+//! The WORLDTEXTSTRING tables and formulas: categories, words, colours, fade, scale and the
+//! emitter splits.
 
 use bevy::prelude::*;
 
-/// One config-table row (`0xce8828`, stride 0x1c, filled by `0x6c79a0`): rise span (world units
-/// over the full duration), fade-in end / fade-out start / duration (ms), the scale value pair
-/// (`valueLo`/`valueHi` — equal except the crit row, whose keyframes ramp `valueHi`), and the
-/// default color (ARGB, packed by `0x4a2c10`).
+/// One config-table row (`0xce8828`, stride 0x1c, filled by `0x6c79a0`): rise in world units over
+/// the whole life, fade-in end, fade-out start and duration in ms, the scale pair (equal except
+/// the crit row, whose keyframes ramp `valueHi`) and the ARGB default colour (`0x4a2c10`).
 pub(super) struct Category {
     pub(super) rise: f32,
     fade_in_ms: f32,
@@ -17,13 +16,12 @@ pub(super) struct Category {
     pub(super) color: u32,
 }
 
-/// The category scale values, bit-exact (`0.018333` = `0x3c962fc9`, `0.0275` = `0x3ce147ad`).
+/// The category scale values, bit-exact: `0.018333` and `0.0275`.
 const VALUE_NORMAL: f32 = f32::from_bits(0x3c96_2fc9);
 const VALUE_CRIT: f32 = f32::from_bits(0x3ce1_47ad);
 
-/// The 6 byte-verified rows: 0 normal number · 1 ABSORB word · 2 crit number · 3 miss/dodge/parry
-/// word · 4 XP · 5 honor. Row 1's `fade_out(90) < fade_in(150)` is real (a quick flicker, not a
-/// decode error); rows 4/5 are the slow colored 4.5 s texts.
+/// Rows: 0 number, 1 ABSORB word, 2 crit number, 3 miss/dodge/parry word, 4 XP, 5 honor. Row 1's
+/// `fade_out(90) < fade_in(150)` is real, a quick flicker.
 pub(super) const CATEGORIES: [Category; 6] = [
     Category {
         rise: 2.0,
@@ -81,60 +79,41 @@ pub(super) const CATEGORIES: [Category; 6] = [
     },
 ];
 
-/// The crit "pop" keyframes (`0x8112dc`, gated on category 2): 3 segments `{t0, t1, s0, s1}` whose
-/// interpolated factor multiplies `valueHi` — pop to 2× in the first 10% of life, settle to 1×
-/// by 20%.
+/// The crit pop keyframes (`0x8112dc`, category 2): `{t0, t1, s0, s1}` factors on `valueHi`, up to
+/// 2x by 10% of life and back to 1x by 20%.
 const CRIT_KEYFRAMES: [(f32, f32, f32, f32); 3] = [
     (0.0, 0.1, 0.1, 2.0),
     (0.1, 0.2, 2.0, 1.0),
     (0.2, 1.0, 1.0, 1.0),
 ];
 
-/// The localized outcome WORDS, indexed by the client's outcome code 1–11 (`0x86582c` key table →
-/// `FrameScript_GetText`) — which is bit-for-bit vmangos's `SpellMissInfo` (`SpellDefines.h:160`).
-/// Strings are the shipped enUS `GlobalStrings.lua` values (patch-2.MPQ), hardcoded like the rest
-/// of our enUS-only data.
+/// The outcome words by code 1-11 (`0x86582c` keys for `FrameScript_GetText`), vmangos
+/// `SpellMissInfo` (`SpellDefines.h:160`); the enUS `GlobalStrings.lua` values.
 const WORDS: [&str; 11] = [
     "Miss", "Resist", "Dodge", "Parry", "Block", "Evade", "Immune", "Immune", "Deflect", "Absorb",
     "Reflect",
 ];
 
-/// Outcome code (1–11) → `(word, category)`: category 3 for every word except ABSORB → 1 (the
-/// parallel category table `0x80c48c`).
+/// Outcome code 1-11 to `(word, category)`: category 3, except ABSORB's 1 (`0x80c48c`).
 pub(crate) fn miss_word(code: u8) -> Option<(&'static str, u8)> {
     let word = *WORDS.get((code as usize).checked_sub(1)?)?;
     Some((word, if code == 10 { 1 } else { 3 }))
 }
 
-/// The emitter override colors, hard-init at `0x5fa0b0`/`0x5fa0f0`: player/pet SPELL damage gold
-/// `[0xc4d8a0]`, pet MELEE damage orange `[0xc4d8cc]`. A NULL override falls to the category
-/// row's default (rows 0–3: white).
+/// The emitter override colours (`0x5fa0b0`/`0x5fa0f0`): spell damage gold `[0xc4d8a0]`, pet melee
+/// orange `[0xc4d8cc]`. No override means the row's default, white for rows 0-3.
 pub(crate) const COLOR_SPELL_GOLD: u32 = 0xFFFF_DE00;
 pub(crate) const COLOR_PET_MELEE_ORANGE: u32 = 0xFFFF_8400;
 
-/// **The three floating-combat-text CVar gates, live** — `CombatDamage` (`[0xc4d944]`),
-/// `PetMeleeDamage` (`[0xc4d9cc]`) and `PetSpellDamage` (`[0xc4d99c]`), each read as the record's
-/// int `+0x28`.
+/// The three combat-text CVar gates: `CombatDamage` (`[0xc4d944]`), `PetMeleeDamage`
+/// (`[0xc4d9cc]`) and `PetSpellDamage` (`[0xc4d99c]`), each read as the record's int `+0x28`.
+/// Their only reads are in the word emitter `0x607140` and the number emitter `0x6128b0`, and a
+/// failed gate suppresses the emit entirely.
 ///
-/// Each has a **closed reader census** in the reference: one store and exactly two reads
-/// image-wide, one in the localized-WORD emitter `0x607140` and one in the `"%d"` NUMBER emitter
-/// `0x6128b0`. Both branch targets are function epilogues, so a gate that fails
-/// **suppresses the emit entirely** — it never falls through to a default colour, which is why
-/// [`damage_color`] returns `Option` rather than a colour.
-///
-/// `CombatDamage` is the master: off, nothing floats over any unit from any source, and — despite
-/// the CVar's own help text saying "damage numbers" — that includes the miss/dodge/parry/block/
-/// absorb/resist WORDS, because the word emitter carries the same gate. The `Pet*` pair are
-/// downstream sub-gates that only ever see the owned-by-you branch; the self sub-case is
-/// unconditional.
-///
-/// **`PetMeleeDamage` and `PetSpellDamage` do not split on "melee vs spell" the way a player
-/// would mean it.** The selector is `B` — no spell record (a real melee swing) *or* the spell's
-/// `AttributesEx` bit 15 — so a pet spell carrying that bit is gated by `PetMeleeDamage` and
-/// coloured orange. Which spell ids carry it is an open question.
-///
-/// These were `const bool`s with the comment "consts until a cvar system exists". The CVar system
-/// existed; this is the row 2077's census was holding the place for.
+/// `CombatDamage` is the master and silences words as well as numbers. The `Pet*` pair gate only
+/// the owned-by-you branch, split by `B`: no spell record, or `AttributesEx3` bit 15 (vmangos
+/// `SPELL_ATTR_EX3_NORMAL_RANGED_ATTACK`, `SpellDefines.h:924`, the basic ranged shots), goes to
+/// `PetMeleeDamage`.
 #[derive(Resource, Clone, Copy)]
 pub(crate) struct DamageTextGates {
     pub(crate) combat_damage: bool,
@@ -143,7 +122,7 @@ pub(crate) struct DamageTextGates {
 }
 
 impl Default for DamageTextGates {
-    /// The reference's registered defaults — all three `"1"`.
+    /// The reference's registered defaults, all `"1"`.
     fn default() -> Self {
         Self {
             combat_damage: true,
@@ -153,38 +132,24 @@ impl Default for DamageTextGates {
     }
 }
 
-/// The `0x5efea0` source-ownership classes that may draw (`K`): the active player itself, or a
-/// unit it owns (pet/guardian/totem — Summoned/CreatedBy = me). Every other source class (other
-/// players, their pets, wild units) is suppressed at the emitter — the caller drops the emit.
+/// The `0x5efea0` source-ownership classes that may draw (`K`): the player, or a unit it summoned
+/// or created. Every other source is suppressed; the caller drops the emit.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) enum DamageSource {
     Player,
     Pet,
 }
 
-/// The color law's `B` bit — "this damage is melee-STYLED" — from the spell record the emitting
-/// call site pushes: `(recordPtr == 0) || sign(byte[SpellRec+0x25])`, i.e. no record at all, or
-/// `AttributesEx3` bit 15 ([`benilla_formats::SpellDisplay::melee_white_damage`]). `display` is
-/// the row the site resolved; `None` stands for BOTH "the site pushed NULL" (a melee swing, a
-/// damage shield) and "we have no catalog" — the client degrades a NULL record to melee-styled,
-/// so a missing catalog degrades the same way.
-///
-/// **It is the WORD emitter's bit as much as the number's** (decision 2229). `0x607140` and
-/// `0x6128b0` are separate functions — different arg counts, different register allocation, not
-/// the "byte-identical twins" an earlier reading called them — but they compute `B` and `K`
-/// identically, and seven of the eight `0x607140` call sites push a resolved SpellRec. Only the
-/// melee swing's word site (`0x624511`, whose seven predecessors are all `6a 00 push 0x0`) pushes
-/// NULL. So a spell's "Miss"/"Resist" is spell-GOLD exactly like its number, and only a white
-/// hit's miss is white.
+/// The colour law's `B` bit: `recordPtr == 0 || sign(byte[SpellRec+0x25])`, no record or
+/// `AttributesEx3` bit 15. `None` is both a pushed NULL (a melee swing, a damage shield) and a
+/// missing catalog. `0x607140` and `0x6128b0` compute it alike; only the melee word site
+/// (`0x624511`) pushes NULL, so a spell's miss word is gold like its number.
 pub(crate) fn melee_styled(display: Option<&benilla_formats::SpellDisplay>) -> bool {
     display.is_none_or(benilla_formats::SpellDisplay::melee_white_damage)
 }
 
-/// The color branch (`0x6128b0` `6128f6`–`612964`): the effective override for a qualifying
-/// source, by `B` (`melee` = record NULL; the AttributesEx bit-15 leg is a named divergence) and
-/// `K`. `None` = the whole emit is gated off (CombatDamage master, or the pet path's Pet* cvar);
-/// `Some(None)` = draw with the category row's default (white); `Some(Some(argb))` = draw with
-/// the override. Crit never enters this pick.
+/// The colour branch (`0x6128b0`, `6128f6`-`612964`) by `B` and `K`: `None` gates the emit off,
+/// `Some(None)` draws in the row's default, `Some(Some(argb))` in the override. Crit never enters.
 pub(crate) fn damage_color(
     gates: DamageTextGates,
     source: DamageSource,
@@ -201,13 +166,10 @@ pub(crate) fn damage_color(
     }
 }
 
-/// The melee emitter split — `0x6243e0`'s branch order, byte-verified (decision 0279, closing
-/// the phase-2 INFERRED flag): a **word state** (victim states 2 dodge · 3 parry · 5 block ·
-/// 6 evade · 7 immune · 8 deflect) floats its word UNCONDITIONALLY, Damage ignored; otherwise
-/// (states 0/1/4) landed damage floats the bare post-mitigation number (category 0, or 2 on
-/// `HITINFO_CRITICALHIT 0x80`) — a partial block or absorb is never annotated — and zero damage
-/// falls to `hit_info & 0x20` → "Absorb", `& 0x40` → "Resist", else the "Miss" word (the fn
-/// never tests `HITINFO_MISS`; a vs-0 miss reaches the word through this default).
+/// The melee emitter split, `0x6243e0`'s branch order: victim states 2, 3, 5, 6, 7, 8 float their
+/// word whatever the damage; otherwise damage floats the bare number (category 2 on
+/// `HITINFO_CRITICALHIT 0x80`), and zero damage is "Absorb" on `0x20`, "Resist" on `0x40`, else
+/// "Miss" (`HITINFO_MISS` is never tested).
 pub(crate) fn melee_text(hit_info: u32, victim_state: u32, damage: u32) -> Option<(u8, String)> {
     let code = match victim_state {
         2 => 3, // DODGE
@@ -217,27 +179,26 @@ pub(crate) fn melee_text(hit_info: u32, victim_state: u32, damage: u32) -> Optio
         7 => 7, // IMMUNE
         8 => 9, // DEFLECT
         _ => {
-            // 0 UNAFFECTED / 1 NORMAL / 4 INTERRUPT (the silent NORMAL alias): Damage-keyed.
+            // 0 UNAFFECTED, 1 NORMAL, 4 INTERRUPT: keyed on damage.
             if damage > 0 {
                 let category = if hit_info & 0x80 != 0 { 2 } else { 0 };
                 return Some((category, damage.to_string()));
             }
             if hit_info & 0x20 != 0 {
-                10 // ABSORB (full — a partial rides the number above)
+                10 // ABSORB, full; a partial one shows only the number
             } else if hit_info & 0x40 != 0 {
-                2 // RESIST (full)
+                2 // RESIST, full
             } else {
-                1 // MISS — the zero-damage default word
+                1 // MISS
             }
         }
     };
     miss_word(code).map(|(w, c)| (c, w.to_string()))
 }
 
-/// The spell/periodic damage emitter split (`0x5e85e0`/`0x626dd0`): landed damage floats as a
-/// number (category 0, or 2 on `SPELL_HIT_TYPE_CRIT 0x2` — periodic ticks never crit in 1.12, the
-/// caller passes `crit: false`); zero damage floats ABSORB or RESIST (the word choice at
-/// `0x5e88d1` is INFERRED from the packet's fields — flagged in the decision record).
+/// The spell and periodic emitter split (`0x5e85e0`/`0x626dd0`): damage floats a number, category
+/// 2 on `SPELL_HIT_TYPE_CRIT 0x2` (periodic ticks never crit); zero damage floats ABSORB or
+/// RESIST, a choice inferred from the packet's fields, as `0x5e88d1` is untraced.
 pub(crate) fn spell_text(
     damage: u32,
     absorb: u32,
@@ -256,33 +217,24 @@ pub(crate) fn spell_text(
     None
 }
 
-/// The gx px round — `ScreenToPixelWidth 0x5c7010` / `ScreenToPixelHeight 0x5c6fa0` verbatim
-/// (`fild; fmul; +0.5; __ftol`): `+0.5` then truncate (half away from zero).
+/// The gx pixel round (`0x5c7010`/`0x5c6fa0`): add 0.5 and truncate, half away from zero.
 fn round_px(t: f64) -> f32 {
     let r = if t > 0.0 { t + 0.5 } else { t - 0.5 };
     r.trunc() as f32
 }
 
-/// The composed size law (module doc): category value `v` → on-screen pixel height. One gx unit
-/// is the **screen diagonal** `√(W²+H²)`: the screencoord device space spans `[0,G44]×[0,G48]`
-/// with `G44 = s/√(s²+1)`, `G48 = 1/√(s²+1)` (`s = W/H` — the live globals `0x832a44/48`), so
-/// `v/G48 × H = v·√(W²+H²)`. The first reading hardcoded G48's **4:3 value** (0.6), which
-/// under-sizes ~22% at 16:9 — the director's "damage numbers should be 1–2 sizes bigger", one
-/// root cause with the small nameplates. The round is the gx px law ([`round_px`]); constant
-/// with unit distance.
+/// Scale value `v` to pixel height, constant with distance. One gx unit is the screen diagonal:
+/// device space spans `[0,G44]x[0,G48]`, `G48 = 1/√(s²+1)` for `s = W/H` (live at `0x832a44/48`),
+/// so `v/G48 × H = v·√(W²+H²)`.
 pub(super) fn text_px(v: f32, viewport: Vec2) -> f32 {
     round_px(f64::from(v) * f64::from(viewport.x).hypot(f64::from(viewport.y)))
 }
 
-/// The shadow's offset — the static at `0xce8804` (`{0.002, 0.002}`, init `0x6c7c20`):
-/// a **viewport fraction**, resolved per-axis and integer-rounded at draw (module doc; `0x5c8710`,
-/// not our first `× diagonal` reading: the
-/// `√(W²+H²)` lives only in the unrelated Lua `GetScreenWidth/Height` path).
+/// The shadow offset, `0xce8804` (`{0.002, 0.002}`, init `0x6c7c20`): a viewport fraction per
+/// axis, rounded at draw (`0x5c8710`).
 const SHADOW_OFFSET_FRAC: f32 = 0.002;
 
-/// The rendered shadow offset: `{round(0.002·W), round(0.002·H)}` px, down-right — anisotropic
-/// (at 1920×1080: `{4, 2}` — the isotropic diagonal read overstated the vertical ~2.2×, the
-/// director's "offset reads too large").
+/// The rendered shadow offset, `{round(0.002·W), round(0.002·H)}` px down-right.
 pub(super) fn shadow_offset_px(viewport: Vec2) -> Vec2 {
     Vec2::new(
         round_px(f64::from(SHADOW_OFFSET_FRAC) * f64::from(viewport.x)),
@@ -290,16 +242,11 @@ pub(super) fn shadow_offset_px(viewport: Vec2) -> Vec2 {
     )
 }
 
-/// The anti-overlap CLAIM box (full width × height, px) — the ref's measured block under its
-/// own units quirk: `0x6c81a0`
-/// stores the halves as SCREEN FRACTIONS — height = the raw size value ÷ G48 verbatim (single
-/// line: no line gap, and the shadow-Y term is a dead store), width = the advance
-/// sum ÷ screen width plus a `round(0.002·diag)` pen seed — and `0x6c7cc0` then spends those
-/// fractions as DDC lengths in the solver rect. A fraction in a DDC slot inflates by diag/dim
-/// (1/G48 ≈ 1.667× tall, 1/G44 ≈ 1.25× wide at 4:3): the reference's generous,
-/// size-proportional between-number padding, ported as the same multiplicative factors. `ink_w`
-/// (our laid-out ink) stands in for the ref's advance sum (side bearings + its 0/2/4 raster
-/// pad stay INFERRED there, ≤ ~3 px).
+/// The anti-overlap claim box in px. `0x6c81a0` stores the halves as screen fractions (height the
+/// size value ÷ G48, width the advance sum ÷ screen width plus a `round(0.002·diag)` pen seed) and
+/// `0x6c7cc0` spends them as DDC lengths, inflating them by diag/dim (1.667x tall, 1.25x wide at
+/// 4:3). `ink_w` stands in for the advance sum; the reference's side bearings and raster pad
+/// (at most ~3 px) are untraced.
 pub(super) fn claimed_box_px(ink_w: f32, size_value: f32, viewport: Vec2) -> Vec2 {
     let diag = viewport.length();
     Vec2::new(
@@ -308,16 +255,10 @@ pub(super) fn claimed_box_px(ink_w: f32, size_value: f32, viewport: Vec2) -> Vec
     )
 }
 
-/// The text and RENDERED shadow alpha bytes at `elapsed_ms` — the alpha fade `0x6c82e0`'s two
-/// lanes (constants 255.0 / 127.0) composed through the store seam (module doc, the
-/// STORE law): the shadow's stored alpha is **`min(shadow lane, text alpha)`** (`SetShadowColor
-/// 0x5cd650`, font node — SetColor runs first each tick, so `mainA` is the fresh text byte).
-/// Branch order is the client's: fade-in first (below fade-in-end the ramp arm wins even when
-/// fade-out-start is earlier — row 1), then the fade-out arm, else the unconditional
-/// `(0xFF, 0x7F)` plateau. The ramps divide by the row's DURATION (the byte-verified quirk: the
-/// fade-in boundary is a step, not a ramp arrival). In fade-out the raw shadow lane inverts into
-/// `[128, 255]` — but the min-cap pins the rendered value to the text alpha there, so the shadow
-/// steps up to ~0xFF as the fade begins and then tracks the text down to 0.
+/// The text and rendered shadow alpha at `elapsed_ms`: `0x6c82e0`'s two lanes (255.0 at
+/// `0x7ffe58`, 127.0 at `0x811310`), fade-in tested first, then fade-out, else the `(0xFF, 0x7F)`
+/// plateau. The ramps divide by the duration, so fade-in ends in a step. `0x5cd650` stores the
+/// shadow as `min(shadow, text)`, so the raw `[128, 255]` fade-out lane renders as the text alpha.
 pub(super) fn fade_alpha(cat: &Category, elapsed_ms: f32) -> (u8, u8) {
     // MSVC __ftol truncates; `as i32` matches.
     let (text, shadow) = if elapsed_ms < cat.fade_in_ms {
@@ -335,14 +276,12 @@ pub(super) fn fade_alpha(cat: &Category, elapsed_ms: f32) -> (u8, u8) {
     } else {
         (0xff, 0x7f)
     };
-    // The store seam: `0x5cd650` writes shadow alpha = min(shadowA, mainA) — every tick, after
-    // SetColor. The raw lane above is what the fade computes; this is what renders.
+    // `0x5cd650` writes the shadow alpha as min(shadowA, mainA) every tick, after SetColor.
     (text, shadow.min(text))
 }
 
-/// The category's scale value at normalized life `t` (`0x6c80b0`): category 2 runs
-/// the crit-pop keyframes × `valueHi`; every other row is the affine `lo + (hi − lo)·t` (constant,
-/// since `lo == hi` outside the crit row). Floor 0.001, as the client clamps.
+/// The scale value at normalized life `t` (`0x6c80b0`): category 2 runs the crit keyframes on
+/// `valueHi`, the rest `lo + (hi − lo)·t`; floored at 0.001.
 pub(super) fn scale_value(category: u8, t: f32) -> f32 {
     let cat = &CATEGORIES[category as usize];
     let v = if category == 2 {
@@ -357,10 +296,8 @@ pub(super) fn scale_value(category: u8, t: f32) -> f32 {
     v.max(0.001)
 }
 
-/// ARGB (client-packed, `0x4a2c10`) → straight-alpha client-space sRGB RGBA, the
-/// [`UiQuads`](crate::ui_pass::UiQuads) color convention. The packed ALPHA byte is discarded (forced 1.0): the per-tick fade REPLACES
-/// it before anything renders (module doc, the ALPHA + SHADOW law) — keeping row 4's `0x80` here
-/// was exactly the half-visible XP text the director reported.
+/// Packed ARGB (`0x4a2c10`) to straight-alpha sRGB RGBA; the alpha byte is dropped, as the fade
+/// replaces it every tick.
 pub(super) fn argb(c: u32) -> [f32; 4] {
     [
         ((c >> 16) & 0xff) as f32 / 255.0,
@@ -374,20 +311,14 @@ pub(super) fn argb(c: u32) -> [f32; 4] {
 mod tests {
     use super::*;
 
-    /// The composed size law (`v · diagonal` → `ScreenToPixelHeight`): the exact pixel heights
-    /// at the 1024×768 reference window (diag 1280 — where the old `/0.6 × H` law coincides),
-    /// the round-half-away behavior, and the ASPECT correction (the whole point: a 16:9 window
-    /// sizes by ITS diagonal through the live G48 `0x832a48`, not the 4:3 constant).
-    /// The claimed-box anchors (`0x6c81a0`) at
-    /// 1024×768: the box the solver sees runs 1/G48 taller than the glyph render — 39.1 px for
-    /// the 23 px steady number, 58.7 px for the 35 px crit settle — and 1/G44 (1.25×) wider
-    /// than ink + the `round(0.002·diag)` pen seed.
+    /// The claimed box (`0x6c81a0`) at 1024×768: 39.1 px tall for the 23 px number, 58.7 px for the
+    /// 35 px crit, and 1.25x the ink plus pen seed wide.
     #[test]
     fn claimed_box_matches_the_measured_block_anchors() {
         let ref43 = Vec2::new(1024.0, 768.0); // diag = 1280, G44 = 0.8, G48 = 0.6
         let steady = claimed_box_px(10.0, VALUE_NORMAL, ref43);
         assert!((steady.y - 39.1).abs() < 0.05, "steady box {}", steady.y);
-        // ink 10 + seed round(2.56)=3 → 13 · 1.25.
+        // ink 10 + seed round(2.56) = 3, times 1.25.
         assert!((steady.x - 16.25).abs() < 1e-3, "steady box {}", steady.x);
         let crit = claimed_box_px(10.0, VALUE_CRIT, ref43);
         assert!((crit.y - 58.7).abs() < 0.05, "crit box {}", crit.y);
@@ -396,87 +327,69 @@ mod tests {
     #[test]
     fn text_px_matches_the_screen_to_pixel_law() {
         let ref43 = Vec2::new(1024.0, 768.0); // diag = 1280
-                                              // Normal number: 0.018333 × 1280 = 23.47 → +0.5 trunc → 23.
+                                              // 0.018333 × 1280 = 23.47, rounds to 23.
         assert_eq!(text_px(VALUE_NORMAL, ref43), 23.0);
-        // Crit settled (1.0 × valueHi): 0.0275 × 1280 = 35.2 → 35.
+        // Crit settled: 0.0275 × 1280 = 35.2.
         assert_eq!(text_px(VALUE_CRIT, ref43), 35.0);
-        // Crit pop peak (2.0 × valueHi): 70.4 → 70.
+        // Crit pop peak: 70.4.
         assert_eq!(text_px(2.0 * VALUE_CRIT, ref43), 70.0);
-        // The +0.5-then-truncate round: t = 23.5 exactly → 24 (half away from zero, not floor).
+        // 23.5 rounds half away from zero, to 24.
         assert_eq!(text_px(23.5, Vec2::new(0.6, 0.8)), 24.0);
-        // The aspect correction: at 1920×1080 (diag ≈ 2202.9) a normal number is 40 px — the
-        // 4:3-hardcoded law gave 33, the ~22% the director read as "1–2 sizes smaller".
+        // At 1920×1080 (diag ≈ 2202.9) a normal number is 40 px.
         assert_eq!(text_px(VALUE_NORMAL, Vec2::new(1920.0, 1080.0)), 40.0);
-        // The size is exactly the scale_value composition the render loop feeds it.
         assert_eq!(text_px(scale_value(0, 0.5), ref43), 23.0);
     }
 
-    /// The shadow offset law (`0x5c8710`): a per-axis viewport
-    /// fraction, gx-rounded — NOT the isotropic diagonal (which overstated the vertical ~2.2×
-    /// at 16:9 and grew with resolution).
     #[test]
     fn shadow_offset_is_a_per_axis_viewport_fraction() {
-        // 1920×1080 → {round(3.84), round(2.16)} = {4, 2}.
+        // {round(3.84), round(2.16)}.
         assert_eq!(
             shadow_offset_px(Vec2::new(1920.0, 1080.0)),
             Vec2::new(4.0, 2.0)
         );
-        // The 4:3 reference window: {round(2.048), round(1.536)} = {2, 2} — the "~2.6 px"
-        // diagonal read never rendered.
+        // {round(2.048), round(1.536)}.
         assert_eq!(
             shadow_offset_px(Vec2::new(1024.0, 768.0)),
             Vec2::new(2.0, 2.0)
         );
     }
 
-    /// The config rows against the byte-verified table (bit patterns for the two scale values).
     #[test]
     fn config_rows_match_the_byte_table() {
         assert_eq!(VALUE_NORMAL.to_bits(), 0x3c96_2fc9);
         assert_eq!(VALUE_CRIT.to_bits(), 0x3ce1_47ad);
         assert_eq!(CATEGORIES[0].dur_ms, 1500.0);
-        assert_eq!(CATEGORIES[1].fade_out_ms, 90.0); // the ABSORB flicker row, as shipped
+        assert_eq!(CATEGORIES[1].fade_out_ms, 90.0); // the ABSORB flicker row
         assert_eq!(CATEGORIES[4].color, 0x8094_008B);
         assert_eq!(CATEGORIES[5].color, 0xFFE0_CA0A);
     }
 
-    /// The alpha fade `0x6c82e0` at the pinned points of row 0 (in 150 / out 760 / dur 1500),
-    /// composed through the store seam (rendered values): fade-in ramps 255·t / 127·t over the
-    /// DURATION (so the fade-in boundary is a step to 255, the pop-in), the
-    /// plateau is the unconditional `(0xFF, 0x7F)`, the fade-out drops the text
-    /// `255 − clamp(255·u)` — and the SHADOW's raw `[128, 255]` inversion is min-capped to the
-    /// text alpha by the `0x5cd650` store, so it steps to ~0xFF at fade-out start and then
-    /// fades in sync to 0 (never the 128-floor black ghost).
+    /// Row 0 (in 150, out 760, duration 1500) and row 1 at their pinned points, as rendered.
     #[test]
     fn fade_law_ramps_holds_and_mirrors() {
         let cat = &CATEGORIES[0];
         assert_eq!(fade_alpha(cat, 0.0), (0, 0));
-        // Fade-in at 75 ms: 255 × 0.05 = 12.75 → trunc 12; shadow 127 × 0.05 = 6.35 → 6.
+        // 255 × 0.05 = 12.75 and 127 × 0.05 = 6.35, truncated.
         assert_eq!(fade_alpha(cat, 75.0), (12, 6));
-        // 149 ms is still the ramp; 150 ms steps onto the plateau — the pop-in.
+        // 149 ms is still the ramp; 150 ms steps onto the plateau.
         assert_eq!(fade_alpha(cat, 149.0), (25, 12));
         assert_eq!(fade_alpha(cat, 150.0), (0xff, 0x7f));
         assert_eq!(fade_alpha(cat, 759.0), (0xff, 0x7f));
-        // Fade-out start (u = 0): both lanes 255 — the shadow's byte-real step up from 0x7f.
+        // Fade-out start: both lanes 255, the shadow stepping up from 0x7f.
         assert_eq!(fade_alpha(cat, 760.0), (0xff, 0xff));
-        // Fade-out midpoint u = 0.5: text 255 − 127.5 → 127; raw shadow lane 191, min-capped
-        // to the text's 127 — the shadow fades WITH the text, not above it.
+        // u = 0.5: text 127; the raw shadow lane's 191 is capped to it.
         assert_eq!(fade_alpha(cat, 1130.0), (127, 127));
         assert_eq!(fade_alpha(cat, 1500.0), (0, 0));
-        // Row 1's fade_out(90) < fade_in(150): the fade-in branch is tested FIRST — this row
-        // has NO plateau; at 150 ms the fade-out arm is already 60/1410 deep.
+        // Row 1 has no plateau: fade-in is tested first, and at 150 ms fade-out is 60/1410 deep.
         let absorb = &CATEGORIES[1];
         assert_eq!(fade_alpha(absorb, 100.0), (17, 8)); // 255·t / 127·t at t = 1/15
         assert_eq!(fade_alpha(absorb, 150.0), (244, 244)); // text 255−10.85; shadow min(249, text)
-                                                           // Row 4 (XP): the plateau is FULLY OPAQUE — the packed 0x80 never renders (the
-                                                           // director's "less visible than ref", root-caused).
+                                                           // Row 4's 0x80 alpha never renders.
         assert_eq!(fade_alpha(&CATEGORIES[4], 1000.0), (0xff, 0x7f));
-        // Row 4's fade tail (u = 0.8, elapsed 4000): text 51, shadow min-capped to 51 — the
-        // 4.5 s XP text's shadow dies with the text (the reported lingering ghost).
+        // Row 4 at u = 0.8: the shadow fades with the text.
         assert_eq!(fade_alpha(&CATEGORIES[4], 4000.0), (51, 51));
     }
 
-    /// The crit pop (`0x8112dc` × valueHi): 0.1→2.0 over the first 10% of life, settle 1.0 by 20%.
     #[test]
     fn crit_keyframes_pop_then_settle() {
         assert!((scale_value(2, 0.0) - 0.1 * VALUE_CRIT).abs() < 1e-7);
@@ -484,14 +397,12 @@ mod tests {
         assert!((scale_value(2, 0.1) - 2.0 * VALUE_CRIT).abs() < 1e-6);
         assert!((scale_value(2, 0.15) - 1.5 * VALUE_CRIT).abs() < 1e-6);
         assert!((scale_value(2, 0.5) - VALUE_CRIT).abs() < 1e-7);
-        // Non-crit rows are constant (lo == hi).
         assert_eq!(scale_value(0, 0.0), scale_value(0, 0.9));
-        // Settled crit = 1.5× a normal number — the verified ratio.
+        // A settled crit is 1.5x a normal number.
         assert!((scale_value(2, 0.5) / scale_value(0, 0.5) - 1.5).abs() < 1e-3);
     }
 
-    /// The emitter splits: melee number/word (`0x6243e0`'s byte-verified branch order, decision
-    /// 0279) and the spell damage/absorb/resist fallbacks; ABSORB is the one category-1 word.
+    /// The melee (`0x6243e0`) and spell splits; ABSORB is the one category-1 word.
     #[test]
     fn emitters_split_numbers_and_words() {
         assert_eq!(melee_text(0x2, 1, 37), Some((0, "37".into())));
@@ -501,11 +412,11 @@ mod tests {
         assert_eq!(melee_text(0x0, 3, 0), Some((3, "Parry".into())));
         assert_eq!(melee_text(0x0, 5, 0), Some((3, "Block".into())));
         assert_eq!(melee_text(0x0, 6, 0), Some((3, "Evade".into())));
-        // A word state ignores Damage entirely (the client's unconditional word arm).
+        // A word state ignores damage.
         assert_eq!(melee_text(0x2, 3, 25), Some((3, "Parry".into())));
         assert_eq!(melee_text(0x22, 1, 0), Some((1, "Absorb".into()))); // full absorb: bit 0x20
         assert_eq!(melee_text(0x42, 1, 0), Some((3, "Resist".into()))); // full resist: bit 0x40
-                                                                        // Zero damage, no absorb/resist bit: the default word is Miss (0x10 is never tested).
+                                                                        // Zero damage: Miss.
         assert_eq!(melee_text(0x2, 1, 0), Some((3, "Miss".into())));
         assert_eq!(spell_text(120, 0, 0, false), Some((0, "120".into())));
         assert_eq!(spell_text(240, 0, 0, true), Some((2, "240".into())));
@@ -517,9 +428,8 @@ mod tests {
         assert_eq!(miss_word(12), None);
     }
 
-    /// The `0x6128b0` B/K color branch (the byte table): self melee → NULL override (row-default
-    /// white), self spell → gold, pet melee → orange (PetMeleeDamage), pet spell → gold
-    /// (PetSpellDamage). Crit never enters the pick (it only selects the pop row).
+    /// The `0x6128b0` B/K colour branch: self melee the row default, self spell gold, pet melee
+    /// orange, pet spell gold.
     #[test]
     fn damage_color_matches_the_byte_table() {
         let on = DamageTextGates::default();
@@ -536,15 +446,13 @@ mod tests {
             damage_color(on, DamageSource::Pet, false),
             Some(Some(COLOR_SPELL_GOLD))
         );
-        // The byte values themselves (`0x5fa0b0`/`0x5fa0f0` hard-inits).
+        // `0x5fa0b0`/`0x5fa0f0`.
         assert_eq!(COLOR_SPELL_GOLD, 0xFFFF_DE00);
         assert_eq!(COLOR_PET_MELEE_ORANGE, 0xFFFF_8400);
     }
 
-    /// **The three gates SUPPRESS; they never recolour** — both of the reference's read sites
-    /// branch to a function epilogue, so a failed gate means no emit at all. And the master's
-    /// reach is total: `CombatDamage = 0` takes the self sub-case with it, which is the one case
-    /// no `Pet*` row can reach.
+    /// Both read sites branch to a function epilogue, so a failed gate means no emit at all, and
+    /// `CombatDamage = 0` takes the self case too.
     #[test]
     fn the_three_gates_suppress_the_emit_rather_than_recolour_it() {
         let master_off = DamageTextGates {
@@ -561,8 +469,7 @@ mod tests {
             }
         }
 
-        // A pet sub-gate takes ONLY its own branch — and leaves the player's alone, because the
-        // self sub-case is unconditional in the reference.
+        // A pet sub-gate takes only its own branch; the self case is unconditional.
         let no_pet_melee = DamageTextGates {
             pet_melee: false,
             ..Default::default()
diff --git a/crates/benilla-app/src/combat_text/mod.rs b/crates/benilla-app/src/combat_text/mod.rs
index d68816c7..1b569d5f 100644
--- a/crates/benilla-app/src/combat_text/mod.rs
+++ b/crates/benilla-app/src/combat_text/mod.rs
@@ -1,122 +1,48 @@
-//! **Floating combat text** (decision 0137 phase 2) — the client's WORLDTEXTSTRING engine.
+//! Floating combat text, the reference's WORLDTEXTSTRING engine.
 //!
-//! The law, transcribed: a combat-log SMSG's handler picks a **category 0–5** and submits a string
-//! over the damage/outcome **recipient**; the text is **world-anchored** — the unit's OVERHEAD
-//! anchor is snapshotted at spawn (`0x6c73f0` → `0x608640`: the posed PlayerName attachment,
-//! slot 18 — head height, tracking model stature intrinsically; fallback `feet + scale × bbox_z ×
-//! 1.25`), lifted `z − 1/3`, then re-projected to the screen every frame (`0x483ee0`), rising and
-//! fading per the category's row in the config table `0xce8828`. Numbers
-//! are bare unsigned `"%d"`; misses are localized WORDS (the shipped enUS `GlobalStrings.lua`
-//! values, patch-2.MPQ). At most **4 concurrent texts per unit — a hard drop, not an eviction**
-//! (`0x6c73f0`). Self-anchored damage text is suppressed at the emitters (Gate A, `0x607140`/
-//! `0x6128b0`): outgoing damage floats over the victim, incoming damage never floats over your own
-//! head; the XP emitter (category 4) is self-anchored by design and skips the gate. Heals and
-//! energize NEVER float in 5875 (chat log only; there is no `CombatHealing` cvar).
+//! A combat-log handler picks a category 0-5 and submits a string over the recipient. The text is
+//! world-anchored: the unit's overhead anchor is snapshotted at spawn (`0x6c73f0` to `0x608640`:
+//! the PlayerName attachment, slot 18, else `feet + scale × bbox_z × 1.25`), moved `z − 1/3`, and
+//! re-projected every frame (`0x483ee0`), rising and fading per its row of `0xce8828`. Numbers
+//! are bare `"%d"`, misses localized words; at most 4 texts per unit, a hard drop (`0x6c73f0`).
+//! Damage over yourself is suppressed at the emitters (Gate A, `0x607140`/`0x6128b0`); the XP
+//! emitter (category 4) is self-anchored and skips it. Heals and energize never float in 1.12.
 //!
-//! **The COLOR law** (the director's "melee vs spell differ" CONFIRMED): the emitters key two bits
-//! — `B` (record NULL ⇒ melee, or **AttributesEx3 bit-15** — `SpellRec+0x24`'s word, tested as the
-//! sign of byte `+0x25`) and `K` (the `0x5efea0` **source-ownership** class: self / owned-by-me /
-//! other). Master gate: the CombatDamage cvar. Self melee → **WHITE** (NULL override ⇒ the row
-//! default); self spell/periodic → **GOLD** `0xFFFFDE00`; pet melee → **ORANGE** `0xFFFF8400`
-//! (PetMeleeDamage cvar); pet spell → GOLD (PetSpellDamage cvar); **any OTHER source is
-//! suppressed entirely** — another unit's fight floats nothing (the emitter returns before
-//! submitting; it was never "white"). Crit does NOT recolor (it only picks the pop row); there
-//! is NO school coloring. The bit-15 flip is [`melee_styled`] (decision 0376): the flag is
-//! `SPELL_ATTR3_NORMAL_RANGED_ATTACK` — set on exactly 8 rows of the real DBC, the ranged
-//! auto-attack family — so a Throw/Auto Shot number floats white off
-//! `SMSG_SPELLNONMELEEDAMAGELOG`.
+//! Colour: the emitters key `B` (no spell record, or `AttributesEx3` bit 15, the sign of byte
+//! `SpellRec+0x25`) and `K` (the `0x5efea0` source class). Under the `CombatDamage` master, self
+//! melee is white, self spell gold `0xFFFFDE00`, pet melee orange `0xFFFF8400` (`PetMeleeDamage`),
+//! pet spell gold (`PetSpellDamage`), and any other source floats nothing. Crit does not recolour
+//! and there is no school colour. Bit 15 is [`melee_styled`]'s (vmangos
+//! `SPELL_ATTR_EX3_NORMAL_RANGED_ATTACK`), set on exactly 8 rows of the real DBC, the basic ranged
+//! shots, so a Throw or Auto Shot
+//! floats white off `SMSG_SPELLNONMELEEDAMAGELOG`. The word emitter `0x607140` runs the same law
+//! and gates, so a spell's miss word is gold like its number.
 //!
-//! **The WORD emitter runs that same law** (decision 2229, closing what phase 2 left open). The
-//! two emitters are separate functions — `0x607140` takes three stack args and `0x6128b0` four,
-//! so they are not the "byte-identical twins" the first reading called them — but they compute
-//! `B` and `K` identically, and **seven of the eight `0x607140` call sites push a resolved
-//! SpellRec**. Only the melee swing's word site (`0x624511`, every one of its seven predecessors
-//! a `6a 00 push 0x0`) pushes NULL. So a spell's "Miss"/"Resist"/"Immune" is spell-GOLD exactly
-//! like its number, and only a white hit's miss is white. The three CVar gates live *inside*
-//! `0x607140`, so `CombatDamage 0` silences words as well as numbers, on every path.
+//! A travelling spell's word waits for the projectile: `SMSG_SPELL_GO`'s inline emit is skipped
+//! when `Spell.dbc` Speed is nonzero (`0x6e7d4e`), and the arrival calls the same emitter
+//! ([`missile_miss_text`]).
 //!
-//! **A travelling spell's word is DEFERRED to the projectile's arrival.** `SMSG_SPELL_GO`'s
-//! inline emit is skipped whenever `Spell.dbc` Speed is nonzero (`0x6e7d4e`), and the missile's
-//! own arrival handlers re-resolve the record and call the same emitter: a resisted Fireball
-//! reads "Resist" when the ball lands, a missed Sinister Strike at packet receive.
-//! [`missile_miss_text`] is that arrival half, fed by [`crate::entities::MissileMiss`].
+//! The rise is added to world z before projection; the block is h-centred with its bottom at the
+//! projected point and clamped on-screen, but a point the projector rejects destroys the text and
+//! frees its slot (`6c7d9d` to `6c6dda` to `0x6c86a0`). The size is constant with distance,
+//! `round_half_away(v × √(W²+H²))` ([`text_px`], `0x5c6fa0`): at 1024×768 a number is 23 px, a
+//! crit settles at 35 and pops to ~70. The face is [`DamageTextFont`], created with flags 0
+//! (`6c8493`): no outline.
 //!
-//! **The render geometry** (zero free
-//! parameters; the anchor-seat half corrected here, see the seating comment in
-//! [`float_combat_text`]): the rise is added to **world z before projection**; the block is
-//! **h-centered with its bottom at** the projected point (rising above it), clamped on-screen —
-//! but only once the projector has ACCEPTED the point at all: a number whose anchor lands behind
-//! the camera or outside the viewport is **destroyed and its slot released**
-//! (`6c7d9d` → `6c6dda` → `0x6c86a0`),
-//! never clamped to a border and never claiming a bucket-1 rect. Ours
-//! clamped, which put another unit's numbers on the screen edge — the worldtext half of 1341's
-//! phantom plates, and the half that record's §7 wrongly called byte-attested;
-//! the on-screen size is
-//! **constant with unit distance** (the depth counter-scale exists only in the *nameplate* path)
-//! and composes as `px = round_half_away(v × √(W²+H²))` — `v` the category's interpolated scale
-//! value, the diagonal the gx screencoord unit (`0x832a44/48` hold the live aspect basis; the
-//! first reading hardcoded its 4:3 value 0.6 — see [`text_px`]), the round being the gx
-//! `ScreenToPixelHeight` law (`0x5c6fa0`). At 1024×768 (diag 1280): normal number 23 px, crit
-//! settles 35 px, pop peaks ~70 px.
-//! The font is **whatever the Lua global `DAMAGE_TEXT_FONT` holds** when `0x6c8470` reads it —
-//! see [`DamageTextFont`] for the binding law (a plain `lua_gettable`, evaluated once, at the tail
-//! of the world-entry UI load, i.e. after every addon's `ADDON_LOADED`). `Fonts\FRIZQT__.TTF` is
-//! only the value the shipped `Fonts.xml` assigns, not a default the engine knows; there is in
-//! fact **no fallback face at all** in the reference — a global that resolves to nothing yields a
-//! NULL handle and the combat text simply does not draw. Created flags 0 (`6c8493 xor edx,edx` —
-//! not `6c8498`, which is `mov ecx,esi`): no outline.
+//! The fade `0x6c82e0` replaces the colour's alpha byte every tick, so the table's packed alpha
+//! never renders. The shadow is black, offset per axis by the viewport fraction at `0xce8804`
+//! (`0x5c8710`), drawn down-right before the text, its alpha capped to the text's by `0x5cd650`.
 //!
-//! **The ALPHA + SHADOW law** (the alpha fade `0x6c82e0`; the director's "XP text less visible
-//! than ref"): the per-tick fade REPLACES the
-//! live color's alpha byte (`mov [obj+0x23], bl` — the ARGB high byte), it never multiplies. The
-//! plateau between fade-in end and fade-out start is an **unconditional `(0xFF, 0x7F)`** — so the
-//! config table's packed alpha (row 4's `0x80`) is dead data, overwritten before it ever renders:
-//! the XP text is FULLY OPAQUE mid-life. Fade-in ramps text `255·t`, shadow `127·t` with
-//! `t = elapsed/DURATION` (the +0x0c field — not fade-in-end, so the boundary is a pop-in step,
-//! not a ramp arrival), and the fade-in branch is tested FIRST (row 1's `fade_out 90 < fade_in
-//! 150` has NO plateau: pop ~25 → ~244 at 150 ms, then the long taper). Fade-out over
-//! `[fade_out, duration]`: text `255 − clamp(255·u)` down to 0 — but the shadow lane is the
-//! byte-true inversion `255 − clamp(127·u, 0, 127)` ∈ [128, 255]: it JUMPS 0x7F→~0xFF at
-//! fade-out start and decays only to 128 (verified constants `[0x7ffe58]=255.0`,
-//! `[0x811310]=127.0` — not a half factor — `[0x7ffd74]=0.0`; `__ftol` truncates). The shadow is
-//! black, `(al<<24)|0` → `SetShadowColor 0x5c27a0` with the static offset `0xce8804 =
-//! {0.002, 0.002}` (init `0x6c7c20`), every category, unconditionally.
+//! Each frame every live string claims bucket 1 of the shared SmartScreenRect solver
+//! ([`crate::smart_rect`], `0x6c7cc0` to `0x509520`), each unit's slots walked descending
+//! (`0x6c6e00`): the newest number seats first and the older one moves, re-derived every frame.
 //!
-//! **The STORE seam caps the shadow**:
-//! `SetShadowColor`'s persistent store `0x5cd650` writes the shadow colour's alpha byte as
-//! **`min(shadowA, mainA)`** — and the alpha fade calls SetColor (text) *then* SetShadowColor
-//! every tick, so the RENDERED shadow alpha is `min(shadow lane, text alpha)`. The fade-out
-//! lane's byte-true `[128, 255]` inversion is dead past the text's own value: the rendered
-//! shadow steps up to ~0xFF at fade-out start, then tracks the text alpha down to **0** — it
-//! never lingers at the 128 floor (transcribing the raw lane as the rendered alpha was exactly
-//! the black ghost the director reported in the fade tail). The offset statics are a **viewport
-//! fraction**, converted per-axis at draw (`0x5c8710` → `ScreenToPixelWidth 0x5c7010` ×W /
-//! `ScreenToPixelHeight 0x5c6fa0` ×H, each `+0.5`-truncate rounded): `offset_px =
-//! {round(0.002·W), round(0.002·H)}`, drawn **down-right** (the Y-down ortho), shadow pass
-//! before main.
-//!
-//! **The anti-overlap push IS real** — decision 0367, superseding 0363's "none exists" (that
-//! verdict was true of the worldtext code and wrong about the system: the push lives in the
-//! shared `UIUtil\SmartScreenRect` draw-time solver). Every frame each live string
-//! submits its desired rect — the clamped projected center ± its **crit-pop-scaled** measured
-//! half-extents — to claim **bucket 1** ([`crate::smart_rect`]), gets relocated off the strings
-//! already seated this frame, and draws from the returned rect (`0x6c7cc0` → `0x509520`,
-//! unconditional). Seat order is the ref's container walk with slots DESCENDING (`0x6c6e00`
-//! reads +0x2c→+0x20) over the first-free-slot fill — so the newest co-anchored number usually
-//! seats first and the OLDER one jumps to make room. The push re-derives from the anchor every
-//! frame: when the blocker expires the string snaps back. On top of that layer ride the timing
-//! mechanisms this module already carries (the impact-frame deferral, the fast rise, the crit
-//! park-and-pop, the 4-slot hard drop).
-//!
-//! The emitters here are fed by `net/apply` (the SMSG spawn table lives in the handlers there,
-//! mirroring the client's registration); this module owns the law: categories, words, cap,
-//! timing/scale/fade, and the projection into [`UiQuads`] (appended *after* the script extract —
-//! see [`crate::ui_pass::UiQuadAppend`]).
+//! The combat-log and spell handlers feed the spawns; the quads append to [`UiQuads`] after the
+//! script extract ([`crate::ui_pass::UiQuadAppend`]).
 
 mod law;
 
-/// The spell-gold override, re-exported so the emitter arms' own tests can assert the colour they
-/// now pass through (decision 2229). Live code never names it — [`damage_color`] picks it.
+/// Re-exported for the emitter arms' tests; live code gets it through [`damage_color`].
 #[cfg(test)]
 pub(crate) use law::COLOR_SPELL_GOLD;
 use law::{
@@ -136,24 +62,20 @@ use crate::ui_pass::{overlay_z, UiQuadAppend, UiQuads};
 use crate::ui_text::{layout_text_quads, FontSpec, Justify, UiFontAtlas};
 use benilla_world::view::WorldCamera;
 
-/// Spawn one floating text over `anchor` — written by the `net/apply` handlers (the SMSG spawn
-/// table), consumed by [`float_combat_text`]. The emitters' self-suppression (Gate A) happens at
-/// the producer, which knows the self guid; by the time a spawn reaches here it is law that it
-/// shows (modulo the cap).
+/// Spawn one floating text over `anchor`. The producer applies Gate A, so a spawn here shows
+/// unless the cap drops it.
 #[derive(Message)]
 pub(crate) struct CombatTextSpawn {
     pub(crate) anchor: Entity,
     pub(crate) text: String,
-    /// Config category 0–5 (see [`CATEGORIES`]).
+    /// Config category 0-5 ([`CATEGORIES`]).
     pub(crate) category: u8,
-    /// The emitter color override (the B/K law, [`damage_color`]); `None` = the category row's
-    /// default color.
+    /// The emitter override ([`damage_color`]); `None` is the row's default.
     pub(crate) color: Option<u32>,
 }
 
-/// One live WORLDTEXTSTRING: the spawn-time position snapshot (already `−1/3` lifted — the text is
-/// **not** a live unit-tracking handle; a unit that walks away leaves its numbers behind, like the
-/// real client) plus birth time and payload. `anchor` is kept for the per-unit cap.
+/// One live WORLDTEXTSTRING. `pos` is a spawn-time snapshot, so a unit that walks away leaves its
+/// numbers behind; `anchor` is kept for the per-unit cap.
 struct WorldText {
     anchor: Entity,
     pos: Vec3,
@@ -162,47 +84,27 @@ struct WorldText {
     category: u8,
     /// Resolved at spawn: the emitter override, else the category row's default.
     color: u32,
-    /// The unit's slot this text occupies (0–3, first-free fill — `0x6c73f0`). Drives the seat
-    /// order: the draw walks each unit's slots DESCENDING (`0x6c6e00`).
+    /// The unit slot, 0-3, first free (`0x6c73f0`); seats walk slots descending (`0x6c6e00`).
     slot: u8,
 }
 
-/// The live texts (all units pooled; the client's per-unit 4-slot arrays are equivalent to the
-/// per-anchor count gate applied at spawn).
+/// The live texts of all units, pooled; the per-anchor slot check stands in for per-unit arrays.
 #[derive(Resource, Default)]
 pub(crate) struct WorldTexts(Vec<WorldText>);
 
-/// **The face the floating numbers draw in — the Lua global `DAMAGE_TEXT_FONT`, resolved once per
-/// world session** (decision 2156).
-///
-/// `0x6c8470` reads the global's *value* eagerly and hands it straight to the font factory:
-/// `6c847c mov ecx,0x86c9ac` ("DAMAGE_TEXT_FONT") → `0x703bf0` `FrameScript_GetText`'s fast arm
-/// (ordinal −1, gender 0) → `0x704350` `GetGlobalString`, which is a plain
-/// `lua_gettable(LUA_GLOBALSINDEX)` — the string is read *now*, not deferred, and the returned
-/// pointer is a borrowed `const char*` into the Lua TString, consumed before the call returns.
-/// `0x6c847c` is the **only** instruction in the image that reads this global.
-///
-/// **When** is the whole finding. `0x6c8470` is not CRT init — it
-/// runs from `0x401570 + 0x1620`, *after* the UI load `0x401602`, so after FrameXML has run
-/// `Fonts.xml` and after every non-LoadOnDemand addon's `ADDON_LOADED`. That is exactly where
-/// MikScrollingBattleText (`MikScrollingBattleText.lua:255`) and pfUI (`pfUI.lua:179`) assign it,
-/// and it is why their assignment reaches the real client's damage numbers.
-///
-/// And it is **once**: the handle `[0xce8820]` has exactly one writer image-wide, there is no
-/// invalidation hook and no per-string re-resolution, and `/reloadui` does **not** re-run
-/// `0x6c8470` (it only sets the deferred flag `[0xb4b3f4]`, whose reader rebuilds the UI through
-/// `0x48fbf0` — a different function). So an assignment made after world-enter lands at the next
-/// world-enter and not before. Hence a resource seated on the load edge rather than a global read
-/// per string.
+/// The face of the floating numbers: the Lua global `DAMAGE_TEXT_FONT`, resolved once per world
+/// session. `0x6c8470` reads its value (`0x6c847c`, the only read) through `FrameScript_GetText`
+/// (`0x703bf0`) and `GetGlobalString` (`0x704350`), a plain `lua_gettable`. It is called at
+/// `0x401620`, inside `0x401570` and after the UI load `0x401602`, so after `Fonts.xml` and every
+/// non-LoadOnDemand addon's `ADDON_LOADED`, where addons assign it. The handle `[0xce8820]` has one
+/// writer and `/reloadui` does not re-run `0x6c8470` (it sets `[0xb4b3f4]` for `0x48fbf0`), so a
+/// later assignment lands at the next world entry. `None` draws in the default face; the
+/// reference has no fallback face and draws nothing.
 #[derive(Resource, Default)]
 pub(crate) struct DamageTextFont(pub(crate) Option<String>);
 
-/// Read `DAMAGE_TEXT_FONT` out of the VM — the `0x6c8481` call, at the moment the reference makes
-/// it (the tail of the world-entry UI load; see [`DamageTextFont`]).
-///
-/// `0x704350` accepts a Lua **string or number** (`lua_isstring`) and reports failure by leaving
-/// `0x703bf0`'s pre-seeded `""` in place, so an absent, nil or non-string global reads as empty —
-/// which is the same thing the factory's own name guard rejects. Empty folds to `None` here.
+/// Read `DAMAGE_TEXT_FONT` at the tail of the world-entry UI load (`0x6c8481`). `0x704350` takes
+/// a string or number and leaves `""` otherwise, which the font factory rejects; empty is `None`.
 pub(crate) fn read_damage_text_font(script: &benilla_ui::script::UiScript) -> DamageTextFont {
     let value: Option<String> = script.lua().globals().get("DAMAGE_TEXT_FONT").ok();
     DamageTextFont(value.filter(|v| !v.is_empty()))
@@ -212,50 +114,42 @@ pub(crate) fn read_damage_text_font(script: &benilla_ui::script::UiScript) -> Da
 /// one unit is dropped outright.
 const MAX_PER_UNIT: usize = 4;
 
-/// World text draws beneath every scripted UI quad (the real client renders it in the world scene,
-/// under all UI) and beneath the other two append-lane systems: the append lane's bottom band
-/// ([`crate::ui_pass::overlay_z`]) sorts first against the frame quads' packed strata keys.
+/// World text draws beneath all UI, as the reference draws it in the world scene: the append
+/// lane's bottom band ([`crate::ui_pass::overlay_z`]).
 const Z_WORLD_TEXT: u64 = overlay_z::WORLD_TEXT;
 
-/// Admit a spawn against the per-unit cap: the client scans the unit's 4 slots for the first
-/// NULL and **returns** when all are occupied — a hard drop, no eviction, no queue (`0x6c73f0`).
-/// The slot index matters beyond the cap: it is the seat-order key (slots walk descending).
+/// The first free of the unit's 4 slots; `None` is a hard drop, no eviction (`0x6c73f0`). The
+/// slot is also the seat-order key.
 fn free_slot(texts: &[WorldText], anchor: Entity) -> Option<u8> {
     (0..MAX_PER_UNIT as u8).find(|s| !texts.iter().any(|t| t.anchor == anchor && t.slot == *s))
 }
 
-/// The whole per-frame engine: drain spawns (snapshot + cap), expire the dead, and re-project the
-/// living into glyph quads appended to [`UiQuads`] after the script extract. Ordering (the
-/// [`UiQuadAppend`] set, after [`UiInput`]) guarantees the mesh rebuild never lands between the
-/// script's replace and our append — see `ui_pass`.
+/// The per-frame engine: admit spawns, expire the dead and project the living into quads appended
+/// to [`UiQuads`]. The [`UiQuadAppend`] set keeps the mesh rebuild from landing between the
+/// script's replace and this append.
 pub(crate) fn float_combat_text(
     mut spawns: MessageReader<CombatTextSpawn>,
     mut texts: ResMut<WorldTexts>,
     time: Res<Time>,
     transforms: Query<&Transform>,
-    // The camera's FRESH per-frame Transform (written by the controller earlier this frame),
-    // not the propagated GlobalTransform (last frame's until PostUpdate — projecting through it
-    // drags the text one frame behind the render when the camera moves). The world camera is a
-    // root entity (player/setup spawns it bare), so `GlobalTransform::from` is exact.
+    // This frame's Transform, not last frame's propagated GlobalTransform, so the text does not
+    // lag a moving camera; the world camera is a root entity, so `GlobalTransform::from` is exact.
     camera: Query<(&Camera, &Transform), With<WorldCamera>>,
     mut atlas: Option<ResMut<UiFontAtlas>>,
     mut quads: ResMut<UiQuads>,
-    // The overhead-anchor resolution (`0x608640`): the unit's PlayerName attachment joint, else
-    // the bbox fallback.
+    // The overhead anchor (`0x608640`): the PlayerName attachment, else the bbox fallback.
     anchors: Query<&BoneAttach>,
     poses: Query<&benilla_world::rig_anim::RigPose>,
     fallbacks: Query<&OverheadFallback>,
     globals: Query<&GlobalTransform>,
     mounts: Query<(), With<crate::entities::mount::MountChild>>,
-    // The frame's claim bucket 1 (worldtext) — cleared and rebuilt every pass; plates own
-    // bucket 0 in `vplates` and the two never interact.
+    // Claim bucket 1, rebuilt every pass; plates own bucket 0.
     mut bucket: Local<crate::smart_rect::SmartBucket>,
-    // The face, bound once on the world-entry load edge ([`DamageTextFont`]). Absent in a bare
-    // test world, where the fallback face is what the reference's stock `Fonts.xml` names anyway.
+    // Absent in a bare test world, which draws the default face.
     font: Option<Res<DamageTextFont>>,
 ) {
     let now = time.elapsed_secs_f64();
-    // Headless (captures/tests) the camera is None — spawns/expiry still run, nothing draws.
+    // Headless there is no camera: spawns and expiry run, nothing draws.
     let cam = camera
         .single()
         .ok()
@@ -268,8 +162,7 @@ pub(crate) fn float_combat_text(
         let Ok(tf) = transforms.get(spawn.anchor) else {
             continue; // anchor despawned before the spawn landed
         };
-        // The spawn snapshot (`0x6c73f0`): the unit's OVERHEAD anchor (`0x608640` — head height,
-        // [`overhead_anchor`]), then the client's `z − 1/3` lift. NOT feet-anchored.
+        // The spawn snapshot (`0x6c73f0`): the overhead anchor (`0x608640`), then `z − 1/3`.
         let overhead = overhead_anchor(
             spawn.anchor,
             tf,
@@ -321,43 +214,35 @@ pub(crate) fn float_combat_text(
         return;
     }
     let (Some((cam, cam_tf)), Some(atlas)) = (cam, atlas.as_mut()) else {
-        return; // headless (captures/tests) or pre-world: age, draw nothing
+        return; // headless or pre-world: age, draw nothing
     };
     let Some(viewport) = viewport else {
         return;
     };
-    // The per-frame reset (`0x509500`) + the ref's seat order: per-unit containers in their
-    // (stable, arbitrary) creation-list order — the anchor id here — and each unit's slots
-    // DESCENDING (`0x6c6e00` walks +0x2c→+0x20). Over the first-free-slot fill that seats the
-    // newest co-anchored number first, so the OLDER one is the pushed one — the reference's
-    // "the second number makes the first jump up".
+    // The per-frame reset (`0x509500`), then seats per unit in creation order (the anchor id
+    // here), slots descending (`0x6c6e00`): the newest number seats first, the older is pushed.
     bucket.clear();
     let mut order: Vec<usize> = (0..texts.0.len()).collect();
     order.sort_by_key(|&i| (texts.0[i].anchor, std::cmp::Reverse(texts.0[i].slot)));
-    // A number whose anchor fails the projector's accept verdict is **destroyed, and its slot
-    // released** (`6c7d9d` → `6c6dda` → `0x6c86a0`) — not skipped for a frame, and never clamped
-    // to a border. Collected here and reaped after the walk, since the walk holds the list.
+    // A rejected anchor destroys the text and frees its slot (`6c7d9d` to `6c6dda` to
+    // `0x6c86a0`); reaped after the walk, which holds the list.
     let mut culled: Vec<usize> = Vec::new();
     for i in order {
         let t = &texts.0[i];
         let cat = &CATEGORIES[t.category as usize];
         let elapsed_ms = ((now - t.born) * 1000.0) as f32;
         let life = elapsed_ms / cat.dur_ms;
-        // The rise enters world z BEFORE the projection (`6c7d29 fadd` into `+0x1c`, projected at
-        // `6c7d96`) — no post-projection y term exists.
+        // The rise enters world z before projection (`6c7d29`, projected at `6c7d96`).
         let world = t.pos + Vec3::Y * (cat.rise * life);
         let Some(screen) = crate::ui_pass::project_overlay(cam, &cam_tf, world, viewport) else {
-            culled.push(i); // behind the camera or off the viewport — the ref destroys it
+            culled.push(i); // behind the camera or off the viewport
             continue;
         };
-        // The size law: constant with distance (no depth term anywhere in the worldtext path).
+        // Constant with distance: the worldtext path has no depth term.
         let size_value = scale_value(t.category, life);
         let target_px = text_px(size_value, viewport);
-        // Laid out AT the target size. The crit pop animates through a continuum of sizes, which
-        // under the old fixed ladder meant shaping at the nearest rung and rescaling every quad
-        // about the anchor — a resampled bitmap for the whole animation. Now the pop steps through
-        // whole device-pixel sizes and each one is rasterized crisp (decision 1342). The real
-        // client stretched a ≤32 px raster here; rendering the true size is the recorded upgrade.
+        // Deviation: the reference stretches a raster of at most 32 px; each whole-pixel size is
+        // rasterized here, so the crit pop stays crisp.
         let mut e = atlas.lock();
         let mut glyphs = layout_text_quads(
             &mut e,
@@ -370,42 +255,29 @@ pub(crate) fn float_combat_text(
             },
             Z_WORLD_TEXT,
             FontSpec {
-                // The bound face, and NOT a hardcoded Friz: `Fonts\\FRIZQT__.TTF` is only what
-                // the stock `Fonts.xml` happens to assign, and an addon that assigns something
-                // else before the load edge closes is what the reference draws.
+                // The bound face, not a hardcoded Friz: an addon's assignment is what draws.
                 path: font.as_ref().and_then(|f| f.0.as_deref()),
                 height: Some(target_px),
                 outline: Outline::None,
                 alpha_gradient: None,
             },
-            // A world overlay riding its own rise/fade seat — the UI grid never applied (the
-            // degenerate rect above already skipped it; this says so out loud).
+            // A world overlay with its own seat; the UI grid does not apply.
             crate::ui_text::TextSeat::Exact,
         );
         drop(e);
         let (alpha_text, alpha_shadow) = fade_alpha(cat, elapsed_ms);
         let mut bounds: Option<Rect> = None;
         for q in &mut glyphs {
-            // REPLACE, never multiply: the fade byte IS the rendered alpha (module doc, the
-            // ALPHA + SHADOW law) — the packed color's alpha byte (row 4's 0x80) never draws.
+            // The fade replaces the alpha byte, never multiplies it.
             q.color[3] = f32::from(alpha_text) / 255.0;
             bounds = Some(bounds.map_or(q.rect, |b| b.union(q.rect)));
         }
-        // The seat (`0x6c7cc0` tail → `0x509520`): clamp the projected CENTER half-extents
-        // inside the viewport, build the centered AABB from the crit-pop-scaled measured
-        // half-extents, run it through claim bucket 1 — normalize → solve → clamp → claim
-        // ([`crate::smart_rect`]) — and place the string at the SOLVED rect's center. The ink
-        // then sits h-centered with its BOTTOM at that point: the string's own justify pair at
-        // creation (`6c8254 push 0x2` in the measure layout `0x6c81a0`'s `GxuFontCreateString` —
-        // vertical justify 2 = BOTTOM through `ComputeAnchor 0x5cdf70`'s `anchor.y = h +
-        // anchor.y` arm; horizontal 0 = left, the caller pre-subtracts hw → net h-centered), so
-        // the ink rises above the seat point while the claimed rect brackets it — the ref's
-        // exact asymmetry.
+        // The seat (`0x6c7cc0` tail to `0x509520`): clamp the centre inside the viewport, claim
+        // through bucket 1 ([`crate::smart_rect`]), and put the ink h-centred with its bottom at
+        // the solved centre. The string is created bottom-justified (`6c8254 push 0x2`, through
+        // `0x5cdf70`), so the ink rises above the point the claimed rect brackets.
         if let Some(b) = bounds {
-            // The claimed box is the ref's MEASURED BLOCK under its own units quirk — the box
-            // the solver sees runs 1/G48 (~1.667×) taller and 1/G44 (~1.25×) wider than the
-            // rendered glyphs, the reference's generous size-proportional padding
-            // ([`claimed_box_px`], `0x6c81a0`).
+            // Claimed box: 1/G48 taller and 1/G44 wider than the glyphs ([`claimed_box_px`]).
             let claim = claimed_box_px(b.width(), size_value, viewport);
             let (hw, hh) = (claim.x * 0.5, claim.y * 0.5);
             let cx = screen
@@ -428,10 +300,8 @@ pub(crate) fn float_combat_text(
                 }
             }
         }
-        // The drop shadow: a second draw of the same string — black, the fade's shadow lane
-        // (`0x5c27a0` + the `0xce8804` viewport-fraction offset, per-axis rounded). Pushed
-        // FIRST so the stable z-sort keeps it behind the fill at the shared Z_WORLD_TEXT key —
-        // the client's shadow-before-main double-walk (`0x5c8710`).
+        // The shadow (`0x5c27a0`, offset `0xce8804`): black, the fade's shadow lane. Pushed first
+        // so the stable z-sort keeps it behind the fill, as `0x5c8710` draws shadow before main.
         if alpha_shadow > 0 {
             let off = shadow_offset_px(viewport);
             quads.overlays.extend(glyphs.iter().map(|q| {
@@ -446,18 +316,11 @@ pub(crate) fn float_combat_text(
         }
         quads.overlays.append(&mut glyphs);
     }
-    // The destroy half of the cull above. Releasing the SLOT is the point, not just skipping the
-    // draw: the per-unit array is 4 deep and a spawn past it is a hard drop, so a number aging out
-    // of sight behind you would otherwise hold a slot a visible number could have had.
+    // Freeing the slot is the point: an unseen number would otherwise hold one of the unit's 4.
     drop_indices(&mut texts.0, culled);
 }
 
 /// Remove `idx` (in any order, no duplicates) from `v`, keeping the rest in order.
-///
-/// Its own function because the walk that decides *which* numbers to destroy runs over a sorted
-/// index permutation while the list is borrowed, so the removal has to happen afterwards by index
-/// — and index bookkeeping under removal is exactly the kind of thing that is quietly wrong for a
-/// month. Tested below.
 fn drop_indices<T>(v: &mut Vec<T>, mut idx: Vec<usize>) {
     if idx.is_empty() {
         return;
@@ -471,9 +334,8 @@ fn drop_indices<T>(v: &mut Vec<T>, mut idx: Vec<usize>) {
     });
 }
 
-/// The `0x5efea0` source-ownership class (`K`) over an attacker **entity** — the ECS-side twin of
-/// `net/apply/combat_log.rs::classify_source`, which does the same job from a guid. `None` is the
-/// classifier's "every other source", which suppresses the emit outright.
+/// The `0x5efea0` source class (`K`) of an attacker entity; `None` suppresses the emit. Must agree
+/// with `combat_log::text::classify_source`, which classifies by guid.
 fn source_class(
     attacker: Entity,
     self_player: &Query<(), With<crate::net::SelfPlayer>>,
@@ -490,15 +352,9 @@ fn source_class(
         .then_some(DamageSource::Pet)
 }
 
-/// The **deferred** outcome-word producer: a travelling spell's miss word, floated when the
-/// projectile lands rather than when `SMSG_SPELL_GO` arrives (decision 2229).
-///
-/// `0x6e7a70`'s inline word emit is skipped whenever the spell's `Spell.dbc` Speed is nonzero
-/// (`0x6e7d4e fld [SpellRec+0x94]; fcomp 0.0; test ah,0x44; jp 0x6e7e71`); the projectile's own
-/// arrival handlers re-resolve the record from `[missile+0x18]` and call the same word emitter
-/// `0x607140`. So a resisted Fireball reads "Resist" when the ball reaches the target, while a
-/// Speed-0 ability's word prints at packet receive. The colour law is the same one the inline
-/// site runs — the arrival pushes a real record, so a bit-15-clear spell's word is spell-GOLD.
+/// A travelling spell's miss word, floated when the projectile lands. `0x6e7a70` skips its inline
+/// emit when Speed (`SpellRec+0x94`) is nonzero (`0x6e7d4e`); the arrival re-resolves the record
+/// from `[missile+0x18]` and calls `0x607140`, so the word takes the spell's colour.
 fn missile_miss_text(
     mut arrivals: MessageReader<crate::entities::MissileMiss>,
     self_player: Query<(), With<crate::net::SelfPlayer>>,
@@ -519,7 +375,7 @@ fn missile_miss_text(
             .as_ref()
             .and_then(|s| s.catalog.get(arrival.spell_id));
         let Some(color) = damage_color(*gates, source, melee_styled(display)) else {
-            continue; // the CombatDamage / Pet* gates, read inside `0x607140` itself
+            continue; // the CombatDamage and Pet* gates, read inside `0x607140`
         };
         if let Some((word, category)) = miss_word(arrival.code) {
             text.write(CombatTextSpawn {
@@ -532,12 +388,8 @@ fn missile_miss_text(
     }
 }
 
-/// The MELEE number/word producer: consumes [`SwingImpact`] (the swing clip's impact keyframe —
-/// `creature_anim::impact`, the client's `0x6247d0 → 0x624530` deferral) rather than the packet,
-/// so the number pops when the blow lands, with the blood and the flinch. Gate A on entities: a
-/// self-player victim floats nothing (incoming damage is chat-log only). Then the color law's
-/// source class (`K`): only MY swings (white) or my pet's (orange) draw — another unit's melee
-/// on a third party floats nothing at all.
+/// The melee number or word, floated on [`SwingImpact`], the swing's impact keyframe (the
+/// reference's `0x6247d0` to `0x624530` deferral), so it lands with the blow. Gate A and `K` apply.
 fn melee_impact_text(
     mut impacts: MessageReader<crate::creature_anim::SwingImpact>,
     self_player: Query<(), With<crate::net::SelfPlayer>>,
@@ -547,10 +399,8 @@ fn melee_impact_text(
     mut text: MessageWriter<CombatTextSpawn>,
 ) {
     for crate::creature_anim::SwingImpact { swing: s, .. } in impacts.read() {
-        // `0x62440d` — the FIRST thing `0x6243e0` does, before the self gate and before the
-        // colour law: a swing from a spell that did not land plainly floats nothing. It is the
-        // same `0x625e40` verdict that suppresses the chat line, and it stops here and nowhere
-        // else — the flinch, the blood and the impact sounds all still fire.
+        // `0x62440d`, first in `0x6243e0`: a swing the `0x625e40` verdict hides floats nothing;
+        // the flinch, blood and sounds still fire.
         if !s.displayed {
             continue;
         }
@@ -562,7 +412,7 @@ fn melee_impact_text(
             continue; // K = other: never drawn
         };
         let Some(color) = damage_color(*gates, source, true) else {
-            continue; // the CombatDamage / PetMeleeDamage gates
+            continue; // the CombatDamage and PetMeleeDamage gates
         };
         if let Some((category, body)) = melee_text(s.hit_info, s.victim_state, s.damage) {
             text.write(CombatTextSpawn {
@@ -579,7 +429,7 @@ fn melee_impact_text(
 /// inside the append window the mesh rebuild waits on).
 pub(crate) struct CombatTextPlugin;
 
-/// The damage-text rows' change callback (decision 2303): three flags.
+/// The damage-text rows' change callback: three flags.
 pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut gates: ResMut<DamageTextGates>) {
     match ev.key().as_str() {
         "combatdamage" => gates.combat_damage = ev.flag(),
@@ -591,8 +441,7 @@ pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut gates: ResMut<Damag
 
 impl Plugin for CombatTextPlugin {
     fn build(&self, app: &mut App) {
-        // The Update append window (see [`UiQuadAppend`]): after the camera controller, and
-        // projecting through the camera's FRESH Transform (not the stale propagated global).
+        // The Update append window ([`UiQuadAppend`]), after the camera controller.
         app.add_observer(on_cvar);
         app.init_resource::<WorldTexts>()
             .init_resource::<DamageTextFont>()
@@ -612,10 +461,8 @@ mod tests {
     use super::law::COLOR_SPELL_GOLD;
     use super::*;
 
-    /// The 4-per-unit hard drop and the spawn snapshot: the real system run headless — no camera,
-    /// no atlas, and (with no `BoneAttach`/`OverheadFallback` on the bare test entities) the
-    /// overhead resolution degenerates to feet + 0 — so the snapshot pins at exactly the −1/3
-    /// lift and only the spawn/expire law engages.
+    /// Headless, and with no attachment on the bare entities the anchor is the feet, so the
+    /// snapshot is exactly `z − 1/3`.
     #[test]
     fn cap_is_four_per_unit_hard_drop() {
         let mut app = App::new();
@@ -649,26 +496,14 @@ mod tests {
         );
         assert_eq!(texts.0.iter().filter(|t| t.anchor == other).count(), 1);
         assert!((texts.0[0].pos.y - (-1.0 / 3.0)).abs() < 1e-6, "z − 1/3");
-        // The color resolution at spawn: NULL override → the row default (white); an override
-        // (the gold spawn over `other`) rides through verbatim.
+        // No override takes the row default; an override rides through.
         assert_eq!(texts.0[0].color, 0xFFFF_FFFF);
         let gold = texts.0.iter().find(|t| t.anchor == other).unwrap();
         assert_eq!(gold.color, COLOR_SPELL_GOLD);
     }
 
-    /// **A travelling spell's outcome word is DEFERRED, and it is GOLD** (decision 2229) — the
-    /// arrival half of the miss text: a resisted Fireball reads "Resist" in spell gold when the
-    /// ball lands, not white at GO.
-    ///
-    /// Four legs, each an independent branch of the law `0x607140` runs for every one of its
-    /// callers:
-    /// - my spell's word takes the **gold** override — `B=0` (Fireball's `AttributesEx3` bit 15 is
-    ///   clear) and `K=self`;
-    /// - a **ranged basic shot** carries that bit, so a missed Auto Shot floats melee-**white**
-    ///   even though it travels too — decision 0376's number pairing, now reaching the words;
-    /// - **Gate A** — a word never floats over your own head, whatever the colour;
-    /// - **`CombatDamage 0`** silences it, because that gate is read inside the word emitter
-    ///   itself and so binds every word path, not just the numbers.
+    /// The arrival word: gold for Fireball, white for Auto Shot (`AttributesEx3` bit 15), and
+    /// silenced by Gate A and by `CombatDamage 0`.
     #[test]
     fn a_travelling_spells_miss_word_is_gold_and_deferred_to_arrival() {
         use crate::entities::MissileMiss;
@@ -703,7 +538,7 @@ mod tests {
             )
         };
 
-        // `(spell, anchor-is-me, CombatDamage)` → the words the arrival floats.
+        // `(spell, anchor-is-me, CombatDamage)` to the words the arrival floats.
         let fire = |spell: u32, over_self: bool, combat_damage: bool| {
             let mut app = App::new();
             app.add_message::<MissileMiss>()
@@ -761,9 +596,7 @@ mod tests {
         );
     }
 
-    /// The destroy half of the off-screen cull (1344): the walk collects indices out of order,
-    /// against the *pre-removal* list, so the reap has to take them all at once and keep the rest
-    /// in order. Slots are freed by this and by nothing else.
+    /// The cull's walk collects indices unsorted, against the list before removal.
     #[test]
     fn drop_indices_takes_exactly_those() {
         let mut v = vec!["a", "b", "c", "d", "e"];
diff --git a/crates/benilla-app/src/console.rs b/crates/benilla-app/src/console.rs
index 161b8fdc..4a85d1da 100644
--- a/crates/benilla-app/src/console.rs
+++ b/crates/benilla-app/src/console.rs
@@ -1,20 +1,13 @@
-//! The in-game **console command registry** (decision 2303) — the reference's `ConsoleCommand`
-//! table, host side: `ConsoleCommandRegister 0x63f9e0` over a `TSExplicitList<CONSOLECOMMAND>`,
-//! with parse / register / lookup / execute (the registry runtime, `[0x63f880, 0x640c50)`). A
-//! subsystem registers its commands from its own plugin ([`ConsoleCommandApp::console_command`]),
-//! the way each of the reference's registers into the one table, and `/console <line>` reaches
-//! [`execute`] through the chat drain.
+//! The console command registry: the reference's `ConsoleCommand` table
+//! (`ConsoleCommandRegister` `0x63f9e0`, runtime `[0x63f880, 0x640c50)`). Subsystems register
+//! from their plugins; `/console <line>` reaches [`execute`] through the chat drain.
 //!
-//! **A CVar is a command too.** The reference's `CVar::Register` installs a per-CVar command
-//! under the CVar's own name (`0x63dde0`): a bare name prints `CVar "%s" is "%s"`, a name with a
-//! value sets it. So does this — over [`Cvars`] — after the registered commands, which is the
-//! reference's own lookup order. The four commands `ConsoleVar.cpp`'s `Initialize` registers
-//! (`set`, `cvar_reset`, `cvar_default`, `cvarlist`) are the built-ins [`ConsolePlugin`] adds,
-//! plus `help`, which the reference's registry runtime owns.
+//! Each CVar is also a command under its own name (`0x63dde0`): a bare name prints
+//! `CVar "%s" is "%s"`, a name with a value sets it, looked up after the registered commands.
+//! The built-ins are `ConsoleVar.cpp`'s four (`set`, `cvar_reset`, `cvar_default`, `cvarlist`)
+//! plus the registry's `help`.
 //!
-//! There is no console screen here — the drop-down that `` ` `` toggles in the reference — so a
-//! command's output is a system line in the chat frame. That is the seam `/console` already
-//! used; the registry is what the arm match behind it became.
+//! The reference's drop-down console screen is not built: output is a system line in chat.
 
 use std::collections::BTreeMap;
 
@@ -22,8 +15,7 @@ use bevy::prelude::*;
 
 use crate::cvars::{Cvars, SetOutcome};
 
-/// A command's body: the whole world, the argument tail after the command name (trimmed), and
-/// the lines to print in return.
+/// A command's body: the world and the trimmed argument tail in, the lines to print out.
 pub(crate) type ConsoleHandler = fn(&mut World, &str) -> Vec<String>;
 
 #[derive(Clone, Copy)]
@@ -34,14 +26,13 @@ struct ConsoleCommand {
     run: ConsoleHandler,
 }
 
-/// The registry — lowercased name → command, in name order.
+/// The registry: lowercased name to command, in name order.
 #[derive(Resource, Default)]
 pub(crate) struct ConsoleCommands {
     by_key: BTreeMap<String, ConsoleCommand>,
 }
 
-/// `app.console_command(name, help, handler)` — a subsystem registering its own command from
-/// its plugin, the reference's `ConsoleCommandRegister`.
+/// Registers a command from a plugin, the reference's `ConsoleCommandRegister`.
 pub(crate) trait ConsoleCommandApp {
     fn console_command(
         &mut self,
@@ -60,8 +51,7 @@ impl ConsoleCommandApp for App {
     ) -> &mut Self {
         let mut table = self.world_mut().get_resource_or_init::<ConsoleCommands>();
         let key = name.to_ascii_lowercase();
-        // Two registrations of one name is a wiring bug, never a runtime condition — and the
-        // reference's registry would silently shadow one with the other.
+        // Two registrations of one name is a wiring bug.
         assert!(
             !table.by_key.contains_key(&key),
             "console command {name:?} registered twice"
@@ -89,14 +79,11 @@ impl Plugin for ConsolePlugin {
     }
 }
 
-/// Run one console line — the reference's `ConsoleCommandExecute`: the first token is a command
-/// name (case-insensitive), the rest is its argument tail. A registered command runs; else a
-/// registered CVar answers as its per-CVar command does; else the line is reported as unknown.
-/// Returns the lines to print.
+/// Runs one console line, the reference's `ConsoleCommandExecute`: a registered command, else a
+/// CVar's own command, else unknown, matched case-insensitively. Returns the lines to print.
 ///
-/// A CVar write here is applied **at once** — its observers run before this returns — which is
-/// the reference's shape (the callback runs inside `CVar::Set`), and what makes a typed
-/// `/console farclip 500` visible on the next frame rather than the one after.
+/// A CVar write runs its observers before this returns, as the callback runs inside `CVar::Set`
+/// in the reference.
 pub(crate) fn execute(world: &mut World, line: &str) -> Vec<String> {
     let line = line.trim();
     let (name, args) = line
@@ -126,8 +113,8 @@ pub(crate) fn execute(world: &mut World, line: &str) -> Vec<String> {
     )]
 }
 
-/// `CVar "%s" is "%s"` — the per-CVar command's empty-argument arm (`0x63dde0`), with the
-/// staged value beside it when one is waiting for the latch boundary.
+/// `CVar "%s" is "%s"`, the per-CVar command with no argument (`0x63dde0`), plus any staged
+/// value.
 fn print_cvar(world: &World, name: &str) -> String {
     let cvars = world.resource::<Cvars>();
     let Some(row) = cvars.row(name) else {
@@ -142,7 +129,7 @@ fn print_cvar(world: &World, name: &str) -> String {
     }
 }
 
-/// A write through the registry, its observers run, and the outcome said back.
+/// A write through the registry with its observers run, and the outcome as a line.
 fn set_cvar(world: &mut World, name: &str, value: &str) -> Vec<String> {
     let (outcome, events) = {
         let mut cvars = world.resource_mut::<Cvars>();
@@ -164,10 +151,9 @@ fn set_cvar(world: &mut World, name: &str, value: &str) -> Vec<String> {
     }
 }
 
-/// `set <name> <value>` — the reference's `0x63d500`. **One stated divergence:** the reference
-/// registers an unknown name as a new category-5 record, invisible to Lua; ours refuses it,
-/// because a row nothing reads is exactly what the registry's honest-tree rule exists to keep
-/// out, and `config.toml` preserves an unknown key on its own.
+/// `set <name> <value>` (`0x63d500`). Deviation: the reference registers an unknown name as a new
+/// category-5 record; this refuses it, because nothing would read the row and `config.toml`
+/// keeps an unknown key anyway.
 fn set(world: &mut World, args: &str) -> Vec<String> {
     let (name, value) = args
         .split_once(char::is_whitespace)
@@ -178,8 +164,8 @@ fn set(world: &mut World, args: &str) -> Vec<String> {
     set_cvar(world, name, value)
 }
 
-/// `cvar_reset <name>` / `cvar_default <name>` — the reference's `0x63d590`/`0x63d640`. One
-/// body for both: our rows carry no separate reset value, so the reset target is the default.
+/// `cvar_reset` and `cvar_default` (`0x63d590`, `0x63d640`): one body, since a row has no reset
+/// value apart from its default.
 fn cvar_default(world: &mut World, args: &str) -> Vec<String> {
     let name = args.split_whitespace().next().unwrap_or("");
     if name.is_empty() {
@@ -195,9 +181,9 @@ fn cvar_default(world: &mut World, args: &str) -> Vec<String> {
     set_cvar(world, name, &default)
 }
 
-/// `cvarlist [match]` — the reference's `0x63d6f0`, in a format of our own: one line per row,
-/// the value, the default when the value moved, the staged value when one is waiting, and
-/// whether the session owns the row or an addon declared it.
+/// `cvarlist [match]` (`0x63d6f0`), one line per row: value, default when moved, staged value,
+/// and whether the session or an addon owns it. The reference's line format is untraced; this
+/// one is benilla's.
 fn cvarlist(world: &mut World, args: &str) -> Vec<String> {
     let wanted = args.split_whitespace().next().map(str::to_ascii_lowercase);
     let cvars = world.resource::<Cvars>();
@@ -233,7 +219,7 @@ fn cvarlist(world: &mut World, args: &str) -> Vec<String> {
     out
 }
 
-/// `help [command]` — the registry's own listing.
+/// `help [command]`: the registry's listing.
 fn help(world: &mut World, args: &str) -> Vec<String> {
     let table = world.resource::<ConsoleCommands>();
     let wanted = args.split_whitespace().next();
@@ -272,9 +258,6 @@ mod tests {
         execute(app.world_mut(), line)
     }
 
-    /// **The lookup order is the reference's**: a registered command first, then the CVar's own
-    /// per-name command (bare name prints, a value sets), then unknown — case-insensitively at
-    /// every step, like the engine's own table lookup.
     #[test]
     fn a_line_is_a_command_then_a_cvar_then_unknown() {
         let mut app = console_app();
@@ -351,7 +334,6 @@ mod tests {
         );
     }
 
-    /// `cvarlist` marks a moved value with its default, a session-owned row, and an addon's.
     #[test]
     fn cvarlist_says_where_each_row_stands() {
         let mut app = console_app();
@@ -379,7 +361,6 @@ mod tests {
         assert_eq!(some.len(), 2, "matched case-insensitively: {some:?}");
     }
 
-    /// `help` lists what is registered, and a subsystem's registration is one call.
     #[test]
     fn help_lists_the_registry_and_a_registration_is_one_call() {
         fn shout(_: &mut World, args: &str) -> Vec<String> {
diff --git a/crates/benilla-app/src/crash.rs b/crates/benilla-app/src/crash.rs
index a8b67d96..d1c26422 100644
--- a/crates/benilla-app/src/crash.rs
+++ b/crates/benilla-app/src/crash.rs
@@ -1,31 +1,12 @@
-//! **A crash leaves an artefact** (decision 2266 §B2).
+//! A panic leaves a crash report. [`install`] chains a hook after Rust's default one, which still
+//! prints to stderr, and writes `benilla-config/Diagnostics/crash-<unix-seconds>.txt` through
+//! [`crate::local_state`]: the build id, time and uptime, thread, location and payload, a
+//! backtrace captured regardless of `RUST_BACKTRACE`, and the last
+//! [`benilla_world::log_ring::CAPACITY`] log lines. The path is the last stderr line.
 //!
-//! Until this module, a panic printed to stderr and the process was gone — and with it everything
-//! a reporter could have attached. The only log sink was the terminal; a packaged Windows build
-//! has no console; of bug B390's four reporters one attached a backtrace, because he had set
-//! `RUST_BACKTRACE=1` on his own. `shutdown.rs` says the other half out loud: *"A crash, a
-//! `SIGKILL`, a wedged teardown. Nothing survives those."*
-//!
-//! [`install`] chains a panic hook in front of Rust's default one. The default still prints to
-//! stderr exactly as before (so every log a session already greps keeps reading the same); then
-//! the report goes to **`benilla-config/Diagnostics/crash-<unix-seconds>.txt`**, resolved through
-//! [`crate::local_state`] like every other file benilla writes (the one-folder rule, 0954/1175 —
-//! never a platform log dir, never beside the install). The file carries: the build id (the sha
-//! is the version, `build_id`), the time and the uptime, the thread, the panic's location and
-//! payload, a backtrace captured **regardless of `RUST_BACKTRACE`**, and the last
-//! [`benilla_world::log_ring::CAPACITY`] log lines — the minute before, which is what turns a
-//! symptom into a story. The path is printed to stderr as the last line, so "attach the file it
-//! names" is the whole instruction to a reporter.
-//!
-//! **What it does not cover, said out loud.** A non-unwinding panic — an allocation failure's
-//! abort, a `panic` inside a `Drop` during unwinding, a foreign frame — never reaches any hook;
-//! B390's own was one (`thread caused non-unwinding panic. aborting.`). The hook covers the
-//! unwinding class (B88, B130, B260, B383's shape: four of the six panics the ledger holds).
-//! Flushing saved variables and the CVar diff from inside a panic is a second, riskier item —
-//! the world is half-torn by then — and is deliberately not bundled here (2265 §B2).
-//!
-//! A hermetic capture run (`local_state::home()` answers `None`) writes no file and loses
-//! nothing: the harness already has stderr.
+//! A non-unwinding panic (an allocation-failure abort, a panic in `Drop` during unwinding) never
+//! reaches a hook. Saved variables and the CVar diff are not flushed from inside a panic.
+//! Without a local state home (a hermetic capture run) no file is written.
 
 use std::fmt::Write as _;
 use std::panic::PanicHookInfo;
@@ -35,8 +16,8 @@ use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
 use crate::BuildId;
 
-/// Chain the crash-report hook in front of the current panic hook. Called once, from
-/// [`crate::run`], before the `App` exists — a panic while plugins build is still a crash.
+/// Chains the crash-report hook after the current one. Called once from [`crate::run`], before
+/// the `App` exists, so a panic while plugins build is covered.
 pub(crate) fn install(build: BuildId) {
     let started = Instant::now();
     let previous = std::panic::take_hook();
@@ -46,14 +27,11 @@ pub(crate) fn install(build: BuildId) {
     }));
 }
 
-// The standing test affordance — `WOW_CRASH_INJECT=<at_secs>`, one deliberate main-thread panic
-// mid-run — is `perf::crash_inject`, a dev root: this module ships to players and knows nothing
-// of the `dev` seam (run_mode's one-door rule, 1176), and an instrument's home is with the
-// instruments. Its module doc carries the cross-platform incident that moved it there.
+// The injected test panic (`WOW_CRASH_INJECT=<at_secs>`) lives in `perf::crash_inject`, behind
+// the `dev` feature.
 
-/// Re-entrancy latch: a panic *inside* the hook (a poisoned lock, a failed write) must not
-/// recurse into it. Never cleared on purpose — after one report the process is on its way out,
-/// and a second panic's report would only overwrite the useful one with a worse one.
+/// Re-entrancy latch, never cleared: a panic inside the hook must not recurse, and only the
+/// first report is kept.
 static REPORTING: AtomicBool = AtomicBool::new(false);
 
 fn report(info: &PanicHookInfo<'_>, build: BuildId, uptime: Duration) {
@@ -93,8 +71,7 @@ fn report(info: &PanicHookInfo<'_>, build: BuildId, uptime: Duration) {
     }
 }
 
-/// Everything the report says, gathered before rendering so the renderer is a pure function the
-/// test can drive without panicking.
+/// Everything the report says, gathered so rendering is pure.
 struct Report<'a> {
     build: BuildId,
     unix: u64,
@@ -138,10 +115,8 @@ fn render(r: &Report<'_>) -> String {
     out
 }
 
-/// Write the report under `dir` as `crash-<unix>.txt`, creating the folder on demand (an empty
-/// `Diagnostics/` on every run would be this instrument advertising itself, `perf::stall`'s
-/// reason). Plain `fs::write`, not `local_state::write_atomic`: the process is dying, and a
-/// half-written report beats none.
+/// Writes `crash-<unix>.txt` under `dir`, creating the folder only now. Plain `fs::write`, not
+/// `write_atomic`: the process is dying, and a partial report beats none.
 fn write(dir: &Path, text: &str) -> Option<PathBuf> {
     let unix = SystemTime::now()
         .duration_since(UNIX_EPOCH)
@@ -164,8 +139,6 @@ mod tests {
         profile: "debug",
     };
 
-    /// The report names the build, the place, the payload and the log — the four things a
-    /// reporter cannot reconstruct after the fact — and lands in the folder it was given.
     #[test]
     fn a_report_carries_the_build_the_place_the_payload_and_the_log() {
         let log = vec!["+  1.000s  INFO benilla_app::net: entered world".to_owned()];
diff --git a/crates/benilla-app/src/cursor.rs b/crates/benilla-app/src/cursor.rs
index 6c385139..406cedd6 100644
--- a/crates/benilla-app/src/cursor.rs
+++ b/crates/benilla-app/src/cursor.rs
@@ -1,47 +1,18 @@
-//! The mouse cursor — the real client's `Interface\Cursor\*.blp` set, shown as a crisp **hardware
-//! (OS-composited) cursor** so it has zero lag, matching the reference 1.12 client (whose cursor is
-//! lag-free on this same machine). Which cursor shows is the targeting classifier's call
-//! ([`crate::target::WorldCursor`], the reference's decision tree at `0x4828d0`): Point by
-//! default, the sword over an attackable unit, the speech bubble / pouch / trainer / taxi over
-//! service NPCs, loot/skin over corpses — each with its grayed `Unable*` twin out of range. The
-//! whole set preloads at startup (18 tiny BLPs); a stem missing from the archives falls back toward
-//! the base cursor, then Point.
+//! The mouse cursor: the `Interface\Cursor\*.blp` set as a hardware cursor, as the reference
+//! shows it. The mode comes from the world classifier (`0x4828d0`) and FrameXML; a held payload's
+//! icon replaces it, composited to 32×32 (`0x523840`) and uploaded the same way (`0x523790`).
 //!
-//! macOS needs native AppKit. winit drives the cursor through the legacy cursor-rect API
-//! (`addCursorRect`/`resetCursorRects`), which a continuously-redrawing Metal view doesn't honor on
-//! mouse-move — so winit's `CursorIcon::Custom` and `CursorOptions.visible = false` both revert to the
-//! arrow the instant you move (verified against winit's source). We bypass that: build an `NSCursor`
-//! per mode from its BLP, call `NSWindow::disableCursorRects` to stop AppKit's cursor-rect
-//! reconciliation, then `[cursor set]` the current mode directly (re-asserted each non-look frame).
-//! During mouselook we `NSCursor::hide()`/`unhide()` (the reliable app-global hide counter). Other
-//! platforms use winit's `CursorIcon::Custom` (which works there), swapped on mode change; their
-//! hide-on-look goes through `CursorOptions.visible`, handled in `player::control`.
-//!
-//! **The held cursor payload** (decision 0216 §5): while `UiScript::cursor_payload()` holds a
-//! payload with a resolved icon, the HARDWARE cursor becomes that icon instead of the classified
-//! mode — the real client composites the item's `Interface\Icons\…` art into its drag bitmap
-//! (`0x523840`) and uploads it via the same `SetHardwareCursor` path the mode art uses
-//! (`0x523790`). Both platform `drive` fns below check the held payload FIRST, each frame, and fall
-//! back to the mode cursor when nothing is held or its icon fails to decode; each caches its built
-//! cursor per icon path ([`other::PayloadCursorImages`]/[`macos::PayloadCursors`]) — repeated
-//! pickups of the same icon never re-decode. The icons are 64×64 (unlike the mode BLPs, already
-//! 32×32); [`box_downsample_32`] shrinks one to the cursor's fixed 32×32 with hotspot `(0, 0)` —
-//! the pointer sits at the icon's top-left corner, the icon hangs down-right, matching the
-//! reference look (and `ui_script::extract::cursor_icon_quad`'s capture-only stand-in).
+//! On macOS winit's cursor-rect route reverts to the arrow on every mouse move under a
+//! continuously redrawing Metal view, so this builds an `NSCursor` per mode, disables the window's
+//! cursor rects and sets the cursor directly; mouselook uses `NSCursor::hide`/`unhide`. Elsewhere
+//! winit's `CursorIcon::Custom` works and hide-on-look is `CursorOptions.visible`.
 
 use benilla_assets::AssetSet;
 use bevy::prelude::*;
 
-/// The held cursor payload's icon path (`Interface\Icons\…`, extensionless — the DBC/FrameXML
-/// convention), any arm — `None` if nothing is held or that arm's icon hasn't resolved yet
-/// (either way, the caller falls back to the mode cursor).
-///
-/// **`covered` — the loading cover drops the overlay** (decision 1990, VERIFIED). The reference's
-/// world transition ends `0x401900 → 0x495920 → 0x6e4940` with `0x523d20(1)` + `0x523c20(1)`:
-/// cursor index **1**, the plain arrow, with any item/spell overlay dropped, set *before* the
-/// screen goes up. Without this a portal taken with an item on the cursor showed the item's icon
-/// over the loading art for the whole load — the mode half of the same rule is
-/// [`drive_displayed_cursor`]'s.
+/// The held cursor payload's extensionless icon path. `covered` drops it: the reference's world
+/// transition (`0x6e4940`) calls `0x523d20(1)` and `0x523c20(1)` before the loading screen goes up,
+/// the plain arrow with no overlay.
 fn payload_icon(script: &benilla_ui::script::UiScript, covered: bool) -> Option<String> {
     use benilla_ui::script::CursorPayload;
     if covered {
@@ -53,25 +24,19 @@ fn payload_icon(script: &benilla_ui::script::UiScript, covered: bool) -> Option<
         CursorPayload::Action(a) => a.texture,
         CursorPayload::Macro(m) => m.texture,
         CursorPayload::PetAction(p) => p.texture,
-        // Mode 10 — the stabled pet's family icon (decision 1677). Always present: a non-empty
-        // icon path is the grab's own gate.
+        // Mode 10: the stabled pet's family icon; a non-empty path gates the grab.
         CursorPayload::StablePet(p) => Some(p.texture),
-        // Mode 2 (1965) — the coin bitmap by magnitude, `GetCoinIcon`'s own table.
+        // Mode 2: the coin bitmap by magnitude, `GetCoinIcon`'s table.
         CursorPayload::Money(m) => {
             Some(benilla_ui::script::coin_icon(i64::from(m.copper)).to_string())
         }
-        // Mode 5 — the vendor row's icon. The reference stores the row's `ItemDisplayInfo` id
-        // (`0xb4d8ec`) and resolves the art from it; we carry the resolved path, so this is the
-        // same picture one hop later.
+        // Mode 5: the vendor row's icon, which the reference resolves from its `ItemDisplayInfo`
+        // id (`0xb4d8ec`).
         CursorPayload::Merchant(m) => m.texture,
     }
 }
 
-/// Box-downsample a raw RGBA8 image (top-to-bottom raster order —
-/// [`benilla_assets::WorldAssets::decode_rgba`]'s layout) to a fixed 32×32 buffer: each output
-/// texel averages a `(w/32)×(h/32)` block of the source. Vanilla item icons are 64×64 — a clean
-/// 2×2 average per output texel (decision 0216 §5) — but this degrades gracefully for any other
-/// source size.
+/// Box-downsample top-to-bottom RGBA8 to 32×32, each texel averaging a `(w/32)×(h/32)` block.
 fn box_downsample_32(w: u32, h: u32, rgba: &[u8]) -> Vec<u8> {
     const OUT: u32 = 32;
     let mut out = vec![0u8; (OUT * OUT * 4) as usize];
@@ -104,10 +69,8 @@ fn box_downsample_32(w: u32, h: u32, rgba: &[u8]) -> Vec<u8> {
     out
 }
 
-/// Decode a payload icon and box-downsample it to a 32×32 hardware-cursor-ready RGBA8 buffer
-/// ([`box_downsample_32`]), alpha forced fully opaque — the client's own drag-bitmap composite
-/// (`0x523840`: 64×64 → 2×2 box filter → 32×32, alpha written 0xFF; folded back by 0218). `None`
-/// on a missing/undecodable icon.
+/// Decode a payload icon to an opaque 32×32 RGBA8 cursor, as the client's drag bitmap does
+/// (`0x523840`: a 64×64 icon, 2×2 box filter, alpha 0xFF).
 fn decode_payload_cursor_rgba(
     assets: &mut benilla_assets::WorldAssets,
     path: &str,
@@ -120,8 +83,7 @@ fn decode_payload_cursor_rgba(
     Some(out)
 }
 
-/// Every cursor BLP stem benilla can currently show ([`crate::target::WorldCursor::stem`]): the
-/// classifier's modes + their grayed twins. Preloaded once at startup.
+/// Every stem [`crate::target::WorldCursor::stem`] can name, preloaded at startup.
 const CURSOR_STEMS: &[&str] = &[
     "Point",
     "Attack",
@@ -130,14 +92,14 @@ const CURSOR_STEMS: &[&str] = &[
     "UnableSpeak",
     "Pickup",
     "UnablePickup",
-    // The loot leg's triple pouch (0965): effective auto-loot on (0961's setting XOR shift).
+    // The loot pouch: auto-loot XOR shift.
     "LootAll",
     "UnableLootAll",
     "Interact",
     "UnableInteract",
     "Buy",
     "UnableBuy",
-    "Inspect", // the Ctrl-hover magnifier (ShowInspectCursor) AND the TEXT-GameObject plaque cursor
+    "Inspect", // the Ctrl-hover magnifier (ShowInspectCursor) and the text GameObject cursor
     "UnableInspect",
     "Trainer",
     "UnableTrainer",
@@ -145,9 +107,8 @@ const CURSOR_STEMS: &[&str] = &[
     "UnableTaxi",
     "Skin",
     "UnableSkin",
-    "Repair", // the repair-mode base cursor (never grayed — the shipped UnableRepair is unreachable)
-    // The data-driven GameObject cursors (decision 0236, `0x5f8760`): a mailbox's Mail, a lock's
-    // Mine / GatherHerbs (grayed out of reach), a picked lock's PickLock (never grayed).
+    "Repair", // the repair-mode base, never grayed: the shipped UnableRepair is unreachable
+    // The data-driven GameObject cursors (`0x5f8760`); PickLock is never grayed.
     "Mail",
     "UnableMail",
     "Mine",
@@ -155,9 +116,7 @@ const CURSOR_STEMS: &[&str] = &[
     "GatherHerbs",
     "UnableGatherHerbs",
     "PickLock",
-    // The spell-targeting pair (`0x4820f0`): Cast(2) / UnableCast(22). Cast is
-    // the armed-enchant-pick overlay's mode; the grayed twin preloads with it (the overlay's
-    // valid/invalid split is its named refinement).
+    // The spell-targeting pair (`0x4820f0`): Cast(2) and UnableCast(22).
     "Cast",
     "UnableCast",
 ];
@@ -167,92 +126,47 @@ fn cursor_path(stem: &str) -> String {
     format!("Interface\\Cursor\\{stem}.blp")
 }
 
-/// The **displayed** cursor — the client's single sticky mode global `0xbe2c2c`. Read by the
-/// platform drivers instead of [`crate::target::WorldCursor`], which is only ever *one* of its two
-/// writers.
+/// The displayed cursor, the client's one sticky mode cell `0xbe2c2c`;
+/// [`crate::target::WorldCursor`] is one of its two writers.
 #[derive(Resource, Clone, Copy, PartialEq, Eq, Debug, Default)]
 pub(crate) struct DisplayedCursor(pub(crate) crate::target::WorldCursor);
 
-/// Resolve this frame's displayed cursor — **one sticky mode with two writers** (decision 1064).
-///
-/// The reference has exactly one cursor-mode cell and everything that wants a cursor calls
-/// `CursorSetMode` on it. Two things do:
-///
-/// - **the world**, from the WorldFrame's hover handler `0x481790` — which runs *only while the
-///   WorldFrame is the frame manager's mouse-focus frame* (`4817ae: cmp [[this+0xa0]+0x7c], this;
-///   jne`). Over a UI frame it does not run, and writes nothing.
-/// - **FrameXML**, from a hover handler — `ShowContainerSellCursor`, `ShowInspectCursor`,
-///   `SetCursor`, `ResetCursor`.
-///
-/// **Between those two, nothing writes it, so the last value simply stands.** That is the whole
-/// correction here, and B208's regression was getting it wrong in each direction at once: the old
-/// code recomputed the mode from the world every frame (so a UI hover could never keep a cursor),
-/// and 1055 then made the world *skip* over UI while the classifier still wrote Point underneath
-/// (so every UI element force-reset the cursor). Either way an armed spell lost its cast cursor the
-/// instant the mouse touched a spellbook button — which is what the director saw.
-///
-/// So: a FrameXML write wins the frame it happens; otherwise the world's verdict applies while the
-/// pointer is over the world; otherwise the mode is left exactly as it was. The bag's `ResetCursor()`
-/// still resets over a bag slot, because it is a *write* — and a spellbook button, which calls no
-/// cursor function at all, correctly changes nothing.
+/// Resolve this frame's displayed cursor: one sticky mode with two writers, the world (the
+/// WorldFrame's hover handler `0x481790`, only while it holds mouse focus) and FrameXML
+/// (`SetCursor`, `ResetCursor`, `ShowContainerSellCursor`, `ShowInspectCursor`). Between writes
+/// the last value stands, so a frame that calls no cursor function changes nothing.
 fn drive_displayed_cursor(
     world: Res<crate::target::WorldCursor>,
     over_ui: Res<crate::ui_script::PointerOverUi>,
     targeting: Res<crate::spell::targeting::SpellTargeting>,
     script: Option<bevy::ecs::system::NonSendMut<benilla_ui::script::UiScript>>,
-    // The base last applied by the UI-entry restore below — `None` while the pointer is over the
-    // world, so re-entering the UI always restores once.
+    // The base last restored on entering the UI; `None` over the world, so re-entry restores.
     mut last: Local<crate::ui_script::VmMemo<Option<crate::target::WorldCursor>>>,
     mut displayed: ResMut<DisplayedCursor>,
-    // The loading cover parks the mode at Point — see the arm at the top of the body.
     screen: Res<crate::loading_screen::LoadingScreen>,
 ) {
     use crate::target::{CursorKind, WorldCursor};
     use benilla_ui::script::UiCursorMode;
 
-    // A VM memo — the restore edge below is armed by `take_cursor_write`, a VM read — but unlike
-    // every other feed this system still drives the cursor with **no VM at all** (the character
-    // screen: the VM lives for one login, decision 1290). `get_for` is the shape for exactly that:
-    // no VM is a session in its own right, so the base restore re-arms once on each side of the
-    // glue phase instead of every frame inside it.
+    // This runs with no VM too (the character screen); `get_for` treats that as its own session,
+    // so the restore re-arms once on each side of the glue phase.
     let last = last.get_for(script.as_deref());
 
-    // **Under the loading cover the cursor is the plain arrow** (decision 1990, VERIFIED). The
-    // reference's transition parks cursor index **1** at `0x6e49f5`/`0x6e49ff` before raising the
-    // screen; ours is parked here every covered frame instead of once, which reads the same because
-    // the cover has already taken the input plane and nothing can write the mode under it. Ahead of
-    // every other arm — a FrameXML write, the repair/targeting base, the sticky UI mode — because
-    // the reference's park is likewise unconditional. `last` is cleared like the over-world arm, so
-    // the first crossing back into the UI after the reveal restores the base once.
+    // Under the loading cover the cursor is the plain arrow, ahead of every other arm: the
+    // reference parks index 1 unconditionally before raising the screen (`0x6e49f5`).
     if screen.covering() {
         displayed.0 = WorldCursor::default();
         *last = None;
         return;
     }
 
-    // **The BASE mode is not a constant** (`0xbe2c4c`: it is independently mutable — e.g. a
-    // spell-cancel flow parks it at Cast(2)), and that is the piece B208 kept missing.
-    // `ResetCursor` restores *the value of this cell*, not a hardcoded Point — so what a bag slot's
-    // `ResetCursor()` shows depends entirely on what is parked here.
-    //
-    // While a spell awaits its click, the base is **Cast(2)**. The director watched the reference
-    // do exactly this: with Feed Pet armed the cursor is blue over *"pretty much anything UI
-    // related"* and grey only out in the world. Both halves fall out of one cell — over the world
-    // the classifier writes the per-seam verdict (grey, for a word with no world handler), and over
-    // UI nothing overrides the base, so the blue shows.
-    //
-    // The corroborating gate is `ShowContainerSellCursor 0x4fa460`'s second test, *"base mode is
-    // Point(1), else bail"*: a test that is only ever meaningful because the base is routinely
-    // **not** Point while targeting.
-    //
-    // Note what this blue does NOT mean: it is not a validity verdict. It says "a spell is armed",
-    // not "this item is a legal target" — no hover-time item verdict exists anywhere in 1.12
-    // (decision 1055), so valid and invalid food look identical here, exactly as they do in the
-    // reference.
+    // The base cell (`0xbe2c4c`) is mutable and `ResetCursor` restores its value, not Point.
+    // While a spell awaits its click it is Cast(2), so the UI reads blue whatever the hovered item:
+    // 1.12 has no hover-time validity verdict. `ShowContainerSellCursor` (`0x4fa460`) bails unless
+    // the base is Point.
     let repair = script.as_ref().is_some_and(|s| s.repair_mode());
     let base = if repair {
-        // `ShowRepairCursor 0x4fbcc0` parks the base at Repair for as long as it holds; it is the
-        // explicit modal, so it wins the cell.
+        // `ShowRepairCursor` (`0x4fbcc0`) parks the base at Repair while it holds.
         WorldCursor {
             kind: CursorKind::Repair,
             unable: false,
@@ -262,12 +176,8 @@ fn drive_displayed_cursor(
             .as_ref()
             .is_some_and(|s| s.gift_wrap_armed().is_some())
     {
-        // An armed **gift wrap** parks the base at Cast(2) for the same reason a targeting spell
-        // does, and by the same act: `0x5edea0`'s three calls are `LockItem`, **`SetCursorBaseMode(2)`**
-        // and `CursorSetMode(2)` (decision 1934). Both cells, deliberately — the displayed one so the
-        // cursor changes at the click, the BASE one so it survives the pointer crossing the world,
-        // where the classifier would otherwise write its own verdict over it. Setting only the
-        // displayed mode would lose the wrap cursor the moment the mouse left the bag.
+        // An armed gift wrap sets both cells to Cast(2) (`0x5edea0`: `SetCursorBaseMode(2)`,
+        // `CursorSetMode(2)`), so its cursor survives the pointer crossing the world.
         WorldCursor {
             kind: CursorKind::Cast,
             unable: false,
@@ -300,7 +210,7 @@ fn drive_displayed_cursor(
                     unable: true,
                 },
                 Some(UiCursorMode::Point) => WorldCursor::default(),
-                // `ResetCursor` — displayed goes back to the base mode, Repair included.
+                // `ResetCursor`: back to the base mode, Repair included.
                 None => base,
             };
             *last = Some(base);
@@ -312,18 +222,9 @@ fn drive_displayed_cursor(
         *last = None;
         return;
     }
-    // Over UI with no FrameXML write this frame. The mode is still sticky between writes — a UI
-    // element that calls no cursor function must not disturb it — but **crossing into the UI, and
-    // any later change of the base, restores the base**, which is what makes an armed spell read
-    // blue over the interface at large rather than dragging the world's grey in behind the mouse.
-    //
-    // In the reference that restore is spread across the UI rather than centralised: nearly every
-    // hover handler ends in `ResetCursor()` (`ContainerFrameItemButton_OnEnter`'s else branch,
-    // `CursorUpdate`/`CursorOnUpdate` in `UIParent.lua`, every `OnLeave`), and the world
-    // classifier's own no-hover path is the same `0x523d30` restore. Modelling it as one edge here
-    // gets the same observable without requiring each of our frames to have grown its
-    // `ResetCursor()` call yet — and a frame that DOES write still wins, so the unit-frame
-    // lit/grey split survives.
+    // Over UI with no FrameXML write: crossing in, or a base change, restores the base once. This
+    // one edge stands for the `ResetCursor()` that ends nearly every reference hover handler and
+    // the classifier's no-hover restore (`0x523d30`).
     if *last != Some(base) {
         *last = Some(base);
         displayed.0 = base;
@@ -357,9 +258,7 @@ impl Plugin for CursorPlugin {
     }
 }
 
-/// Non-macOS: winit's custom OS cursor works fine — preload every mode's image and swap the
-/// window's `CursorIcon` when the classified mode changes. Hide-on-look is `CursorOptions.visible`,
-/// driven by `player::control`.
+/// Non-macOS: winit's custom cursor, swapped on change; hide-on-look is in `player::control`.
 #[cfg(not(target_os = "macos"))]
 mod other {
     use super::{cursor_path, payload_icon, CURSOR_STEMS};
@@ -368,13 +267,11 @@ mod other {
     use bevy::prelude::*;
     use bevy::window::{CursorIcon, CustomCursor, CustomCursorImage, PrimaryWindow};
 
-    /// stem → decoded cursor image, preloaded at startup.
+    /// Stem → decoded cursor image, preloaded at startup.
     #[derive(Resource, Default)]
     pub(super) struct CursorImages(HashMap<String, Handle<Image>>);
 
-    /// Held-payload icon path → its decoded 32×32 hardware cursor (decision 0216 §5), built
-    /// lazily on first use (unlike [`CursorImages`]'s fixed startup preload — the icon set is far
-    /// too large to preload) and cached so a repeated pickup never re-decodes.
+    /// Held-payload icon path → its 32×32 cursor, built on first use and cached.
     #[derive(Resource, Default)]
     pub(super) struct PayloadCursorImages(HashMap<String, Handle<Image>>);
 
@@ -398,9 +295,8 @@ mod other {
         commands.insert_resource(CursorImages(map));
     }
 
-    /// Each frame: while a cursor payload with a resolved icon is held, show ITS 32×32 hardware
-    /// cursor (decoded/downsampled on first use, then cached by path); otherwise swap to the
-    /// classified mode (base-stem fallback, then Point, then OS) — unchanged from before 0216 §5.
+    /// Show the held payload's icon when it resolves, else the displayed mode (then its base stem,
+    /// then Point).
     pub(super) fn drive(
         mut commands: Commands,
         cursor: Res<super::DisplayedCursor>,
@@ -409,12 +305,10 @@ mod other {
         world_assets: Option<ResMut<WorldAssets>>,
         mut images: ResMut<Assets<Image>>,
         mut payload_cursors: ResMut<PayloadCursorImages>,
-        // The loading cover drops the payload overlay — see [`payload_icon`].
         screen: Res<crate::loading_screen::LoadingScreen>,
         window: Option<Single<Entity, With<PrimaryWindow>>>,
-        // The key of the cursor we last handed the window — the macOS arm's `last_set` under the
-        // same name, because it is the same fact: OS state, not memory about the VM, so it is not a
-        // [`crate::ui_script::VmMemo`] and does not re-seat at a new login (decision 1290's sweep).
+        // The key of the cursor last handed the window: OS state, so not a
+        // [`crate::ui_script::VmMemo`].
         mut last_set: Local<Option<String>>,
         mut decode_failed: Local<HashSet<String>>,
     ) {
@@ -448,7 +342,7 @@ mod other {
                 *last_set = Some(icon);
                 return;
             }
-            // Decode failed (or still pending catalogs): fall through to the mode cursor below.
+            // Decode failed: fall through to the mode cursor.
         }
 
         let Some(cursors) = cursors else {
@@ -469,9 +363,7 @@ mod other {
         *last_set = Some(stem);
     }
 
-    /// The shared `CustomCursor::Image` insert — hotspot `(0, 0)`: the vanilla mode cursors' active
-    /// tip is their top-left pixel, and the held-payload icon is downsampled to match that same
-    /// top-left hotspot convention (decision 0216 §5).
+    /// Insert a custom cursor with hotspot `(0, 0)`, the vanilla cursors' top-left tip.
     fn set_custom_cursor(commands: &mut Commands, window: Entity, handle: Handle<Image>) {
         commands
             .entity(window)
@@ -502,27 +394,17 @@ mod macos {
 
     use super::{cursor_path, payload_icon, CURSOR_STEMS};
 
-    /// The built `NSCursor` per mode stem. Held as a non-send resource because AppKit types aren't
-    /// `Send`/`Sync` and must only be touched on the main thread. `pub(super)` only so it can appear
-    /// in `drive`'s param list (the plugin registers `drive` from the parent module).
+    /// The built `NSCursor` per mode stem; non-send, as AppKit types are main-thread only.
     pub(super) struct NativeCursors(HashMap<&'static str, Retained<NSCursor>>);
 
-    /// Held-payload icon path → its built 32×32 `NSCursor` (decision 0216 §5) — the mac twin of
-    /// [`super::other::PayloadCursorImages`], built lazily on first use and cached by path.
+    /// Held-payload icon path → its 32×32 `NSCursor`, built on first use and cached.
     pub(super) struct PayloadCursors(HashMap<String, Retained<NSCursor>>);
 
-    /// Build every mode's `NSCursor` from its BLP and store them. An **exclusive** system so it runs
-    /// on the main thread (AppKit's requirement) and can insert the non-send resource. The
-    /// window-level `disableCursorRects` + first `set` happen in [`drive`], once the window
-    /// definitely exists.
+    /// Build every mode's `NSCursor`; exclusive, so it runs on the main thread.
     pub(super) fn setup(world: &mut World) {
-        // Inserted unconditionally (ahead of the native-cursor early-return below) — `drive` reads
-        // it every frame regardless of whether any MODE cursor decoded.
+        // Ahead of the early returns: `drive` reads it every frame.
         world.insert_non_send_resource(PayloadCursors(HashMap::new()));
-        // No client data at all → say it ONCE. The per-stem warning below means *this cursor is
-        // missing from an install that exists*, which is worth a line each; with no install it is
-        // 31 lines of the same fact, and they were the loudest thing in the log of the frame-one
-        // crash that decision 1451 is about.
+        // No client data: one warning, not one per stem.
         if world.get_resource::<WorldAssets>().is_none() {
             warn!("no client data — the OS cursor stands in for every mode cursor");
             return;
@@ -549,46 +431,31 @@ mod macos {
         world.insert_non_send_resource(NativeCursors(cursors));
     }
 
-    /// Each frame (main thread, forced by the `NonSend` params): the first frame, stop AppKit's
-    /// cursor-rect reconciliation on our window (the thing that reverts winit's cursor on move);
-    /// then, while not looking, assert the cursor to show — the held payload's icon (decision 0216
-    /// §5, decoded/downsampled to 32×32 on first use and cached by path) if one is held and
-    /// resolved, else the classified mode (base-stem fallback, then Point); on entering/leaving
-    /// mouselook, hide/show it via the app-global hide counter.
+    /// Disable the window's cursor rects once, set the payload or mode cursor while not looking,
+    /// and hide or unhide it across mouselook.
     pub(super) fn drive(
         cursors: Option<NonSend<NativeCursors>>,
         mut payload_cursors: NonSendMut<PayloadCursors>,
         script: Option<NonSend<benilla_ui::script::UiScript>>,
         world_assets: Option<ResMut<WorldAssets>>,
         mode: Res<super::DisplayedCursor>,
-        // The loading cover drops the payload overlay — see [`super::payload_icon`].
         screen: Res<crate::loading_screen::LoadingScreen>,
         rig: Res<CameraControl>,
         cinematic: Option<Res<crate::cinematic::Cinematic>>,
         mut focus: MessageReader<bevy::window::WindowFocused>,
-        // None of the `Local`s below is a [`crate::ui_script::VmMemo`], deliberately (decision
-        // 1290's sweep): every one of them remembers something about the **OS** — what we last told
-        // AppKit, which BLPs failed to decode, whether the pointer rects are off — and the OS keeps
-        // that state across the VM's death and rebirth, so re-seating them at a new login would
-        // re-assert a cursor nothing changed.
+        // The `Local`s below remember OS state, which outlives the VM, so none is a
+        // [`crate::ui_script::VmMemo`].
         mut was_looking: Local<bool>,
         mut rects_disabled: Local<bool>,
         mut decode_failed: Local<HashSet<String>>,
         mut last_set: Local<Option<String>>,
-        // The raw pointer of the NSCursor we last `set` — the drift detector's baseline
-        // (`WOW_CURSOR_TRACE`). Kept alive by the `cursors`/`payload_cursors` caches, and only
-        // ever compared, never dereferenced.
+        // The last `set` cursor's pointer, the drift baseline; only compared, never dereferenced.
         mut last_ptr: Local<usize>,
     ) {
         let Some(cursors) = cursors else {
             return;
         };
-        // macOS resets the app's cursor to the arrow on every activation — a set that happened
-        // while we weren't key (the very first frames run before the window shows; any cmd-tab
-        // away) is simply lost. Re-assert on each focus gain, the moments AppKit forgets us.
-        // (Before this, the glue screens showed the OS arrow: their cursor never changes off
-        // Point, so nothing ever re-asserted after activation; in-world the constant mouselook
-        // transitions masked it.)
+        // macOS resets the cursor to the arrow on every activation: re-assert on focus gain.
         for ev in focus.read() {
             if ev.focused {
                 *last_set = None;
@@ -614,23 +481,12 @@ mod macos {
                 }
             }
         }
-        // **A cinematic hides the pointer too**, and on this platform it can only be done here:
-        // the reference's `0x58b590(0)` at StartCinematic / `(1)` at End. `crate::cinematic` writes
-        // `CursorOptions.visible`, which is the right lever everywhere else and is *inert on
-        // macOS* for the reason this module exists — winit's cursor-rect route does not survive a
-        // continuously-redrawing Metal view. So the fly-by's pointer is hidden by joining the
-        // look session's own `NSCursor::hide()`/`unhide()` pair, which keeps AppKit's app-global
-        // hide counter balanced across both reasons instead of racing a second one against it.
+        // A cinematic hides the pointer too (`0x58b590`); `CursorOptions.visible` is inert here, so
+        // it joins the look's hide/unhide pair, keeping AppKit's hide counter balanced.
         let looking = rig.is_looking() || cinematic.is_some_and(|c| c.is_playing());
         let stem = mode.0.stem();
-        // The held payload's cursor wins over the classified mode (falls back to the mode cursor
-        // when nothing is held, or its icon hasn't resolved/decoded this frame). The KEY names what
-        // we chose, so the set below fires only on a real cursor change or a detected drift —
-        // `NSCursor::set` is a WindowServer round-trip that intermittently stalls the main thread
-        // for milliseconds, and asserting it unconditionally every frame was the single biggest
-        // line of the 0366 frame-time tail. `disableCursorRects` (below, once) stops AppKit's
-        // cursor-RECT reconciliation (the every-mouse-move revert); the drift check in the set
-        // block below catches what that can't — the other in-process `set` callers.
+        // The key names the chosen cursor, so `NSCursor::set`, a WindowServer round-trip that can
+        // stall the main thread for milliseconds, fires only on a change or a drift.
         let key = held_icon
             .as_ref()
             .filter(|icon| payload_cursors.0.contains_key(icon.as_str()))
@@ -642,8 +498,8 @@ mod macos {
             .or_else(|| cursors.0.get(stem.as_str()))
             .or_else(|| cursors.0.get(stem.trim_start_matches("Unable")))
             .or_else(|| cursors.0.get("Point"));
-        // SAFETY: main thread (guaranteed by the `NonSend` params). hide/unhide are balanced across
-        // the look transition so the app-global hide counter never drifts.
+        // SAFETY: main thread, guaranteed by the `NonSend` params; hide and unhide stay balanced
+        // across the look transition.
         unsafe {
             if !*rects_disabled {
                 if let Some(mtm) = MainThreadMarker::new() {
@@ -658,32 +514,22 @@ mod macos {
             }
             if looking && !*was_looking {
                 NSCursor::hide();
-                // The next un-look must re-assert even an unchanged cursor (the hidden period is
-                // AppKit's to fiddle with).
+                // The next un-look re-asserts even an unchanged cursor.
                 *last_set = None;
             } else if !looking && *was_looking {
                 NSCursor::unhide();
             }
             if !looking {
-                // Assert on a key change OR on detected **drift**. The set is not fire-and-forget:
-                // other in-process actors — winit's AppKit view (tracking-area `cursorUpdate:` /
-                // `mouseEntered:` handlers) and AppKit's own activation resets — call `[NSCursor
-                // set]` with THEIR cursor (the arrow) at unpredictable moments, replacing ours.
-                // The mode cursors self-healed by accident (their `key` churns as the hover
-                // classification changes), but a held payload's key is CONSTANT for the whole
-                // carry, so one usurped set left the icon gone for good while the payload was
-                // still held — the "spell disappears from the cursor but is still stuck to it"
-                // bug (reproduced via WOW_CURSOR_TRACE; the drift fired with no input at all).
-                // `currentCursor` is the app-local top of the cursor stack — a plain ObjC read,
-                // no WindowServer round-trip — so checking it every frame is free, and `set`
-                // still fires only on change-or-drift, preserving the 0366 frame-time rule.
+                // Assert on a key change or on drift: winit's view and AppKit's activation resets
+                // set the arrow at any moment, and a held payload's key never changes during a
+                // carry. `currentCursor` is an app-local read, free every frame.
                 let drifted = *last_ptr != 0
                     && Retained::as_ptr(&NSCursor::currentCursor()) as usize != *last_ptr;
                 if drifted || last_set.as_deref() != Some(key.as_str()) {
                     if let Some(cursor) = cursor {
                         cursor.set();
                         *last_ptr = Retained::as_ptr(cursor) as usize;
-                        // `WOW_CURSOR_TRACE=1` — the assert/usurp timeline instrument.
+                        // `WOW_CURSOR_TRACE=1`: the assert and drift timeline.
                         if std::env::var_os("WOW_CURSOR_TRACE").is_some() {
                             eprintln!(
                                 "[cursor-trace] set {key} ({:#x}){}",
@@ -699,8 +545,7 @@ mod macos {
         *was_looking = looking;
     }
 
-    /// RGBA → `NSCursor`. Goes via PNG + `NSImage::initWithData` (standard image data) rather than
-    /// hand-rolling an `NSBitmapImageRep`.
+    /// RGBA → `NSCursor`, via PNG and `NSImage::initWithData`.
     fn build_cursor(width: u32, height: u32, rgba: &[u8]) -> Option<Retained<NSCursor>> {
         let buf = image::RgbaImage::from_raw(width, height, rgba.to_vec())?;
         let mut png = Vec::new();
@@ -709,7 +554,7 @@ mod macos {
             .ok()?;
         let data = NSData::with_bytes(&png);
         let image = NSImage::initWithData(NSImage::alloc(), &data)?;
-        // Hotspot = the vanilla cursors' top-left active tip.
+        // Hotspot: the vanilla cursors' top-left tip.
         Some(NSCursor::initWithImage_hotSpot(
             NSCursor::alloc(),
             &image,
@@ -733,14 +578,12 @@ mod tests {
         unable: false,
     };
 
-    /// Run one frame of [`drive_displayed_cursor`] with the displayed mode pre-set to `standing`,
-    /// and return what it becomes. `lua` is whatever FrameXML did this frame.
+    /// One frame of [`drive_displayed_cursor`] from `standing`; `lua` is what FrameXML did.
     fn frame(standing: WorldCursor, world: WorldCursor, over_ui: bool, lua: &str) -> WorldCursor {
         frame_armed(standing, world, over_ui, lua, false)
     }
 
-    /// One frame, with `armed` deciding whether a spell awaits its click — which is what parks the
-    /// BASE mode at Cast.
+    /// One frame; `armed` parks the base at Cast.
     fn frame_armed(
         standing: WorldCursor,
         world: WorldCursor,
@@ -751,8 +594,7 @@ mod tests {
         frame_covered(standing, world, over_ui, lua, armed, false)
     }
 
-    /// One frame, with `covered` deciding whether the loading cover is up — the arm that parks the
-    /// plain arrow ahead of every other rule.
+    /// One frame; `covered` raises the loading cover.
     fn frame_covered(
         standing: WorldCursor,
         world: WorldCursor,
@@ -775,7 +617,7 @@ mod tests {
         app.insert_resource(DisplayedCursor(standing));
         let mut targeting = crate::spell::SpellTargeting::default();
         if armed {
-            // Feed Pet's own bare ITEM word.
+            // Feed Pet's own bare item word.
             targeting.enter(6991, crate::spell::CastCommit::Spell, 0x0010);
         }
         app.insert_resource(targeting);
@@ -785,13 +627,7 @@ mod tests {
         app.world().resource::<DisplayedCursor>().0
     }
 
-    /// **Under the loading cover the cursor is the plain arrow, whatever else is true** (decision
-    /// 1990). The reference's world transition parks cursor index 1 (`0x6e49f5`/`0x6e49ff`) and
-    /// drops any item/spell overlay *before* the screen goes up, so a portal taken with a spell
-    /// armed — or with an item on the cursor — arrives showing the arrow, not the payload.
-    ///
-    /// Both of the arms that would otherwise win are exercised here: an armed spell (which parks
-    /// the BASE at Cast, so even the UI restore reads blue) and a FrameXML write in the same frame.
+    /// The reference parks cursor index 1 before the loading screen goes up (`0x6e49f5`).
     #[test]
     fn the_loading_cover_parks_the_plain_arrow_over_every_other_rule() {
         for (over_ui, lua, armed) in [
@@ -806,7 +642,7 @@ mod tests {
                 "covered: the arrow wins (over_ui={over_ui}, armed={armed}, lua={lua:?})"
             );
         }
-        // …and the cover is the only reason: the same frame uncovered keeps the world's verdict.
+        // Uncovered, the same frame keeps the world's verdict.
         assert_eq!(
             frame_covered(SWORD, SWORD, false, "", false, false),
             SWORD,
@@ -814,18 +650,8 @@ mod tests {
         );
     }
 
-    /// **The base mode is Cast while a spell awaits its click** (the base cell `0xbe2c4c` is
-    /// independently mutable — e.g. a spell-cancel flow parks it at Cast(2)), and `ResetCursor`
-    /// restores *that value*, never a hardcoded Point.
-    ///
-    /// This is what the director watched the reference do with Feed Pet armed: **blue over the
-    /// interface at large, grey only out in the world**. Both fall out of the one cell — the world
-    /// classifier writes the per-seam verdict (grey, for a word with no world handler), and over UI
-    /// nothing overrides the base.
-    ///
-    /// It is emphatically NOT a validity verdict: no hover-time item verdict exists in 1.12, so
-    /// good food and bad food are the same blue. The last assertion pins that, because reading the
-    /// blue as "this food is correct" is exactly the misreading that sent B208 round twice.
+    /// `ResetCursor` restores the base cell (`0xbe2c4c`): blue over the UI while armed, grey only
+    /// in the world, and no item validity verdict.
     #[test]
     fn an_armed_spell_parks_the_base_at_cast_so_the_ui_reads_blue() {
         const GREY: WorldCursor = CAST_GREY;
@@ -833,40 +659,33 @@ mod tests {
             kind: CursorKind::Cast,
             unable: false,
         };
-        // Out in the world the classifier's verdict stands: an item-only word greys.
+        // In the world an item-only word greys.
         assert_eq!(frame_armed(BLUE, GREY, false, "", true), GREY);
-        // Crossing into the UI restores the base — blue — rather than dragging the world's grey in.
+        // Crossing into the UI restores the base.
         assert_eq!(frame_armed(GREY, GREY, true, "", true), BLUE);
-        // A bag slot's real `ResetCursor()` resolves to the same base, so the food reads blue…
+        // A bag slot's `ResetCursor()` resolves to the base, whatever the slot holds:
         assert_eq!(frame_armed(GREY, GREY, true, "ResetCursor()", true), BLUE);
-        // …and so does a slot holding something the pet would never eat. The blue says "a spell is
-        // armed", not "this item is a legal target".
+        // the blue means a spell is armed, not that the item is a legal target.
         assert_eq!(frame_armed(GREY, GREY, true, "ResetCursor()", true), BLUE);
-        // Nothing armed: the base is Point again, and the UI reads as the ordinary pointer.
+        // Nothing armed: the base is Point.
         assert_eq!(
             frame_armed(GREY, WorldCursor::default(), true, "ResetCursor()", false),
             WorldCursor::default()
         );
     }
 
-    /// **A UI element that writes no cursor does not get to invent one.** The mode has two
-    /// writers and only two — the world (while the pointer is over it) and a FrameXML cursor call.
-    /// Crossing into the UI restores the BASE, which is the reference's own behaviour spread across
-    /// dozens of `ResetCursor()` calls; what must never happen is a *third* party recomputing a
-    /// value each frame, which is what made B208 go round twice.
+    /// A UI element that writes no cursor does not invent one.
     #[test]
     fn only_the_world_and_framexml_write_the_cursor() {
-        // Over the world the classifier's verdict applies, every frame.
+        // Over the world the classifier's verdict applies.
         assert_eq!(frame(CAST_GREY, SWORD, false, ""), SWORD);
-        // Over the UI with nothing armed the base is Point — the ordinary pointer, which is what a
-        // bag slot shows in the reference.
+        // Over the UI with nothing armed the base is Point.
         assert_eq!(frame(SWORD, SWORD, true, ""), WorldCursor::default());
         assert_eq!(
             frame(SWORD, SWORD, true, "ResetCursor()"),
             WorldCursor::default()
         );
-        // An explicit FrameXML write wins and then STAYS — the unit-frame lit/grey split would be
-        // pointless if the next frame's base restore stamped over it.
+        // A FrameXML write wins and stays, or the unit-frame lit/grey split would be stamped over.
         let lit = WorldCursor {
             kind: CursorKind::Cast,
             unable: false,
@@ -886,13 +705,10 @@ mod tests {
         );
     }
 
-    /// `ShowContainerSellCursor` bails on `IsTargeting` at its first instruction, so an armed spell
-    /// keeps its cast cursor over a vendor-open bag instead of getting the coin. With a sticky mode
-    /// this gate is load-bearing: a Buy write would stamp over the cast cursor and no per-frame
-    /// world write would put it back.
+    /// `ShowContainerSellCursor` bails on `IsTargeting` first, so an armed spell keeps its cursor.
     #[test]
     fn the_sell_cursor_does_not_paint_over_an_armed_spell() {
-        // The gate reads the app-fed targeting flag, so drive it the way the app does.
+        // The gate reads the app-fed targeting flag.
         let mut app = App::new();
         let mut script = benilla_ui::script::UiScript::new().unwrap();
         script.set_spell_targeting(true);
diff --git a/crates/benilla-app/src/cvars.rs b/crates/benilla-app/src/cvars.rs
index 71b73ea7..17f00d63 100644
--- a/crates/benilla-app/src/cvars.rs
+++ b/crates/benilla-app/src/cvars.rs
@@ -1,51 +1,23 @@
-//! benilla's **CVar registry** — the client's configuration store, host side (decisions 0954,
-//! 2303). The reference keeps every player setting in one engine-side table
-//! (`ConsoleVar.cpp`, a `TSHashTable<CVar>` of 0xc4-byte records: name, value, default, the
-//! latch slot, and a change callback the owning subsystem hands `CVar::Register 0x63db90`).
-//! This module is that table: [`Cvars`] holds the live value of every registered row, it is
-//! what survives a VM replacement, and it is what `config.toml` is composed from. The script VM
-//! carries a **mirror** of it for Lua's synchronous `GetCVar`/`SetCVar`
-//! ([`benilla_ui::script::UiScript::seed_cvars`]); the mirror's writes ride a queue back here.
+//! The CVar registry, host side: the reference's engine-side table (`ConsoleVar.cpp`, 0xc4-byte
+//! records of name, value, default, latch slot and the change callback handed to `CVar::Register`,
+//! `0x63db90`). [`Cvars`] holds every registered row's live value, survives a VM replacement and is
+//! what `config.toml` is composed from; the script VM keeps a mirror for Lua's synchronous
+//! `GetCVar`/`SetCVar` ([`benilla_ui::script::UiScript::seed_cvars`]) whose writes queue back here.
 //!
-//! - **The registered set** ([`REGISTERED`]): only vars something actually reads — a host knob,
-//!   or (since 1140) a live Lua consumer. **A row's default is the REFERENCE's default**
-//!   (decision 1804), and every row says where it stands against it — [`Registered::reference`],
-//!   a mandatory column with no "unknown" variant. Two tests hold it: one checks each row's claim
-//!   in both directions, the other pins the deviation set as a readable list. A row the reference
-//!   **latches** (flag bit1 at its register site) says so with [`Registered::latched`]; a
-//!   structural test insists every row has a reader somewhere in the source.
+//! - [`REGISTERED`] holds only vars something reads, a host knob or a Lua consumer. A row's default
+//!   is the reference's, and [`Registered::reference`] says where it stands against it.
+//! - The change callback is a Bevy observer on [`CvarChanged`], beside the knob it writes; the
+//!   registry applies nothing itself.
+//! - A latched row's write is staged in [`Row::pending`] until [`Cvars::commit_latched`], the
+//!   reference's `0x639ec0` inside `RestartGx`. A stage never committed is dropped at exit, as the
+//!   reference's `SaveConfig` writes only the applied value (`rec+0x20`).
+//! - Boot folds `benilla-config/config.toml` in and fires the observers before anything after
+//!   [`CvarLoad`]; each frame drains the VM's writes in and pushes the registry's out; a dirty
+//!   registry saves after one quiet second or at exit, writing only values off their default and
+//!   keeping unknown keys verbatim.
 //!
-//!   **The reference column has one source**: all 214 of the reference's `CVar::Register` sites,
-//!   with name, help, flags, default string, callback, category and record global. A new row
-//!   looks its answer up there rather than re-deriving it.
-//!
-//! - **The change callback is a Bevy observer** ([`CvarChanged`]). An accepted move of a row's
-//!   applied value is triggered as one event, and the subsystem that owns the knob observes it
-//!   beside the knob (`sound::on_cvar`, `video::on_cvar`, …), writing only its own resource — so
-//!   `Res::is_changed()` on a knob is honest again, which the 32-resource bundle this replaced
-//!   could not offer (it deref-mutted every knob on every write; three consumers carried the
-//!   written workaround). The registry never applies anything itself: it has no knob, and no arm.
-//!
-//! - **The latch** ([`Row::pending`]): a write to a latched row is staged, `GetCVar` keeps
-//!   answering the applied value, and nothing fires until [`Cvars::commit_latched`] — the
-//!   reference's `0x639ec0`, `CVar::Commit 0x63e060` on the fourteen gx records, called from
-//!   inside `RestartGx` (the video window's Okay). A staged value that is never committed is dropped at exit, as
-//!   the reference's is (`SaveConfig` writes `rec+0x20`, the applied value).
-//!
-//! - **Boot**: read `benilla-config/config.toml` ([`crate::local_state`]) into the registry and
-//!   fire the observers synchronously, before anything ordered after [`CvarLoad`] runs; when the
-//!   UI VM exists, seed its mirror from the registry so `GetCVar` answers what the client is doing.
-//! - **Sync**: per frame, drain the VM's registrations and writes into the registry, push the
-//!   registry's own writes into the mirror, and trigger the accepted moves.
-//! - **Save**: dirty + one quiet second → rewrite `config.toml` atomically (and flush on
-//!   `AppExit`). The file holds **only values that moved off their default** — a diff, not a
-//!   dump — plus any entries this build doesn't know (a newer build's keys, an addon's before it
-//!   registers them: preserved verbatim, warned once).
-//!
-//! **Env overrides win for the session and never touch the file**: `WOW_UI_SCALE`/`WOW_FARCLIP`
-//! and their siblings beat the loaded config (they exist to make taste iteration a relaunch —
-//! pinning one into the config would make the A/B sticky), the session runs and saves around
-//! them, and the file keeps whatever it already said for those keys ([`Cvars::own_for_session`]).
+//! Env overrides (`WOW_UI_SCALE`, `WOW_FARCLIP`, …) win for the session and never touch the file
+//! ([`Cvars::own_for_session`]).
 
 use std::collections::{BTreeMap, HashMap, HashSet};
 use std::time::Instant;
@@ -55,41 +27,24 @@ use bevy::prelude::*;
 use crate::ui_script::VmMemo;
 use benilla_ui::script::{SeededCvar, UiScript};
 
-/// One host-backed CVar: its registered name, benilla's shipped default, and — the column that
-/// exists so a divergence is a *decision* rather than an accident — **what the reference ships**
-/// ([`Reference`]).
-///
-/// **The standard this table encodes: a benilla option's default IS the reference's.** Shipping
-/// something else is allowed and sometimes right, but it costs a [`Reference::Deviates`] row
-/// naming the reference's own value and the reason. `Reference` has no `Default` and no "unknown"
-/// variant, so adding a row means answering the question; and because [`Reference::Same`] and
-/// [`Reference::Deviates`] both carry the reference's value, the test
-/// [`tests::defaults_stand_where_the_reference_column_says`] checks the claim in both directions —
-/// a `Same` row that stopped matching fails, and so does a `Deviates` row that has quietly come
-/// back into agreement.
+/// One host-backed CVar: its name, benilla's default, and where that default stands against the
+/// reference's ([`Reference`]).
 pub(crate) struct Registered {
     /// The registered name, in the reference's own spelling.
     pub(crate) name: &'static str,
-    /// What a fresh `benilla-config` runs at — seeded into the knob, and what `GetCVar` answers
-    /// until the player moves it.
+    /// What a fresh `benilla-config` runs at, and what `GetCVar` answers until the player moves it.
     pub(crate) default: &'static str,
-    /// Where that value stands against the reference's.
-    ///
-    /// `#[allow(dead_code)]` because this column's readers are a **human** and
-    /// [`tests::defaults_stand_where_the_reference_column_says`] — nothing at runtime consults
-    /// it, and nothing should: it records what the *reference* does, which is an input to the
-    /// choice above it, never a value this client acts on.
+    /// Where `default` stands against the reference's. Read only by the tests: it records the
+    /// reference, never a value this client acts on.
     #[allow(dead_code)]
     pub(crate) reference: Reference,
-    /// The reference registers it with flag bit1 (`rec+0x1c & 0x2`, decision 2303): a write is
-    /// staged in [`Row::pending`] and applied only at the latch boundary
-    /// ([`Cvars::commit_latched`]). Read off each register site's `flags` argument (2 or 3); a test
-    /// pins the set.
+    /// Registered with flag bit1 (`rec+0x1c & 0x2`, `flags` 2 or 3 at the register site): a write
+    /// is staged in [`Row::pending`] until [`Cvars::commit_latched`].
     pub(crate) latched: bool,
 }
 
 impl Registered {
-    /// Mark the row latched — see [`Registered::latched`].
+    /// Mark the row latched.
     pub(crate) const fn latched(self) -> Self {
         Self {
             latched: true,
@@ -98,49 +53,29 @@ impl Registered {
     }
 }
 
-/// benilla's default, weighed against the reference's own.
-///
-/// **What "the reference's default" means here** is the **registered factory default** — the
-/// string the real client's `CVar::Register` (`0x63db90`) call passes for that name, byte-read —
-/// or, for a setting 1.12 keeps FrameXML-side instead of as a CVar, the value
-/// `UIOptionsFrame.lua` boots it at. Two readings it deliberately is **not**, both of which have
-/// misled a reader before:
-///
-/// - **Not what the reference install's `Config.wtf` says.** That file is one player's saved
-///   *diff*: `SaveConfig 0x63d980` writes only what has moved off its default, so a line's mere
-///   presence is proof the registered default is something *else*.
-/// - **Not, by itself, what a fresh install ends up running at.** `hwDetect` rewrites sixteen
-///   video CVars out of `VideoHardware.dbc` before the first frame, and the `useUiScale`-OFF leg
-///   computes a UI scale of its own. Where the client's own boot code overrides the registered
-///   string like that, benilla follows the *behaviour* and the row says so — that is
-///   [`Reference::Overridden`], not a deviation.
-///
-/// Every row's provenance — the register-site VA, or the FrameXML line — belongs in the comment
-/// above it. That is not decoration: it is what lets the next reader re-check the claim instead
-/// of trusting this table.
-#[allow(dead_code)] // read by a human and by the test — see `Registered::reference`
+/// benilla's default against the reference's: the string the reference's `CVar::Register`
+/// (`0x63db90`) passes for the name, or, for a setting 1.12 keeps in FrameXML, the value
+/// `UIOptionsFrame.lua` boots it at. Not a `Config.wtf` line (`SaveConfig 0x63d980` writes only
+/// values off their default), and not always what a fresh install runs at: `hwDetect` rewrites
+/// sixteen video CVars from `VideoHardware.dbc` before the first frame ([`Reference::Overridden`]).
+/// Each row's register site or FrameXML line is cited above it.
+#[allow(dead_code)] // read only by the tests
 pub(crate) enum Reference {
-    /// The reference registers this exact default string, and benilla ships it too. The copy is
-    /// deliberate: the test compares the two, so an edit to `default` that forgets the reference
-    /// fails here rather than shipping.
+    /// The reference registers this default and benilla ships it; the test compares the two.
     Same(&'static str),
-    /// The reference *registers* `registered`, but its own boot code overwrites that before the
-    /// first frame, and benilla's `default` is what that code lands on — faithful to the client's
-    /// behaviour, which is what the standard asks for. `why` is the override.
+    /// The reference registers `registered`, but its own boot code overwrites it before the first
+    /// frame; `default` is where that lands, and `why` is the override.
     Overridden {
         registered: &'static str,
         why: &'static str,
     },
-    /// The reference ships `value`; benilla knowingly ships something else. `why` is the reason
-    /// and the decision that ruled it. **This is the variant that answers "where do we differ?"**
-    /// — every row here is a standing choice somebody made, reviewable as a list.
+    /// The reference ships `value` and benilla ships another; `why` is the reason.
     Deviates {
         value: &'static str,
         why: &'static str,
     },
-    /// The reference has no such setting to match: benilla's own knob (`renderScale`), or an era
-    /// name for something 1.12 never made settable. `why` says which — and, where the reference
-    /// still *behaves* some way, what that behaviour is.
+    /// No reference setting to match: benilla's own knob, or a later-era name for something 1.12
+    /// never made settable. `why` says which, and what the reference does instead.
     Ours(&'static str),
 }
 
@@ -154,8 +89,7 @@ const fn same(name: &'static str, default: &'static str) -> Registered {
     }
 }
 
-/// A row that follows the reference's *behaviour* where its own boot code overrides the
-/// registered string — see [`Reference::Overridden`].
+/// A row whose default follows the reference's boot-time override of its registered string.
 const fn overridden(
     name: &'static str,
     default: &'static str,
@@ -170,8 +104,7 @@ const fn overridden(
     }
 }
 
-/// A row that knowingly leaves the reference's default — `value` is the reference's, `why` the
-/// recorded reason.
+/// A row that ships something other than the reference's `value`, for `why`.
 const fn deviates(
     name: &'static str,
     default: &'static str,
@@ -196,44 +129,26 @@ const fn ours(name: &'static str, default: &'static str, why: &'static str) -> R
     }
 }
 
-/// The table as the script VM's registrar wants it — `(name, default)` pairs, in table order.
-///
-/// The registrar has no use for the [`Reference`] column: that column is for *us* (and for the
-/// test that holds the standard), never for the engine.
+/// The table as the script VM's registrar wants it: `(name, default)` pairs in table order.
 pub(crate) fn registered_pairs() -> impl Iterator<Item = (&'static str, &'static str)> {
     REGISTERED.iter().map(|r| (r.name, r.default))
 }
 
-/// The host-backed CVars. Grows one row per knob a settings page actually wires — never ahead of
-/// the knob (see the module doc) — and every row states where its default stands against the
-/// reference's ([`Registered`]).
+/// The host-backed CVars, one row per knob that has a reader.
 ///
-/// Unregistered for want of a reader, though pfUI's `hdgraphic` writes them through `ConsoleExec`:
-/// `lodDist` (`0x688524`, "100.0", read at `0x6afb1d` for the doodad LOD swap), `footstepBias`
-/// (`0x6888b4`, "0.125", read at `0x68fcb6`), `mapObjLightLOD` (`0x6886ec`, "0") and `SkyCloudLOD`
-/// (`0x6d1d33`, "0"). `DistCull` (`0x688570`) and `texLodBias` (`0x6885e2`, whose sink `0x672640`
-/// is `ret 4`) have no reader in the reference either. `maxLOD` is no CVar: none of the 214
-/// `CVar::Register` (`0x63db90`) sites names it.
+/// Not registered for want of a reader, though pfUI's `hdgraphic` writes them: `lodDist`
+/// (`0x688524`, "100.0", read at `0x6afb1d` for the doodad LOD swap), `footstepBias` (`0x6888b4`,
+/// "0.125", read at `0x68fcb6`), `mapObjLightLOD` (`0x6886ec`, "0") and `SkyCloudLOD` (`0x6d1d33`,
+/// "0"). `DistCull` (`0x688570`) and `texLodBias` (`0x6885e2`, whose sink `0x672640` is `ret 4`)
+/// have no reader in the reference either. `maxLOD` is no 1.12 CVar.
 pub(crate) const REGISTERED: &[Registered] = &[
-    // The realm the session is on — a REAL 1.12 CVar (`0x83f2d0`, persisted: the client builds its
-    // SavedVariables path from it through `0x5ab7d0`), and a live
-    // Lua consumer in the strongest sense the honest-tree rule asks for. `Ace/AceState.lua:27` does
-    // `ace.trim(GetCVar("realmName"))` inside `SetGameState`, which every Ace addon runs at
-    // PLAYER_ENTERING_WORLD — so a nil there was `gsub(nil)` and took the whole Ace family down.
-    // 18 corpus folders read the name.
-    //
-    // The default is EMPTY, deliberately and not as a guess: the value is written from the session's
-    // real realm the moment addons load (`ui_script::addons::load_third_party`), so the default only
-    // ever describes a client that has not connected. `0x85d684` holds a string
-    // `"Last realm connected to"` beside the registration, but that reads like the CVar's HELP text
-    // rather than its value and nothing here needs to resolve it — `""` is what `ace.trim` handles
-    // cleanly, and inventing a realm name would be worse than admitting we have none yet.
+    // `realmName` (`0x83f2d0`): registered `""` (`0x882748`), help "Last realm connected to"
+    // (`0x85d684`); the client builds its SavedVariables path from it (`0x5ab7d0`). Written from
+    // the session's realm when addons load. `Ace/AceState.lua:27` trims it at
+    // PLAYER_ENTERING_WORLD, so a nil breaks every Ace addon.
     same("realmName", ""),
-    // The address of the logon server — the reference's own CVar (register site `0x5ab6a6`; the
-    // registration's string neighbours are `realmlist.wtf`, "Address of realm list server" and
-    // `us.logon.worldofwarcraft.com:3724`).
-    // A **string** row: the registry takes any string for it, and `realmlist::on_cvar` judges it.
-    // The default diverges knowingly — see `realmlist::DEFAULT_REALMLIST`.
+    // The logon server address (register site `0x5ab6a6`), a string row judged by
+    // `realmlist::on_cvar`.
     deviates(
         crate::realmlist::CVAR_REALMLIST,
         crate::realmlist::DEFAULT_REALMLIST,
@@ -241,53 +156,29 @@ pub(crate) const REGISTERED: &[Registered] = &[
         "1667: that host has not resolved since 2019, so shipping it makes every first launch a \
          DNS failure; benilla dials the machine it is running on",
     ),
-    // The implicit AFK clear (2088) — a REAL 1.12 CVar, byte-read off its own registration
-    // (`0x5e24d4 push 0x82e748`, handle taken from the store AFTER the call at `0x5e24ef` into
-    // `[0xc4d68c]`, whose single reader `0x5eb84b` tests `[cvar+0x28]` for non-zero). Registered
-    // default `"1"`.
-    //
-    // It gates FIVE implicit clears, not one: any chat send whose type is not `0x14` (which is why
-    // `/dnd` clears AFK before marking), plus Jump, forward/back, strafe and turn
-    // (`0x513d36`/`0x514e23`/`0x514f0b`/`0x514fca`). With the CVar off the clear is a **total**
-    // no-op — no echo, no mirror write, no packet.
+    // `autoClearAFK` (`0x5e24d4`, "1" `0x82e748`, handle `[0xc4d68c]` set at `0x5e24ef`, read at
+    // `0x5eb84b`) gates five implicit AFK clears: any chat send but type `0x14`, Jump,
+    // forward/back, strafe and turn (`0x513d36`/`0x514e23`/`0x514f0b`/`0x514fca`). Off, the clear
+    // does nothing at all: no echo, no mirror write, no packet.
     same("autoClearAFK", "1"),
     same("MasterVolume", "1"),
     same("SoundVolume", "1"),
     same("MusicVolume", "0.4"),
     same("AmbienceVolume", "0.6"),
-    // The three 1.12 sound enables (registrar defaults all "1", `0x45737a`/`0x45739b`/`0x460a9d`):
-    // `MasterSoundEffects` is the MASTER "Enable All Sound" checkbox (SoundOptionsFrame.lua
-    // index 1 — its callback sets the engine-wide pause flag), NOT an SFX-only toggle; 1.12
-    // has no `EnableSound`/`EnableSFX` at all.
+    // Registered "1" at `0x45737a`/`0x45739b`/`0x460a9d`. `MasterSoundEffects` is the Enable All
+    // Sound box (`SoundOptionsFrame.lua:6`), which pauses the whole sound engine, not an SFX
+    // toggle.
     same("MasterSoundEffects", "1"),
     same("EnableMusic", "1"),
     same("EnableAmbience", "1"),
-    // Error speech (1815) — the race/sex refusal lines your character says. A real 1.12 CVar
-    // (`CVar::Register` at `0x457877`, registrar default `"1"`) and a real 1.12 checkbox:
-    // SoundOptionsFrame.lua's `ENABLE_ERROR_SPEECH`, index 4, which the master enable greys along
-    // with Ambience.
+    // The race/sex refusal voice lines (`0x457877`), `SoundOptionsFrame.lua:3`; the master enable
+    // greys it.
     same("EnableErrorSpeech", "1"),
-    // Sound while the window is in the background (1847). **Not a 1.12 CVar and not a 1.12
-    // checkbox**: none of the reference's 214 `CVar::Register` (`0x63db90`) sites names it, and
-    // `SoundOptionsFrame.lua` declares seven checkboxes
-    // (indices 1, 2, 4-8) and four sliders, none of them this. `CVar::Register` is the only
-    // creation path, so `Config.wtf` can hold no such key either. The spelling is the later-era
-    // engine's — the `autoLootDefault` / `nameplateShowEnemies` posture, where benilla's
-    // persistence IS the CVar store (0954) and a setting 1.12 never made settable takes the era
-    // name rather than an invented one.
-    //
-    // **`same`, not `ours`**, for the nameplate pair's reason: the reference has no CVar to match
-    // but it very much has a *behaviour* to match, and it goes quiet in the background —
-    // unconditionally, on `WM_ACTIVATE` → event-bus category 2 → `0x7a4860`'s
-    // `FSOUND_SetMute(-3, active ? 0 : 1)`, music included. "0" IS the reference's own behaviour.
-    // The knob is `SoundConfig::background_sound`, which carries the mechanism and the one
-    // disclosed divergence.
+    // Not a 1.12 CVar or checkbox; the later-era name. The reference mutes on losing focus, music
+    // included (`WM_ACTIVATE` to `0x7a4860`'s `FSOUND_SetMute(-3, active ? 0 : 1)`), so "0" is its
+    // behaviour. The knob is `SoundConfig::background_sound`.
     same("Sound_EnableSoundWhenGameIsInBG", "0"),
-    // Zone reverb (1153). The binary registers this one `"1"` (`0x4573be`) and we register it
-    // `"0"` — the only row here that knowingly leaves the registrar's default, because the
-    // reference's reverb is EAX-over-hardware and that hardware has not existed since Vista:
-    // `"1"` would ship audio the real client has never actually produced (bug B236).
-    // `SoundConfig::reverb` carries the evidence.
+    // Registered "1" (`0x4573be`); `SoundConfig::reverb` carries the evidence for shipping "0".
     deviates(
         "SoundReverb",
         "0",
@@ -296,21 +187,15 @@ pub(crate) const REGISTERED: &[Registered] = &[
          since Vista, so \"1\" would ship audio the real client has never actually produced \
          (B236)",
     ),
-    // The mix-ahead depth (1857) — 1.12's own `SoundBufferSize` (`0x4571ca`, flags 2: latched,
-    // read once at sound-system init), "sound buffer size (milliseconds)": FMOD 3's mix-ahead
-    // buffer, the distance the software mixer runs ahead of the output device. benilla's own
-    // output has the same quantity — the render thread's ring ahead of the IO callback
-    // (`sound::output`) — so the reference's dial drives it, in the reference's unit. The
-    // registrar's default is a two-way host choice: `0x457520` returns "50" or "100" from an
-    // OS-version probe (strings at `0x835e10`/`0x835e0c`, byte-read 2026-09-02). Ours is the
-    // larger of its two, because the stall the crackle was measured from was a whole IO cycle
-    // long and the depth exists to hide the next one. Applies at the next launch, like the
-    // reference's.
+    // FMOD 3's mix-ahead buffer in ms (`0x4571ca`, flags 2: read once at sound init); here it sizes
+    // the render thread's ring ahead of the IO callback (`sound::output`). `0x457520` registers
+    // "50" or "100" by a host probe (`0x835e10`/`0x835e0c`), which one on a current machine
+    // untraced; ours is the larger, since the depth has to hide a whole stalled IO cycle.
     same("SoundBufferSize", "100").latched(),
-    // The output limiter (1551) — benilla's own, not a 1.12 CVar. The reference needs no such DSP
-    // (its mix is FMOD 3's and its headroom lives in the SFX-bus auto-duck); benilla sums into f32
-    // behind a hard clamp, and every WoW SFX is mastered to full scale, so two overlapping kits
-    // clip. Registered so the fix can be A/B'd live against the defect it fixes.
+    // benilla's own, not a 1.12 CVar. Deviation: the reference clips at full scale and has no
+    // headroom mechanism (its SFX-bus duck `0x457960` is a sidechain armed only by server-pushed
+    // voice lines); benilla limits because every SFX is mastered to full scale and overlapping
+    // kits clip.
     ours(
         "SoundOutputLimiter",
         "1",
@@ -327,70 +212,28 @@ pub(crate) const REGISTERED: &[Registered] = &[
          below, where our flat 0.9 does diverge; `ui_script::DEFAULT_UI_SCALE` carries that. \
          See `useUiScale` below, whose row this one used to say did not exist",
     ),
-    // **`useUiScale` (`0x8430c0`, default `"0"`)** — the switch the row above gates on.
-    //
-    // Its absence used to be argued for here as *"nothing reads it, and registering it would only
-    // offer a switch whose ON path we do not implement"*, and the first half of that has been
-    // false since the interface went stock: `ContainerFrame.lua:483` and `UIDropDownMenu.lua:525`
-    // both branch on `GetCVar("useUiScale") == "1"`, and `OptionsFrame.lua:13` gives it a
-    // checkbox. Nobody noticed because the only thing that said so was a host warning with
-    // nowhere to go (decision 2135, which is how this was found).
-    //
-    // Registering it changes no behaviour today — `nil ~= "1"` and `"0" ~= "1"` take the same
-    // branch — and makes the read the reference's read rather than an accident. The ON path
-    // lands where the reference's does, because our `uiScale` default *is* the reference's OFF-leg
-    // result: at `useUiScale = 1` both clients scale the bag frames and the dropdown list by
-    // `GetCVar("uiscale")`, and both read 0.9 there on every window we ship against.
+    // `useUiScale` (`0x8430c0`), the switch the `uiScale` override gates on:
+    // `ContainerFrame.lua:483` and `UIDropDownMenu.lua:525` branch on it and `OptionsFrame.lua:13`
+    // gives it a checkbox.
     same("useUiScale", "0"),
     same("farclip", "350"),
-    // **`nearclip` — farclip's other half, and a knob we had been holding as a constant** (2163).
-    // `0x68867a` passes name `0x84ffb0` `"nearclip"`, default string `0x84fb48` `"0.1"`, help
-    // "Near clip plane distance", flags `1`, callback `0x688d90`, record `[0xc7f348]`.
-    //
-    // **The reader is the camera, and it re-reads every frame.** `0x511bc0` — the per-frame camera
-    // outer, sole caller `0x483094` — stamps `[cam+0x38]` from this record's float before the
-    // `[cam+0x48]` branch and unconditionally: `511bcf mov eax,[0xbe1078]; 511bd4 fld [eax+0x24];
-    // 511bdc fstp [esi+0x38]`, with `[0xbe1078]` the handle `0x50b728` caches from a `"nearclip"`
-    // Lookup. `farclip` is the next four instructions. `benilla_world::view::stamp_near_clip` is
-    // that, and `ViewDistance` is the pair.
-    //
-    // **Why it was not registered for so long, and why that reasoning was wrong.** The near plane
-    // was a `CAM_NEAR = 1.0/9.0` const documented as the reference's own, on the true finding that
-    // the callback's *derived global* `[0xc7b480]` has one writer and no readers. The camera does
-    // not read that global; it reads the record. So the ctor's
-    // `0x3de38e39` = 1/9 is overwritten by the first frame's stamp and never reaches a picture —
-    // a verified-but-partial mechanism, which docs/METHOD.md §4 names as the classic trap.
-    //
-    // pfUI's `hdgraphic` writes it (`ConsoleExec("nearClip " .. arg*2/100)`, 0.06..0.30 across its
-    // extended stops) — every value inside the reference's own `[0.01, 0.33]`, which is why that
-    // module could ask for it.
+    // `nearclip` (`0x68867a`: name `0x84ffb0`, default `0x84fb48` "0.1", flags 1, callback
+    // `0x688d90`, record `[0xc7f348]`). The camera re-reads the record every frame: `0x511bc0`
+    // (sole caller `0x483094`) stamps `[cam+0x38]` from it through the handle `[0xbe1078]` that
+    // `0x50b728` caches, overwriting the ctor's 1/9 (`0x3de38e39`);
+    // `benilla_world::view::stamp_near_clip` is that.
+    // The callback's derived global `[0xc7b480]` has no reader. pfUI's `hdgraphic` writes
+    // 0.06..0.30, inside `[0.01, 0.33]`.
     same("nearclip", "0.1"),
-    // The Controls-page trio (0961). `deselectOnClick`/`mouseInvertPitch` are 1.12's own
-    // Interface Options CVars (UIOptionsFrame.lua indices 45/1); their defaults are the
-    // reference behaviors benilla already shipped (empty-world click clears the target; no
-    // pitch invert). `autoLootDefault` is era's — no 1.12 CVar exists, vanilla only had the
-    // shift gesture — default off, like era's engine registrar.
+    // `deselectOnClick` and `mouseInvertPitch` are 1.12's own (`UIOptionsFrame.lua:8,4`);
+    // `autoLootDefault` is the later-era name, 1.12 having only the shift gesture.
     same("deselectOnClick", "1"),
-    // *Block Trades* (decision 1764) — 1.12's own `BlockTrades` (`0x842fbc`), the General-box
-    // checkbox at index 14 whose tooltip is "Block all incoming trade requests.". Registered
-    // **"0"**: the reference's own `0x4bf7bc` leg only refuses when the CVar is set, so an
-    // unset/absent value has to mean "trades allowed" — and a client that shipped with trades
-    // blocked would refuse every trade until the player found the box. The knob is
-    // [`crate::ui_trade::BlockTrades`], read by the incoming-request answerer.
+    // `BlockTrades` (`0x842fbc`), `UIOptionsFrame.lua:11`: the refusal leg `0x4bf7bc` fires only
+    // when it is set. The knob is [`crate::ui_trade::BlockTrades`].
     same("BlockTrades", "0"),
-    // 1.12's own `autoSelfCast` — a friendly cast that binds nothing falls back to the caster.
-    // The behaviour has been here since the cast arm landed, welded to a Resource default; it is a
-    // CVar now because 1.12's `TOGGLEAUTOSELFCAST` binding is `GetCVar`/`SetCVar` over this exact
-    // name and there was nothing for it to toggle (decision 1745).
-    //
-    // Register site `0x6e731d`, default string `"0"`, record `[0xceac34]`, one reader at
-    // `0x6e53d7` (1804). **This row used to cite `0x870dc0` as the record; that is the NAME
-    // string**.
-    //
-    // **benilla ships it ON and the reference registers "0"** — a named deviation that predates
-    // this row (`cast_target::AutoSelfCast`): with it off, an unbindable friendly cast falls into
-    // the reference's targeting-cursor machine, which is unmodeled, leaving no path at all. Flip
-    // to the reference's default when that machine lands.
+    // `autoSelfCast` (register site `0x6e731d`, record `[0xceac34]`, read at `0x6e53d7`; `0x870dc0`
+    // is its name string): a friendly cast that binds nothing falls back to the caster.
+    // `TOGGLEAUTOSELFCAST` toggles it.
     deviates(
         "autoSelfCast",
         "1",
@@ -399,11 +242,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
          targeting-cursor machine, which is unmodeled — leaving no path at all. Flip when that \
          machine lands",
     ),
-    // The five saved camera views and the live index (decision 1745) — the reference's own
-    // sixteen names and its own shipped default strings, both read out of `WoW.exe` and owned by
-    // [`crate::player::camera_view`], which is also the only writer. Registered here so they are
-    // ordinary CVars: persisted as a diff like everything else, readable from a macro, and
-    // reachable by `SetCVar` — which is what makes a `SaveView` survive a restart.
+    // The five saved camera views and the live index, at the reference's names and default strings;
+    // owned by [`crate::player::camera_view`]. Registered so a `SaveView` persists.
     same(
         crate::player::camera_view::CVAR_ACTIVE_VIEW,
         crate::player::camera_view::ACTIVE_VIEW_DEFAULT,
@@ -475,100 +315,33 @@ pub(crate) const REGISTERED: &[Registered] = &[
         "0961: 1.12 has no auto-loot CVar at all — vanilla offers only the shift gesture, so OFF \
          IS the reference's own behaviour; the spelling is era's",
     ),
-    // The overhead-name trio (0992): 1.12's own UnitName* CVars (UIOptionsFrame.lua indices
-    // 21/30/67) over the nameplates module's gates. Defaults mirror `NameConfig::default()` and
-    // are the binary's own, byte-read at the `0x6c7470` registrar (name string / default string
-    // per row, folded into
-    // mask `0xce8720`) — `UnitNamePlayer` `0x86c694` → `"1"` `0x82e748`, `UnitNameNPC` `0x86c6a4`
-    // and `UnitNameOwn` `0x86c6b0` → `"0"` `0x82e570`. Corroborated the other way by the
-    // reference install's own `Config.wtf`, which carries `SET UnitNameNPC "1"` and
-    // `SET UnitNameOwn "1"`: `SaveConfig 0x63d980` writes only what has MOVED off its default, so
-    // those two lines existing is proof the defaults are not "1".
-    //
-    // **npc and own shipped ON here from 2026-07-12 until 1804** — see `NameConfig`'s doc.
+    // The overhead-name gates, registered at `0x6c7470` into mask `0xce8720`: `UnitNamePlayer`
+    // (`0x86c694`) "1" (`0x82e748`), `UnitNameNPC` (`0x86c6a4`) and `UnitNameOwn` (`0x86c6b0`) "0"
+    // (`0x82e570`).
     same("UnitNamePlayer", "1"),
     same("UnitNameNPC", "0"),
     same("UnitNameOwn", "0"),
-    // The fourth of the same registrar's five (2149): `UnitNamePlayerGuild` `0x86c680` -> `"1"`
-    // `0x82e748`, mask bit `0x10`. It is NOT a show gate like the three above — `ShouldShowName
-    // 0x6070a0` consults only bits `0x1/0x2/0x4` — it gates ONE LINE of the player stack, the a5
-    // `"\n<%s>"` guild decoration at `0x609085`. Its fifth sibling `UnitNamePlayerPVPTitle` (bit
-    // `0x20`, also `"1"`) has no row: a4's rank prefix needs a faction side `ui_unit` cannot
-    // resolve for an arbitrary player, so there is no reader and 1134 §4 says no key.
+    // `UnitNamePlayerGuild` (`0x86c680`, "1", mask bit `0x10`) is not a show gate: `ShouldShowName`
+    // (`0x6070a0`) reads bits `0x1/0x2/0x4`, and this gates the `"\n<%s>"` guild line at
+    // `0x609085`. `UnitNamePlayerPVPTitle` (bit `0x20`, "1") has no row: nothing here draws the
+    // rank prefix.
     same("UnitNamePlayerGuild", "1"),
-    // The two V-plate toggles over `VPlateMode` — the engine bitmask `[0xc4da34]`'s bit 0 and
-    // bit 3. 1.12 registers NO nameplate CVar (the bitmask is a plain runtime
-    // global, persisted FrameXML-side as the `RegisterForSave`'d `NAMEPLATES_ON` /
-    // `FRIENDNAMEPLATES_ON`), so these take the LATER-era engine's names: the `autoLootDefault`
-    // posture, where benilla's persistence IS the CVar store (0954) and a setting with no 1.12
-    // CVar gets the era spelling rather than an invented one.
-    //
-    // **`same`, not `ours`, and that distinction is the point**: the reference has no CVar to
-    // match, but it very much has a *setting* to match, and it boots both halves OFF —
-    // `UIOptionsFrame_Init` assigns `NAMEPLATES_ON = nil` / `FRIENDNAMEPLATES_ON = nil` and
-    // `UpdateNameplates` only calls `ShowNameplates()` on a truthy value (the install's
-    // `Interface\FrameXML\UIOptionsFrame.lua` l.180-183 / l.769-775 — both of them the stock
-    // file's own, off the chain since 2115; our copies of each are gone). A fresh 1.12 client
-    // draws no plates until V is pressed. Enemy plates shipped ON here from 0167
-    // until 1804 — `VPlateMode::default()` carries that history.
+    // 1.12 has no nameplate CVar: the bitmask `[0xc4da34]` (bits 0 and 3) persists through
+    // FrameXML's `NAMEPLATES_ON`/`FRIENDNAMEPLATES_ON`, so these take the later-era names. Both
+    // boot off (`UIOptionsFrame.lua:180-183`, `:769-775`): no plates until V.
     same(crate::vplates::CVAR_ENEMIES, "0"),
     same(crate::vplates::CVAR_FRIENDS, "0"),
-    // World detail (0992) — the ENVIRONMENT_DETAIL slider's 0..2, over the clutter-density knob.
-    // 0 is the client's bare `frillDensity` baseline (×1 = 16 visits), each step +1×, so 0/1/2 are
-    // the 16/32/48 `SetWorldDetail` itself writes.
-    //
-    // **Not a 1.12 CVar** (corrected 1804 — this row used to call it "1.12's video-panel var").
-    // `WorldDetail` does not exist as a string in `WoW.exe` (scanned; positive control
-    // `frillDensity` present), and `OptionsFrame.lua:27`'s `func = "WorldDetail"` is a *function
-    // name suffix*: the slider calls the engine's `GetWorldDetail`/`SetWorldDetail`. So the
-    // spelling is the API's — the `autoLootDefault` posture.
-    //
-    // **"1" IS the reference's own setting, and getting there took two goes.** `SetWorldDetail
-    // 0x488dd0` writes **two** CVars per stop: `frillDensity` {16,32,48} and `SmallCull`
-    // {0.07,0.04,0.01}. The registered pair is `frillDensity` **16** (stop 0) with `SmallCull`
-    // **0.04** (stop **1**) — the reference boots an inconsistent pair — and `GetWorldDetail`
-    // reads only `SmallCull`. So its own slider **reads Medium at boot**, which is this row.
-    // Mid-1804 this was filed as a deviation against "0" on two true facts that are not the
-    // answer: `OptionsFrame.lua:430`'s Defaults ladder yields 0, and `frillDensity` registers 16.
-    // A partly-verified mechanism is not the mechanism (1804).
-    //
-    // What IS still divergent is the grass, and that is a *mapping* difference rather than a
-    // default: our stop 1 scatters ×2 (32) where the reference's boot `frillDensity` is 16
-    // registered, 24 after `hwDetect` reads `VideoHardware.dbc` (row 170 on any D3D9-class part,
-    // 8 on the weakest). 24 is on no stop of ours; 1649 broke that tie toward the denser stop,
-    // because erring sparse is the worse failure for a knob about ground cover. **That divergence
-    // is a row of its own now** — 2151 registered the CVar it lives in, immediately below, so it
-    // is on the deviation inventory instead of only in this paragraph.
+    // `WorldDetail` is no 1.12 CVar but the `GetWorldDetail`/`SetWorldDetail` verb name
+    // (`OptionsFrame.lua:27`); stops 0/1/2 are `frillDensity` 16/32/48. `SetWorldDetail 0x488dd0`
+    // also writes `SmallCull` {0.07, 0.04, 0.01}, and `GetWorldDetail` reads only `SmallCull`,
+    // whose registered 0.04 is stop 1: the reference's slider boots at Medium.
     same("WorldDetail", "1"),
-    // The SAME knob in the reference's own unit (2151), and the CVar 1.12 actually registers for
-    // it: `0x68862e` passes name `0x8423d8` `"frillDensity"`, default string `0x864644` `"16"`,
-    // help "Terrain frill density", flags `1`, callback `0x688de0`, record `[0xc7f2f4]`. The value
-    // is **cells visited per chunk**: the
-    // callback clamps `[1, 256]` and hands the number to `0x6725a0` → `[0xc7b494]`, which bounds
-    // the detail-doodad scatter loop at `0x6bfcfb`/`0x6bff1c`. Our scatter is the byte-exact port
-    // of that loop, so `frillDensity` is not a new dial — it is the unit
-    // `benilla_formats::scatter_ground_doodads` has always counted in, and
-    // `ClutterConfig::frill_density` is the conversion.
-    //
-    // **Two names for one knob is the reference's own shape, not ours.** `SetWorldDetail 0x488dd0`
-    // writes this CVar per stop (16/32/48) alongside `SmallCull` — the row above is that stop,
-    // this row is what the stop wrote. Writing either moves the same ground cover here, and each
-    // keeps the clamp its own writer has: the stop's `[0, 2]`, the cells' `[1, 256]`. So a console
-    // `frillDensity 200` is honoured, exactly as it is there, and the panel row then reads
-    // off-grid — which is already this pair's stated posture for an off-grid multiplier.
-    //
-    // **It has a live Lua consumer, which is why it is registered now** (the module doc's rule):
-    // pfUI's `hdgraphic` replaces `GetWorldDetail` with `tonumber(GetCVar("frillDensity")) > 48`,
-    // and unregistered that is `nil > 48` — an error, not a fallback. Its extended arm drives the
-    // knob the other way, `ConsoleExec("frillDensity " .. (arg+1)*16)` up to 256, which is the
-    // whole reason the reference's range is wider than its slider.
-    //
-    // **The deviation is 1649's grass, finally visible as a row.** 1804 recorded it in prose and
-    // could not table it, because the CVar it is a deviation *in* was not registered: our stop 1
-    // scatters 32 where the reference's boot value is 16 registered, and 24 after `hwDetect`
-    // (`0x639a60` CVar::Sets sixteen video CVars from the matched `VideoHardware.dbc` row; field
-    // `+0x18` holds 8/12/16/24 across the table, 24 on the videoID 170 that the reference
-    // install's own `Logs/gx.log` resolves to). 24 is on no stop of ours.
+    // `frillDensity` (`0x68862e`: name `0x8423d8`, default `0x864644` "16", flags 1, callback
+    // `0x688de0`, record `[0xc7f2f4]`): detail-doodad cells visited per chunk, clamped to [1, 256]
+    // and handed through `0x6725a0` to `[0xc7b494]`, the bound of the scatter loop at
+    // `0x6bfcfb`/`0x6bff1c`. One knob with `WorldDetail`, each keeping its own clamp. `hwDetect`
+    // (`0x639a60`) sets it from `VideoHardware.dbc` field `+0x18`, 24 on videoID 170. pfUI's
+    // `hdgraphic` reads `GetCVar("frillDensity") > 48` and writes up to 256.
     deviates(
         "frillDensity",
         "32",
@@ -577,21 +350,11 @@ pub(crate) const REGISTERED: &[Registered] = &[
          stop at all, so every stop diverges; Medium (32) is the nearest one no sparser than a \
          fresh install, and erring sparse is the worse failure for ground cover",
     ),
-    // ── The combat log's display ranges: the reference's own `0x8629e0` table, in yards ─────────
+    // ── Combat log display ranges, in yards ──────────────────────────────────────────────────────
     //
-    // Eight rows, registered by the reference in ONE place — `0x626d00`, a loop over the
-    // `{cvarName, defaultValue}` pairs at `0x8629e0` skipping the NULL/empty names, then one
-    // unrolled call for the death range. They read as the CVar record's **float** (`+0x24`), unlike
-    // the periodic gate below, which reads the int.
-    //
-    // **They are why a damage meter's range slider does something.** `BigWigs/Plugins/Range.lua`
-    // and `DPSMate/DPSMate_DataBuilder.lua` both read and write all eight; unregistered, every
-    // `SetCVar` here wrote nothing and every `GetCVar` answered nil. The reader was already built
-    // — `ui_chat::combat::in_range` has run this exact table since 1571, off the compiled-in
-    // defaults, with `UnitClass::range_cvar` parked under `#[cfg(test)]` waiting for this row.
-    //
-    // Classes 0 and 1 — you and your pet — have NO CVar in the reference's table (a NULL name and
-    // the `100000.0` sentinel), so there is nothing to register for them and nothing to miss.
+    // Registered by `0x626d00` from the `{name, default}` pairs at `0x8629e0`, read as the record's
+    // float (`+0x24`). Classes 0 and 1, you and your pet, have no CVar there, only the `100000.0`
+    // sentinel.
     same("CombatLogRangeParty", "50"),
     same("CombatLogRangePartyPet", "50"),
     same("CombatLogRangeFriendlyPlayers", "50"),
@@ -599,287 +362,144 @@ pub(crate) const REGISTERED: &[Registered] = &[
     same("CombatLogRangeHostilePlayers", "50"),
     same("CombatLogRangeHostilePlayersPets", "50"),
     same("CombatLogRangeCreature", "30"),
-    // The one range CVar OUTSIDE that table (`0x626d5f`, default string `"60"` at `0x862e14`) —
-    // and the only formatter with a range of its own. `0x62c160` reads it first and falls back to
-    // the per-class getter only when the *lookup* fails, which a registered client never sees.
+    // Outside that table (`0x626d5f`, "60" at `0x862e14`): `0x62c160` reads it first and falls back
+    // to the per-class range only when the lookup fails.
     same(crate::ui_chat::combat::DEATH_LOG_RANGE_CVAR, "60"),
-    // ── The floating-combat-text gates, and the periodic one ────────────────────────────────────
+    // ── Floating combat text ─────────────────────────────────────────────────────────────────────
     //
-    // `CombatDamage` (`0x6032df`, record `[0xc4d944]`) is the MASTER: its only two readers are the
-    // localized-WORD emitter `0x607140` and the `"%d"` NUMBER emitter `0x6128b0`, and both branch
-    // targets are epilogues — so at "0" nothing floats over any unit from any source, words
-    // included, despite the CVar's own help text saying "damage numbers". The two `Pet*` rows are
-    // sub-gates below it, on the owned-by-you branch only; the self sub-case is unconditional.
-    //
-    // `PetSpellDamage` has no row in `UIOptionsFrameCheckButtons` — the *Show Pet Melee Damage*
-    // box writes both (`UIOptionsFrame_Save` l.334-336) — which is why 2077's census, which reads
-    // that table, could not see it while it saw its two siblings. Our own Pet Damage row carries
-    // the same partner write (2180); all three are on the Combat page, under `CombatDamage`.
+    // `CombatDamage` (`0x6032df`, record `[0xc4d944]`) is the master: its two readers, the word
+    // emitter `0x607140` and the number emitter `0x6128b0`, both return at "0", so nothing floats.
+    // The `Pet*` rows gate only the owned-by-you branch; the stock Pet Melee Damage box writes both
+    // (`UIOptionsFrame.lua:335-336`).
     same("CombatDamage", "1"),
     same("PetMeleeDamage", "1"),
     same("PetSpellDamage", "1"),
-    // `CombatLogPeriodicSpells` (`0x6033b3`, handle deliberately DISCARDED — every use re-looks it
-    // up by name). Read as the record's INT, unlike the ranges above, which read its float.
+    // `CombatLogPeriodicSpells` (`0x6033b3`): the handle is discarded and every use looks it up by
+    // name; read as the record's int.
     same(crate::ui_chat::combat::LOG_PERIODIC_CVAR, "1"),
-    // ── The three Sound-panel check buttons benilla had the machinery for and no key to ─────────
+    // ── Sound-panel check buttons ────────────────────────────────────────────────────────────────
     //
-    // All three are category-7 (sound) registrations that keep **no** `CVar::Register` handle: the
-    // reference looks each up by name at the point of use. Each already had its reader here.
+    // Category-7 registrations that keep no handle: the reference looks each up by name at use.
     //
-    // `SoundListenerAtCharacter` (`0x457890`, "lock listener at character"): both of its branches
-    // were already written in `update_audio_listener` — the at-character seat and the at-camera
-    // one — with the camera path reachable only as a no-character fallback. This is the selector
-    // they were missing.
+    // `SoundListenerAtCharacter` (`0x457890`): the listener at the character, else at the camera
+    // (`update_audio_listener`).
     same("SoundListenerAtCharacter", "1"),
     // `EmoteSounds` (`0x4573b9`): the received text-emote voice kit, and only that.
     same("EmoteSounds", "1"),
-    // `SoundZoneMusicNoDelay` (`0x4578b3`): `next_track_time`'s own comment named it as "the
-    // immediate path, a \"0\" CVar we don't expose". Now exposed, at the reference's `"0"`.
+    // `SoundZoneMusicNoDelay` (`0x4578b3`): `next_track_time`'s immediate path.
     same("SoundZoneMusicNoDelay", "0"),
-    // `assistAttack` (`0x48fc50`, record `[0xb4d8f8]`) — `/assist`'s opt-in second leg: select the
-    // basis unit's target AND open the swing on it. Three references image-wide, two of them the
-    // shared assist tails; `CanAssist 0x6066f0` is verified NOT on the path. The `"0"` default is
-    // easy to misread: the *next* registration's default (`minimapZoom`) is `"3"`, and reading it
-    // off instead is the `mov ds:` adjacency trap — so it is worth saying plainly here: stock
-    // `/assist` selects and does not swing.
+    // `assistAttack` (`0x48fc50`, record `[0xb4d8f8]`): `/assist` also starts the swing. The "3"
+    // beside it is the next registration's, `minimapZoom`: stock `/assist` selects without
+    // swinging.
     same("assistAttack", "0"),
-    // ── Mouse-look, per axis: the two CVars whose absence RAISED in the stock window ────────────
+    // ── Mouse-look speed, per axis ───────────────────────────────────────────────────────────────
     //
-    // `cameraYawMoveSpeed` is `UIOptionsFrameSliders` row 3, MOUSE_LOOK_SPEED (90…270 step 10) —
-    // and it is what made stock `UIOptionsFrame_Load()` die: `slider:SetValue(GetCVar(value.cvar))`
-    // is a shape-A binding (`0x790980`) that raises on a nil in the reference too, so the whole
-    // window's `_Load` (and `_SetDefaults`, through `GetCVarDefault`) stopped at slider 3.
-    // `cameraPitchMoveSpeed` has no row of its own: `UIOptionsFrame_Save` writes it as
-    // `sliderValue / 2` beside the yaw one (l.352-356), which is exactly this 180/90 pair — and
-    // the Controls page's Mouse Look Speed row carries that partner write (2180), so dragging it
-    // keeps the two axes in the ratio the registrar ships them at.
-    //
-    // **Both defaults are the reference's, and the shipped feel does not change** — the two facts
-    // are compatible only because the unit divergence is carried in `camera::LOOK_YAW_PER_SPEED`
-    // instead of in these numbers. The reference integrates OS-accelerated `WM_MOUSEMOVE` pixels
-    // (it imports no DirectInput at all) while we integrate winit's raw device delta, so its
-    // `deg per pixel` is not our `deg per unit` and the factor between them is a per-machine
-    // pointer setting. Anchoring the scale there and keeping the defaults here is what lets 1804
-    // hold honestly rather than by picking a number that merely looks right.
-    //
-    // The validator is `0x50c000` → `0x50b330`, range [0.1, 360], and it **rejects rather than
-    // clamps** — `player::camera::on_cvar` does the same, which is why these two do not use the
-    // clamping shape every other numeric row uses.
+    // `cameraYawMoveSpeed` is the MOUSE_LOOK_SPEED slider (`UIOptionsFrame.lua:89`); a nil there
+    // raises in `slider:SetValue` (`0x790980`) and stops `UIOptionsFrame_Load`. The stock Save
+    // writes `cameraPitchMoveSpeed` as half of it (`:355-356`). The reference integrates
+    // OS-accelerated pixels where we take raw device deltas, so the unit factor lives in
+    // `camera::LOOK_YAW_PER_SPEED` and these defaults stay the reference's. The validator
+    // `0x50c000` → `0x50b330` rejects values outside [0.1, 360] rather than clamping, and
+    // `player::camera::on_cvar` does the same.
     same("cameraYawMoveSpeed", "180"),
     same("cameraPitchMoveSpeed", "90"),
-    // Mouse Sensitivity (1140): 1.12's own MOUSE_SENSITIVITY slider (`UIOptionsFrameSliders` row
-    // 1, 0.5..1.5 step 0.05), a MULTIPLIER over the camera's own per-pixel rate — which was a
-    // frozen constant until this row. Default "1" is the shipped feel exactly, welded to
-    // `LookConfig::default()`.
-    //
-    // **The spelling is FrameXML's, not the binary's**, and that is deliberate: `WoW.exe` holds
-    // `mouseSpeed` (capital S, register site `0x402c7b`) while `UIOptionsFrame.lua`'s slider
-    // writes `cvar = "mousespeed"`. The reference reconciles them by looking CVars up
-    // case-insensitively (`SStrCmpI` in `CVar::Lookup 0x63de30`), and so do we (the registry and
-    // every observer lowercase first), so both spellings answer. We take the one the interface uses, because
-    // that is the one an addon will type.
-    //
-    // **The VALUE agrees and the MECHANISM does not** (1804). The reference's default is not a
-    // literal at all: it is `sprintf("%1.1f", SPI_GETMOUSESPEED × 0.1)`, which is `"1.0"` on a
-    // stock Windows host — so "1" is the right number. But its record `[0x882704]` has **zero
-    // readers**: the slider drives the *operating system's* pointer speed through
-    // `SPI_SETMOUSESPEED` (callback `0x402ec0`, clamped [0.1, 2.0]), not an in-engine gain.
-    // benilla will not reach out and repoint the OS mouse, so ours is a multiplier over our own
-    // per-pixel rate — the same dial, the same range, the same resting value, a different thing
-    // underneath. Recorded here rather than filed as a deviation because the default is the
-    // question this table answers, and the default matches.
+    // MOUSE_SENSITIVITY (`UIOptionsFrame.lua:87`): FrameXML's spelling of the binary's `mouseSpeed`
+    // (`0x402c7b`); lookups are case-insensitive (`CVar::Lookup 0x63de30`), here as there. The
+    // reference's default is `SPI_GETMOUSESPEED × 0.1`, "1.0" on stock Windows, and its record
+    // `[0x882704]` has no reader: the slider sets the OS pointer speed (`0x402ec0`, [0.1, 2.0]).
+    // The default matches; Deviation: here the dial multiplies the camera's own rate, because
+    // benilla does not change the OS pointer speed, a system-wide setting.
     same("mousespeed", "1"),
-    // Max Camera Distance (1140): 1.12's `cameraDistanceMaxFactor` (its MAX_FOLLOW_DIST slider,
-    // 1..2 step 0.1) over `cameraDistanceMax`'s 15 yd base. **"1", the reference's registrar
-    // value** (`cameraDistanceMax` "15.0" `0x84fbd0`, `cameraDistanceMaxFactor` "1.0" `0x82e92c`)
-    // — so the shipped ceiling is 15 yd, not the 30 this row registered from 1140 until 1804.
-    // `ZoomLimit`'s doc carries why that changed; the slider still reaches 2.
+    // MAX_FOLLOW_DIST (`UIOptionsFrame.lua:90`), a factor over `cameraDistanceMax`'s 15 yd
+    // (`0x84fbd0`); registered "1.0" (`0x82e92c`).
     same("cameraDistanceMaxFactor", "1"),
-    // Camera Following Style (1493, re-pinned by 1502): 1.12's `cameraSmoothStyle` — the
-    // auto-return that swings the camera back behind the character. Registered "1" = Smart, which
-    // is BOTH the reference's registrar default (byte-verified: the argument is loaded from
-    // `[0x84f4f4]` -> "1" at the `0x50ba92` register site) and the director's call; benilla behaved
-    // as Never unconditionally until this row. The enum is the ENGINE's — 0 Never, 1 Smart,
-    // 2 Always — NOT the 1/2/3 the reference's own dropdown writes; see `FollowStyle`.
+    // `cameraSmoothStyle` (`0x50ba92`, default `[0x84f4f4]` "1"), the auto-return behind the
+    // character. The engine's enum is 0 Never, 1 Smart, 2 Always, as the stock dropdown writes it
+    // (`UIOptionsFrame.lua:525,536,547`); 3, the Never entry's position, is the validator's upper
+    // bound (`0x50b330(v, 0, 3)`). See `FollowStyle`.
     same("cameraSmoothStyle", "1"),
-    // Its sibling selector (1502), also registered "1": the reference reads THIS style instead
-    // whenever the state mask contains Track or Fear — the externally-driven states — indexing the
-    // same matrices. No row on any 1.12 panel, here or there; the reader is the host.
+    // Read instead of `cameraSmoothStyle` while the state mask holds Track or Fear; no panel row.
     same("cameraSmoothTrackingStyle", "1"),
-    // The auto-follow's rate (1502), °/s — 1.12's own AUTO_FOLLOW_SPEED slider
-    // (`UIOptionsFrameSliders`, 90..270 by 10), registered at the binary's "180.0" (`[0xbe1070]`).
-    // It sets the transition's DURATION (`|dyaw| / rate * factor`), so it is an average rate, not a
-    // slew. Its slider is the Controls page's Auto-Follow Speed row (2180), greyed while the
-    // following style is Never — and it writes only this one, where the reference also writes
-    // `cameraPitchSmoothSpeed` at a quarter of it: that name is deliberately unregistered here,
-    // because `FollowRig` has a single rate and a key with no reader is 1134 §4's pretence.
+    // AUTO_FOLLOW_SPEED (`UIOptionsFrame.lua:88`), deg/s, registered "180.0" (`[0xbe1070]`): it
+    // sets the transition's duration (`|dyaw| / rate * factor`), an average rate, not a slew. The
+    // knob clamps it to `FOLLOW_SPEED_RANGE`. The stock Save also writes `cameraPitchSmoothSpeed`
+    // at a quarter (`:353`), unregistered here: `FollowRig` has one rate.
     same("cameraYawSmoothSpeed", "180"),
-    // **The four 1.12 camera-option toggles** (decision 2149) — the `UIOptionsFrame` checkboxes
-    // FOLLOW_TERRAIN / HEAD_BOB / SMART_PIVOT / WATER_COLLISION, all four of which sat on the
-    // unbacked-CVar census with a byte-level spec and no feature until now. Defaults are the
-    // registrar's own, and two of them are **"1"** — which is why building them was not cosmetic:
-    // benilla was the divergence on those, not the reference.
-    //
-    // `cameraPivot` `[0xbe10a4]` "1" (`0x50bda3`) — smart pivot. Mechanism: gate `0x510690`,
-    // routing `0x50fee0`, release `0x5107f0`; ours is `player::camera_dynamics::SmartPivot`.
+    // `cameraPivot` `[0xbe10a4]` "1" (`0x50bda3`), smart pivot: gate `0x510690`, routing
+    // `0x50fee0`, release `0x5107f0`; ours is `player::camera_dynamics::SmartPivot`.
     same("cameraPivot", "1"),
-    // Its two drag-shape thresholds, both read by that routing (`0x50fff5`/`0x510004`) and both
-    // in RADIANS of camera rotation — the deltas they are compared against are already scaled by
-    // `camera<Yaw|Pitch>MoveSpeed · π/180`, so unlike the sensitivity itself these two transfer
-    // to benilla's raw-device units exactly (see `camera::LOOK_YAW_PER_SPEED`'s note).
+    // Read by the routing (`0x50fff5`/`0x510004`) in radians of camera rotation, so they carry to
+    // benilla's raw-device units unchanged.
     same("cameraPivotDXMax", "0.05"),
     same("cameraPivotDYMin", "0"),
-    // The rate the pitch bias eases back on once the pivot lets go, deg/s (`[0xbe0fc8]`,
-    // `0x512a50`'s `duration = |Δ| / (rate · π/180)`). No panel row here or there — the reader is
-    // the host, exactly like `cameraSmoothTrackingStyle` above it.
+    // The pitch bias's ease-back once the pivot lets go, deg/s (`[0xbe0fc8]`; `0x512a50` divides
+    // |Δ| by rate · π/180 for the duration); no panel row.
     same("cameraTargetSmoothSpeed", "90"),
-    // **`cameraWaterCollision`** `[0xbe1088]` "1" (`0x50bd63`, default string `0x82e748`) — one of
-    // the two that ship ON, and this row is its THIRD life. It is **one CVar with two consumers**,
-    // and this tree has now shipped each of them alone and broken the camera both times: 2149 the
-    // pivot corridor without the trace (a 19/18 yd step reached continuously), 2170 the trace
-    // without the corridor (the boom straddling a plane the pivot sits 11 mm under — 2173 §1).
-    // Both halves are here now, and the row exists to say they may never again be separated.
-    //
-    // `0x50e5ec` produces one register. Its `0xf0000` nibble rides the trace mask to all three of
-    // `0x50e570`'s queries, reaching `0x69cc13` through four direct calls; and `0x50e629` tests
-    // the SAME register to admit the floor/cap block that lifts the sweep origin to
-    // `surface + 2/9`. Readers: the camera boom's collision filter
-    // (`benilla_world::collision::camera_filter`) and `player::camera_water`.
+    // `cameraWaterCollision` `[0xbe1088]` "1" (`0x50bd63`, `0x82e748`): one register, two consumers
+    // that must ship together. `0x50e5ec` builds it; its `0xf0000` nibble joins the trace mask of
+    // all three `0x50e570` queries (reaching `0x69cc13`), and `0x50e629` tests it to lift the sweep
+    // origin to `surface + 2/9`. Ours: `benilla_world::collision::camera_filter` and
+    // `player::camera_water`.
     same("cameraWaterCollision", "1"),
-    // `cameraTerrainTilt` `[0xbe0fd4]` **"0"** (`0x50bcfd`) — Follow Terrain, and the one of the
-    // four that ships OFF, so building it changed nothing until a player ticks the box. Mechanism:
-    // the ahead-probe and the five-step staircase (`0x50d900`) and the arm (`0x50dbc0`); ours is
-    // `player::camera_dynamics::TerrainTilt`.
+    // `cameraTerrainTilt` `[0xbe0fd4]` "0" (`0x50bcfd`), Follow Terrain: probe and staircase
+    // `0x50d900`, arm `0x50dbc0`; ours is `player::camera_dynamics::TerrainTilt`.
     same("cameraTerrainTilt", "0"),
-    // The ground channel's rate, deg/s (`[0xbe0fc0]`) and the duration bound its `Factor` scales
-    // (`[0xbe1050]`/`[0xbe1054]`, seconds). The floor always binds — `20° / 7.5°/s` is 2.67 s
-    // against a 3 s minimum — which is why a followed terrain leans rather than tracks.
+    // Rate in deg/s (`[0xbe0fc0]`), duration bounds in seconds (`[0xbe1050]`/`[0xbe1054]`). The 3 s
+    // floor always binds (20° at 7.5°/s is 2.67 s), so the camera leans rather than tracks.
     same("cameraGroundSmoothSpeed", "7.5"),
     same("cameraTerrainTiltTimeMin", "3"),
     same("cameraTerrainTiltTimeMax", "10"),
-    // `cameraBobbing` `[0xbe10c0]` **"0"** (`0x50b76d`) — head bob, the fourth of the four and the
-    // second that ships OFF. Mechanism: the kernel `0x511920` and its gate `0x5105e0`; ours is
-    // `player::camera_dynamics::HeadBob`.
+    // `cameraBobbing` `[0xbe10c0]` "0" (`0x50b76d`), head bob: kernel `0x511920`, gate `0x5105e0`;
+    // ours is `player::camera_dynamics::HeadBob`.
     same("cameraBobbing", "0"),
-    // Its four numeric siblings. The two amplitudes are in the CVar's own units — the kernel
-    // scales both by 1/36 (`[0x7ff9d0]`) to reach yards. `cameraBobbingSmoothSpeed` is the odd one
-    // and its name is the trap: it is **not** a bob rate, it is the DECAY rate, and its single
-    // image-wide read is in the disarm `0x51113a`, where `|largest component| / speed` becomes the
-    // ramp's duration (~0.069 s at these defaults).
+    // Amplitudes in the CVar's units, scaled by 1/36 (`[0x7ff9d0]`) to yards.
+    // `cameraBobbingSmoothSpeed` is the decay rate, read only in the disarm `0x51113a`, which
+    // divides the largest component by it for the ramp's duration (~0.069 s at these defaults).
     same("cameraBobbingLRAmplitude", "2"),
     same("cameraBobbingUDAmplitude", "2"),
     same("cameraBobbingFrequency", "0.8"),
     same("cameraBobbingSmoothSpeed", "0.8"),
-    // Status Text (1140): 1.12's `statusBarText`, the "always show value / max on a status bar"
-    // switch. **No host knob** — its consumer is Lua (TextStatusBar.xml, decision 1082, which was
-    // written waiting for this key and reads it on every repaint). Default "0": the reference's
-    // out-of-box look is hover-only numerals.
-    //
-    // **Byte-read since 1804** — register site `0x48fc34`, default string `"0"`, record
-    // `[0xb4d904]`, and a whole-image census finds that record has **no engine reader at all**:
-    // this CVar is FrameXML's alone, which is exactly the shape this row was built for. It used to
-    // concede "behaviour-derived, not byte-read"; that hedge is retired.
+    // `statusBarText` (`0x48fc34`, record `[0xb4d904]`, no engine reader), read by
+    // `TextStatusBar.lua:47,97`: "0" shows the numbers on hover only.
     same("statusBarText", "0"),
-    // Enhanced Tooltips (B230): 1.12's `UberTooltips`, the *Enhanced Tooltips* checkbox
-    // (`UIOptionsFrame.lua:15`, `USE_UBERTOOLTIPS`). **No host knob** — its consumers are Lua, and
-    // there are three: PetActionBar.xml forks the whole tooltip on it (a token's own text with the
-    // binding appended, vs the engine's pet-spell channel), the stock action and shapeshift buttons fork
-    // their anchor. Registered "1" — byte-read, not behaviour-derived: WoW.exe `0x48fdd9`, default
-    // string `0x82e748`, with the sibling rows `BlockTrades`→"0" and `UnitNameRenderMode`→"2"
-    // confirming the layout. Those three Lua sites each carried the reference's fork in prose and
-    // then collapsed it to this default, on the stated premise that benilla shipped no CVar state
-    // for anything to move. That premise expired with 0954, and this row is what un-collapses them.
+    // Enhanced Tooltips (`UIOptionsFrame.lua:15`), registered "1" at `0x48fddd` (`0x82e748`); read
+    // only by the stock interface.
     same("UberTooltips", "1"),
-    // The two chat-bubble switches (1139): 1.12's own registrar CVars over the bubble gate,
-    // which held them as `const bool` from 0598 until this window had a page for them. Both are
-    // the binary's own (registrar `0x603280`:
-    // `ChatBubbles` "1", `ChatBubblesParty` "0"); the party half shipped ON from 0598 to 1804 on
-    // the director's `/p` ask, and is a click away on the Chat page.
+    // Registered at `0x603280`: `ChatBubbles` "1", `ChatBubblesParty` "0".
     same("ChatBubbles", "1"),
     same("ChatBubblesParty", "0"),
-    // **The two text filters** (2077) — 1.12's own pair, and both are real features rather than
-    // vestigial switches.
-    // Registered `"1"` each, byte-read: `0x402e68` (`profanityFilter`, name `0x82e7f4`, callback
-    // `0x403570`) and `0x402e8e` (`spamFilter`, name `0x82e7d4`, callback `0x4035b0`), both pushing
-    // the shared `"1"` literal `0x82e748`, both category 4.
-    //
-    // `profanityFilter` masks matched spans of `ChatProfanity.dbc` in place, and it gates INSIDE
-    // the shared masker (`0x4a1a66`), so all thirteen of its call sites are covered by the one
-    // switch — the 14 social chat types, mail, the guild MOTD/info/rank names, item text and the
-    // send path. `spamFilter` is a predicate over `SpamMessages.dbc` at the chat chokepoint that
-    // **drops** a matching line silently. The knob for both is
-    // [`crate::text_filter::TextFilterSwitches`]; the engine is `crate::text_filter`.
+    // Registered "1" (`0x82e748`), category 4. `profanityFilter` (`0x402e68`, name `0x82e7f4`,
+    // callback `0x403570`) masks `ChatProfanity.dbc` spans inside the shared masker `0x4a1a66`,
+    // covering all thirteen call sites; `spamFilter` (`0x402e8e`, name `0x82e7d4`, callback
+    // `0x4035b0`) silently drops a line matching `SpamMessages.dbc`. The knob is
+    // [`crate::text_filter::TextFilterSwitches`].
     same("profanityFilter", "1"),
     same("spamFilter", "1"),
-    // **The loading-screen tip of the day** (2077) — 1.12's own pair, both registered lazily by
-    // `CGlueMgr::EnterWorld` on its way to the config flush (`0x46b633` `gameTip` `"0"`,
-    // `0x46b658` `showGameTips` `"1"`, both category 5, neither with a callback or a help string).
-    //
-    // `gameTip` is not a preference — it is the **cursor**, and it holds the NEXT row rather than
-    // the one on screen, which is why the reference's own `Config.wtf` reads `SET gameTip "34"`
-    // while showing row 33. It is registered here because that is how it persists: the file is
-    // composed from the VM's live table, so the host's advance writes through it. `crate::game_tip`
-    // is the law.
+    // Registered by `CGlueMgr::EnterWorld` (`0x46b633` `gameTip` "0", `0x46b658` `showGameTips`
+    // "1"), category 5. `gameTip` is the cursor and holds the next tip, not the one on screen;
+    // `crate::game_tip` advances it.
     same("gameTip", "0"),
     same("showGameTips", "1"),
-    // *Detailed Loot Information* (1589, the Chat page) — 1.12's `showLootSpam`, whose subject is
-    // group LOOT ROLLS (its own tooltip: "Uncheck this to hide individual loot roll messages and
-    // only show the winner"). Registered `"1"`, **byte-read**: a census of `0xb4e2bc` has the
-    // register site at `0x48fd1c`, name `0x8430a0`,
-    // default string `0x82e748` = "1", **category** 5 — and exactly four references to the global,
-    // one writer and three readers, all in the roll-line composers. The knob is
-    // [`crate::ui_loot::LootConfig::show_loot_spam`], welded to that default below.
+    // `showLootSpam` (`0x48fd1c`, name `0x8430a0`, "1" `0x82e748`, record `0xb4e2bc`): off, group
+    // loot-roll lines are hidden and only the winner shows. Its three readers are the roll-line
+    // composers; the knob is [`crate::ui_loot::LootConfig::show_loot_spam`].
     same("showLootSpam", "1"),
-    // *Guild Member Alert* (1589, the Chat page) — 1.12's `guildMemberNotify`, whose registered
-    // help string says what it does: "Receive notification when guild members log on/off".
-    //
-    // Registered **`"0"`** — this is one of the few rows that ships a feature OFF, and it is
-    // byte-read rather than chosen: the register site `0x5e24c7` pushes default `0x82e570` = "0".
-    // A stock 1.12 client is
-    // silent when a guildmate logs in, and a whole-image census of the record global `0xc4d3c4`
-    // finds exactly two readers, both inside `SMSG_GUILD_EVENT`'s handler. The knob is
-    // [`crate::ui_guild::GuildMemberNotify`]; the other three conjuncts of the line's display
-    // condition live on `ui_guild::net::event`.
+    // `guildMemberNotify` (`0x5e24c7`, "0" `0x82e570`, record `0xc4d3c4`): guildmate log on/off
+    // lines, read only in `SMSG_GUILD_EVENT`'s handler. The knob is
+    // [`crate::ui_guild::GuildMemberNotify`].
     same("guildMemberNotify", "0"),
-    // The minimap's two zoom indices (1131). 1.12 CVars, both registered `"3"` (`0x48fc6c`,
-    // `0x48fc88`, at the `RegisterCVar 0x63db90` argument slot). No options row drives these — the
-    // +/- buttons on the minimap do, through `Minimap:SetZoom`, exactly as in the reference, where
-    // `set_zoom` writes the live index and `CVar::Set`s the CVar in one breath. The knob is
-    // [`crate::minimap::MinimapZoom`], the widget's live index is seeded from it at UI load.
+    // Both registered "3" (`0x48fc6c`, `0x48fc88`); the minimap's +/- buttons write them through
+    // `Minimap:SetZoom`. The knob is [`crate::minimap::MinimapZoom`].
     same("minimapZoom", "3"),
     same("minimapInsideZoom", "3"),
-    // The addon version gate (decision 1292): 1.12's own `checkAddonVersion`, the *Load out of
-    // date AddOns* checkbox INVERTED. Registrar default "1" = check enforced = box unticked
-    // (`0x402c3b`; the key appears in Config.wtf exactly
-    // while force-load is on and vanishes when it is turned off, `SaveConfig 0x63d980`'s
-    // skip-default rule). No host knob: its consumers are the load walk (via the persisted value,
-    // [`Cvars::addon_version_check`]) and the gate's live per-query read in the VM.
+    // Load out of date AddOns, inverted (`0x402c3b`): "1" enforces the check. Read by the load walk
+    // ([`Cvars::addon_version_check`]) and live by the VM's gate.
     same("checkAddonVersion", "1"),
-    // **Which graphics API this run is actually on** (2151) — 1.12's own `gxApi`, byte-read at
-    // `0x63a833`: name `0x842a64`, default string `0x864f7c` `"direct3d"`, help "graphics api",
-    // flags `3` (registered | latched), callback `0x63b030`, record `[0xc4ea94]`. There it is a
-    // real selector — `0x63a3c4` compares the live value case-insensitively against `"OpenGl"`
-    // (`0x842a5c`) and `GxDevCreate` builds `CGxDeviceD3d` on anything else — but no shipped
-    // `WTF` overrides it, so the stock client is always D3D9 and the whole GL arm is dead code
-    // image-wide.
-    //
-    // **Here it DESCRIBES, it does not steer** — the `gxColorBits`/`gxDepthBits` posture. benilla
-    // renders through wgpu, which has no D3D9 backend to name and no chooser to offer: the backend
-    // is the adapter's, picked before the first frame, and this row is the honest report of it
-    // (`wgpu::Backend::to_str` — `metal`, `vulkan`, `dx12`, `gl`). Answering `"direct3d"` on a Mac
-    // would be a name with no behaviour behind it, which is the one thing 1203 forbids outright.
-    //
-    // **Default EMPTY, and pushed live** — the `realmName` posture (1140), for the same reason:
-    // the value is a fact about the machine, written from `RenderAdapterInfo` the moment the VM's
-    // table is seeded, so the default only ever describes a client with no render adapter (a
-    // headless test). Inventing a backend for that case would be worse than admitting we have
-    // none. And because it is the machine's fact rather than the player's choice, it is
-    // **session-owned**: `SetCVar` consumes it and `config.toml` never carries it, so a GPU swap
-    // or a `WGPU_BACKEND` run cannot leave a stale renderer name pinned in the file.
-    //
-    // Its live Lua consumer is pfUI's system panel — `panel.lua:185` does
-    // `"|cffffffff" .. GetCVar("gxApi")` in a tooltip, which on a nil is a concat error rather
-    // than a blank row.
+    // `gxApi` (`0x63a833`: name `0x842a64`, default `0x864f7c` "direct3d", flags 3, callback
+    // `0x63b030`, record `[0xc4ea94]`): the reference builds D3D9 unless it reads "OpenGl"
+    // (`0x63a3c4`, `0x842a5c`). Here it reports the wgpu backend (`wgpu::Backend::to_str`), pushed
+    // from `RenderAdapterInfo` and owned by the session, so it is never persisted. pfUI's
+    // `panel.lua:185` concatenates it.
     deviates(
         "gxApi",
         "",
@@ -888,49 +508,18 @@ pub(crate) const REGISTERED: &[Registered] = &[
          backend and no chooser; the value is the live adapter's own and is never persisted",
     )
     .latched(),
-    // Vertical Sync — 1.12's own `gxVSync`, the Video Options checkbox at index 5
-    // (`OptionsFrame.lua`'s `OptionsFrameCheckButtons["VERTICAL_SYNC"]`, in the install's
-    // FrameXML). The knob is [`crate::video::VideoConfig::vsync`], which the window's
-    // `present_mode` follows.
-    //
-    // Default "1" is BEHAVIOUR-derived, not byte-read: 1.12's registrar value for this var is
-    // unconfirmed, and "1" is what benilla actually ships — the primary window is born at
-    // `PresentMode::default()` (Fifo), and a test in `video.rs` welds the two together.
-    //
-    // Two knowing departures from the reference row, both stated on [`crate::video`]: its
-    // `gxRestart = 1` does not apply (wgpu swaps the presentation interval live, so the box takes
-    // effect on click), and `$WOW_NOVSYNC=1` overrides it session-only, below.
+    // `gxVSync` (`0x63a859`, "1", flags 3), `OptionsFrame.lua:9`. The knob is
+    // [`crate::video::VideoConfig::vsync`], which the window's present mode follows at the
+    // `RestartGx` commit. `$WOW_NOVSYNC=1` overrides it for the session.
     same("gxVSync", "1").latched(),
-    // **Display mode** (decisions 1627, 1650) — 1.12's own `gxWindow`, worn since 1650 as modern
-    // Classic's two-entry *Display Mode* dropdown rather than 1.12's *Windowed Mode* checkbox: the
-    // two states 1627 settled on ARE that client's two (its own `Graphics.lua` builds the list from
-    // `VIDEO_OPTIONS_WINDOWED_FULLSCREEN` and `VIDEO_OPTIONS_WINDOWED`, and nothing else), and a
-    // checkbox could only name one of them. The knob is [`crate::video::VideoConfig::display`],
-    // which the window's `mode` follows.
-    //
-    // Default **"0" = not windowed**, which is the reference's own default and every shipped
-    // game's — but "0" does NOT mean what it means in 1.12. The reference mode-sets the display;
-    // we raise a **borderless** fullscreen window, and ship no exclusive mode at all.
-    // [`crate::video`] carries the three-platform argument for why that is the whole of it (short
-    // version: Wayland cannot do exclusive, X11's XRandR path cannot restore the desktop after a
-    // crash, macOS has no such mode, and WoW itself dropped exclusive fullscreen in 8.0.1).
-    //
-    // Departs from the reference row's `gxRestart = 1` exactly like `gxVSync` above: ours applies
-    // on the click.
-    // Byte-read `"0"` at register site `0x63a889` — **for enUS**. Three defaults in this binary
-    // are locale-conditional and this is one: `gxWindow` and `gxMaximize` (`0x63a8e0`) register
-    // `"1"` on zhCN, `AutoInteract` (`0x603390`) `"1"` on koKR. benilla is enUS-only, so `"0"`
-    // is the answer here; the note exists so the next reader does not take a locale-conditional
-    // default for an unconditional one.
+    // `gxWindow` (`0x63a889`): "0" on enUS; zhCN registers "1", as it does `gxMaximize`
+    // (`0x63a8e0`), and koKR `AutoInteract` (`0x603390`). The knob is
+    // [`crate::video::VideoConfig::display`]. Deviation: "0" raises a borderless fullscreen window
+    // instead of mode-setting the display, because Wayland and macOS offer no mode-set and X11's
+    // leaves the desktop changed after a crash ([`crate::video`]).
     same("gxWindow", "0").latched(),
-    // The **windowed** size, `gxResolution` — 1.12's own CVar name, narrowed to half its job.
-    // There it is the display mode *and* the backbuffer; here it is only what "windowed" means,
-    // because fullscreen is the monitor's own size and we expose no mode list to pick from (the
-    // deviation decision 1092 already records for `GxAspect`, unchanged by 1627).
-    //
-    // A **string** CVar, like it is in the reference — the registry takes any string for it and
-    // `video::on_cvar` parses it. Default is the 1600×900 that was the client's only size before
-    // 1627, so a windowed run is bit-for-bit where it was.
+    // `gxResolution`, a string row parsed by `video::on_cvar`. Here it is only the windowed size:
+    // fullscreen is the monitor's own and no mode list is offered.
     deviates(
         "gxResolution",
         "1600x900",
@@ -939,63 +528,22 @@ pub(crate) const REGISTERED: &[Registered] = &[
          no mode list, and 640x480 is not a window anyone would ship a client at",
     )
     .latched(),
-    // The body panes' half-rate render (decision 1444) — **benilla's own CVar**, no 1.12
-    // counterpart: the reference draws its doll inside the main pass (no second view exists to
-    // rate-limit), while our RTT booths (1069) re-run the render graph per pane per frame. "1" =
-    // the doll renders at half the frame rate while its pane is open; the knob is
-    // [`crate::portrait::PaneRate`], and the default mirrors it (welded below).
-    //
-    // **Default ON (half-rate) — restored by 1607.** 1444 shipped it on; 1559 turned it off for
-    // a smoother doll (a look-call); the 08-25 weak-GPU perf reports (B329) measured the cost —
-    // ~1.6 ms at 1600×900, 7.6 ms at 4K, per frame while a body pane is open — and the director
-    // retested the 30 fps doll as fine. Full-rate is one `SetCVar("boothHalfRate", 0)` away.
+    // benilla's own: a body pane's doll renders at half the frame rate while the pane is open; the
+    // reference draws it in the main pass. The knob is [`crate::portrait::PaneRate`].
     ours(
         "boothHalfRate",
         "1",
         "1444/1607: benilla's own — the reference draws its doll inside the main pass and has no \
          second view to rate-limit",
     ),
-    // The select screen's memory of who you last entered the world as (decision 1622) — 1.12's
-    // own `lastCharacterIndex`, help string "Last character selected". **No host knob**: the live
-    // value is the character screen's own state ([`crate::char_select::Roster::pending_index`]),
-    // which this row only mirrors — the `statusBarText` posture, and why no observer watches it.
-    //
-    // Registered **"0"**, byte-read rather than chosen: `CVar::Register` at `0x402d93` pushes
-    // default string `0x82e570` = "0", category 4, and caches the CVar* at `[0x882674]`. The value
-    // is a **0-based** row (the engine's selection cell `[0x83856c]` under `"%d"`), so "0" is the
-    // FIRST character and not a "no memory" sentinel — which is exactly why a stock `Config.wtf`
-    // has no such line until you have played somebody other than your first character
-    // (`SaveConfig 0x63d980` skips values equal to their default; [`Cvars::compose`] does the same).
-    // Multisample antialiasing — 1.12's own `gxMultisample`, registered at `0x63a950` with help
-    // "multisample antialiasing" and flags `3` = registered | **latched**. The knob is
-    // [`benilla_world::view::MsaaSetting`], read once at the world camera's spawn; its doc carries
-    // the full derivation.
-    //
-    // **Default "1" — off — and BYTE-DERIVED, unusually indirectly.** The reference registers no
-    // literal here: the default string is `snprintf("%d")`'d at runtime from field 21 of the
-    // `VideoHardware.dbc` row `DetectHardware` (`0x641260`) matched the GPU to. Across the shipped
-    // 193-row table that field only ever holds 1 (144 rows) or 2 (49 rows), and the three rows the
-    // fallback match can reach all hold 1 — so on any GPU the 2004-era table does not list, which
-    // is every machine this client runs on now, the registered string is "1". A 1 is genuinely no
-    // multisampling on both of its backends, not a one-sample mode. (Decision 1629.)
-    //
-    // Latched means a change is PENDING until the next launch — the reference's own callback
-    // echoes "set pending gxRestart" — so this row persists and `GetCVar` answers it, while the
-    // camera keeps what it was born with. `$WOW_MSAA` overrides it session-only, below.
+    // `gxMultisample` (`0x63a950`, flags 3). The reference formats its default from field 21 of the
+    // `VideoHardware.dbc` row `DetectHardware` (`0x641260`) matches, which is 1, no multisampling,
+    // on every fallback row a modern GPU reaches. The knob is [`benilla_world::view::MsaaSetting`],
+    // read once at the camera's spawn; `$WOW_MSAA` overrides it for the session.
     same("gxMultisample", "1").latched(),
-    // The multisample triple's other two thirds. The reference's Video dropdown formats all three
-    // into one row (`MULTISAMPLING_FORMAT_STRING` = "%d-bit color %d-bit depth %dx multisample")
-    // and `GetCurrentMultisampleFormat 0x48c580` looks up all three by name to find which row is
-    // selected — so without these registered that lookup can never match and the dropdown would
-    // sit on entry 1 forever.
-    //
-    // **They describe, they do not steer.** benilla does not offer a colour or depth format to
-    // choose: every format `benilla_world::view::MsaaFormats` publishes carries the same pair,
-    // derived from the swapchain format and `Depth32Float`. `SetMultisampleFormat` writes them
-    // from the chosen entry exactly like `0x48c640` does, which is a no-op in value and the right
-    // shape to keep. The defaults here are the literals that pair matches on every target we ship;
-    // if a target ever disagrees the dropdown's own row wins, because it is written from the live
-    // enumeration.
+    // `GetCurrentMultisampleFormat 0x48c580` looks up all three of the Video dropdown's values by
+    // name, so these must exist. They describe the swapchain's own pair and steer nothing;
+    // `SetMultisampleFormat` writes them as `0x48c640` does.
     deviates(
         "gxColorBits",
         "32",
@@ -1011,27 +559,15 @@ pub(crate) const REGISTERED: &[Registered] = &[
         "1643: as `gxColorBits` — the depth half of the same descriptive pair",
     )
     .latched(),
-    // **The texture filter policy** — 1.12's own `trilinear` and `anisotropic`, over
-    // `benilla_assets::TexFilterSetting`. The defaults are the reference's registered strings, and
-    // benilla had neither CVar: it hardcoded trilinear + aniso 8 at every sampler it built, which
-    // is mode 5 — the *top* of what these two can ask for — shipped as the thing you get before
-    // asking. `tex_filter.rs` carries the derivation and the cost.
+    // `trilinear` and `anisotropic`, over `benilla_assets::TexFilterSetting` (`tex_filter.rs`
+    // carries the derivation). A change applies at the next launch, since a sampler is baked into
+    // each texture at load; the reference's UI says "enabled upon restart".
+    // `$WOW_TRILINEAR`/`$WOW_ANISO` override for the session.
     //
-    // Latched, exactly like `gxMultisample` above and for a harder reason: a sampler is baked into
-    // the `Image` at load and lives in the uploaded texture, so a live change would mean rebuilding
-    // every texture in the world. The reference's own UI says "enabled upon restart".
-    // `$WOW_TRILINEAR` / `$WOW_ANISO` override session-only, below.
-    // **`trilinear` registers "1", not the registrar's "0"** (decision 1645, correcting 1642).
-    // The reference's `CVar::Register` string is `"0"`, but `hwDetect` — registered `"1"` — runs
-    // `DetectHardware 0x641260` at boot and `CVar::Set`s sixteen video CVars from the matched
-    // `VideoHardware.dbc` row before the first frame, then self-clears. Every GPU this client runs
-    // on is unlisted in a 2004 table, so the row is the fallback scan's, whose reachable set is
-    // exactly rows 168/169/170 — and `trilinear` is 1 on 169 and 170, at both CPU tiers, with no
-    // CPU bias term. Measured as well as derived: the reference's own `WoW/Logs/gx.log` reads
-    // `VID: 106b` → `DID: 2` → `videoID: 170`.
-    //
-    // This is the same shape as `gxMultisample` above, which also registers the value the hardware
-    // table yields rather than a literal the registrar never emits on a modern machine.
+    // `trilinear` registers "0", but `hwDetect` runs `DetectHardware 0x641260` and sets it from the
+    // matched `VideoHardware.dbc` row before the first frame; the fallback rows an unlisted GPU
+    // reaches are 168/169/170, and 169 and 170 give 1. The reference install's `gx.log` resolves to
+    // videoID 170.
     overridden(
         "trilinear",
         "1",
@@ -1040,21 +576,13 @@ pub(crate) const REGISTERED: &[Registered] = &[
          that field is 1 on both fallback rows an unlisted modern GPU can reach — measured on the \
          reference's own `Logs/gx.log` (`videoID: 170`)",
     ),
-    // `anisotropic` registers `"1"` — off — and here the registrar's string IS the answer: it is
-    // **not** one of `hwDetect`'s sixteen (scan of `[0x639a60, 0x639b80)`: sixteen record-pointer
-    // reads, `0xc7f2e4` absent), so nothing overwrites it on any path.
+    // Not one of `hwDetect`'s sixteen (`[0x639a60, 0x639b80)` never reads `0xc7f2e4`), so the
+    // registered "1", off, stands.
     same("anisotropic", "1"),
-    // **Weather Intensity** — the video panel's slider 9 (`OptionsFrame.lua:29`,
-    // `func = "weatherDensity"`, a real CVar name rather than an engine binding), and the nearest
-    // of 2177 §10's named-not-done: benilla has had the feature since 0310 and only the switch was
-    // missing. The reader is `benilla_world::weather::WeatherState::weather_density`, which scales
-    // the rain/snow/mist spawn rate through the reference's own `0x67b870` quality table
-    // {0.1, 0.33, 0.66, 1.0}. Rendering only — it never touches the wire grade, the two ramp
-    // channels, or the storm/fog blend, so no server-visible behaviour rides it.
-    //
-    // The reference registers **`"2"`** at `0x67b806` (flags 0, callback `0x67b870`, name string
-    // `0x8685ac`), and this row is among the twelve the reference install's `Config.wtf` moves off
-    // its default.
+    // Weather Intensity (`OptionsFrame.lua:33`), registered "2" (`0x67b806`, flags 0, callback
+    // `0x67b870`, name `0x8685ac`). The reader is `benilla_world::weather::WeatherState`, which
+    // scales the precipitation spawn rate by `0x67b870`'s table {0.1, 0.33, 0.66, 1.0}; rendering
+    // only.
     deviates(
         "weatherDensity",
         "3",
@@ -1066,68 +594,39 @@ pub(crate) const REGISTERED: &[Registered] = &[
          side-by-side is correct at, and the registered 2 would thin every rate to 0.66 against \
          the only client we compare with. The slider is how a player takes it back down",
     ),
-    // **Brightness** (decision 2182) — the reference's `gamma`, registered at `0x402d70` with
-    // name `0x82e924` `"Gamma"`, default string `0x82e92c` **`"1.0"`** and flags **0** (not
-    // latched, so its change callback `0x4034d0` applies on the write).
-    //
-    // There the callback builds `ramp[i] = __ftol(pow(i · 1/255, gamma) · 65535)` (`0x591680`) and
-    // hands the 3×256 words to `GDI32!SetDeviceGammaRamp` — and **skips the upload windowed**
-    // (`byte[dev+0x20b]` = `CGxFormat +0x07` = `gxWindow`), which is every mode benilla has. So the
-    // reader here is not a ramp upload: it is [`crate::ui_gamma::DisplayGamma`], the same curve
-    // applied to the same values one stage later, inside the pass that already owns the composited
-    // image's single decode.
-    //
-    // 1.0 is the identity ramp — load-bearing rather than tidy: at the default this client's
-    // output is what it was before the setting existed, so no visual golden moves.
-    //
-    // **Written `"1.000000"` rather than `"1.0"` or `"1"`, and that is not cosmetic.** Every value
-    // this key ever receives comes through `SetGamma 0x4891f0`, whose
-    // `SStrPrintf(buf, 0x10, "%f", …)` is six decimals — so the row that Restore Defaults produces
-    // is `"1.000000"`, and a default
-    // string in any other spelling would make it compare *moved* and write a `config.toml` line
-    // holding the default value. The slider rows dodge this with their own trailing-zero strip
-    // (`OptionsSlider_OnValueChanged`); a row whose store is an engine verb cannot, because the
-    // verb owns the formatting. So the table speaks the verb's spelling instead, and
-    // [`sync_cvars`] seeds it the same way. `Same` is still exact: the test parse-compares, and
-    // the reference registers this value as `"1.0"` (`0x82e92c`).
+    // `gamma` (`0x402d70`: name `0x82e924` "Gamma", default `0x82e92c` "1.0", flags 0, callback
+    // `0x4034d0`). The reference uploads `pow(i/255, gamma)` (`0x591680`) through
+    // `SetDeviceGammaRamp`, except when windowed (`byte[dev+0x20b]`). Deviation: benilla, which
+    // has no exclusive mode, applies the same curve in the composite pass
+    // ([`crate::ui_gamma::DisplayGamma`]), because the skipped upload would make a slider that
+    // moves no pixel. Spelled "1.000000" because `SetGamma 0x4891f0` formats with `"%f"`, and
+    // Restore Defaults must compare equal to the default; [`sync_cvars`] seeds it the same way.
     same("gamma", "1.000000"),
-    // **Render scale** (decision 1639) — benilla's own CVar, no 1.12 counterpart, in the
-    // `boothHalfRate` / `SoundOutputLimiter` mould: the reference has no such dial because it has
-    // no second buffer to hang one on. The world renders into the composite lane's off-screen image
-    // at `window × this` while the UI stays at native resolution; the knob is
-    // [`crate::world_backdrop::RenderScale`], clamped to its `RENDER_SCALE_RANGE`.
-    //
-    // The era's nearest equivalent is `gxResolution`, which drops the interface along with the
-    // world and, in fullscreen, mode-sets the display — the thing 1627 deliberately stopped doing.
-    //
-    // Default "1" is off, and that is load-bearing rather than cautious: at 1.0 the lane reproduces
-    // its pre-1639 numbers bit-for-bit, so no visual golden in the tree moves. `$WOW_RENDER_SCALE`
-    // overrides it session-only, below.
+    // benilla's own: the world renders at `window × this` while the UI stays native. The knob is
+    // [`crate::world_backdrop::RenderScale`], clamped to `RENDER_SCALE_RANGE`; at "1" nothing is
+    // resampled. `$WOW_RENDER_SCALE` overrides it for the session.
     ours(
         "renderScale",
         "1",
         "1639: benilla's own — the reference has no off-screen buffer to hang a resolution dial \
          on; its nearest equivalent, `gxResolution`, drops the interface with the world",
     ),
-    // **The FPS journal** (decision 2008) — benilla's own, and the one instrument that ships:
-    // `/console fpsJournal 1` appends a per-second row of position, frame cost and the GPU's
-    // per-pass split to `benilla-config/Diagnostics/fps-journal.csv` in any build, which is how
-    // a player on hardware we do not own measures for us. The knob is
-    // [`crate::perf::FpsJournalSetting`]. Off by default; persisted like every row, so a
-    // reporter who turns it on keeps it on until they turn it off — the file is theirs to
-    // attach and theirs to delete.
+    // benilla's own: `/console fpsJournal 1` appends a per-second row of position, frame cost and
+    // per-pass GPU time to `benilla-config/Diagnostics/fps-journal.csv`. The knob is
+    // [`crate::perf::FpsJournalSetting`].
     ours(
         "fpsJournal",
         "0",
         "2008: benilla's own — 1.12 has no player-side perf log; its nearest thing is the \
          Ctrl+R framerate label, a number with no file behind it",
     ),
+    // `lastCharacterIndex` (`0x402d93`, "0" `0x82e570`, category 4, handle `[0x882674]`), help
+    // "Last character selected": a 0-based row (the selection cell `[0x83856c]` under `"%d"`), so
+    // "0" is the first character. It mirrors [`crate::char_select::Roster::pending_index`].
     same(crate::char_select::CVAR_LAST_CHARACTER, "0"),
 ];
 
-/// `config.toml`'s shape: a `[cvars]` table of `Name = "value"` strings (CVars are strings in
-/// the reference too; consumers parse and clamp at their edge). BTreeMap so the file is stably
-/// sorted on every save.
+/// `config.toml`: a `[cvars]` table of `Name = "value"` strings, sorted so every save is stable.
 #[derive(serde::Serialize, serde::Deserialize, Default)]
 struct LocalConfig {
     #[serde(default)]
@@ -1136,14 +635,8 @@ struct LocalConfig {
 
 // ─── The registry ────────────────────────────────────────────────────────────────────────────
 
-/// **One accepted move of a CVar's applied value** — the reference's change callback, as the
-/// Bevy event it is (decision 2303). Triggered by the registry's flushers for every write that
-/// changed a row's applied value (a Lua `SetCVar`, a `/console` line, a host write, a committed
-/// latch, and the loaded file at boot); observed by the subsystem that owns the knob, beside the
-/// knob, writing only its own resource.
-///
-/// Not fired for a write that changed nothing, for a staged (latched) value, or for a session
-/// override taking a row (the knob already read the env).
+/// An accepted move of a CVar's applied value: the reference's change callback, as a Bevy event.
+/// Not fired for a no-op write, a staged latched value, or a session override.
 #[derive(Event, Clone, Debug, PartialEq, Eq)]
 pub(crate) struct CvarChanged {
     /// The registered spelling (`MasterVolume`).
@@ -1158,14 +651,13 @@ impl CvarChanged {
         self.name.eq_ignore_ascii_case(name)
     }
 
-    /// The lowercased name — what an observer's `match` arms are spelled in.
+    /// The lowercased name, as observers' `match` arms spell it.
     pub(crate) fn key(&self) -> String {
         self.name.to_ascii_lowercase()
     }
 
-    /// The new value as a number. **The registry refuses an unparseable write to a numeric
-    /// row** ([`Cvars::set`]), so on a row whose default is a number this is never a fallback;
-    /// on a string row it is `0`, and an observer for a string row reads [`Self::new`] instead.
+    /// The new value as a number; `0` on a string row, whose observer reads [`Self::new`]. The
+    /// registry refuses an unparseable write to a numeric row ([`Cvars::set`]).
     pub(crate) fn num(&self) -> f32 {
         self.new.trim().parse().unwrap_or(0.0)
     }
@@ -1176,27 +668,25 @@ impl CvarChanged {
     }
 }
 
-/// One row of the live registry — the reference's `CVar` record, the parts benilla keeps.
+/// One row of the live registry: the parts of the reference's `CVar` record benilla keeps.
 #[derive(Clone, Debug)]
 pub(crate) struct Row {
     /// The registered spelling.
     pub(crate) name: String,
     pub(crate) default: String,
-    /// The **applied** value: what `GetCVar` answers and what the file is composed from.
+    /// The applied value: what `GetCVar` answers and what the file is composed from.
     pub(crate) value: String,
     /// A latched row's staged value (`rec+0x38`), applied by [`Cvars::commit_latched`].
     pub(crate) pending: Option<String>,
-    /// [`Registered::latched`] — the reference's flag bit1.
+    /// The reference's flag bit1.
     pub(crate) latched: bool,
-    /// Declared by an addon's `RegisterCVar` rather than by [`REGISTERED`] (decision 1195): it
-    /// persists like any other row, and it is re-seeded into every later VM so the addon's own
-    /// re-declaration finds it and no-ops.
+    /// Declared by an addon's `RegisterCVar`: persisted like any row and re-seeded into every later
+    /// VM, so the addon's re-declaration is a no-op.
     pub(crate) addon: bool,
 }
 
 impl Row {
-    /// A row whose default parses as a number holds numbers — the registry refuses a write
-    /// that does not parse ([`Cvars::set`]), so a numeric observer can trust [`CvarChanged::num`].
+    /// A row whose default parses as a number refuses a write that does not ([`Cvars::set`]).
     fn numeric(&self) -> bool {
         self.default.trim().parse::<f32>().is_ok()
     }
@@ -1207,7 +697,7 @@ impl Row {
 pub(crate) enum SetOutcome {
     /// No such row (warned).
     Unknown,
-    /// A numeric row, and the value does not parse — refused, the applied value stands (warned).
+    /// A numeric row and a value that does not parse: refused, the applied value stands (warned).
     Refused,
     /// Already the applied value (or already the staged one).
     Unchanged,
@@ -1217,30 +707,21 @@ pub(crate) enum SetOutcome {
     Changed,
 }
 
-/// **The registry** — the engine-side CVar table. See the module doc.
+/// The engine-side CVar table.
 #[derive(Resource)]
 pub(crate) struct Cvars {
     rows: Vec<Row>,
     /// Lowercased name → row.
     index: HashMap<String, usize>,
-    /// The file's `[cvars]` entries, verbatim spelling — the merge base every save starts from:
-    /// unknown keys ride through untouched, session-owned keys keep their stored value.
+    /// The file's `[cvars]` entries in their own spelling, the merge base of every save.
     file: BTreeMap<String, String>,
-    /// Lowercased names this SESSION owns rather than the player — never saved, and the file's
-    /// own entry for them is left exactly as it was found.
-    ///
-    /// Almost all of them are env levers (`$WOW_UI_SCALE`, `$WOW_MSAA`, `$WOW_HOST`, …): a value
-    /// that stuck in `config.toml` would make an A/B or an instrument run sticky across
-    /// relaunches. `gxApi` (2151) is the member that is not — it is owned by the session because
-    /// it is a fact about the *machine* (the render adapter's backend), which is nobody's setting
-    /// to persist.
+    /// Lowercased names the session owns rather than the player: the env levers, and `gxApi`, the
+    /// render backend. Never saved; the file's entry is left as found.
     session_owned: HashSet<String>,
-    /// Accepted moves not yet triggered — flushed by [`sync_cvars`] every frame, synchronously by
-    /// the boot load and the session-edge fold, and by any caller that wants its observers to
-    /// have run before its own dependents ([`Cvars::take_events`]).
+    /// Accepted moves not yet triggered, flushed by [`sync_cvars`], the boot load, the session-edge
+    /// fold, or a caller of [`Cvars::take_events`].
     events: Vec<CvarChanged>,
-    /// Host-side writes the VM's mirror has not seen yet — pushed by [`sync_cvars`] as host
-    /// writes (no echo). Cleared by a seed, which carries the whole table anyway.
+    /// Host-side writes the VM's mirror has not seen; cleared by a seed.
     outbox: Vec<(String, String)>,
     /// A change since the last save; `last_change` drives the one-quiet-second debounce.
     dirty: bool,
@@ -1299,33 +780,28 @@ impl Cvars {
         self.rows.iter()
     }
 
-    /// The applied value.
     pub(crate) fn get(&self, name: &str) -> Option<&str> {
         self.row(name).map(|r| r.value.as_str())
     }
 
-    /// The applied value as a number, `None` for an unknown row or a non-numeric value.
     pub(crate) fn num(&self, name: &str) -> Option<f32> {
         self.get(name).and_then(|v| v.trim().parse().ok())
     }
 
-    /// The applied value as the client's flag (int-parse, `!= 0`), `None` for an unknown row.
+    /// The applied value as the client's flag (int-parse, `!= 0`).
     pub(crate) fn flag(&self, name: &str) -> Option<bool> {
         self.num(name).map(|v| v != 0.0)
     }
 
-    /// The registered default.
     pub(crate) fn default_of(&self, name: &str) -> Option<&str> {
         self.row(name).map(|r| r.default.as_str())
     }
 
-    /// Whether this session owns the row rather than the player.
     pub(crate) fn is_session_owned(&self, name: &str) -> bool {
         self.session_owned.contains(&name.to_ascii_lowercase())
     }
 
-    /// The persisted `checkAddonVersion` (decision 1292) — what the addon load walk gates on.
-    /// The registrar default is check ON.
+    /// The persisted `checkAddonVersion` the addon load walk gates on; registered on.
     pub(crate) fn addon_version_check(&self) -> bool {
         self.flag("checkAddonVersion").unwrap_or(true)
     }
@@ -1335,9 +811,8 @@ impl Cvars {
         self.last_change = Some(Instant::now());
     }
 
-    /// The write, from either side of the VM boundary. `from_vm` is a write the mirror has
-    /// already made (a Lua `SetCVar`, `ConsoleExec`, an engine verb), so it is not echoed back;
-    /// a refusal IS pushed back, because the mirror stored what this refused.
+    /// A write from either side of the VM boundary. A `from_vm` write is not echoed back, but a
+    /// refusal is, because the mirror already stored the refused value.
     fn write(&mut self, name: &str, value: &str, from_vm: bool) -> SetOutcome {
         let Some(i) = self.slot(name) else {
             warn!("cvar {name}: not registered — write ignored");
@@ -1355,13 +830,9 @@ impl Cvars {
             return SetOutcome::Refused;
         }
         if row.latched {
-            // The reference's `Set 0x63df50` on flag bit1: `latchedValue` takes the string and
-            // `InternalSet` does not run — no dirty, no callback. Staging the applied value
-            // back clears the stage.
-            // The stage lives HERE, not in the mirror: the VM only ever learns applied values
-            // (a host write into the mirror IS a commit there), so a host-side stage is not
-            // echoed — `GetCVar` keeps answering the applied value either way, and the commit
-            // below is what reaches the VM.
+            // The reference's `Set 0x63df50` on flag bit1 stores `latchedValue` and skips
+            // `InternalSet`: no dirty, no callback. The stage lives here, not in the mirror, which
+            // only ever learns applied values.
             let staged = (value != row.value).then(|| value.to_string());
             if row.pending == staged {
                 return SetOutcome::Unchanged;
@@ -1390,24 +861,21 @@ impl Cvars {
         SetOutcome::Changed
     }
 
-    /// **A host-side write** — the counterpart of a Lua `SetCVar`, for the engine's own values:
-    /// the minimap zoom, the camera views, the remembered character, the loading screen's tip
-    /// cursor. Mirrored into the VM, persisted, and observed like any other write.
+    /// A host-side write (minimap zoom, camera views, the remembered character, the tip cursor):
+    /// mirrored into the VM, persisted and observed.
     pub(crate) fn set(&mut self, name: &str, value: &str) -> SetOutcome {
         self.write(name, value, false)
     }
 
-    /// A write the VM's mirror already made — drained from its change queue.
+    /// A write the VM's mirror already made, drained from its change queue.
     pub(crate) fn set_from_vm(&mut self, name: &str, value: &str) -> SetOutcome {
         self.write(name, value, true)
     }
 
-    /// **The table follows a value the engine already applied** — a mirror, not a write: the
-    /// applied value moves, the config dirties, the VM's mirror learns it, and **no observer
-    /// fires**, because the knob is already there. For a second registered spelling of one knob
-    /// (`WorldDetail`/`frillDensity`, 2151) — an observer that answered its sibling's move with a
-    /// full write would queue an event that lands one flush later, by which time the row may
-    /// have moved again, and the stale event would win. Returns whether the row moved.
+    /// Follow a value the engine already applied, for a second spelling of one knob
+    /// (`WorldDetail`/`frillDensity`): the row moves, persists and reaches the mirror, but no
+    /// observer fires, since a full write would queue an event that lands a flush late and wins
+    /// stale. Returns whether the row moved.
     pub(crate) fn mirror(&mut self, name: &str, value: &str) -> bool {
         let Some(i) = self.slot(name) else {
             warn!("cvar {name}: not registered — mirror ignored");
@@ -1424,20 +892,15 @@ impl Cvars {
         true
     }
 
-    /// **The latch boundary `RestartGx` crosses** — the reference's `0x639ec0`, fourteen
-    /// `CVar::Commit 0x63e060` calls on fourteen gx records (`[0xc4ea90]` … `[0xc4eab4]`,
-    /// `0x639ec0..0x639f5a`): each of THOSE staged values becomes the applied one, fires,
-    /// persists, and reaches the mirror. Returns how many moved.
+    /// The latch boundary `RestartGx` crosses: the reference's `0x639ec0..0x639f5a`, which calls
+    /// `CVar::Commit` (`0x63e060`) on the fourteen gx records `[0xc4ea90]` … `[0xc4eab4]`. Each
+    /// staged `gx*` value is applied, fires, persists and reaches the mirror; returns how many
+    /// moved.
     ///
-    /// **Only the `gx*` rows.** A latched row outside the video set is not on that list and
-    /// nothing else commits it: `SoundBufferSize`'s register site (`0x4571ca`) discards the
-    /// record pointer `0x63db90` returns, so no global holds it for any commit to name. It
-    /// holds its stage until exit and loses it there, as the reference's does. Until 2343 this
-    /// walked every row, and a console `SoundBufferSize` rode the next video Okay into the file.
-    ///
-    /// The reference runs a gx CVar's change callback at `SetCVar` time (`0x63df50`), and the
-    /// commit fires nothing; our observers fire here instead. Nothing reads the difference
-    /// today — the appliers are the device rebuild's, and that runs after this boundary.
+    /// Only `gx*` rows: `SoundBufferSize`'s register site (`0x4571ca`) discards its record, so
+    /// nothing commits it and its stage is lost at exit, as in the reference. The reference runs a
+    /// gx callback at `SetCVar` time (`0x63df50`); ours fire here, before the device rebuild reads
+    /// them.
     pub(crate) fn commit_latched(&mut self) -> usize {
         let mut moved = 0;
         for row in &mut self.rows {
@@ -1465,10 +928,9 @@ impl Cvars {
         moved
     }
 
-    /// **This session owns the row**: an env lever or the machine's own fact took it, so it is
-    /// never saved and the file's entry for it is left alone. `value` is what the row answers
-    /// this session — `None` marks the row without moving it (the resource is absent, so the
-    /// registered default is the truth). No observer fires: the knob already read the env.
+    /// The session owns this row: it is never saved and the file's entry is left alone. `value` is
+    /// what it answers this session; `None` marks it without moving it. No observer fires: the knob
+    /// already read the env.
     pub(crate) fn own_for_session(&mut self, name: &str, value: Option<&str>) {
         let key = name.to_ascii_lowercase();
         self.session_owned.insert(key.clone());
@@ -1487,10 +949,8 @@ impl Cvars {
         }
     }
 
-    /// An addon's `RegisterCVar` (decision 1195), reported by the VM: a row of its own, starting
-    /// at the file's value for that name when it carries one (the 1291 bridge, now on the store
-    /// that survives the VM), else at the declared default. A name already registered — the
-    /// client's own, or the same addon's earlier declaration — is the no-op it always was.
+    /// An addon's `RegisterCVar`: a row of its own at the file's value for the name, else at the
+    /// declared default. A name already registered is a no-op.
     pub(crate) fn learn_addon_row(&mut self, name: &str, default: &str) {
         if self.slot(name).is_some() {
             return;
@@ -1510,11 +970,9 @@ impl Cvars {
         });
     }
 
-    /// Fold the file in: every known, player-owned key becomes its row's applied value (an
-    /// accepted move, so the observers hear it — the reference's `Register` on a record
-    /// `Config.wtf` already created calls the callback with the file's value); an unknown key is
-    /// preserved for the save and warned once; a session-owned key is skipped and the file keeps
-    /// it. Loading is not a change: nothing is dirtied.
+    /// Fold the file in: a known, player-owned key becomes its row's applied value and fires (the
+    /// reference's `Register` on a record `Config.wtf` created calls the callback); an unknown key
+    /// is kept for the save and warned; a session-owned one is skipped. Nothing dirties.
     fn load_file(&mut self, file: BTreeMap<String, String>) {
         for (name, value) in &file {
             let key = name.to_ascii_lowercase();
@@ -1544,9 +1002,8 @@ impl Cvars {
         self.file = file;
     }
 
-    /// The file's entries no row claims — a newer build's keys, or an addon's before it
-    /// registers them this session. Handed to the VM as its saved base, so an addon's
-    /// `RegisterCVar` starts at the player's value (decision 1291).
+    /// The file's entries no row claims: a newer build's keys, or an addon's not yet registered.
+    /// Handed to the VM as its saved base, so an addon's `RegisterCVar` starts at the saved value.
     pub(crate) fn orphans(&self) -> Vec<(String, String)> {
         self.file
             .iter()
@@ -1568,13 +1025,12 @@ impl Cvars {
             .collect()
     }
 
-    /// Whether a flush has something to trigger — read before taking, so a quiet frame never
-    /// deref-muts the registry.
+    /// Read before taking, so a quiet frame never deref-muts the registry.
     pub(crate) fn has_events(&self) -> bool {
         !self.events.is_empty()
     }
 
-    /// The accepted moves since the last flush — the caller triggers each one.
+    /// The accepted moves since the last flush, for the caller to trigger.
     pub(crate) fn take_events(&mut self) -> Vec<CvarChanged> {
         std::mem::take(&mut self.events)
     }
@@ -1587,10 +1043,9 @@ impl Cvars {
         std::mem::take(&mut self.outbox)
     }
 
-    /// Compose the file to save: the previous file as the merge base, every row that moved off
-    /// its default written (the **applied** value — a staged one is not the player's setting
-    /// yet), every one back at its default removed — session-owned keys and unknown keys
-    /// untouched.
+    /// The file to save: the previous file as the merge base, each row off its default at its
+    /// applied value (a staged one is not the player's yet), each at its default removed;
+    /// session-owned and unknown keys untouched.
     fn compose(&self) -> BTreeMap<String, String> {
         let mut out = self.file.clone();
         for row in &self.rows {
@@ -1617,9 +1072,7 @@ impl Cvars {
         out
     }
 
-    /// A registry that already holds one stored value — a launch whose `config.toml` said so,
-    /// without a file. For the tests that drive a real consumer over a real remembered row
-    /// (`char_select`'s restore test) rather than a copy of its logic.
+    /// A registry already holding one stored value, as if `config.toml` said so.
     #[cfg(test)]
     pub(crate) fn with_value(name: &str, value: &str) -> Self {
         let mut cvars = Self::default();
@@ -1629,24 +1082,12 @@ impl Cvars {
     }
 }
 
-/// How long a dirty config sits before the save fires — long enough to coalesce a slider drag,
-/// short enough that a crash loses one gesture, not a session ("write-on-change, debounced").
+/// How long a dirty config waits before saving: long enough to coalesce a slider drag.
 const SAVE_QUIET: std::time::Duration = std::time::Duration::from_secs(1);
 
-/// The startup fold of `config.toml` into the registry and, through the observers, the knobs
-/// ([`load_config`]).
-///
-/// A set rather than a bare system because one knob is **read once and never again**: the world
-/// camera takes its `Msaa` at spawn (decision 1629, the reference's latched `gxMultisample`), so
-/// `setup_player` must not be able to run before the file has been folded in. Every other knob is
-/// live-read and does not care.
-///
-/// This removes a **race, not an observed bug**. Measured: with the constraint deleted, a
-/// `gxMultisample = "4"` in `config.toml` still reached the camera — and it did so despite
-/// `PlayerPlugin` being added *before* `CvarPlugin` (`lib.rs`), i.e. the order that happened to
-/// hold was the executor's choice out of an unconstrained graph, not insertion order and not
-/// anything we could point at. The failure it prevents is silent (the player's setting is simply a
-/// launch late) and would surface as a bug report nobody could reproduce.
+/// The startup fold of `config.toml` into the registry and the knobs ([`load_config`]). A set
+/// because the world camera reads `gxMultisample` once at spawn, so `setup_player` must order after
+/// it; without the constraint that order is the executor's choice.
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub(crate) struct CvarLoad;
 
@@ -1661,29 +1102,19 @@ impl Plugin for CvarPlugin {
                     .chain()
                     .in_set(CvarLoad),
             )
-            // After the tick (decision 2304): a `SetCVar` the interface made this frame reaches
-            // the registry — and its observers — before the frame's drains read it. The video
-            // window's Okay is the case: `SetCVar` per changed row, then `RestartGx()`, in one
-            // handler; `video::drain_restart_gx` orders after this so the commit finds the stage.
+            // After the tick, so a `SetCVar` from this frame reaches the registry and its observers
+            // before the frame's drains; `video::drain_restart_gx` orders after this so the commit
+            // finds the stage.
             .add_systems(Update, sync_cvars.after(crate::ui_script::UiInput));
-        // **The flush is on the exit edge, not beside its feed** (decision 1528). It used to be
-        // `(sync_cvars, save_config).chain()` in `Update`, which made the "or the app exiting"
-        // half of its own gate dead on the exit a player actually causes: the close button's
-        // `AppExit` is not written until `PostUpdate`, so the last second of slider drags went
-        // with the process. `Last` still runs after `sync_cvars` — schedule order does what the
-        // `.chain()` did — and now also after every announcement.
+        // The save runs on the exit edge: the close button's `AppExit` is written in `PostUpdate`,
+        // and `Last` still runs after `sync_cvars`.
         crate::shutdown::on_app_exit(app, save_config.into_configs());
     }
 }
 
-/// **What the environment took for this session, and what it set it to** — read off the knobs
-/// the env levers already seeded (`RenderScale::default()` reads `$WOW_RENDER_SCALE`, and so
-/// on), so the registry answers `GetCVar` with the value the client is actually running at.
-///
-/// This is the (iv) residue 2265 named: each lever here is one the env still reaches through a
-/// resource's `Default` rather than through a `category: debug` row of this table, and each
-/// line goes the day its lever does. A lever whose resource is absent (a stripped test app)
-/// still marks its row session-owned — the file must not apply over an env the caller set.
+/// What the environment took for this session and its value, read off the knobs the env levers
+/// seeded (`RenderScale::default()` reads `$WOW_RENDER_SCALE`, …). A lever whose resource is absent
+/// still marks its row, so the file cannot apply over the env.
 fn session_values(world: &World) -> Vec<(&'static str, Option<String>)> {
     let set = |k: &str| std::env::var_os(k).is_some();
     let flag = |b: bool| if b { "1" } else { "0" }.to_string();
@@ -1696,24 +1127,16 @@ fn session_values(world: &World) -> Vec<(&'static str, Option<String>)> {
         let v = world.get_resource::<benilla_world::view::ViewDistance>();
         out.push(("farclip", v.map(|s| s.farclip.to_string())));
     }
-    // The clutter A/B env drives the same knob WorldDetail lands on — same session-only law, over
-    // BOTH of that knob's spellings ([`CLUTTER_DENSITY_CVARS`]). An off-grid multiplier seeds
-    // off-grid honestly: the dropdown shows the raw number and checks nothing (the 0959
-    // out-of-range posture, dropdown-flavored).
+    // The clutter lever takes both spellings of its knob; an off-grid multiplier seeds off-grid.
     if set("WOW_CLUTTER_DENSITY") {
         let v = world.get_resource::<benilla_world::clutter::ClutterConfig>();
         out.push(("WorldDetail", v.map(|c| (c.density - 1.0).to_string())));
         out.push(("frillDensity", v.map(|c| c.frill_density().to_string())));
     }
-    // `$WOW_NOVSYNC=1` is the measurement uncap: session-only, exactly like the taste-iteration
-    // overrides above. Pinning it into the config would make an instrument run sticky.
     if crate::video::novsync_env() {
         let v = world.get_resource::<crate::video::VideoConfig>();
         out.push(("gxVSync", v.map(|c| flag(c.vsync))));
     }
-    // The filter policy's A/B levers, under the same law: pricing mode 3 against mode 5 on one
-    // machine in one session is exactly what these are for, and a value that stuck in
-    // `config.toml` would silently denominate every later reading.
     let tex = world.get_resource::<benilla_assets::TexFilterSetting>();
     if set("WOW_TRILINEAR") {
         out.push(("trilinear", tex.map(|t| flag(t.trilinear))));
@@ -1721,9 +1144,7 @@ fn session_values(world: &World) -> Vec<(&'static str, Option<String>)> {
     if set("WOW_ANISO") {
         out.push(("anisotropic", tex.map(|t| t.aniso.to_string())));
     }
-    // `$WOW_WIN`, a capture scenario, or any instrumented run owns the window's geometry for the
-    // session (decision 1627), so the two CVars that would otherwise move it mid-run are
-    // session-only under exactly the same law as the levers above.
+    // `$WOW_WIN`, a capture scenario or an instrumented run owns the window geometry.
     if crate::video::windowed_env() {
         let v = world.get_resource::<crate::video::VideoConfig>();
         out.push((
@@ -1735,10 +1156,7 @@ fn session_values(world: &World) -> Vec<(&'static str, Option<String>)> {
             v.map(|c| format!("{}x{}", c.windowed.x, c.windowed.y)),
         ));
     }
-    // `$WOW_MSAA` is the multisampling A/B lever (1629); `$WOW_RENDER_SCALE` the render-scale one
-    // (1639), doubly session-only because it is also the supersampling instrument this machine
-    // prices pixels with, and an instrument run that pinned 4× into the file would come back at
-    // 4× the next time the client opened.
+    // The multisampling and render-scale levers: an instrument run must not pin 4× into the file.
     if set("WOW_MSAA") {
         let v = world.get_resource::<benilla_world::view::MsaaSetting>();
         out.push(("gxMultisample", v.map(|m| m.samples.to_string())));
@@ -1747,9 +1165,7 @@ fn session_values(world: &World) -> Vec<(&'static str, Option<String>)> {
         let v = world.get_resource::<crate::world_backdrop::RenderScale>();
         out.push(("renderScale", v.map(|r| r.0.to_string())));
     }
-    // `$WOW_HOST` is the realmlist for the session (1667) — every probe, smoke run and harness leg
-    // sets it, and a value pinned into the file would silently repoint the player's client at
-    // whatever a test dialed. `Realmlist::default()` has already taken it; this keeps it off disk.
+    // `$WOW_HOST` is the session's realmlist, which a test run must never write into the file.
     if set("WOW_HOST") {
         let v = world.get_resource::<crate::realmlist::Realmlist>();
         out.push((
@@ -1760,11 +1176,9 @@ fn session_values(world: &World) -> Vec<(&'static str, Option<String>)> {
     out
 }
 
-/// Startup: mark what the session owns, read `benilla-config/config.toml` (absent file = all
-/// defaults, not an error) into the registry, and **fire the observers here and now** — this is
-/// exclusive so that everything ordered after [`CvarLoad`] finds its knob already written, the
-/// way the reference's subsystems find their callback already run by the time they read a
-/// record. The VM does not exist yet; [`sync_cvars`] seeds its mirror when it does.
+/// Startup: mark what the session owns, fold `config.toml` in (no file means all defaults) and fire
+/// the observers now, so everything after [`CvarLoad`] finds its knob written. The VM does not
+/// exist yet; [`sync_cvars`] seeds its mirror.
 fn load_config(world: &mut World) {
     let session = session_values(world);
     let stored = stored_config();
@@ -1773,18 +1187,14 @@ fn load_config(world: &mut World) {
         for (name, value) in session {
             cvars.own_for_session(name, value.as_deref());
         }
-        // The one member with no env var behind it (2151): `gxApi` reports the render adapter's
-        // backend, which is a fact about the machine rather than a setting the player chose. It
-        // is pushed live by [`sync_cvars`] once the adapter exists, so persisting it could only
-        // ever write a name that the next launch overwrites — or, worse, a stale one that
-        // outlives the GPU it described.
+        // `gxApi` is the render backend, a fact about the machine that `sync_cvars` pushes live, so
+        // it is never persisted.
         cvars.own_for_session("gxApi", None);
         match stored {
             StoredConfig::Absent => {} // no file, hermetic capture, or no install
             StoredConfig::Bad(msg) => {
-                // A malformed file is preserved, not clobbered: nothing loads, but nothing
-                // saves over it either until a change actually happens — and the warn names
-                // the file.
+                // A malformed file is kept: nothing loads, and nothing saves over it until a
+                // change.
                 warn!("{msg}");
             }
             StoredConfig::Table(table) => cvars.load_file(table),
@@ -1798,32 +1208,20 @@ fn load_config(world: &mut World) {
 
 /// What the one read of `config.toml` found.
 enum StoredConfig {
-    /// No file, no install, or a hermetic capture — every value is its registered default.
+    /// No file, no install, or a hermetic capture: every value is its registered default.
     Absent,
-    /// The file's `[cvars]` table.
     Table(BTreeMap<String, String>),
-    /// The file is there but unreadable or malformed. The string is what [`load_config`] warns
-    /// with — carried rather than logged, because this read happens before the `App` (and so
-    /// before `LogPlugin`) exists.
+    /// Unreadable or malformed; the message is carried because this read runs before `LogPlugin`
+    /// exists.
     Bad(String),
 }
 
-/// Read `config.toml`.
-///
-/// **One parser, two callers at two different times** — [`load_config`] at `Startup`, and the
-/// primary window literal in [`crate::run`], which has to know `gxWindow`/`gxResolution` *before*
-/// the window exists ([`crate::video::boot_window_mode`] carries why booting windowed and flipping
-/// a frame later is not good enough).
-///
-/// Deliberately **not** cached in a `OnceLock`, though it was written that way first. Three reads
-/// of a sub-kilobyte file at process start is not a cost worth a global, and a process-wide cache
-/// is actively wrong: every test that lays a config down and then runs `load_config` would be
-/// answered from whatever the *first* test in the binary happened to see, and `local_state`'s home
-/// law can legitimately move under a run. The thing worth having exactly one of is this function,
-/// not its result.
+/// Read `config.toml`, for [`load_config`] and for the primary window in [`crate::run`], which
+/// needs `gxWindow`/`gxResolution` before it exists. Not cached: a process-wide cache would answer
+/// every test from the first one's file.
 fn stored_config() -> StoredConfig {
     let Some(path) = crate::local_state::config_path() else {
-        return StoredConfig::Absent; // hermetic capture, or no install — session-only state
+        return StoredConfig::Absent; // hermetic capture or no install: session-only state
     };
     let text = match std::fs::read_to_string(&path) {
         Ok(t) => t,
@@ -1839,13 +1237,8 @@ fn stored_config() -> StoredConfig {
     }
 }
 
-/// One CVar as `config.toml` holds it, matched case-insensitively — **before the `App` exists**
-/// (decision 1627).
-///
-/// Every other consumer wants [`Cvars::get`], which answers from the registry once it is a
-/// resource and stays current across a VM replacement (1291). This one exists for the
-/// single caller that cannot wait for a resource: the primary window has to be *built* with its
-/// display mode already resolved.
+/// One CVar as `config.toml` holds it, before the `App` exists: for the primary window, which is
+/// built with its display mode resolved. Everything else reads [`Cvars::get`].
 pub(crate) fn boot_cvar(name: &str) -> Option<String> {
     match stored_config() {
         StoredConfig::Table(t) => t
@@ -1856,10 +1249,8 @@ pub(crate) fn boot_cvar(name: &str) -> Option<String> {
     }
 }
 
-/// Per frame: seed the VM's mirror once it exists (the registered set at its live values, so
-/// `GetCVar` reflects env overrides and the loaded config alike), drain the VM's registrations
-/// and writes into the registry, push the registry's own writes into the mirror, and trigger
-/// every accepted move for its observers.
+/// Per frame: seed a new VM's mirror, drain its registrations and writes into the registry, push
+/// the registry's writes into the mirror, and trigger every accepted move.
 pub(crate) fn sync_cvars(
     script: Option<NonSendMut<UiScript>>,
     mut cvars: ResMut<Cvars>,
@@ -1868,9 +1259,7 @@ pub(crate) fn sync_cvars(
     mut seeded: Local<VmMemo<bool>>,
     mut commands: Commands,
 ) {
-    // **The machine's, not the player's** (2151): the live render backend, so `GetCVar` and
-    // pfUI's system tooltip answer what this run is actually on. Absent in a headless app with
-    // no renderer, where the registered `""` stands and says so.
+    // The live render backend; absent headless, where the registered `""` stands.
     if let Some(adapter) = adapter.as_deref() {
         let backend = adapter.backend.to_str();
         if cvars.get("gxApi") != Some(backend) {
@@ -1889,12 +1278,9 @@ pub(crate) fn sync_cvars(
         }
         return;
     };
-    // **The VM's writes first, the seed second.** A fresh VM loads the whole interface before
-    // this system's first turn against it, and an addon's `SetCVar` at load is already in the
-    // queue by then; seeding first would overwrite the mirror with the registry's older value
-    // and then apply the write to the registry alone, leaving `GetCVar` a frame behind for the
-    // rest of the session. Registrations before writes: an addon declares a row and sets it in
-    // the same breath.
+    // The VM's writes before the seed: an addon's `SetCVar` at load is already queued, and seeding
+    // first would overwrite the mirror with the older value. Registrations before writes, since an
+    // addon declares a row and sets it together.
     let registrations = script.take_cvar_registrations();
     let changes = script.take_cvar_changes();
     if !registrations.is_empty() || !changes.is_empty() {
@@ -1906,17 +1292,15 @@ pub(crate) fn sync_cvars(
         }
     }
     if seeded.claim(&script) {
-        // The file's unclaimed entries go in FIRST (decision 1291): an addon's `RegisterCVar`
-        // later starts its key at the saved value. Then the table itself, at its live values.
+        // The file's unclaimed entries first, so an addon's `RegisterCVar` starts at the saved
+        // value; then the table.
         script.set_cvar_saved_base(cvars.orphans());
         script.seed_cvars(cvars.vm_seed());
         if cvars.has_outbox() {
             cvars.take_outbox(); // the seed just carried everything
         }
-        // The Video dropdown's menu — what this device actually accepts, enumerated once at
-        // `finish()` by `view::MsaaSupportPlugin` (decision 1631) and handed over whole. Pushed
-        // here rather than owned by the VM because the list is a fact about the render adapter,
-        // which `benilla-ui` has no way to ask and should not grow one.
+        // The Video dropdown's menu: what this device accepts, enumerated by
+        // `view::MsaaSupportPlugin`.
         script.set_multisample_formats(
             msaa_formats
                 .as_deref()
@@ -1934,28 +1318,12 @@ pub(crate) fn sync_cvars(
                 })
                 .unwrap_or_default(),
         );
-        // **What `GetVideoCaps` answers with** (decision 2177) — the seven values the stock video
-        // window's `OptionsFrame_Load` destructures. Pushed beside the multisample list because it
-        // is the same kind of fact: what this client's device and presentation path really offer,
-        // which the VM has no way to ask.
-        //
-        // Six of the seven are properties of the client rather than of the adapter, and each is
-        // true here by construction:
-        //   * shaders — wgpu has no non-programmable path; there is no fixed-function fallback to
-        //     be missing. The reference asked because 2004 hardware could genuinely lack them.
-        //   * trilinear and anisotropy — `benilla_assets::tex_filter` builds every sampler with
-        //     both available; `ANISO_RANGE`'s top is the ceiling the `anisotropic` CVar clamps to
-        //     and is reported raw, because `OptionsFrame.lua:124` matches it against
-        //     `ANISOTROPIC_VALUES = {"1","2","4","8","16"}` with `tonumber` and ignores a value
-        //     that is not one of them.
-        //   * the hardware cursor — `crate::cursor` composites the reference's own
-        //     `Interface\Cursor\*.blp` into an OS cursor on every target (an `NSCursor` on macOS,
-        //     winit's `CursorIcon::Custom` elsewhere).
-        //   * triple buffering — **false, and it is the one that does visible work**. wgpu's
-        //     surface decides its own buffering and benilla exposes no knob, so the reference's own
-        //     `OptionsFrame_Load` hides check button 13 and re-seats button 6 against button 5
-        //     (`OptionsFrame.lua:168-175`). Answering `true` would light a checkbox writing a CVar
-        //     nothing reads — 2115 §2's wrong answer that succeeds.
+        // `GetVideoCaps`, the seven values `OptionsFrame_Load` destructures. Shaders, trilinear,
+        // anisotropy and the hardware cursor are always there (`crate::cursor` composites the
+        // reference's cursors into an OS cursor); `max_anisotropy` is reported raw because
+        // `OptionsFrame.lua:122` matches it against `ANISOTROPIC_VALUES`. Triple buffering is
+        // false: wgpu owns the surface's buffering, so the stock frame hides check button 13
+        // (`OptionsFrame.lua:163-165`).
         script.set_video_caps(benilla_ui::script::VideoCaps {
             anisotropic: true,
             pixel_shaders: true,
@@ -1978,19 +1346,12 @@ pub(crate) fn sync_cvars(
     }
 }
 
-/// Fold the dying VM's last writes into the registry — the session edge's half of decision
-/// 1291's bridge (the seed in [`sync_cvars`] is the other). Called from
-/// [`crate::ui_script::end_ui_session`] **after** the shutdown events (an addon's
-/// `PLAYER_LOGOUT` handler may `SetCVar`, and in the reference that write lands in an
-/// engine-side store that survives) and **before** the VM is replaced.
-///
-/// The registry IS the store that survives, so there is nothing to copy back: only the writes
-/// the per-frame sync never got to see — a `SetCVar` in the final frame would otherwise be
-/// overwritten by the stale value when the next VM's seed runs. The observers fire here, so the
-/// knobs are current before the next VM is even built.
+/// Fold the dying VM's last writes into the registry. Called from
+/// [`crate::ui_script::end_ui_session`] after the shutdown events (a `PLAYER_LOGOUT` handler may
+/// `SetCVar`, and the reference keeps that write) and before the VM is replaced, so a final-frame
+/// write is not lost to the next VM's seed. The observers fire here.
 pub(crate) fn fold_dying_vm_cvars(world: &mut World) {
-    // A world with no registry has no file to bridge — a test world or a stripped scenario that
-    // never added the plugin.
+    // No registry: a test or stripped world without the plugin.
     if !world.contains_resource::<Cvars>() {
         return;
     }
@@ -2022,15 +1383,14 @@ pub(crate) fn fold_dying_vm_cvars(world: &mut World) {
     }
 }
 
-/// The file's header comment — where these values come from and where the law lives.
+/// The file's header comment.
 const HEADER: &str = "\
 # benilla local config (decision 0954) — CVar values that moved off their defaults.
 # Managed by the client; hand edits are read on next launch and preserved on save.
 ";
 
-/// Dirty + one quiet second (or the app exiting) → rewrite `config.toml` atomically, from the
-/// registry — the store, not the VM's mirror, so a session with no VM at all (the glue screens,
-/// a headless run) saves exactly what it changed.
+/// Dirty and one quiet second, or the app exiting: rewrite `config.toml` atomically from the
+/// registry, so a session with no VM saves what it changed.
 fn save_config(mut cvars: ResMut<Cvars>, mut exits: MessageReader<AppExit>) {
     let exiting = exits.read().next().is_some();
     if !cvars.dirty {
@@ -2061,18 +1421,9 @@ fn save_config(mut cvars: ResMut<Cvars>, mut exits: MessageReader<AppExit>) {
     }
 }
 
-/// Freeze the texture filter policy for the process, and say what it resolved to.
-///
-/// **A separate system, chained after [`load_config`], deliberately.** `load_config` returns early
-/// on an absent or malformed file, and the policy has to be published on every one of those paths:
-/// the sampler lanes are an async `AssetLoader` and a set of ordinary systems, none of which can
-/// read a resource the others own, so a run that never published would be reading
-/// [`benilla_assets::tex_filter`]'s fallback while a player's `config.toml` said otherwise.
-///
-/// The log line is not decoration — it is the same reasoning as `video::log_display_session`
-/// (1627). Every filtering report this client will get comes from a machine nobody here can run,
-/// and "which mode was that run actually in" must be readable off the log a player pastes rather
-/// than reasoned about.
+/// Freeze the texture filter policy for the process and log the mode, so a player's log says which
+/// mode the run was in. Its own system after [`load_config`], so it publishes whatever the file
+/// held.
 fn publish_filter_policy(filter: Res<benilla_assets::TexFilterSetting>) {
     benilla_assets::publish_tex_filter(*filter);
     let mode = filter.mode();
@@ -2109,30 +1460,12 @@ mod tests {
     use benilla_world::clutter::ClutterConfig;
     use benilla_world::view::{MsaaSetting, ViewDistance, FARCLIP_RANGE, MSAA_RANGE};
 
-    /// **The standard, enforced: a benilla option's default IS the reference's** (decision 1804)
-    /// — every row's [`Reference`] column stands up.
-    ///
-    /// This is the half that could not be a convention. Before it, the reference's value for a row
-    /// lived only in the prose above that row, which meant a default could be *chosen* without
-    /// anyone establishing what the client it imitates does — and five of them were: NPC and own
-    /// overhead names, enemy V-plates, party chat bubbles and the camera's max-distance factor all
-    /// shipped ON or raised while a stock 1.12 client ships them off or low, each one a reasonable
-    /// call on its own day and none of them visible as a *set* until somebody went looking. A
-    /// third column, mandatory and typed, is what makes the question unskippable; this test is
-    /// what makes the answer stay true.
-    ///
-    /// It checks **both directions**, which is the part that matters over years:
-    /// - a [`Reference::Same`] row whose default has drifted off the reference's fails — you
-    ///   cannot edit a default and leave the claim behind;
-    /// - a [`Reference::Deviates`] or [`Reference::Overridden`] row that has quietly come back
-    ///   into agreement *also* fails, because a stale deviation note is worse than none: it hides
-    ///   that we are already faithful and invites the next reader to "restore" a divergence.
-    ///
-    /// Values are parse-compared where both sides are numeric, so `"1"` and `"1.0"` are one claim.
+    /// Every row's [`Reference`] column holds, both ways: a `Same` row that drifted fails, and so
+    /// does a `Deviates` or `Overridden` row back in agreement. Numbers parse-compare, so "1" and
+    /// "1.0" agree.
     #[test]
     fn defaults_stand_where_the_reference_column_says() {
-        /// One value against another — numeric when both parse, textual otherwise (`gxResolution`,
-        /// `realmList`).
+        /// Numeric when both parse, textual otherwise.
         fn agrees(ours: &str, theirs: &str) -> bool {
             match (ours.parse::<f32>(), theirs.parse::<f32>()) {
                 (Ok(a), Ok(b)) => a == b,
@@ -2179,17 +1512,6 @@ mod tests {
         }
     }
 
-    /// **The inventory** — the exact set of options benilla ships at something other than what a
-    /// stock 1.12 client ships, as one readable list.
-    ///
-    /// The list is the deliverable, not the assertion: a reviewer (or the director) reads *this*
-    /// to answer "where do we differ, and is each one still worth it?", and growing it is a
-    /// deliberate edit rather than a side effect of adding a row. [`Reference::Overridden`] and
-    /// [`Reference::Ours`] are deliberately **not** here — those rows follow the reference's
-    /// behaviour, or have no reference behaviour to follow.
-    ///
-    /// Every name below is argued at its own row; this is the index, and the reason it is sorted
-    /// is that the table's order is a load order, not a ranking.
     #[test]
     fn the_options_that_leave_the_reference_are_this_list_and_no_other() {
         let mut names: Vec<&str> = REGISTERED
@@ -2214,15 +1536,8 @@ mod tests {
         );
     }
 
-    /// Every registered default IS the code constant it mirrors — parse-compared so "1" vs
-    /// "1.0" cannot fail it, welded so neither side can drift alone.
-    ///
-    /// **The numeric ones**, which was every one of them until `realmName` — the first
-    /// string-valued CVar in the table, and the reason this now filters rather than unwraps. It is
-    /// asserted on its own terms in
-    /// [`the_only_string_valued_cvar_is_the_realm_and_it_defaults_empty`]; a `parse::<f32>()` over
-    /// the whole table would either panic (it did) or quietly need every future string CVar to be
-    /// numeric.
+    /// Every numeric registered default equals the code constant it mirrors; the string rows are
+    /// checked in [`the_string_valued_cvars_are_the_realm_and_the_windowed_size`].
     #[test]
     fn registered_defaults_mirror_the_code_truths() {
         let d: BTreeMap<&str, f32> = REGISTERED
@@ -2246,27 +1561,21 @@ mod tests {
             !sound.background_sound,
             "the reference goes quiet in the background and offers no way out (decision 1847)"
         );
-        // Welded like the rest — and deliberately NOT the binary's registrar "1" (1153).
         assert_eq!(d["SoundReverb"] != 0.0, sound.reverb);
         assert_eq!(d["SoundOutputLimiter"] != 0.0, sound.limiter);
         assert!(sound.limiter, "the output limiter ships on (decision 1551)");
         assert!(!sound.reverb, "zone reverb ships off (decision 1153)");
         assert_eq!(d["uiScale"], DEFAULT_UI_SCALE);
-        // ViewDistance::default() reads $WOW_FARCLIP; the registered default mirrors the
-        // env-less 350 literal (view.rs doc: "Default 350" — the reference's own, 1624).
+        // `ViewDistance::default()` reads `$WOW_FARCLIP`, so this is the env-less literal.
         assert_eq!(d["farclip"], 350.0);
-        // `nearclip` welds to the const the off-world spawners use, so the viewer, the depth probe
-        // and the player's camera cannot open on three different near planes again (2163).
         assert_eq!(d["nearclip"], benilla_world::view::NEARCLIP_DEFAULT);
         assert_eq!(
             d["nearclip"],
             ViewDistance::default().nearclip,
             "the registered default and the resource's own must be one number"
         );
-        // Same shape as farclip: `MsaaSetting::default()` reads $WOW_MSAA, so the registered
-        // default mirrors the env-less literal — 1, the reference's own (1629).
+        // `MsaaSetting::default()` reads `$WOW_MSAA`, so this is the env-less literal.
         assert_eq!(d["gxMultisample"], 1.0);
-        // The Controls trio (0961) welds to its knob Defaults the same way.
         assert_eq!(
             d["deselectOnClick"] != 0.0,
             ClickConfig::default().deselect_on_click
@@ -2277,9 +1586,6 @@ mod tests {
         );
         assert_eq!(d["mousespeed"], LookConfig::default().sensitivity);
         assert_eq!(d["cameraDistanceMaxFactor"], ZoomLimit::default().factor());
-        // The follow trio (1493/1502) welds to FollowConfig's own defaults — and all three ARE
-        // the binary's registrar values, byte-verified: "1"/"1"/"180.0". The one corner of this
-        // arc that agrees with the reference outright.
         let follow = FollowConfig::default();
         assert_eq!(
             d["cameraSmoothStyle"],
@@ -2292,27 +1598,20 @@ mod tests {
         assert_eq!(d["cameraYawSmoothSpeed"], follow.yaw_speed);
         assert_eq!(FollowStyle::default(), FollowStyle::Smart);
         assert_eq!(d["autoLootDefault"] != 0.0, LootConfig::default().auto_loot);
-        // The roll-detail switch (1589) welds to the same knob's default — and that default IS
-        // the binary's registered "1", so this row agrees with the reference on both sides.
         assert_eq!(
             d["showLootSpam"] != 0.0,
             LootConfig::default().show_loot_spam
         );
-        // …and the one row that ships a feature OFF, byte-read at `0x5e24c7`.
         assert_eq!(
             d["guildMemberNotify"] != 0.0,
             crate::ui_guild::GuildMemberNotify::default().0
         );
         assert_eq!(d["guildMemberNotify"], 0.0, "the binary registers \"0\"");
-        // Block Trades (1764) welds the same way, and its "0" is behaviour: the refusal leg only
-        // fires when the CVar is SET, so an unset value must read as "trades allowed".
         assert_eq!(
             d["BlockTrades"] != 0.0,
             crate::ui_trade::BlockTrades::default().0
         );
         assert_eq!(d["BlockTrades"], 0.0, "an unset BlockTrades allows trades");
-        // The name trio (0992) welds to NameConfig's defaults the same way — and all three are
-        // the binary's own registrar values now (1804), not two director pins over one.
         let names = NameConfig::default();
         assert_eq!(d["UnitNamePlayer"] != 0.0, names.player);
         assert_eq!(d["UnitNameNPC"] != 0.0, names.npc);
@@ -2323,9 +1622,6 @@ mod tests {
             "the binary registers UnitNamePlayer \"1\", NPC \"0\", Own \"0\", \
              PlayerGuild \"1\""
         );
-        // The camera options weld to `CameraOptions::default()` the same way (2149) — and the one
-        // that matters here is the one registered "1": a `cameraPivot` that shipped OFF would be
-        // benilla diverging from the reference on a feature it now has.
         let camera_opts = crate::player::camera_dynamics::CameraOptions::default();
         assert_eq!(d["cameraPivot"] != 0.0, camera_opts.pivot);
         assert!(camera_opts.pivot, "the binary registers cameraPivot \"1\"");
@@ -2363,13 +1659,6 @@ mod tests {
             d["cameraTargetSmoothSpeed"],
             camera_opts.target_smooth_speed
         );
-        // The V-plate pair welds to VPlateMode's defaults — both OFF, which is the reference's
-        // own boot state on both of its halves (the `[0xc4da34]` bitmask and FrameXML's
-        // `NAMEPLATES_ON = nil`). Enemy plates were the 0167 director pin until 1804.
-        // Weather Intensity (2181): the CVar's default and the weather driver's own must be
-        // the same rain, or a fresh config writes a row the world does not agree with. This is
-        // also where the DEVIATION is held honest — the reference registers "2" and the row
-        // above says why we ship 3; the weld makes sure it is 3 in both places.
         assert_eq!(
             d["weatherDensity"],
             f32::from(benilla_world::weather::WeatherState::default().weather_density)
@@ -2381,56 +1670,33 @@ mod tests {
             !plates.enemies && !plates.friends,
             "a fresh 1.12 client draws no plates until V is pressed"
         );
-        // ClutterConfig::default() reads $WOW_CLUTTER_DENSITY; the registered default mirrors
-        // the env-less ×2 literal (clutter.rs: "Default ×2 = Medium", 1649) on the panel's 0..2
-        // scale. The weld is the point: the CVar's default and the engine's must be the same
-        // ground cover, or a fresh config writes a row the world does not agree with.
+        // `ClutterConfig::default()` reads `$WOW_CLUTTER_DENSITY`; stop 1 is its env-less ×2.
         assert_eq!(d["WorldDetail"], 1.0);
-        // …and its twin in the reference's own unit (2151) welds to it, not beside it: the two
-        // rows are one knob read two ways, so a default that disagreed would ship a client whose
-        // panel stop and whose cells-per-chunk describe different ground.
         assert_eq!(
             d["frillDensity"],
             (d["WorldDetail"] + 1.0) * benilla_formats::FRILL_DENSITY as f32
         );
-        // The bubble pair (1139) welds to BubbleConfig's defaults — both the binary's own since
-        // 1804 (`ChatBubbles` "1", `ChatBubblesParty` "0"; the party half was 0598's director pin).
         let bubbles = BubbleConfig::default();
         assert_eq!(d["ChatBubbles"] != 0.0, bubbles.all);
         assert_eq!(d["ChatBubblesParty"] != 0.0, bubbles.party);
         assert!(bubbles.all && !bubbles.party, "the binary's own pair");
-        // The minimap pair (1131) welds to the widget's own `MINIMAP_DEFAULT_ZOOM`, which is the
-        // byte-verified registration default `"3"` — one truth, mirrored in three places.
         let zoom = MinimapZoom::default();
         assert_eq!(d["minimapZoom"], f32::from(zoom.outdoor));
         assert_eq!(d["minimapInsideZoom"], f32::from(zoom.inside));
         assert_eq!(zoom.outdoor, benilla_ui::widget::MINIMAP_DEFAULT_ZOOM);
-        // VSync welds to the video knob, which in turn welds to the window literal's boot
-        // mode (`video::tests`) — so the registered "1" cannot drift from what we ship.
+        // `video::tests` welds `VideoConfig::vsync` to the window's boot present mode.
         assert_eq!(d["gxVSync"] != 0.0, VideoConfig::default().vsync);
-        // The pane half-rate (1444) welds to the portrait knob's shipped default.
         assert_eq!(d["boothHalfRate"] != 0.0, PaneRate::default().half);
-        // Render scale (1639) welds to OFF. Not a taste default: the whole tree of visual
-        // goldens is denominated in a 1:1 backdrop, so a registered value other than 1 would
-        // silently re-render every one of them through a resample.
+        // Every visual golden assumes a 1:1 backdrop.
         assert_eq!(d["renderScale"], 1.0);
     }
 
-    /// **Every arm, through the registry and its observers.** The old central `apply_to_knobs`
-    /// match is gone (2303); each arm lives beside the knob it writes, and this drives the whole
-    /// set through a real `App` — a host write, the observers firing synchronously — so a knob
-    /// whose observer forgot an arm, or clamps differently from what its row promises, fails here.
-    ///
-    /// `apply` crosses the latch boundary at once, so the arms are what is under test; the latch
-    /// itself has its own test.
     #[test]
     fn the_observers_apply_every_arm() {
         let mut app = cvar_app();
         apply(&mut app, "MusicVolume", "0.7");
         assert_eq!(res::<SoundConfig>(&app).music, 0.7);
-        // The second string-valued row (1667): it must reach the knob rather than being rejected
-        // by the numeric parse every other row goes through, and a value that is not an address
-        // must be consumed (known key) while leaving the knob's truth alone.
+        // A string row reaches its knob; a value that is not an address leaves the knob alone.
         apply(&mut app, "realmList", "logon.example.org:3724");
         assert_eq!(
             res::<crate::realmlist::Realmlist>(&app).address(),
@@ -2456,8 +1722,7 @@ mod tests {
         assert_eq!(res::<SoundConfig>(&app).master, 1.0);
         apply(&mut app, "farclip", "50");
         assert_eq!(res::<ViewDistance>(&app).farclip, *FARCLIP_RANGE.start());
-        // `nearclip` clamps to the reference's own callback bounds `[0.01, 0.33]` (`0x688d90`),
-        // both ends. pfUI's extended stops write 0.06..0.30, so its whole range passes untouched.
+        // `nearclip` clamps to the callback's `[0.01, 0.33]` (`0x688d90`).
         apply(&mut app, "nearclip", "0.001");
         assert_eq!(
             res::<ViewDistance>(&app).nearclip,
@@ -2472,13 +1737,9 @@ mod tests {
         );
         apply(&mut app, "nearclip", "0.3");
         assert_eq!(res::<ViewDistance>(&app).nearclip, 0.3);
-        // Multisampling clamps to the reference's own [1, 16] and takes an int the way its `atoi`
-        // does — the value reaching the camera is a sample COUNT, where 1 is none (1629).
+        // A sample count, clamped to the reference's [1, 16]; 1 is none.
         apply(&mut app, "gxMultisample", "4");
         assert_eq!(res::<MsaaSetting>(&app).samples, 4);
-        // The filter policy's two rows: `anisotropic` takes the reference's own [1, 16] clamp,
-        // `trilinear` is a flag. Both write the pending value; the process policy is already
-        // published by the time either can be typed (1642).
         apply(&mut app, "anisotropic", "99");
         assert_eq!(
             res::<benilla_assets::TexFilterSetting>(&app).aniso,
@@ -2489,15 +1750,13 @@ mod tests {
             res::<benilla_assets::TexFilterSetting>(&app).aniso,
             *benilla_assets::ANISO_RANGE.start()
         );
-        // Both directions: the knob starts at what ships (on), so only the flip to 0 proves the
-        // arm does anything.
+        // The knob ships on, so only the flip to 0 proves the arm.
         apply(&mut app, "trilinear", "0");
         assert!(!res::<benilla_assets::TexFilterSetting>(&app).trilinear);
         apply(&mut app, "trilinear", "1");
         assert!(res::<benilla_assets::TexFilterSetting>(&app).trilinear);
-        // **The DEVICE's ceiling, not the reference's** (decision 1643). 99 clamps to the
-        // reference's 16 and then to the 4 this GPU offers — before 1643 it stopped at 16 and the
-        // camera was handed a sample count wgpu refuses, killing the render thread on frame one.
+        // Clamped to the device's ceiling too: this GPU offers 4, and wgpu refuses a count it
+        // lacks.
         apply(&mut app, "gxmultisample", "99");
         assert_eq!(res::<MsaaSetting>(&app).samples, 4);
         // The realistic route in: a config written where 8x exists, opened where it does not.
@@ -2507,19 +1766,16 @@ mod tests {
             4,
             "a device that stops at 4x must never be handed an 8"
         );
-        // A count the device DOES offer is untouched.
         apply(&mut app, "gxmultisample", "2");
         assert_eq!(res::<MsaaSetting>(&app).samples, 2);
         apply(&mut app, "gxmultisample", "0");
         assert_eq!(res::<MsaaSetting>(&app).samples, *MSAA_RANGE.start());
-        // Render scale takes a fraction and clamps to its own range at both ends (1639).
         apply(&mut app, "renderScale", "0.75");
         assert_eq!(res::<RenderScale>(&app).0, 0.75);
         apply(&mut app, "renderscale", "9");
         assert_eq!(res::<RenderScale>(&app).0, *RENDER_SCALE_RANGE.end());
         apply(&mut app, "renderscale", "0");
         assert_eq!(res::<RenderScale>(&app).0, *RENDER_SCALE_RANGE.start());
-        // The FPS journal switch (2008): a flag, case-insensitive, off as shipped.
         assert!(!res::<crate::perf::FpsJournalSetting>(&app).0);
         apply(&mut app, "fpsJournal", "1");
         assert!(res::<crate::perf::FpsJournalSetting>(&app).0);
@@ -2530,18 +1786,15 @@ mod tests {
         assert!(!res::<SoundConfig>(&app).music_enabled);
         apply(&mut app, "mastersoundeffects", "1");
         assert!(res::<SoundConfig>(&app).enabled);
-        // The Controls trio lands on its knobs (case-insensitive like everything else).
         apply(&mut app, "deselectonclick", "0");
         assert!(!res::<ClickConfig>(&app).deselect_on_click);
         apply(&mut app, "MouseInvertPitch", "1");
         assert!(res::<LookConfig>(&app).invert_pitch);
-        // The sensitivity multiplier clamps to the 1.12 slider's range at the knob.
         apply(&mut app, "mousespeed", "1.4");
         assert_eq!(res::<LookConfig>(&app).sensitivity, 1.4);
         apply(&mut app, "mousespeed", "9");
         assert_eq!(res::<LookConfig>(&app).sensitivity, 1.5);
-        // The following style lands as the ENGINE's enum (0 Never / 1 Smart / 2 Always), and the
-        // "3" the reference's own dropdown writes for Never still means Never.
+        // The engine's enum (0 Never, 1 Smart, 2 Always); 3, the validator's upper bound, is Never.
         apply(&mut app, "cameraSmoothStyle", "0");
         assert_eq!(res::<FollowConfig>(&app).style, FollowStyle::Never);
         apply(&mut app, "camerasmoothstyle", "2");
@@ -2550,8 +1803,6 @@ mod tests {
         assert_eq!(res::<FollowConfig>(&app).style, FollowStyle::Never);
         apply(&mut app, "cameraSmoothStyle", "1");
         assert_eq!(res::<FollowConfig>(&app).style, FollowStyle::Smart);
-        // Its two siblings land on the same knob — the tracking selector, and the rate, which
-        // clamps to 1.12's AUTO_FOLLOW_SPEED slider range.
         apply(&mut app, "cameraSmoothTrackingStyle", "2");
         assert_eq!(
             res::<FollowConfig>(&app).tracking_style,
@@ -2578,55 +1829,43 @@ mod tests {
         assert!(res::<LootConfig>(&app).auto_loot);
         apply(&mut app, "showLootSpam", "0");
         assert!(!res::<LootConfig>(&app).show_loot_spam);
-        // Guild Member Alert (1589) — the row that ships OFF, so its ON is the interesting write.
         apply(&mut app, "guildMemberNotify", "1");
         assert!(res::<crate::ui_guild::GuildMemberNotify>(&app).0);
-        // Block Trades (1764) — the other row that ships OFF; its ON is what refuses a trade.
         apply(&mut app, "BlockTrades", "1");
         assert!(res::<crate::ui_trade::BlockTrades>(&app).0);
-        // The name trio lands on its gates (0992).
         apply(&mut app, "UnitNameNPC", "0");
         assert!(!res::<NameConfig>(&app).npc);
         apply(&mut app, "unitnameown", "1");
         assert!(res::<NameConfig>(&app).own);
-        // …and the plate pair on the two bits of the bitmask, either casing.
         apply(&mut app, crate::vplates::CVAR_ENEMIES, "0");
         assert!(!res::<VPlateMode>(&app).enemies);
         apply(&mut app, "nameplateshowfriends", "1");
         assert!(res::<VPlateMode>(&app).friends);
-        // The bubble pair lands on the spawn gate's own knob (1139).
         apply(&mut app, "ChatBubbles", "0");
         assert!(!res::<BubbleConfig>(&app).all);
         apply(&mut app, "chatbubblesparty", "0");
         assert!(!res::<BubbleConfig>(&app).party);
-        // WorldDetail: panel 0/1/2 → density ×1/×2/×3, clamped to the 1.12 slider's range.
+        // WorldDetail: stop 0/1/2 is density ×1/×2/×3, clamped to the slider's range.
         apply(&mut app, "WorldDetail", "0");
         assert_eq!(res::<ClutterConfig>(&app).density, 1.0);
         apply(&mut app, "worlddetail", "7");
         assert_eq!(res::<ClutterConfig>(&app).density, 3.0);
-        // frillDensity: the SAME field in the reference's cells-per-chunk (2151), and the two
-        // arms' clamps are deliberately different — the stop's `[0, 2]` above, the cells'
-        // `[1, 256]` here (callback `0x688de0`). The stops round-trip through both spellings,
-        // which is the property that makes them one knob rather than two that agree by habit.
+        // `frillDensity` is the same field in cells per chunk, with its own clamp `[1, 256]`
+        // (`0x688de0`); the stops round-trip through both spellings.
         apply(&mut app, "frillDensity", "48");
         assert_eq!(res::<ClutterConfig>(&app).density, 3.0);
         apply(&mut app, "frilldensity", "16");
         assert_eq!(res::<ClutterConfig>(&app).density, 1.0);
-        // Past the top stop is HONOURED, not clamped to it — pfUI's `hdgraphic` drives exactly
-        // this, `ConsoleExec("frillDensity " .. (arg+1)*16)` for arg up to 15.
+        // Past the top stop is honoured; pfUI's `hdgraphic` writes up to 256.
         apply(&mut app, "frillDensity", "256");
         assert_eq!(res::<ClutterConfig>(&app).density, 16.0);
-        // …and the reference's own bounds hold at both ends. `0` is NOT clutter-off: the callback
-        // pins it to 1, and turning grass off stays the `$WOW_CLUTTER_DENSITY` instrument's.
+        // `0` is not clutter-off: the callback pins it to 1.
         apply(&mut app, "frillDensity", "9000");
         assert_eq!(res::<ClutterConfig>(&app).density, 16.0);
         apply(&mut app, "frillDensity", "0");
         assert_eq!(res::<ClutterConfig>(&app).density, 1.0 / 16.0);
-        // The row `GetCVar` answers is the same field seen the other way round.
         apply(&mut app, "WorldDetail", "1");
         assert_eq!(res::<ClutterConfig>(&app).density, 2.0);
-        // Weather Intensity (2181): the panel's four stops land whole, an off-grid value
-        // truncates toward zero the way every int-valued row here does, and both ends clamp.
         for (wrote, want) in [
             ("0", 0u8),
             ("1", 1),
@@ -2643,10 +1882,8 @@ mod tests {
                 "weatherDensity {wrote}"
             );
         }
-        // Brightness (2182): the CVar's own unit is the ramp exponent, NOT the slider's offset —
-        // `SetGamma` does the `1 - v` on the way in, so what arrives here is already `gamma`.
-        // Both ends of the stock slider land whole, and the consumer's clamp holds the values the
-        // reference accepts without one (`SetGamma(5)` writes -4 there).
+        // `gamma` is the ramp exponent: `SetGamma` applies `1 - v` before it arrives here. The
+        // consumer clamps what the reference accepts unclamped (`SetGamma(5)` writes -4 there).
         for (wrote, want) in [("1.000000", 1.0), ("0.500000", 0.5), ("1.500000", 1.5)] {
             apply(&mut app, "gamma", wrote);
             assert_eq!(
@@ -2667,10 +1904,8 @@ mod tests {
             *crate::ui_gamma::GAMMA_RANGE.end()
         );
         assert_eq!(res::<ClutterConfig>(&app).frill_density(), 32.0);
-        // Both spellings reach the same field, from a state neither of them holds — and
-        // `$WOW_CLUTTER_DENSITY` takes both for the session (`session_values`), so the lever
-        // cannot ride into `config.toml` through the other name (2151). Two different values,
-        // because a write of the sibling's mirrored value is the no-op it should be.
+        // Both spellings reach the field from a state neither holds; `$WOW_CLUTTER_DENSITY` takes
+        // both for the session. Two values, since writing the sibling's mirrored value is a no-op.
         for (key, value) in [
             (benilla_ui::script::CVAR_WORLD_DETAIL, "2"),
             (benilla_ui::script::CVAR_FRILL_DENSITY, "16"),
@@ -2683,28 +1918,21 @@ mod tests {
                 "{key}: reached no knob"
             );
         }
-        // **The engine verbs' half of the same weld** (2163). `SetWorldDetail`/`GetWorldDetail` live
-        // in `benilla-ui`, which cannot see this table, so the two CVar names and the stop table it
-        // writes are consts there — and if either name stopped being registered, or the reference's
-        // {16, 32, 48} stopped being `frillDensity`'s unit times the stop, the verbs would write
-        // into nothing and only this assertion would say so.
+        // `benilla-ui`'s `SetWorldDetail`/`GetWorldDetail` name these CVars by const and cannot see
+        // this table, so both must stay registered and the stops must stay `frillDensity`'s unit
+        // times n.
         assert!(REGISTERED
             .iter()
             .any(|r| r.name == benilla_ui::script::CVAR_WORLD_DETAIL));
         assert!(REGISTERED
             .iter()
             .any(|r| r.name == benilla_ui::script::CVAR_FRILL_DENSITY));
-        // …and the display-gamma pair's (2182), for exactly the same reason: `GetGamma` answers
-        // `1 - <this CVar>` and `SetGamma` writes `1 - v` into it, both from a crate that cannot
-        // see this table, so an unregistered name would make the getter answer a constant 0 and
-        // the setter write into nothing.
+        // The same for `GetGamma`/`SetGamma`, which read and write `1 - gamma`.
         assert!(REGISTERED
             .iter()
             .any(|r| r.name == benilla_ui::script::CVAR_GAMMA));
-        // **`RestoreVideoDefaults`' row list, welded the same way** (2177). It lives in
-        // `benilla-ui` beside the binding that walks it and cannot see this table, so a rename or
-        // a retirement here would turn one of its rows into a silent skip — the verb would restore
-        // eleven settings out of twelve and say nothing. This is the only place that can notice.
+        // `RestoreVideoDefaults`' row list lives in `benilla-ui` too; an unregistered row would be
+        // skipped silently.
         for key in benilla_ui::script::VIDEO_DEFAULT_CVARS {
             assert!(
                 REGISTERED.iter().any(|r| r.name.eq_ignore_ascii_case(key)),
@@ -2717,12 +1945,9 @@ mod tests {
                 benilla_formats::FRILL_DENSITY * (n as u32 + 1),
                 "stop {n}: the reference's own 0x804518 entry must be this knob's unit times the stop"
             );
-            // Either spelling of the stop lands on the same ground cover — which is what lets the
-            // setter write `frillDensity` and the getter read `WorldDetail` without disagreeing.
             apply(&mut app, "WorldDetail", &n.to_string());
             let by_stop = res::<ClutterConfig>(&app).density;
-            // Off the stop first — the mirror already wrote this spelling — then the stop's
-            // own cells through it.
+            // Off the stop first (the mirror already wrote this spelling), then the stop's cells.
             apply(&mut app, "frillDensity", "1");
             app.world_mut().resource_mut::<ClutterConfig>().density = 0.5;
             apply(&mut app, "frillDensity", &frill.to_string());
@@ -2733,10 +1958,8 @@ mod tests {
             );
             assert_eq!(res::<ClutterConfig>(&app).frill_density(), *frill as f32);
         }
-        // Back to the shipped stop, so the rows after this one read the default ground cover.
         apply(&mut app, "WorldDetail", "1");
         assert_eq!(res::<ClutterConfig>(&app).density, 2.0);
-        // The zoom pair (1131): each index lands on its own field, clamped like `set_zoom`.
         apply(&mut app, "minimapZoom", "5");
         assert_eq!(res::<MinimapZoom>(&app).outdoor, 5);
         assert_eq!(
@@ -2748,8 +1971,6 @@ mod tests {
         assert_eq!(res::<MinimapZoom>(&app).inside, MINIMAP_ZOOM_LEVELS - 1);
         apply(&mut app, "minimapZoom", "-2");
         assert_eq!(res::<MinimapZoom>(&app).outdoor, 0);
-        // A bad value on a numeric row is REFUSED by the registry (2303) — the resource keeps
-        // its truth and the row keeps its value; an unknown name is reported as such.
         assert_eq!(apply(&mut app, "uiScale", "banana"), SetOutcome::Refused);
         assert_eq!(res::<UiScaleCvar>(&app).0, 0.9);
         assert_eq!(apply(&mut app, "bogus", "1"), SetOutcome::Unknown);
@@ -2777,10 +1998,6 @@ mod tests {
         assert_eq!(out.get("FutureKnob").map(String::as_str), Some("3"));
     }
 
-    /// End to end on a real App: a pre-written `config.toml` loads into the knobs at Startup, a
-    /// Lua `SetCVar` drains into the knobs and — on the exit flush — lands back in the file as a
-    /// diff (the moved value present, the untouched ones absent). This is the whole 0954 slice-1
-    /// loop in one place: file → knobs → VM table → Lua write → knobs → file.
     #[test]
     fn a_lua_setcvar_lands_in_config_toml_end_to_end() {
         use crate::local_state::test_env::{EnvGuard, ENV_LOCK};
@@ -2832,10 +2049,8 @@ mod tests {
         std::fs::remove_dir_all(&tmp).ok();
     }
 
-    /// A client whose CVar host is real: every knob resource an observer writes, every
-    /// observer, [`CvarPlugin`] itself, and a VM for the mirror to live in. The end-to-end tests below
-    /// each stand a whole client up, and the census is one row per knob — copied per test, adding
-    /// a knob meant editing every copy.
+    /// A client with a real CVar host: every knob resource an observer writes, every observer,
+    /// [`CvarPlugin`] and a VM for the mirror.
     fn cvar_app() -> App {
         let mut app = App::new();
         app.add_plugins(bevy::MinimalPlugins)
@@ -2846,14 +2061,12 @@ mod tests {
                 nearclip: benilla_world::view::NEARCLIP_DEFAULT,
             })
             .insert_resource(MsaaSetting { samples: 1 })
-            // Literal for the same reason (1642): TexFilterSetting::default() reads
-            // $WOW_TRILINEAR / $WOW_ANISO. These are what ships (1645).
+            // Literal: `TexFilterSetting::default()` reads `$WOW_TRILINEAR`/`$WOW_ANISO`.
             .insert_resource(benilla_assets::TexFilterSetting {
                 trilinear: true,
                 aniso: 1,
             })
-            // The device menu the Video dropdown reads. A real-shaped list, not empty: these
-            // tests exercise `GetCurrentMultisampleFormat`'s lookup, which needs rows to find.
+            // A real-shaped device menu: `GetCurrentMultisampleFormat` needs rows to find.
             .insert_resource(benilla_world::view::MsaaFormats {
                 formats: vec![(32, 32, 1), (32, 32, 2), (32, 32, 4)],
             })
@@ -2877,7 +2090,7 @@ mod tests {
             .init_resource::<VideoConfig>()
             // Literal, not Default: RenderScale::default() reads $WOW_RENDER_SCALE.
             .insert_resource(RenderScale(1.0))
-            // Literal for the same reason again (1667): Realmlist::default() reads $WOW_HOST.
+            // Literal: `Realmlist::default()` reads `$WOW_HOST`.
             .insert_resource(crate::realmlist::Realmlist::unpinned(
                 crate::realmlist::DEFAULT_REALMLIST,
             ))
@@ -2896,9 +2109,8 @@ mod tests {
         app
     }
 
-    /// Every CVar observer in the crate, as the plugins register them — the census this test
-    /// module stands a client up with. A new observer is one line here and one
-    /// `add_observer` in its plugin.
+    /// Every CVar observer in the crate; a new one is a line here and an `add_observer` in its
+    /// plugin.
     const ALL_OBSERVERS: &[fn(&mut App)] = &[
         |app| {
             app.add_observer(crate::sound::on_cvar);
@@ -2990,16 +2202,9 @@ mod tests {
         app.world().resource::<T>()
     }
 
-    /// **The reported bug, end to end** (decision 1622): "char screen doesn't remember the last
-    /// logged in char, the ref does". Two launches over one `benilla-config/`, with the real
-    /// [`CvarPlugin`] and the real [`crate::char_select`] systems in between — entering the world
-    /// as somebody has to survive the quit and bring the screen back to them.
-    ///
-    /// The seam this covers and the per-module tests cannot: the screen's host write has to
-    /// reach the file through the registry's own dirty/compose path. Before 2303 a knobless CVar
-    /// fell through the central arm match to `_ => return false`, reached the VM's table, read
-    /// back correctly all session, and was silently dropped at the save — this bug again, one
-    /// layer down.
+    /// The last character entered survives a quit: two launches over one `benilla-config/` with the
+    /// real [`CvarPlugin`] and [`crate::char_select`] systems, so the screen's host write must
+    /// reach the file through the registry's dirty/compose path.
     #[test]
     fn entering_the_world_survives_the_quit_and_comes_back_selected() {
         use crate::char_select::{ClientState, Roster};
@@ -3073,10 +2278,6 @@ mod tests {
         std::fs::remove_dir_all(&tmp).ok();
     }
 
-    /// The minimap's zoom rides the same loop, driven from the **engine** rather than a Lua
-    /// `SetCVar` (decision 1131): the `+`/`-` buttons call `Minimap:SetZoom`, which writes the live
-    /// index and its CVar together — and that has to reach the knob and the file exactly like a
-    /// settings row's write does, or the level is forgotten at the next launch.
     #[test]
     fn a_minimap_setzoom_reaches_the_knob_and_the_file() {
         use crate::local_state::test_env::{EnvGuard, ENV_LOCK};
@@ -3100,8 +2301,6 @@ mod tests {
         let mut app = cvar_app();
         app.update();
 
-        // Startup restored the knob, and the VM's table answers with it — which is what the UI-load
-        // seam hands to `set_minimap_zoom` when the widget is born.
         assert_eq!(app.world().resource::<MinimapZoom>().outdoor, 5);
         assert_eq!(app.world().resource::<MinimapZoom>().inside, 3);
         let seed = {
@@ -3111,13 +2310,11 @@ mod tests {
         {
             let mut script = app.world_mut().non_send_resource_mut::<UiScript>();
             assert_eq!(script.cvar("minimapZoom").as_deref(), Some("5"));
-            // The UI-load seam's own order: the widget is born (at its `MinimapState` default),
-            // THEN the persisted level is pushed into it. Seeding a widget that does not exist yet
-            // is a no-op — which is exactly why that call sits after `load_ingame_ui`.
+            // The widget is born first, then the persisted level is pushed into it: seeding a
+            // widget that does not exist is a no-op.
             script.run(r#"m = CreateFrame("Minimap", "Mini")"#).unwrap();
             script.set_minimap_zoom(seed.0, seed.1);
             assert_eq!(script.eval::<u8>("return m:GetZoom()").unwrap(), 5);
-            // The player zooms out two notches with the minimap's own buttons.
             script.run("m:SetZoom(m:GetZoom() - 2)").unwrap();
         }
         app.update();
@@ -3131,7 +2328,6 @@ mod tests {
             "back at the registered default 3, so it leaves the diff entirely:\n{text}"
         );
 
-        // …and one more notch out is a real diff again.
         app.world_mut()
             .non_send_resource_mut::<UiScript>()
             .run("m:SetZoom(1)")
@@ -3153,35 +2349,15 @@ mod tests {
         let text = format!("{HEADER}{}", toml::to_string(&cfg).unwrap());
         let back: LocalConfig = toml::from_str(&text).unwrap();
         assert_eq!(back.cvars, cfg.cvars);
-        // The header survives as comments; a hand edit with comments parses too.
         let hand = "# my note\n[cvars]\nFarclip = \"500\"\n";
         let parsed: LocalConfig = toml::from_str(hand).unwrap();
         assert_eq!(parsed.cvars.get("Farclip").map(String::as_str), Some("500"));
     }
 
-    /// **The table's string-valued CVars, named — and each one's default asserted on its own
-    /// terms.**
-    ///
-    /// Pinned as a closed list so a new string CVar has to come here and think about the numeric
-    /// test above rather than silently widening it. That is exactly what happened at 1627, when
-    /// this test still said "the ONE": `gxResolution` arrived and the list grew by one, on purpose.
-    ///
-    /// **`realmName` defaults EMPTY** — empty rather than a guess: the value is written from the
-    /// session's real realm by `set_realm_name`, so the default only ever describes a client that
-    /// has not connected. `0x85d684` holds `"Last realm connected to"` beside the registration, but
-    /// that reads like the CVar's HELP text rather than its value, and nothing here needs it
-    /// resolved — `""` is what `Ace/AceState.lua:27`'s `ace.trim(GetCVar("realmName"))` handles
-    /// cleanly, and inventing a realm name would be worse than admitting we have none yet.
-    ///
-    /// **`gxResolution` defaults to the pre-1627 window** (decision 1627), and **`realmList` to
-    /// `localhost`** (1667). These are the rows the registry takes any string for (a row's
-    /// default decides whether it is numeric — [`Cvars::set`]), so each default is asserted
-    /// through the parser its observer uses on the live value — a spelling this table accepts
-    /// but [`crate::video::parse_resolution`] or [`crate::realmlist::normalize`] rejects would
-    /// otherwise ship as a silent fall back.
-    ///
-    /// The list itself is the load-bearing half: a new string-valued row has to come here and
-    /// name its parser, which is what makes adding one impossible to do quietly.
+    /// The string-valued rows, a closed list, each default checked on its own terms: `realmName`
+    /// (the reference's registered `""`, `0x882748`) and `gxApi` are empty until the session writes
+    /// them; `gxResolution` and `realmList` pass their observers' parsers
+    /// ([`crate::video::parse_resolution`], [`crate::realmlist::normalize`]).
     #[test]
     fn the_string_valued_cvars_are_the_realm_and_the_windowed_size() {
         let mut strings: Vec<&str> = REGISTERED
@@ -3202,26 +2378,19 @@ mod tests {
                 .expect("registered")
         };
         assert_eq!(default_of("realmName"), "");
-        // **`gxApi` defaults EMPTY on the same argument** (2151): the value is the render
-        // adapter's backend, written by `sync_cvars` on every launch, so the default only ever
-        // describes a client with no renderer. Naming one — `"direct3d"` least of all, which is
-        // the reference's and is a backend wgpu does not have — would be a claim about a machine
-        // we have not looked at.
         assert_eq!(default_of("gxApi"), "");
         assert_eq!(
             crate::video::parse_resolution(default_of("gxResolution")),
             Some(crate::video::DEFAULT_WINDOWED)
         );
-        // Same posture for the third row (1667): a default this table accepts but
-        // `realmlist::normalize` rejects would ship as a client that silently cannot dial.
+        // A default `realmlist::normalize` rejects would ship a client that cannot dial.
         assert_eq!(
             crate::realmlist::normalize(default_of(crate::realmlist::CVAR_REALMLIST)).as_deref(),
             Some(crate::realmlist::DEFAULT_REALMLIST),
         );
     }
 
-    /// A registry with the file's entries and the session's env values, no disk: the pure
-    /// half of the load, for the tests below.
+    /// A registry loaded from `file`, with no disk.
     fn registry(file: &[(&str, &str)]) -> Cvars {
         let mut cvars = Cvars::default();
         cvars.load_file(
@@ -3232,12 +2401,9 @@ mod tests {
         cvars
     }
 
-    /// **The latch** (decision 2303): a write to a row the reference registers with flag bit1
-    /// is staged, the applied value stands, nothing fires and nothing dirties — the reference's
-    /// `Set 0x63df50` storing to `latchedValue` with `InternalSet` skipped — until the boundary
-    /// commits it (`CVar::Update 0x63e060`), at which point it fires, persists and reaches the
-    /// mirror. Staging the applied value back clears the stage; a stage never committed is not
-    /// what the file gets.
+    /// A latched row's write is staged: the applied value stands and nothing fires or dirties (the
+    /// reference's `Set 0x63df50` stores `latchedValue` and skips `InternalSet`) until the commit
+    /// (`0x63e060`) applies, fires, persists and mirrors it.
     #[test]
     fn a_latched_row_stages_the_write_until_the_boundary_commits_it() {
         let mut cvars = Cvars::default();
@@ -3259,7 +2425,6 @@ mod tests {
             !cvars.compose().contains_key("gxVSync"),
             "a stage that is never committed never reaches the file"
         );
-        // The boundary.
         assert_eq!(cvars.commit_latched(), 1);
         assert_eq!(cvars.get("gxVSync"), Some("0"));
         assert_eq!(cvars.row("gxVSync").unwrap().pending, None);
@@ -3280,13 +2445,11 @@ mod tests {
             cvars.take_outbox(),
             vec![("gxVSync".to_string(), "0".to_string())]
         );
-        // Staging the applied value back over a stage clears the stage, and the next boundary
-        // has nothing to do.
         cvars.set("gxVSync", "1");
         assert_eq!(cvars.set("gxVSync", "0"), SetOutcome::Unchanged);
         assert_eq!(cvars.row("gxVSync").unwrap().pending, None);
         assert_eq!(cvars.commit_latched(), 0);
-        // A latched row outside the gx set is not the video restart's to commit (2343).
+        // A latched row outside the gx set is not the video restart's to commit.
         assert_eq!(cvars.set("SoundBufferSize", "200"), SetOutcome::Staged);
         assert_eq!(cvars.commit_latched(), 0);
         assert_eq!(cvars.get("SoundBufferSize"), Some("100"));
@@ -3295,16 +2458,11 @@ mod tests {
             Some("200")
         );
         assert!(!cvars.compose().contains_key("SoundBufferSize"));
-        // An unlatched row applies at once, fires, and dirties.
         assert_eq!(cvars.set("MusicVolume", "0.7"), SetOutcome::Changed);
         assert_eq!(cvars.get("MusicVolume"), Some("0.7"));
         assert_eq!(cvars.take_events().len(), 1);
     }
 
-    /// **A numeric row refuses what does not parse** — the applied value stands, the mirror
-    /// that already stored the garbage is corrected through the outbox, and nothing fires. The
-    /// old central parse consumed the value and let it into the file; the registry does not.
-    /// A string row takes any string, and its observer is the one that judges it.
     #[test]
     fn a_numeric_row_refuses_what_does_not_parse_and_corrects_the_mirror() {
         let mut cvars = Cvars::default();
@@ -3329,12 +2487,6 @@ mod tests {
         assert_eq!(cvars.set("nosuchrow", "1"), SetOutcome::Unknown);
     }
 
-    /// **An addon-declared row persists like the client's own** (decisions 1195, 1291, 2303):
-    /// the VM reports the registration, the registry gives it a row starting at the file's
-    /// value when the file carries one, a write to it dirties the config, and the save writes it
-    /// as a diff against the addon's default. Before the registry the write reached the VM's
-    /// table and nothing dirtied, so an addon-only change was saved only if something else
-    /// happened to move.
     #[test]
     fn an_addon_row_persists_like_the_clients_own() {
         let mut cvars = registry(&[("myAddonKnob", "3")]);
@@ -3369,7 +2521,6 @@ mod tests {
             !cvars.compose().contains_key("myAddonKnob"),
             "back at the addon's default, it leaves the diff"
         );
-        // A newer build's key stays an orphan and rides through the save verbatim.
         let cvars = registry(&[("FutureKnob", "3")]);
         assert_eq!(
             cvars.compose().get("FutureKnob").map(String::as_str),
@@ -3377,10 +2528,6 @@ mod tests {
         );
     }
 
-    /// **A session-owned row answers the env and never reaches the file**: the value the knob
-    /// is running at is what `GetCVar` answers, the file's own entry for the key is neither
-    /// applied nor rewritten, and a player's write to it during the session still works — it
-    /// just stays out of the diff.
     #[test]
     fn a_session_owned_row_answers_the_env_and_never_reaches_the_file() {
         let mut cvars = Cvars::default();
@@ -3401,18 +2548,15 @@ mod tests {
             Some("0.8"),
             "the file keeps what it said"
         );
-        // A lever whose resource is absent still marks the row, so the file cannot apply over
-        // the env — the registered default stands as the truth.
+        // A lever with no resource still marks the row, so the file cannot apply over the env.
         cvars.own_for_session("farclip", None);
         cvars.load_file(BTreeMap::from([("farclip".to_string(), "500".to_string())]));
         assert_eq!(cvars.get("farclip"), Some("350"));
         assert!(cvars.is_session_owned("FARCLIP"));
     }
 
-    /// **The loaded file reaches a knob synchronously, before anything ordered after
-    /// [`CvarLoad`]** — the observers fire inside the exclusive load, which is what lets the
-    /// camera read `gxMultisample` at spawn (1629) and every other `Startup` reader of a knob
-    /// see the player's value rather than the default.
+    /// The camera reads `gxMultisample` once at spawn, so the file must be applied inside
+    /// [`CvarLoad`].
     #[test]
     fn the_loaded_file_reaches_a_knob_before_anything_ordered_after_cvar_load() {
         use crate::local_state::test_env::{EnvGuard, ENV_LOCK};
@@ -3458,15 +2602,11 @@ mod tests {
         std::fs::remove_dir_all(&tmp).ok();
     }
 
-    /// **Every registered row has a reader** — the honest-tree rule (module doc, 1140), made
-    /// structural now that the registry has no central arm to answer `false` from. A row's
-    /// reader is a string literal naming it somewhere in the crate's code or `benilla-ui`'s (an
-    /// observer's arm in the lowercased spelling, a `cvars.get("…")`, a `const` the row is
-    /// registered through), or the row is named in [`LUA_ONLY`] with the stock file that reads
-    /// it. Test files are not readers.
+    /// Every registered row has a reader: a string literal naming it in this crate's or
+    /// `benilla-ui`'s code, or a `LUA_ONLY` entry naming its stock reader. Test files do not count.
     #[test]
     fn every_registered_row_has_a_reader_in_the_source() {
-        /// Rows whose only reader is the stock interface, by decision.
+        /// Rows whose only reader is the stock interface.
         const LUA_ONLY: &[(&str, &str)] = &[
             (
                 "statusBarText",
@@ -3530,10 +2670,9 @@ mod tests {
         }
     }
 
-    /// The eight rows the reference latches that benilla registers, and no other — read off their
-    /// register sites (`flags` 2 or 3): the sound-init row, and the `gx*` block `RestartGx`
-    /// commits. `trilinear`/`anisotropic`/`farclip` register with `flags = 1` and apply live, so
-    /// they are deliberately not here.
+    /// The rows the reference latches (`flags` 2 or 3 at the register site): the sound-init row and
+    /// the `gx*` block `RestartGx` commits. `trilinear`, `anisotropic` and `farclip` register with
+    /// `flags = 1` and apply live.
     #[test]
     fn the_latched_rows_are_the_references_own() {
         let mut latched: Vec<&str> = REGISTERED
diff --git a/crates/benilla-app/src/death/mod.rs b/crates/benilla-app/src/death/mod.rs
index 62fcf1d1..96cf8e26 100644
--- a/crates/benilla-app/src/death/mod.rs
+++ b/crates/benilla-app/src/death/mod.rs
@@ -1,13 +1,7 @@
-//! The death arc (decision 0308): the wire-fed stores, the state-machine edges into the Lua UI,
-//! the intent drain back to the wire, and the root/water-walk messages the controller acks.
-//!
-//! The state machine is derived, never simulated (0308 §1): dead = health 0, ghost =
-//! `PLAYER_FLAGS` bit 0x10 — read off the self descriptor each frame, edges fired as the
-//! reference's own events (`PLAYER_DEAD` / `PLAYER_ALIVE` / `PLAYER_UNGHOST`, the classic
-//! semantics: ALIVE fires on release *and* on a pre-release res; UNGHOST on ghost → alive). What
-//! lives in [`DeathNet`] is only what the descriptor does not carry: the reclaim-delay expiry
-//! (`SMSG_CORPSE_RECLAIM_DELAY`), the corpse location (`MSG_CORPSE_QUERY`), a pending resurrect
-//! offer (`SMSG_RESURRECT_REQUEST`), and the spirit-healer confirm (`SMSG_SPIRIT_HEALER_CONFIRM`).
+//! Death and resurrection: the wire-fed stores, the events into the Lua UI and the intents back
+//! to the wire. Dead is health 0 and ghost is `PLAYER_FLAGS` bit 0x10, read off the self
+//! descriptor each frame; `PLAYER_ALIVE` fires on release and on a pre-release res,
+//! `PLAYER_UNGHOST` on ghost to alive.
 
 use bevy::prelude::*;
 
@@ -20,146 +14,99 @@ use crate::ui_script::{UiFeed, UiInput};
 
 pub(crate) mod net;
 
-/// Where our corpse is — the `MSG_CORPSE_QUERY` answer (decision 0308 §5). Raw WoW coords.
+/// Where our corpse is, the `MSG_CORPSE_QUERY` answer, in raw WoW coordinates.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub(crate) struct CorpsePoint {
-    /// The map to show/route toward — dungeon-entrance-adjusted server-side (a corpse inside an
-    /// instance points at its `ghostEntranceMap` position instead).
+    /// The map to route toward; for a corpse inside an instance, the entrance's.
     pub(crate) display_map: i32,
-    /// Raw WoW position of the corpse (or the dungeon entrance standing in for it).
+    /// The corpse, or the dungeon entrance standing in for it.
     pub(crate) position: [f32; 3],
-    /// The corpse's REAL map id, never adjusted — the marker shows only while we're on this map
-    /// (or on `display_map` for the entrance stand-in).
-    #[allow(dead_code)] // read by the slice-2 map markers
+    /// The corpse's real map id, never adjusted.
+    #[allow(dead_code)] // for the map markers
     pub(crate) corpse_map: u32,
 }
 
-/// A pending resurrection offer (`SMSG_RESURRECT_REQUEST`) — the RESURRECT popup's data.
+/// A pending resurrection offer (`SMSG_RESURRECT_REQUEST`), the RESURRECT popup's data.
 #[derive(Debug, Clone, PartialEq)]
 pub(crate) struct ResurrectOffer {
-    /// The offerer. The popup answers `CMSG_RESURRECT_RESPONSE` with this guid.
+    /// Answered in `CMSG_RESURRECT_RESPONSE`.
     pub(crate) caster: u64,
-    /// The offerer's display name — EMPTY on the wire for a player caster (the feed resolves it
-    /// through the guid name cache, ask-once, like every other player name).
+    /// Empty on the wire for a player caster, resolved through the name cache.
     pub(crate) name: String,
-    /// Accepting will apply resurrection sickness (picks the RESURRECT popup variant).
+    /// Accepting applies resurrection sickness; picks the popup variant.
     pub(crate) sickness: bool,
-    /// The client should still honor the reclaim-delay gate (RESURRECT vs RESURRECT_NO_TIMER).
+    /// The reclaim-delay gate still holds: RESURRECT, not RESURRECT_NO_TIMER.
     pub(crate) has_timer: bool,
 }
 
-/// The wire-fed death state (decision 0308 §1's death feed). Filled by the net drain; read by the
-/// death UI feed and the corpse-run systems. Cleared on session teardown with the rest of the
-/// net-owned resources.
+/// The death state the descriptor does not carry, filled from the wire and cleared at session
+/// teardown.
 #[derive(Resource, Default)]
 pub(crate) struct DeathNet {
-    /// `Time::elapsed_secs_f64` when the corpse becomes reclaimable — `SMSG_CORPSE_RECLAIM_DELAY`'s
-    /// delay anchored to arrival time (the packet lands at release and at login-while-dead).
-    /// `GetCorpseRecoveryDelay` reads `max(0, reclaim_at − now)`; `None` before any delay landed.
+    /// When the corpse becomes reclaimable: `SMSG_CORPSE_RECLAIM_DELAY` anchored at arrival.
     pub(crate) reclaim_at: Option<f64>,
-    /// Bumped on every `SMSG_CORPSE_RECLAIM_DELAY` — the feed's range latch re-announces on it
-    /// (the client's 0x269 handler re-fires IN_RANGE/IN_INSTANCE through its latch).
+    /// Bumped per `SMSG_CORPSE_RECLAIM_DELAY`: the 1.12 client's handler re-fires the range
+    /// events on each.
     pub(crate) reclaim_generation: u32,
-    /// The corpse location, from the last `MSG_CORPSE_QUERY` answer. `None` = no corpse (also the
-    /// server's unprompted not-found at bones-conversion — "drop the marker").
+    /// The last `MSG_CORPSE_QUERY` answer; a not-found drops it.
     pub(crate) corpse: Option<CorpsePoint>,
     /// A pending resurrection offer; cleared when answered or when the popup times out.
     pub(crate) resurrect: Option<ResurrectOffer>,
-    /// Bumped on every `SMSG_RESURRECT_REQUEST` — the offer announces per MESSAGE (handler
-    /// `0x5e7bc0` signals per arrival through `0x5ded50`), not per
-    /// `Some`-edge. `resurrect` is only cleared by an Accept/Decline, and the stock UI can hide
-    /// the popup without either (PLAYER_UNGHOST's `StaticPopup_Hide` runs no `OnCancel`), so an
-    /// edge latch there swallowed every later offer for the session.
+    /// Bumped per `SMSG_RESURRECT_REQUEST`: the offer announces per message (`0x5e7bc0` through
+    /// `0x5ded50`), because the stock UI can hide the popup without answering it.
     pub(crate) resurrect_generation: u32,
-    /// Our streamed corpse OBJECT's guid (a TYPEID_CORPSE create whose `CORPSE_FIELD_OWNER` is
-    /// us) — what `CMSG_RECLAIM_CORPSE` carries, like the real client. `None` until the corpse
-    /// streams into range (vmangos ignores the guid's content, so a 0 send still reclaims —
-    /// the real-client shape is kept where we have it).
+    /// Our streamed corpse object's guid, which `CMSG_RECLAIM_CORPSE` carries like the 1.12 client.
     pub(crate) corpse_guid: Option<u64>,
-    /// The spirit healer whose confirm (`SMSG_SPIRIT_HEALER_CONFIRM`) is awaiting the XP_LOSS
-    /// two-step; its Accept sends `CMSG_SPIRIT_HEALER_ACTIVATE` with this guid.
+    /// The spirit healer awaiting the XP-loss answer; Accept sends `CMSG_SPIRIT_HEALER_ACTIVATE`.
     pub(crate) spirit_healer: Option<u64>,
-    /// Bumped on every `SMSG_SPIRIT_HEALER_CONFIRM` — the confirm announces per MESSAGE, not per
-    /// Some-edge (decision 1068): a Cancel sends nothing and clears nothing, so only a fresh
-    /// message can re-show the dialog, and the healer re-sends one on every gossip ask.
+    /// Bumped per ask: a Cancel clears nothing, so only a fresh ask re-shows the dialog.
     pub(crate) confirm_generation: u32,
-    /// Water-walking is granted on our mover (the ghost's walk-on-water). Mirrored for the swim
-    /// arc's future mover regime (0308 defers the actual water-surface walk); the ack itself is
-    /// the controller's.
+    /// Water-walking is granted on our mover; mirrored, not applied: walking on the water surface
+    /// is not built.
     #[allow(dead_code)]
     pub(crate) water_walk: bool,
 }
 
 impl DeathNet {
-    /// **Arm the spirit healer's XP-loss question** — the one entry point, because there are two
-    /// ways to arrive at it and they must not drift.
-    ///
-    /// The reference raises this dialog **client-side, on the click**: `0x5f0130`'s bit-5 arm
-    /// (`0x5df730`) sends no packet at all — it caches the healer's guid and fires
-    /// `CONFIRM_XP_LOSS`, and `CMSG_SPIRIT_HEALER_ACTIVATE` belongs to the Lua Accept
-    /// (`AcceptXPLoss`), which calls the same function with a ZERO guid. vmangos also *pushes* the
-    /// question as `SMSG_SPIRIT_HEALER_CONFIRM` off its gossip route, and benilla honours both
-    /// roads in.
-    ///
-    /// The generation bump is what makes a re-ask re-show a cancelled dialog: the confirm
-    /// announces per MESSAGE, not per `Some`-edge (decision 1068).
+    /// Arm the spirit healer's XP-loss question. The reference raises it on the click with no
+    /// packet (`0x5df730`), and vmangos also pushes `SMSG_SPIRIT_HEALER_CONFIRM`; both come here.
     pub(crate) fn ask_spirit_healer(&mut self, npc: u64) {
         self.spirit_healer = Some(npc);
         self.confirm_generation = self.confirm_generation.wrapping_add(1);
     }
 }
 
-/// The feed's memory, in **two scopes** (decisions 1290/1291): the body's own state machine is
-/// world memory and survives a `/reload`; what this VM has been *told* dies with the VM.
-///
-/// The reference draws the same line by construction — its death mirror is engine-side
-/// (`[0xb4e340]`), so a `ReloadUI` neither re-arms the release window nor loses it, while the
-/// rebuilt UI repaints from the surviving state. Ours mirrors that: `mirror`/`died_at` stay put
-/// across a VM replacement, and the announce latches reset with the VM so the fresh frame tree
-/// hears the events the old one consumed.
+/// The feed's memory in two scopes: the body's state survives a `/reload`, as the reference's
+/// engine-side death mirror (`[0xb4e340]`) does, while what the VM was told dies with the VM.
 #[derive(Resource, Default)]
 struct DeathFeedState {
-    /// **World-scoped.** The last `(guid, dead, ghost)` the self body showed — the edge that
-    /// arms and clears the release window. `None` before a world session's first snapshot.
+    /// World-scoped: the last `(guid, dead, ghost)` the self body showed.
     mirror: Option<(u64, bool, bool)>,
-    /// **World-scoped.** `Time::elapsed_secs_f64` at the death edge — the anchor of the
-    /// client-side release window (the wire carries only the PLAYER_FIELD_BYTES timer BIT; the
-    /// client arms `now + 360000 ms` (`0x5e9a30`) at its own
-    /// alive→dead mirror-edge — so a login-while-dead re-arms at login exactly like ours, and
-    /// expiry reads 0, never negative). Deliberately NOT per-VM: a `/reload` must not restart
-    /// the six minutes — the reference's engine-side window keeps running through one.
+    /// World-scoped: the death edge, anchoring the release window. The wire carries only the
+    /// timer bit; the 1.12 client arms `now + 360000 ms` at its own death edge (`0x5e9a30`).
     died_at: Option<f64>,
-    /// **VM-scoped** — the announce latches, keyed on the VM they announced to.
+    /// VM-scoped: the announce latches.
     vm: crate::ui_script::VmMemo<DeathAnnounced>,
 }
 
-/// What the live VM has been told about the death state — [`DeathFeedState::vm`]'s payload
-/// (guid-keyed, first-snapshot-counts-as-edge so logging in dead brings the popup up — and so
-/// does reloading dead, which is the same situation from the frame tree's point of view).
+/// What the live VM has been told; a first snapshot counts as an edge, so logging in or
+/// reloading dead brings the popup up.
 #[derive(Default)]
 struct DeathAnnounced {
-    /// The last `(guid, dead, ghost)` THIS VM was given an event for; `None` for a fresh VM.
+    /// The last `(guid, dead, ghost)` this VM was given an event for.
     last: Option<(u64, bool, bool)>,
-    /// The last corpse-range verdict announced to the UI (`None` = nothing announced): the
-    /// CORPSE_IN_RANGE / CORPSE_OUT_OF_RANGE / CORPSE_IN_INSTANCE edge memory (decision 0308 §5).
+    /// The last corpse-range verdict announced.
     corpse_range: Option<CorpseRange>,
-    /// The [`DeathNet::reclaim_generation`] this latch last saw — a fresh `0x269` re-fires the
-    /// range events through the latch (the client's own re-announce, `0x4962d0`), so the
-    /// RECOVER_CORPSE popup re-shows with the new delay.
+    /// A fresh reclaim delay re-fires the range events, as the 1.12 client does (`0x4962d0`),
+    /// so RECOVER_CORPSE re-shows with the new delay.
     reclaim_generation: u32,
-    /// The [`DeathNet::resurrect_generation`] this VM was last told about (`RESURRECT_REQUEST`
-    /// fired) — held back while a player-caster's name is still resolving through the name cache.
+    /// Held back while a player caster's name is still resolving.
     offer_generation: u32,
-    /// The [`DeathNet::confirm_generation`] this latch last announced — a fresh
-    /// `SMSG_SPIRIT_HEALER_CONFIRM` re-fires `CONFIRM_XP_LOSS` through the latch (decision 1068;
-    /// the reclaim-latch pattern above). The old Some-edge latch here was B80's deadlock: it
-    /// reset only when `spirit_healer` went `None`, which nothing but Accept ever does, so one
-    /// Cancel swallowed every later confirm.
+    /// A fresh ask re-fires `CONFIRM_XP_LOSS`.
     confirm_generation: u32,
 }
 
-/// The three corpse-range verdicts the reference's events distinguish (RECOVER_CORPSE /
-/// hide / RECOVER_CORPSE_INSTANCE).
+/// The corpse-range verdicts the reference's events distinguish.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum CorpseRange {
     Out,
@@ -167,38 +114,29 @@ enum CorpseRange {
     InInstance,
 }
 
-/// The server's forced-release window (vmangos `CORPSE_REPOP_TIME` = 6 min) — the client-side
-/// mirror both sides know; never on the wire.
+/// The forced-release window, vmangos `CORPSE_REPOP_TIME` (`Player.h:71`); never on the wire.
 const RELEASE_WINDOW_SECS: f64 = 360.0;
 
-/// The corpse-range dialog radius — **40.0 yd, inclusive** (the client compares
-/// d² ≤ `[0xb4e2ac]` = 1600.0 per frame against the corpse-QUERY cache, never
-/// the streamed corpse object; edge-latched, no hysteresis). vmangos's `CORPSE_RECLAIM_RADIUS 39`
-/// comment "equal client dialog show radius" is off by one against the client's own constant —
-/// the server reclaim gate simply sits 1 yd inside the dialog radius. Squared yards.
+/// The corpse-range dialog radius, 40 yd inclusive: the 1.12 client compares d² ≤ `[0xb4e2ac]`
+/// (1600.0) against the corpse-query position. The server's reclaim gate,
+/// `CORPSE_RECLAIM_RADIUS` 39 (`Corpse.h:40`), sits 1 yd inside it.
 const CORPSE_RANGE_SQ: f32 = 40.0 * 40.0;
 
-/// The spirit-healer dialog range (CheckSpiritHealerDist
-/// compares d² ≤ `[0xc4c28c]` = 30.864 = 5.5556², the service interaction range). Squared yards.
+/// The spirit-healer dialog range: `CheckSpiritHealerDist` compares d² ≤ `[0xc4c28c]` (30.864).
 const SPIRIT_HEALER_RANGE_SQ: f32 = 5.5556 * 5.5556;
 
-/// Per-frame: derive the death state from the self descriptor, push the countdown/offer snapshot,
-/// and fire the reference's death events on the edges (before `UiInput`, so a frame's `OnEvent`
-/// sees current values — the [`crate::ui_unit`] feed convention).
+/// Derive the death state from the self descriptor, push the snapshot, and fire the death events
+/// on its edges.
 fn feed_death(
     script: Option<NonSendMut<UiScript>>,
     self_q: Query<(&ObjectStore, &Transform), With<SelfPlayer>>,
     self_guid: Res<SelfGuid>,
     death_net: Res<DeathNet>,
-    // Real, not virtual: this reads a stamp the net apply path wrote on `Time<Real>` (see the
-    // aura tuple there) — a server-sent countdown lives in real seconds, and the two ends of the
-    // comparison must be the same clock.
+    // Real time: `reclaim_at` is stamped on `Time<Real>` by the net path.
     time: Res<Time<Real>>,
     mut feed: ResMut<DeathFeedState>,
     names: Res<crate::names::NameCache>,
     net: Res<NetCommands>,
-    // The object lookup (2334) — the spirit healer's entity, and the bag walk the self-res
-    // item leg takes.
     objects: Objects,
     transforms: Query<&Transform>,
     map: Option<Res<benilla_world::world_map::CurrentMap>>,
@@ -206,14 +144,8 @@ fn feed_death(
     spells: Option<Res<Spells>>,
     items: Res<crate::items::Items>,
 ) {
-    // **Only a LIVE session's descriptor is a snapshot** (decision 1732). A reconnect-able
-    // disconnect keeps the self avatar as the local puppet (0065) — descriptor and all — so
-    // without this gate the frames between the socket dying and the reconnect landing would
-    // re-arm `mirror` from a frozen relic, and the reconnect would then find no edge to fire.
-    // That is the same hole from the other side as [`end_session_death_feed`]: the body's state
-    // machine may only be driven by the wire, and while there is no wire there is nothing to
-    // mirror. (The `/logout` path needs no gate — the avatar is despawned, so the `self_q` below
-    // already ends the feed.)
+    // A disconnect keeps the self avatar with its frozen descriptor; only a live session's
+    // descriptor may drive the state machine.
     if !status.connected {
         return;
     }
@@ -230,12 +162,12 @@ fn feed_death(
     let dead = store.0.unit_is_dead();
     let ghost = store.0.player_is_ghost();
 
-    // ── The snapshot (set before the events fire, so their handlers read current values) ──────
+    // ── The snapshot, set before the events fire so their handlers read current values ──
     let release_remaining = if store.0.player_release_timer_running() {
         feed.died_at
             .map(|t| ((t + RELEASE_WINDOW_SECS - now).max(0.0)) as f32)
     } else {
-        None // → GetReleaseTimeRemaining() == −1, the no-timer DEATH text
+        None // GetReleaseTimeRemaining() == -1, the no-timer DEATH text
     };
     let recovery_delay = death_net
         .reclaim_at
@@ -248,8 +180,7 @@ fn feed_death(
                 t.translation.distance_squared(self_t.translation) <= SPIRIT_HEALER_RANGE_SQ
             })
     });
-    // Resolved before the push, because the lookup borrows the VM and `set_death` needs it
-    // mutably.
+    // Resolved first: the lookup borrows the VM that `set_death` needs mutably.
     let sickness = sickness_duration(store.0.unit_level().unwrap_or(0), &|key: &str| {
         script
             .lua()
@@ -265,54 +196,44 @@ fn feed_death(
         resurrect_has_timer: death_net.resurrect.as_ref().is_some_and(|o| o.has_timer),
         spirit_healer_in_range,
         sickness_duration: sickness,
-        // `HasSoulstone()` — see [`resolve_self_res`] for the three gates and their order. Not a
-        // per-frame inventory walk in general: the dead gate is first, so while alive this is one
-        // health read, and while dead-unreleased the walk only runs on a zero field.
+        // `HasSoulstone()`; the dead gate is first, so the inventory walk runs only while dead.
         self_res_label: resolve_self_res(&store.0, &objects, &items, spells.as_deref(), &net)
             .map(|r| r.label().to_owned()),
     });
 
-    // ── The WORLD edges (the body's own state machine): the release-window anchor and the
-    // corpse asks. These run off `mirror`, which survives a VM replacement — a `/reload` while
-    // dead must neither restart the six minutes nor re-query the corpse (the cache has it).
+    // ── The world edges: the release window and the corpse asks, which a `/reload` must not
+    // repeat.
     let prev = feed.mirror.filter(|&(g, ..)| g == guid);
     feed.mirror = Some((guid, dead, ghost));
     match (prev, dead, ghost) {
-        // Alive → dead (and the login-while-dead first snapshot): arm the release window.
+        // Alive to dead, or logging in dead: arm the release window.
         (Some((_, false, false)) | None, true, false) => {
             feed.died_at = Some(now);
         }
-        // Dead-unreleased → ghost (the release landed), or → alive (a pre-release res).
+        // Dead to ghost (released), or to alive (a pre-release res).
         (Some((_, true, false)), d, g) if g || !d => {
             feed.died_at = None;
             if g {
-                // Now a ghost: ask where the corpse is (feeds the slice-2 markers + range gate).
+                // Now a ghost: ask where the corpse is.
                 let _ = net.0.send(ClientCommand::CorpseQuery);
             }
         }
-        // Ghost → alive (reclaim / spirit healer / accepted res).
+        // Ghost to alive: reclaim, spirit healer or an accepted res.
         (Some((_, _, true)), false, false) => {
             feed.died_at = None;
-            // Re-ask where the corpse is — the answer is the authoritative NOT-FOUND that drops
-            // the map markers. The server's own "corpse gone" push is LOOTER-gated (vmangos
-            // Map.cpp:3617-3629: the unprompted u8(0) goes out only when a PvP looter exists), so
-            // a PvE res never gets one; the real client re-runs its corpse query off the same
-            // ghost-bit edge (the watcher `0x5ee990`), and post-res the player→corpse
-            // binding is gone (SpawnCorpseBones unbinds), so the answer clears the cache.
-            // Director-reported: the map tombstone survived a spirit-healer res without this.
+            // The 1.12 client re-queries on the ghost-bit edge (`0x5ee990`), and the not-found
+            // answer drops the map markers; the server's own push is sent only with a looter
+            // (`Map.cpp:3617-3629`).
             let _ = net.0.send(ClientCommand::CorpseQuery);
         }
-        // Logging in already a ghost: no edge, just the corpse ask.
+        // Logging in a ghost: no edge, just the corpse ask.
         (None, _, true) => {
             let _ = net.0.send(ClientCommand::CorpseQuery);
         }
         _ => {}
     }
 
-    // ── The VM edges: the classic events, fired off what THIS VM has heard (module doc). A
-    // fresh VM's memo is empty, so a reload-while-dead re-fires PLAYER_DEAD to the rebuilt
-    // frame tree — the same first-snapshot-counts-as-edge that brings the popup up at a
-    // login-while-dead, which is our design's own posture for both (decision 1291).
+    // ── The VM edges: a fresh VM's memo is empty, so reloading dead re-fires PLAYER_DEAD.
     let memo = feed.vm.get(&script);
     let prev = memo.last.filter(|&(g, ..)| g == guid);
     memo.last = Some((guid, dead, ghost));
@@ -329,10 +250,9 @@ fn feed_death(
         _ => {}
     }
 
-    // ── The offer/confirm announcements (edge-fired, name-gated) ───────────────────────────────
+    // ── The offer and confirm announcements ──
     if let Some(name) = offer_announcement(memo, &death_net, dead || ghost, |offer| {
-        // A player caster's wire name is empty — resolve through the ask-once name cache and
-        // hold the popup until it lands (the ref popup formats "%s wants to resurrect you").
+        // A player caster's name is empty on the wire; hold the popup until the cache resolves it.
         if offer.name.is_empty() {
             names.resolve(offer.caster, &net).map(str::to_owned)
         } else {
@@ -341,29 +261,12 @@ fn feed_death(
     }) {
         script.fire_event("RESURRECT_REQUEST", vec![ScriptValue::Str(name)]);
     }
-    // The confirm is message-fired, not state-edged (decision 1068): each SMSG bumps the
-    // generation, so asking the healer again after a Cancel brings the dialog back.
     if death_net.spirit_healer.is_some() && memo.confirm_generation != death_net.confirm_generation
     {
         memo.confirm_generation = death_net.confirm_generation;
-        // **`arg1` is the XP the resurrection will cost** — byte-read at the fire site
-        // (`0x5df837`, `SignalEvent2(396, "%d", …)`), because the argument gate (2140) found this
-        // fired argless and the shapes table says one number:
-        //
-        // ```
-        // 5df80f  mov ecx,[ebx+0xe68]          ; the player's descriptor window
-        // 5df815  mov edx,[ecx+0x844]          ; +0x844 -> field 188 + 529 = PLAYER_NEXT_LEVEL_XP
-        // 5df81e  fild [ebp+8]
-        // 5df821  fmul ds:0x80ae90             ; 0.05f
-        // 5df827  call 0x40a2b0                ; _ftol — TRUNCATES, not rounds
-        // ```
-        //
-        // and `0x5df806`'s arm pushes **0** when the object is not the local player, which is why
-        // an absent field answers 0 here rather than suppressing the event.
-        //
-        // Nothing in 1.12 FrameXML reads it — `UIParent.lua:399` asks `GetResSicknessDuration()`
-        // instead — so this is fidelity for the callers that are not ours, exactly 1776's reason
-        // for settling `PLAYERBANKSLOTS_CHANGED`'s shape when nothing read that either.
+        // `arg1` is the XP the res costs: `PLAYER_NEXT_LEVEL_XP` × 0.05, truncated (`0x5df837`),
+        // and 0 without the field, as `0x5df806` pushes 0 for a non-local object. No stock
+        // FrameXML reads it; `UIParent.lua:399` asks `GetResSicknessDuration()`.
         let xp_cost = store
             .0
             .player_next_level_xp()
@@ -371,16 +274,12 @@ fn feed_death(
         script.fire_event("CONFIRM_XP_LOSS", vec![ScriptValue::Int(xp_cost)]);
     }
 
-    // ── The corpse-run range gate (0308 §5): fires the reference's range events on the edges. ──
-    // Only a ghost runs its corpse; the verdict compares 3-D distance to the query's DISPLAY
-    // position (for a dungeon corpse that's the entrance — standing there with the corpse on
-    // another map is exactly the CORPSE_IN_INSTANCE case). Distances are isometric across the
-    // coord transform, so the Bevy-space compare is the yard compare.
+    // ── The corpse-run range gate: only a ghost, against the query's display position; the
+    // coordinate transform is isometric, so the Bevy-space compare is in yards.
     let range = if ghost {
         death_net.corpse.map(|cp| {
-            // The client's own law (`0x492130`, `0x4920f0`): within 40 yd (inclusive) of the QUERY
-            // cache position, on the display map → IN_RANGE when displayMapId == corpseMapId,
-            // else IN_INSTANCE (standing at a dungeon's ghost entrance, corpse inside).
+            // Within range on the display map: IN_RANGE when it is the corpse's map, else
+            // IN_INSTANCE, at a dungeon's entrance (`0x492130`, `0x4920f0`).
             let on_display_map = map
                 .as_ref()
                 .is_some_and(|m| m.0 == u32::try_from(cp.display_map).unwrap_or(u32::MAX));
@@ -398,14 +297,13 @@ fn feed_death(
     };
     if memo.reclaim_generation != death_net.reclaim_generation {
         memo.reclaim_generation = death_net.reclaim_generation;
-        memo.corpse_range = None; // re-announce whatever holds now (the client's 0x269 re-fire)
+        memo.corpse_range = None; // re-announce whatever holds now
     }
     if range != memo.corpse_range {
         match range {
             Some(CorpseRange::In) => script.fire_event("CORPSE_IN_RANGE", vec![]),
             Some(CorpseRange::InInstance) => script.fire_event("CORPSE_IN_INSTANCE", vec![]),
-            // Leaving range — and the corpse/ghost state ENDING while a range dialog could be
-            // up — both land on the same hide event (the ref's OUT arm hides all three).
+            // Leaving range and the ghost state ending both fire the one hide event.
             Some(CorpseRange::Out) | None if memo.corpse_range.is_some() => {
                 script.fire_event("CORPSE_OUT_OF_RANGE", vec![]);
             }
@@ -415,23 +313,21 @@ fn feed_death(
     }
 }
 
-/// `SPELL_EFFECT_SELF_RESURRECT` — `Spell.dbc`'s effect-slot value the client's item leg scans for
-/// (`0x5ed650`, `cmp … 0x5e`). Exactly eleven 1.12 spells carry it.
+/// `SPELL_EFFECT_SELF_RESURRECT`, the `Spell.dbc` effect the item leg scans for (`0x5ed650`).
 const SPELL_EFFECT_SELF_RESURRECT: u32 = 94;
 
-/// What a `UseSoulstone()` would spend right now — the client's own two-legged fork
-/// (`Script::UseSoulstone 0x48ad70`), resolved app-side because neither
-/// leg's inputs (the spell catalog, the item cache) are bound in the script VM.
+/// What `UseSoulstone()` (`0x48ad70`) would spend now; resolved app-side, where the spell catalog
+/// and item cache live.
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) enum SelfRes {
-    /// `PLAYER_SELF_RES_SPELL` is non-zero — send `CMSG_SELF_RES` and let the server cast it.
+    /// `PLAYER_SELF_RES_SPELL` is non-zero: send `CMSG_SELF_RES` and the server casts it.
     Spell {
-        #[allow(dead_code)] // the wire needs no id: the server reads its own field
+        #[allow(dead_code)] // the server reads its own field
         spell: u32,
         label: String,
     },
-    /// The field is zero, but a carried item's ON-USE spell self-resurrects — the client **uses
-    /// the item** instead, and labels the button with the ITEM's name.
+    /// The field is zero but a carried item's on-use spell self-resurrects: use the item, named
+    /// for the item.
     Item {
         bag_index: u8,
         slot: u8,
@@ -442,7 +338,7 @@ pub(crate) enum SelfRes {
 }
 
 impl SelfRes {
-    /// The button text — what `HasSoulstone()` returns.
+    /// What `HasSoulstone()` returns.
     fn label(&self) -> &str {
         match self {
             Self::Spell { label, .. } | Self::Item { label, .. } => label,
@@ -450,27 +346,15 @@ impl SelfRes {
     }
 }
 
-/// **`HasSoulstone()`'s whole answer**, and `UseSoulstone()`'s routing — one resolver, because the
-/// binary is one predicate the two bindings share (`0x48ac80`, `0x48ad70`).
+/// `HasSoulstone()`'s answer and `UseSoulstone()`'s routing, one predicate in the 1.12 client
+/// (`0x48ac80`, `0x48ad70`), with its gates in its order:
 ///
-/// Three gates in the client's own order, and the order is the performance story as much as the
-/// fidelity one:
+/// 1. Dead: nil while `UNIT_FIELD_HEALTH` is positive; a released ghost has health 1.
+/// 2. The field: non-zero is the spell leg, named from `Spell.dbc`, `"UNKNOWN"` when unresolved.
+/// 3. On a zero field, the carried inventory at the walker's default mask (`0x47`) for an item
+///    whose on-use spell carries [`SPELL_EFFECT_SELF_RESURRECT`].
 ///
-/// 1. **Dead.** `HasSoulstone` reads `UNIT_FIELD_HEALTH` (signed) and answers nil while it is
-///    positive — so it speaks only inside the pre-release dead window, which is exactly where the
-///    DEATH dialog lives. A released ghost has health **1** (vmangos `BuildPlayerRepop`), so it
-///    stops answering the moment you release, and the walk below never runs while alive.
-/// 2. **The field.** Non-zero → the spell leg, named through `Spell.dbc`. An id the catalog cannot
-///    resolve is **`"UNKNOWN"`**, not nil — the client pushes that literal rather than hiding the
-///    button, and hiding it would silently strip a self-res the server is holding for us.
-/// 3. **The carried item.** Only on a zero field: the reference's own inventory walker at its
-///    default section mask (gear + bags + backpack + keyring, no bank, no buyback — which is
-///    [`InventoryScope::DEFAULT`], the same `0x47` the walker rewrites to) for an item with an
-///    ON-USE (`trigger == 0`) spell carrying [`SPELL_EFFECT_SELF_RESURRECT`] in any effect slot.
-///    The label is the **item's** name.
-///
-/// A template still in flight can't be judged and reads as "not a self-res"; the ask-once query
-/// the lookup fires answers within a frame or two and the next resolve sees it.
+/// An item template still in flight reads as no self-res until it lands.
 fn resolve_self_res(
     store: &benilla_protocol::ObjectFields,
     objects: &Objects,
@@ -487,8 +371,6 @@ fn resolve_self_res(
             .map_or_else(|| "UNKNOWN".to_owned(), |d| d.name.clone());
         return Some(SelfRes::Spell { spell, label });
     }
-    // Collected first, then judged — `has_key`'s own idiom: the walk reads the object index,
-    // the judging reads the ask-once template cache beside it.
     let slots = crate::ui_items::collect_inventory(
         store,
         objects,
@@ -515,22 +397,12 @@ fn resolve_self_res(
     })
 }
 
-/// The sickness-duration string a spirit-healer res would apply at `level` — the verified server
-/// table (vmangos `Player::ResurrectPlayer` + `Death.SicknessLevel` 11, 0308 §6): nil below 11,
-/// `(level − 10)` minutes through 19, the aura's full 10 minutes from 20.
+/// The sickness a spirit-healer res applies at `level`, per vmangos `Player::ResurrectPlayer`:
+/// none below 11, `level - 10` minutes through 19, 10 minutes from 20. Worded with `GENERIC_MIN`,
+/// the minute arm of the reference's formatter (`0x51a3a0` into `0x52fa50`).
 ///
-/// **The wording is the `GENERIC_MIN`/`GENERIC_MIN_P1` pair, read off the player's own
-/// `GlobalStrings.lua`** (decision 2045). That is the reference's own key: `GetResSicknessDuration`
-/// (`0x51a3a0`) computes a millisecond duration off `Spell.dbc` 15007 × `SpellDuration.dbc` and
-/// hands it to the shared formatter `0x52fa50(ms, "GENERIC", 0, 1)`, whose minute arm is
-/// `GENERIC_MIN[_P1]` with `ms / 60000`. Every value this table can produce — 1 to 10 minutes —
-/// lands in that arm, so the day/hour/second arms have no case here and the ladder is not
-/// reproduced.
-///
-/// **What benilla still models differently, deliberately:** the *number* comes from vmangos's
-/// server-side table rather than from `Spell.dbc`'s `Base + PerLevel·level`, because the aura the
-/// server actually applies is what the dialog must warn about. The `≤ 999 ms → nil` gate the
-/// reference gets from that data is our `0..=10 => None` row.
+/// Deviation: the minutes come from the server's table, not from spell 15007's `Spell.dbc`
+/// duration, because the aura the server applies is what the dialog must warn about.
 fn sickness_duration(level: u32, get: &dyn Fn(&str) -> Option<String>) -> Option<String> {
     let minutes = match level {
         0..=10 => return None,
@@ -545,11 +417,8 @@ fn sickness_duration(level: u32, get: &dyn Fn(&str) -> Option<String>) -> Option
     ))
 }
 
-/// Drive the ghost-world look (decision 0308 §7): the FFXDeath screen pass gates on
-/// `PLAYER_FLAGS_GHOST` — instant on release, instant off at resurrect (the flag's CMirrorHandler
-/// watcher `0x5ee990` is the single driver of the FFX pass swap,
-/// the death light profile, and the ghost ambience — one watcher, several consumers; ours splits
-/// the consumers across their owning systems off the same derived flag).
+/// Drive the FFXDeath screen pass off `PLAYER_FLAGS_GHOST`, instant both ways; in the reference
+/// the flag's watcher `0x5ee990` also drives the death light and ambience.
 fn drive_death_look(
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
     mut ffx: ResMut<benilla_world::ffx_glow::FfxDeathFade>,
@@ -562,16 +431,9 @@ fn drive_death_look(
     }
 }
 
-/// `WOW_GHOST_PROBE=1|0` — pin the **ghost world** on or off without dying, so the ghost-world look
-/// (and everything that must NOT inherit it — the portrait bakes, decision 1481) can be A/B'd from a
-/// capture instead of from a corpse run.
-///
-/// It drives all three halves of that look together, because they are one state: this screen pass,
-/// the death light (`LightParams` slot 4) and the DeathClouds sky, the latter two through
-/// [`Viewer::ghost`](benilla_world::view::Viewer::ghost), whose only readers they are. It pinned
-/// the screen pass alone until the sky landed, which made an A/B of "the ghost world" quietly a
-/// third of one. The death arc's state machine, its events and its UI stay untouched and still
-/// follow the wire.
+/// `WOW_GHOST_PROBE=1|0`: pin the ghost-world look on or off without dying: the screen pass,
+/// the death light (`LightParams` slot 4) and the DeathClouds sky. The death events still follow
+/// the wire.
 pub(crate) fn ghost_probe() -> Option<bool> {
     static PROBE: std::sync::OnceLock<Option<bool>> = std::sync::OnceLock::new();
     *PROBE.get_or_init(|| match std::env::var("WOW_GHOST_PROBE").ok()?.trim() {
@@ -581,8 +443,7 @@ pub(crate) fn ghost_probe() -> Option<bool> {
     })
 }
 
-/// Per-frame (after `UiInput`, so this frame's clicks drain this frame): map the queued Lua death
-/// intents onto the wire.
+/// Map the queued Lua death intents onto the wire, after `UiInput` so a click drains that frame.
 fn drain_death(
     script: Option<NonSendMut<UiScript>>,
     mut death_net: ResMut<DeathNet>,
@@ -590,9 +451,7 @@ fn drain_death(
     targeting: crate::spell::cast_target::CastTargeting,
     mut ladder: crate::spell::CastLadder,
     mut ui_errors: ResMut<crate::ui_action::UiErrorKeys>,
-    // The soulstone leg is a real arm-290 caller in the reference (290 = `0x5d8d00` ←
-    // UseSoulstone · UseInventoryItem · UseAction · UseContainerItem),
-    // so it goes through the shared send carrying the same bind gate every other item use does.
+    // The soulstone's item leg is an item use (`0x5d8d00`), so it carries the bind gate.
     mut gate: crate::ui_bind_confirm::BindGate,
 ) {
     let Some(mut script) = script else {
@@ -601,10 +460,8 @@ fn drain_death(
     for action in script.take_death_actions() {
         let _ = match action {
             DeathAction::Repop => net.0.send(ClientCommand::RepopRequest),
-            // The corpse guid: the streamed corpse object's, when it reached view range (the
-            // real client's shape); else 0 — vmangos never reads the content (it resolves the
-            // corpse via the player, MiscHandler.cpp:573-603), and inside 39 yd the object has
-            // long streamed anyway.
+            // Else 0: vmangos resolves the corpse through the player and never reads the guid
+            // (`MiscHandler.cpp:573-603`).
             DeathAction::RetrieveCorpse => net.0.send(ClientCommand::ReclaimCorpse {
                 corpse: death_net.corpse_guid.unwrap_or(0),
             }),
@@ -615,21 +472,15 @@ fn drain_death(
                         caster: offer.caster,
                         accept,
                     }),
-                    None => Ok(()), // stale click after the offer timed out — nothing to answer
+                    None => Ok(()), // the offer timed out; nothing to answer
                 }
             }
             DeathAction::AcceptXpLoss => match death_net.spirit_healer.take() {
                 Some(npc) => net.0.send(ClientCommand::SpiritHealerActivate { npc }),
                 None => Ok(()),
             },
-            // The self-resurrect button — the client's own two-legged fork, **re-resolved
-            // here at click time** rather than remembered from the frame the dialog opened. That
-            // is the reference's posture too: its `OnCancel` calls `HasSoulstone()` again before
-            // branching, because the field belongs to the server and can have been spent since.
-            //
-            // Nothing is taken or cleared on our side on either leg: the server owns
-            // `PLAYER_SELF_RES_SPELL` and zeroes it as it casts, so the button's disappearance is
-            // a descriptor delta like every other death-arc confirmation.
+            // Re-resolved at click time, as the reference's `OnCancel` calls `HasSoulstone()`
+            // again; nothing is cleared here, the server zeroes `PLAYER_SELF_RES_SPELL`.
             DeathAction::UseSoulstone => {
                 let store = targeting.self_store.single().ok().map(|s| s.0.clone());
                 match store.as_ref().and_then(|store| {
@@ -642,9 +493,7 @@ fn drain_death(
                     )
                 }) {
                     Some(SelfRes::Spell { .. }) => net.0.send(ClientCommand::SelfRes),
-                    // The item leg is an ordinary item use — the same `CGItem_C::Use 0x5d8d00`
-                    // every bag click and action button ends at, which is why it goes through the
-                    // one send rather than growing a second path (decision 0914).
+                    // An ordinary item use, `0x5d8d00`, like every bag click.
                     Some(SelfRes::Item {
                         bag_index,
                         slot,
@@ -678,8 +527,7 @@ fn drain_death(
                         );
                         Ok(())
                     }
-                    // Nothing to spend — the reference's silent return (it pushes nothing and
-                    // sends nothing on this path either).
+                    // Nothing to spend: the reference returns silently.
                     None => Ok(()),
                 }
             }
@@ -687,25 +535,8 @@ fn drain_death(
     }
 }
 
-/// **The world scope of [`DeathFeedState`] dies with the world session** (decision 1732) — the
-/// teardown [`DeathNet`]'s own has had since 0065, which this half never got.
-///
-/// `mirror` is the body's state machine and `died_at` its release-window anchor; both are
-/// deliberately not per-VM, so a `/reload` cannot restart the six minutes. But "not per-VM" was
-/// implemented as "never cleared", and the two scopes then disagreed across a relog: the session
-/// teardown resets `DeathNet` (corpse marker included) while `mirror` still read
-/// `(same guid, dead, ghost)` from before the socket died. Re-entering the world as a ghost
-/// therefore matched **no** arm of the world-edge machine — `(None, _, true)`, the "logging in
-/// already a ghost" arm, needs `prev == None` — so `MSG_CORPSE_QUERY` was never re-sent, the
-/// corpse cache stayed empty, the range gate could not fire `CORPSE_IN_RANGE`, and the
-/// **RECOVER_CORPSE ("Resurrect Now") popup never came up again after a relog**
-/// (director-reported, 2026-08-30).
-///
-/// The guid filter on `mirror` looked like it covered this and does not: it distinguishes a
-/// *different* character, not the *same* one re-entering the world. `DisconnectedMessage` is the
-/// one total edge — a socket death, a kick, and a `/logout` all reach it (the IO thread emits a
-/// `Disconnected` behind `SessionEnd::LoggedOut`) — and it is the very edge `DeathNet` is reset
-/// on, which is what keeps the two scopes in lockstep by construction rather than by memory.
+/// Clear [`DeathFeedState`]'s world scope on `DisconnectedMessage`, the edge [`DeathNet`] resets
+/// on: a relog as a ghost must find no mirror, or the corpse query is never re-sent.
 fn end_session_death_feed(
     mut msgs: MessageReader<crate::net::DisconnectedMessage>,
     mut feed: ResMut<DeathFeedState>,
@@ -715,8 +546,7 @@ fn end_session_death_feed(
     }
 }
 
-/// The death arc's app plugin (decision 0308): the net-fed stores, the state-machine feed + the
-/// intent drain, and the controller-facing root/water-walk messages.
+/// The death stores, the feed into the UI, the intent drain and the root and water-walk messages.
 pub(crate) struct DeathPlugin;
 
 impl Plugin for DeathPlugin {
@@ -730,21 +560,15 @@ impl Plugin for DeathPlugin {
                     feed_death.in_set(UiFeed),
                     drain_death.after(UiInput),
                     drive_death_look,
-                    // Before the feed, so the frame a session ends is already a frame the feed
-                    // sees no memory of the last one.
+                    // Before the feed, so the frame a session ends carries no memory of it.
                     end_session_death_feed.before(feed_death),
                 ),
             );
     }
 }
 
-/// The name `RESURRECT_REQUEST` should fire with this frame, if it should — and the latch
-/// advanced when it does.
-///
-/// Per message, gated on the dead predicate: `0x5ded50` fires only while `0x605f30` holds (health
-/// ≤ 0 or the ghost flag — `dead_or_ghost`), so a stale offer never reaches a living player's UI,
-/// even through a fresh VM after a `/reload`. A caster whose name is still resolving holds the
-/// announcement without consuming it.
+/// The name `RESURRECT_REQUEST` fires with this frame, if any. Per message, and only while dead
+/// or a ghost (`0x5ded50` gated on `0x605f30`); an unresolved name holds without consuming it.
 fn offer_announcement(
     memo: &mut DeathAnnounced,
     death_net: &DeathNet,
@@ -773,21 +597,19 @@ mod tests {
         }
     }
 
-    /// **An offer the UI hid without answering must not swallow the next one.** PLAYER_UNGHOST
-    /// hides the RESURRECT popups with `StaticPopup_Hide`, which runs no `OnCancel`, so no
-    /// Decline clears `resurrect`; the next death's `SMSG_RESURRECT_REQUEST` must still announce.
-    /// And a stale offer must never reach the UI of a living player (a `/reload` after the res).
+    /// PLAYER_UNGHOST hides the popup with `StaticPopup_Hide`, which runs no `OnCancel`, so no
+    /// Decline clears `resurrect`.
     #[test]
     fn every_resurrect_message_announces_while_dead_and_never_while_alive() {
         let mut net = DeathNet::default();
         let mut memo = DeathAnnounced::default();
         let name = |o: &ResurrectOffer| Some(o.name.clone());
 
-        net.resurrect = Some(offer(1, "Pone"));
+        net.resurrect = Some(offer(1, "Healer"));
         net.resurrect_generation += 1;
         assert_eq!(
             offer_announcement(&mut memo, &net, true, name).as_deref(),
-            Some("Pone")
+            Some("Healer")
         );
         assert_eq!(
             offer_announcement(&mut memo, &net, true, name),
@@ -795,8 +617,7 @@ mod tests {
             "once per message"
         );
 
-        // Ran back instead: alive, the popup hidden, the offer never answered. A /reload now
-        // (a fresh VM memo) must not show "Pone wants to resurrect you" to a living player.
+        // Alive with the offer unanswered: a fresh VM must not announce it.
         let mut reloaded = DeathAnnounced::default();
         assert_eq!(offer_announcement(&mut reloaded, &net, false, name), None);
 
@@ -818,13 +639,7 @@ mod tests {
         );
     }
 
-    /// **The world scope dies with the session, and only with the session** (decision 1732).
-    ///
-    /// Both halves matter and they pull opposite ways: a `/reload` must NOT restart the six
-    /// minutes (which is why `mirror`/`died_at` are not per-VM in the first place), and a relog
-    /// MUST clear them (or the "logging in already a ghost" arm never fires, no
-    /// `MSG_CORPSE_QUERY` goes out, and the RECOVER_CORPSE popup stays down — the reported bug).
-    /// A test that only asserted the clear would pass on a resource wiped every frame.
+    /// A `/reload` must not restart the release window; a relog must clear it.
     #[test]
     fn the_session_edge_clears_the_world_scoped_death_memory_and_nothing_else_does() {
         let mut app = App::new();
@@ -835,7 +650,7 @@ mod tests {
                 vm: crate::ui_script::VmMemo::default(),
             });
 
-        // No session edge — the memory stands (the `/reload` half).
+        // No session edge: the memory stands.
         app.world_mut()
             .run_system_once(end_session_death_feed)
             .expect("the teardown runs");
@@ -845,8 +660,7 @@ mod tests {
             "nothing but the session edge may clear the body's own state machine"
         );
 
-        // A `/logout` is a session edge too — `session_over` is false for it, and the clear may
-        // not depend on that (a relog is exactly the `false` case).
+        // A `/logout` is a session edge although `session_over` is false for it.
         app.world_mut()
             .write_message(crate::net::DisconnectedMessage::new(
                 "logged out".into(),
@@ -880,17 +694,14 @@ mod self_res_tests {
     use crate::net::{ClientCommand, NetCommands};
     use crate::ui_action::Spells;
 
-    /// Reincarnation's effect spell — what the server writes into the field, named in `Spell.dbc`
-    /// as the button text (decision 1746).
+    /// Reincarnation's effect spell, what the server writes into the field.
     const REINCARNATION: u32 = 21169;
     /// `PLAYER_SELF_RES_SPELL`.
     const F_SELF_RES: u16 = 1224;
-    /// `UNIT_FIELD_HEALTH` / `UNIT_FIELD_MAXHEALTH`. Both, because benilla's `unit_is_dead()`
-    /// guards on a non-zero max — an all-empty store must not read as a corpse (its own doc). The
-    /// binary's gate is the bare signed `health <= 0`; for the self player the two never differ.
+    /// `UNIT_FIELD_HEALTH` and `UNIT_FIELD_MAXHEALTH`: `unit_is_dead()` also needs a non-zero max.
     const F_HEALTH: u16 = 22;
     const F_MAXHEALTH: u16 = 28;
-    /// `PLAYER_FIELD_PACK_SLOT_1` — the backpack's 16 slots, two dwords per guid.
+    /// `PLAYER_FIELD_PACK_SLOT_1`: the backpack's 16 slots, two dwords per guid.
     const F_PACK_1: u16 = 532;
 
     fn commands() -> (NetCommands, crossbeam_channel::Receiver<ClientCommand>) {
@@ -913,16 +724,13 @@ mod self_res_tests {
         }
     }
 
-    /// **The dead gate comes first** (`0x48acba`): `HasSoulstone` reads
-    /// `UNIT_FIELD_HEALTH` and answers nil while it is positive. A living player holding a
-    /// standing self-res spell gets nothing — and neither does a released **ghost**, whose health
-    /// the server sets to exactly 1 (`BuildPlayerRepop`). That is what confines the answer to the
-    /// pre-release window the DEATH dialog lives in.
+    /// `0x48acba`: nil while health is positive, including a released ghost's 1
+    /// (`BuildPlayerRepop`).
     #[test]
     fn the_dead_gate_precedes_the_field() {
         let (net, _rx) = commands();
         let items = Items::default();
-        // Nothing streamed: the spell leg answers before the inventory walk is reached (2334).
+        // Nothing streamed: the spell leg answers before the inventory walk.
         let mut objs = crate::ui_items::TestObjects::new();
         let objects = objs.get();
         let spells = catalog([(REINCARNATION, named("Reincarnation", [94, 0, 0]))]);
@@ -938,8 +746,6 @@ mod self_res_tests {
             "alive with a self-res owed: nil"
         );
 
-        // A ghost's health is 1, not 0 — the same positive-health path, which is why releasing
-        // takes the button away rather than the dialog merely hiding it.
         let ghost = ObjectFields::from_pairs(&[
             (F_MAXHEALTH, 4000),
             (F_HEALTH, 1),
@@ -965,8 +771,7 @@ mod self_res_tests {
         );
     }
 
-    /// An id the catalog cannot resolve is **"UNKNOWN"**, not nil (`0x48ad1d`). Hiding
-    /// the button instead would silently strip a self-res the server is holding for us.
+    /// The reference pushes the literal (`0x48ad1d`).
     #[test]
     fn an_unresolvable_spell_id_reads_unknown_not_nil() {
         let (net, _rx) = commands();
@@ -987,11 +792,8 @@ mod self_res_tests {
         }
     }
 
-    /// **A zero field is not the nil path** (`0x5ed630`): the client falls through to the carried
-    /// inventory and looks for an item whose ON-USE (`trigger == 0`) spell carries
-    /// `SPELL_EFFECT_SELF_RESURRECT`, labelling the button with the ITEM's name. Three items
-    /// stand in the backpack — one whose self-res spell is on an EQUIP trigger (must not count),
-    /// one whose on-use spell is something else (must not count), and the real one.
+    /// The item leg (`0x5ed630`); the backpack holds a self-res on an equip trigger, an unrelated
+    /// on-use spell, and the real one.
     #[test]
     fn a_zero_field_falls_through_to_a_carried_item() {
         let (net, _rx) = commands();
@@ -1030,7 +832,7 @@ mod self_res_tests {
             (439, named("Healing Potion", [6, 0, 0])),
         ]);
 
-        // Backpack slots 23/24/25 hold the three, in that order.
+        // Backpack slots 23, 24 and 25 hold the three, in that order.
         let mut pairs = vec![(F_MAXHEALTH, 4000), (F_HEALTH, 0)];
         for (i, guid) in [0xA0_u64, 0xA1, 0xA2].iter().enumerate() {
             let f = F_PACK_1 + 2 * i as u16;
@@ -1050,7 +852,7 @@ mod self_res_tests {
             other => panic!("expected the item leg, got {other:?}"),
         }
 
-        // Take it away and the answer is nil again — not "UNKNOWN", which is the spell leg's.
+        // Without it the answer is nil, not the spell leg's "UNKNOWN".
         let bare = ObjectFields::from_pairs(&[(F_MAXHEALTH, 4000), (F_HEALTH, 0)]);
         assert_eq!(
             resolve_self_res(&bare, &objects, &items, Some(&spells), &net),
diff --git a/crates/benilla-app/src/death/net.rs b/crates/benilla-app/src/death/net.rs
index 09d7fd33..c3d3501a 100644
--- a/crates/benilla-app/src/death/net.rs
+++ b/crates/benilla-app/src/death/net.rs
@@ -1,10 +1,5 @@
-//! The death arc's packet handlers (decision 0308; in the net handler table since 2322, moved out
-//! of the drain's death arm file) — the wire-fed [`DeathNet`] stores (the corpse marker and its
-//! guid latch, the reclaim clock, the resurrect offer, the spirit-healer confirm, the death
-//! durability notice) plus the granted movement-mode forward the server addresses to our own
-//! mover. Three bodies here are not packet handlers but the corpse-guid latch's hooks on the
-//! object lifecycle ([`note_corpse`], [`recheck_corpse`], [`forget_corpse`]); the drain's object
-//! arms still call them, and they become listeners on the object kinds once those are peeled.
+//! The death packet handlers filling [`DeathNet`], the movement-mode forward for our own mover,
+//! and the corpse-guid latch's hooks on the object lifecycle, called from the drain's object arms.
 
 use benilla_protocol::{EntityKind, MoveMode, ObjectFields, SessionEvent, SessionEventKind};
 use bevy::prelude::*;
@@ -12,8 +7,7 @@ use bevy::prelude::*;
 use super::{CorpsePoint, DeathNet, ResurrectOffer};
 use crate::net::{MoveModeMessage, NetHandlerApp, SelfGuid};
 
-/// Register the death handlers — called from [`super::DeathPlugin`]. One per kind, plus the
-/// session-end listener.
+/// Register the death handlers and the session-end listener.
 pub(super) fn register(app: &mut App) {
     use SessionEventKind as K;
     app.net_handler(K::CorpseQuery, on_corpse_query)
@@ -96,26 +90,15 @@ fn on_move_mode(
     }
 }
 
-/// The death stores are session-scoped: a reclaim expiry, resurrect offer, or corpse marker must
-/// not survive the socket (the reconnect re-sends the reclaim delay when dead). A listener on
-/// the session end (a second handler on the kind, after the bridge's own teardown).
+/// The death stores are session-scoped; a reconnect while dead re-sends the reclaim delay.
 fn on_session_end(In(_): In<SessionEvent>, mut death_net: ResMut<DeathNet>) {
     *death_net = DeathNet::default();
 }
 
-/// OUR corpse streaming into range (a `TYPEID_CORPSE` create whose owner is us): remember its guid
-/// for the reclaim send (decision 0308 §5). The kind is exact ([`EntityKind::Corpse`] since 1706 —
-/// it was `Other` while nothing rendered a corpse), and the owner field is corpse-only, so nothing
-/// else can match. Rides the `ObjectCreate` arm.
-///
-/// **Two gates, not one**: the reference's
-/// reclaim guid `[0xb4e328/32c]` has exactly one writer, `0x4920d0`, called from three sites in the
-/// CGCorpse translation unit — and every one of them is gated on `CORPSE_FIELD_OWNER == me`
-/// **and `CORPSE_FIELD_FLAGS` bit 0 clear**, i.e. a real body and not a bone pile. So the latch is
-/// a property of the streamed corpse OBJECT, not of the `MSG_CORPSE_QUERY` answer, and a pile of
-/// bones never arms it. That matters because `RetrieveCorpse` itself carries **no guard of any
-/// kind** — whatever is in the latch is what goes out on `CMSG_RECLAIM_CORPSE`. The bones gate is
-/// the only thing standing between a converted corpse and a reclaim send naming it.
+/// Our corpse streaming in: latch its guid for the reclaim send. The reference's latch
+/// `[0xb4e328]` has one writer, `0x4920d0`, gated on `CORPSE_FIELD_OWNER == me` and
+/// `CORPSE_FIELD_FLAGS` bit 0 clear, so bones never arm it; `RetrieveCorpse` sends whatever is in
+/// the latch.
 pub(crate) fn note_corpse(
     guid: u64,
     kind: EntityKind,
@@ -131,23 +114,15 @@ pub(crate) fn note_corpse(
     }
 }
 
-/// The same latch, re-evaluated when a corpse's **`CORPSE_FIELD_FLAGS` changes under a live guid**.
-///
-/// [`forget_corpse`] covers the conversion shape where the server destroys the corpse object and
-/// creates the bone pile as a new one. It does not cover an in-place flip — the same guid gaining
-/// `CORPSE_FLAG_BONES` through a values delta — and the reference is immune to that shape by
-/// construction: its three latch writers include the `FLAGS` mirror handler `0x5d6d60`, so the
-/// gate is re-asked on every change of the very field that carries the bones bit. Ours asks it
-/// here, on the same edge. Rides the `ObjectValues` arm.
+/// The same latch, re-asked when `CORPSE_FIELD_FLAGS` changes under a live guid, as the
+/// reference's `FLAGS` mirror handler `0x5d6d60` does, so an in-place flip to bones drops it.
 pub(crate) fn recheck_corpse(
     guid: u64,
     fields: &ObjectFields,
     self_guid: &SelfGuid,
     death_net: &mut DeathNet,
 ) {
-    // A values delta carries only what changed: an untouched FLAGS field reads absent, and absent
-    // must not be read as "bit clear" (that is the `ObjectFields` create-vs-delta seam). So act
-    // only when the field is actually present in this delta.
+    // A delta carries only what changed: an absent FLAGS field is not a clear bit.
     let Some(flags) = fields.corpse_flags_present() else {
         return;
     };
@@ -156,7 +131,6 @@ pub(crate) fn recheck_corpse(
         return;
     }
     if flags & 0x01 != 0 {
-        // Converted to bones under our own guid — drop it before a reclaim can name it.
         if death_net.corpse_guid == Some(guid) {
             death_net.corpse_guid = None;
         }
@@ -165,16 +139,14 @@ pub(crate) fn recheck_corpse(
     }
 }
 
-/// The corpse-to-bones swap destroys the corpse object under its guid (0308 §1); a stale guid must
-/// not ride a later reclaim. Rides the `ObjectDestroyed` arm.
+/// The corpse-to-bones swap destroys the corpse object; a stale guid must not ride a reclaim.
 pub(crate) fn forget_corpse(guid: u64, death_net: &mut DeathNet) {
     if death_net.corpse_guid == Some(guid) {
         death_net.corpse_guid = None;
     }
 }
 
-/// `MSG_CORPSE_QUERY`'s answer — where the corpse marker goes. A not-found (reactive, or the
-/// server's unprompted bones-conversion push) drops the marker.
+/// `MSG_CORPSE_QUERY`'s answer; a not-found, asked or pushed at bones conversion, drops the marker.
 fn corpse_query(
     found: bool,
     display_map: i32,
@@ -189,16 +161,14 @@ fn corpse_query(
     });
 }
 
-/// `SMSG_CORPSE_RECLAIM_DELAY` — the delay, anchored to arrival time (`now_secs` is the same
-/// `Time::elapsed_secs_f64` the feed reads back). The client's `0x269` handler re-fires the
-/// corpse-range events through its latch (`0x4962d0`), so the feed re-announces on the
-/// generation bump.
+/// `SMSG_CORPSE_RECLAIM_DELAY`, anchored at arrival on the clock the feed reads. The 1.12 client
+/// re-fires the corpse-range events on each (`0x4962d0`), hence the generation bump.
 fn corpse_reclaim_delay(delay_ms: u32, now_secs: f64, death_net: &mut DeathNet) {
     death_net.reclaim_at = Some(now_secs + f64::from(delay_ms) / 1000.0);
     death_net.reclaim_generation = death_net.reclaim_generation.wrapping_add(1);
 }
 
-/// `SMSG_RESURRECT_REQUEST` — the RESURRECT popup's data.
+/// `SMSG_RESURRECT_REQUEST`, the RESURRECT popup's data.
 fn resurrect_request(
     caster: u64,
     name: String,
@@ -215,25 +185,14 @@ fn resurrect_request(
     death_net.resurrect_generation = death_net.resurrect_generation.wrapping_add(1);
 }
 
-/// `SMSG_SPIRIT_HEALER_CONFIRM` — the healer awaiting the XP-loss two-step's Accept. The message
-/// IS the announce (decision 1068): the healer's gossip re-sends it on every ask, and the
-/// reference fires `CONFIRM_XP_LOSS` per arrival — so the generation bump is what re-shows a
-/// cancelled confirm, exactly the `SMSG_CORPSE_RECLAIM_DELAY` re-fire pattern above.
+/// `SMSG_SPIRIT_HEALER_CONFIRM`: the healer's gossip re-sends it on every ask, and the reference
+/// fires `CONFIRM_XP_LOSS` per arrival.
 fn spirit_healer_confirm(npc: u64, death_net: &mut DeathNet) {
-    // Through [`DeathNet::ask_spirit_healer`], which the right-click's own bit-5 arm also calls —
-    // the reference raises this dialog client-side and vmangos also pushes it, and one entry
-    // point is what keeps the two roads saying the same thing (decision 1861).
     death_net.ask_spirit_healer(npc);
 }
 
-/// `SMSG_DURABILITY_DAMAGE_DEATH` — the 10% death durability loss.
-///
-/// **It is a combat-log line, not a red error** (1703, correcting the shape 0308 shipped):
-/// `0x628e60` is itself the packet's handler and it emits at the literal chat type `0x19`
-/// `COMBAT_MISC_INFO`, with **zero arguments** — the packet's body is empty and both of vmangos's
-/// fields are ignored. Routing it to `UIErrorsFrame` put it in the wrong frame and, worse, meant
-/// hard-coding Blizzard's English sentence in our source; as a combat-log family it resolves
-/// `DURABILITYDAMAGE_DEATH` out of the player's own `GlobalStrings.lua` like every other line.
+/// `SMSG_DURABILITY_DAMAGE_DEATH`, the 10% death durability loss: a combat-log line at chat type
+/// `0x19` `COMBAT_MISC_INFO` with no arguments (`0x628e60`), not an error; the body is ignored.
 fn durability_damage_death(log: &mut crate::ui_chat::ChatLog) {
     log.push_combat(crate::ui_chat::combat::PendingCombat {
         kind: crate::ui_chat::ChatEventKind::CombatMiscInfo,
@@ -247,11 +206,9 @@ fn durability_damage_death(log: &mut crate::ui_chat::ChatLog) {
     });
 }
 
-/// **The ack'd movement-mode family** (decision 0866) — root, water-walk, feather-fall, hover. The
-/// server only ever addresses the controlling client's own mover; the guard keeps a stray relay
-/// harmless. Water-walk is additionally mirrored into [`DeathNet`], which reads it as a ghost-form
-/// cue — but the *mover* effect of every mode, this one included, is the controller's
-/// ([`crate::player::wire_in`]).
+/// The acked movement modes, root, water-walk, feather-fall and hover, addressed only to our own
+/// mover and applied by the controller ([`crate::player::wire_in`]); water-walk is also mirrored
+/// into [`DeathNet`] as a ghost cue.
 fn move_mode(
     guid: u64,
     counter: u32,
diff --git a/crates/benilla-app/src/debug_panel/inspect.rs b/crates/benilla-app/src/debug_panel/inspect.rs
index 07c62921..5cd74b11 100644
--- a/crates/benilla-app/src/debug_panel/inspect.rs
+++ b/crates/benilla-app/src/debug_panel/inspect.rs
@@ -1,6 +1,5 @@
-//! The **inspector surface** — the dev-chord `I` overlay: an "armed" pill plus a compact identity
-//! card that follows the cursor over whatever [`MouseoverTarget`] picked. Split from the module
-//! face for size only; the toggle, the card, and its readout lines live here unchanged.
+//! The inspector, the dev-chord `I` overlay: an "armed" pill and an identity card that follows
+//! the cursor over whatever [`MouseoverTarget`] picked.
 
 use bevy::platform::collections::HashSet;
 use bevy::prelude::*;
@@ -15,34 +14,27 @@ use benilla_world::model_render::ModelKind;
 use benilla_world::modkeys::DEV_CHORD;
 use benilla_world::view::WorldCamera;
 
-/// The **dev chord + `I`** (for *inspect*) arms/disarms the inspector — off the bare-letter plane the
-/// game's own bindings own (0585), on whichever plane this OS leaves free (0867). Unmistakable as a
-/// chord, so unlike the old bare `i` it needs no chat-bar/EditBox gate.
+/// The dev chord + `I` arms and disarms the inspector; a chord needs no EditBox gate.
 pub(super) fn toggle_inspect(keys: Res<ButtonInput<KeyCode>>, mut inspect: ResMut<InspectMode>) {
     if benilla_world::modkeys::dev_chord(&keys, KeyCode::KeyI) {
         inspect.enabled = !inspect.enabled;
     }
 }
 
-/// How long the inspector card shows its "copied to clipboard" confirmation after a left-click.
-/// Shared with the journal's row-copy flash ([`super::journal`]).
+/// How long a "copied to clipboard" confirmation shows, on the card and the journal's rows.
 pub(super) const COPY_FLASH_SECS: f32 = 1.2;
 
-/// A per-kind accent so the card's header is glanceable (which *sort* of thing am I over?) before you
-/// even read the label.
+/// A per-kind accent for the card's header.
 fn kind_color(kind: ModelKind) -> egui::Color32 {
     match kind {
-        ModelKind::Doodad => egui::Color32::from_rgb(140, 220, 140), // green — props/trees
-        ModelKind::Wmo => egui::Color32::from_rgb(150, 185, 240),    // blue — buildings
-        ModelKind::Creature => egui::Color32::from_rgb(240, 205, 130), // gold — NPCs
-        ModelKind::GameObject => egui::Color32::from_rgb(220, 165, 220), // violet — GameObjects
+        ModelKind::Doodad => egui::Color32::from_rgb(140, 220, 140), // green: props, trees
+        ModelKind::Wmo => egui::Color32::from_rgb(150, 185, 240),    // blue: buildings
+        ModelKind::Creature => egui::Color32::from_rgb(240, 205, 130), // gold: NPCs
+        ModelKind::GameObject => egui::Color32::from_rgb(220, 165, 220), // violet: GameObjects
     }
 }
 
-/// The granted movement modes as the card names them (decision 1780) — `None` when the unit has
-/// none, which is nearly all of them, so the common line is unchanged. Named rather than derived
-/// from the raw word on the card: `0x40001000` says nothing to the eye, and the whole reason this
-/// is on the card is that the modes explain a body that looks wrong and is not.
+/// The granted movement modes by name, `None` for a unit with none (nearly all of them).
 fn granted_modes(modes: Option<&crate::net::UnitMoveModes>) -> Option<String> {
     use crate::creature_anim::move_flags as f;
     let w = modes?.0;
@@ -61,54 +53,35 @@ fn granted_modes(modes: Option<&crate::net::UnitMoveModes>) -> Option<String> {
     (!named.is_empty()).then(|| format!("granted {}", named.join("+")))
 }
 
-/// The inspector's GameObject collision readout (decision 0763): does a hull exist, is it disabled
-/// right now, and what stored state does the passability gate see. Named so the bundled `stores`
-/// param stays readable.
+/// A GameObject's collision readout: hull present, hull disabled, and the stored state the
+/// passability gate sees.
 type GoCollisionReadout = (
     Has<avian3d::prelude::Collider>,
     Has<avian3d::prelude::ColliderDisabled>,
     Option<&'static crate::go_anim::GoAnim>,
 );
 
-/// The inspector's **motion** readout: the server-dictated path a creature is riding
-/// ([`crate::net::Spline`]) and the dead-reckoned state of a remote mover
-/// ([`crate::net::RemoteMotion`]) — the two producers of "this thing is moving" that the animation
-/// selector itself unifies. On the card because the identity lines alone cannot answer the one
-/// question a "that creature looks wrong" report always turns on: *is it actually moving, and how
-/// fast?* The AQ drakes are the case that earned it — a Brood of Nozdormu 190 yd overhead beating
-/// its wings at a flat 1× while its path crawls at walk pace reads as frozen, and nothing on the
-/// card said the path was the slow half.
-///
-/// …and, since 1780, the third producer: the modes the server **granted** this unit
-/// ([`crate::net::UnitMoveModes`]). They belong on the same line because they answer the same
-/// report from the other side — a body a yard off the floor, standing on water, or refusing every
-/// path the server sends it looks broken and is not, and the mode word is the only place that
-/// difference is written down. A unit with none reads nothing extra, which is nearly all of them.
+/// A unit's motion readout: its server path ([`crate::net::Spline`]), its dead-reckoned remote
+/// motion ([`crate::net::RemoteMotion`]) and the modes the server granted it
+/// ([`crate::net::UnitMoveModes`]), which explain a hovering, water-walking or rooted body.
 type MotionReadout = (
     Option<&'static crate::net::Spline>,
     Option<&'static crate::net::RemoteMotion>,
     Option<&'static crate::net::UnitMoveModes>,
-    // The clamp's memo, for the card's `ground` line — the only place a "this mob is under the
-    // world" sighting becomes a measurement instead of a picture.
+    // The ground clamp's memo, for the card's `ground` line.
     Option<&'static crate::net::GroundClamped>,
-    // Where the unit is standing *now*, which the `ground` line reads the terrain against.
+    // Where the unit stands now, which the `ground` line reads the terrain against.
     &'static Transform,
 );
 
-/// The inspector's entity LIGHT readout (decision 0776): the lane this object's parts render
-/// under, and which attach found the room — "two identical GameObjects a few yards apart, one lit
-/// like the room and one like the street" is the report that made this a card line rather than a
-/// rebuild with `WOW_INTERIOR_LOG`.
+/// An object's light readout: the lane its parts render under, and which attach found the room.
 type EntityLightReadout = (
     &'static benilla_world::interior::InteriorAnchor,
     Has<benilla_world::interior::ContainmentAttach>,
 );
 
-/// One pickable part as the card's `parts alive` and glow-card lines read it: the object, its
-/// draw verdict, its transform, whether it is a billboard card, the material + mesh tag the glow
-/// line names, and the visibility class the STACKED count reads. A tuple alias like
-/// [`EntityLightReadout`] above, for the same reason: as an inline `Query<>` the field trips
-/// clippy's `type_complexity` at the workspace gate.
+/// One pickable part as the card's `parts alive` and glow-card lines read it; an alias because an
+/// inline `Query<>` trips clippy's `type_complexity`.
 type PartReadout = (
     &'static benilla_world::interact::WorldObject,
     &'static bevy::camera::visibility::ViewVisibility,
@@ -119,58 +92,42 @@ type PartReadout = (
     Option<&'static bevy::camera::visibility::VisibilityClass>,
 );
 
-/// Everything the identity card reads off the **net entity** under the cursor, as one named
-/// [`SystemParam`] — the descriptor store and the coarse kind the line gates go by, the GameObject
-/// collision readout (decision 0763), the light readout, and the two remaining inputs of the
-/// **interact gate** ([`crate::target::cursor_mode::go_highlightable`]): the faction catalog and our
-/// own store. A bundle because `inspect_ui` sits at Bevy's 16-param ceiling; a named struct rather
-/// than the tuple it grew out of, so each member says what it is at the point of use.
+/// Everything the identity card reads off the net entity under the cursor, bundled because
+/// `inspect_ui` sits at Bevy's 16-param ceiling.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(super) struct InspectStores<'w, 's> {
     stores: Query<'w, 's, &'static ObjectStore>,
     kinds: Query<'w, 's, &'static crate::net::NetEntity>,
-    /// Every pickable part with its draw verdict, for the card's `parts alive` line: a prop
-    /// spawned twice reads twice its model's batch count here, and nowhere else.
+    /// Every pickable part with its draw verdict; a prop spawned twice reads twice its batches.
     objects: Query<'w, 's, PartReadout>,
-    /// The realized materials + images, for the card line: which material a glow card is bound
-    /// to, whether that material still says ADDITIVE, and whether its texture is resident.
+    /// For a glow card: its bound material, whether that is still additive, and whether its
+    /// texture is resident.
     model_mats: Res<'w, Assets<benilla_assets::materials::WowModelMaterial>>,
     images: Res<'w, Assets<bevy::image::Image>>,
     collision: Query<'w, 's, GoCollisionReadout>,
     lit: Query<'w, 's, EntityLightReadout>,
     motion: Query<'w, 's, MotionReadout>,
-    /// The MCNK heightfield under the hovered unit — the `ground` line's third number, and the one
-    /// that separates "the server put it there" from "we sank it".
+    /// The MCNK height under the hovered unit, the `ground` line's `terrain`.
     points: benilla_world::world_point::WorldPoint<'w, 's>,
     factions: Option<Res<'w, crate::target::ring::Factions>>,
     self_store: Query<'w, 's, &'static ObjectStore, With<crate::net::SelfPlayer>>,
-    /// The live standings — the other half of the reaction resolve (`ring_reaction` takes the
-    /// reputation branch first, and a rank that came off a standing rather than a faction-template
-    /// comparison is the single most confusing thing about a unit's colour).
+    /// The live standings: `ring_reaction` takes the reputation branch before the template one.
     reputations: Res<'w, crate::net::Reputations>,
-    /// This frame's plate verdict ([`crate::vplates::VPlates`]) — the *rendered* answer, not a
-    /// re-derivation, so the card can never disagree with what is on screen.
+    /// This frame's rendered plate verdict, not a re-derivation, so the card matches the screen.
     plates: Res<'w, crate::vplates::VPlates>,
-    /// Which of the two master bits are on, so a `plate ✗` can say whether the unit lost its plate
-    /// on the category gate or on something else.
+    /// The two master bits, so a `plate ✗` can say whether the category gate refused it.
     plate_mode: Res<'w, crate::vplates::VPlateMode>,
-    /// The ask-once GO template cache — the readable head a TEXT object's line reports
-    /// (decision 1105), and the highlight column + name the tooltip ladder reports (2246).
+    /// The GO template cache: a TEXT object's page and the tooltip ladder's highlight column
+    /// and name.
     go_templates: Res<'w, crate::go_templates::GameObjectTemplates>,
-    /// `[0xb72038]` — the meeting-stone queue, the other half of MEETINGSTONE(23)'s own
-    /// highlightable term (decision 2283), so the card's `interact` verdict reads the same
-    /// predicate the cursor and the click do.
+    /// The meeting-stone queue (`[0xb72038]`), part of MEETINGSTONE(23)'s highlightable term, so
+    /// the card's `interact` verdict reads the same predicate as the cursor.
     stone: Option<Res<'w, crate::ui_dialog_verbs::MeetingStone>>,
-    /// **The published GameObject mouseover** — the one the tooltip actually reads
-    /// ([`crate::target::HoveredObject`]). The card's own pick is a dev pick and does not go
-    /// through the publish, so without this the card can show an object the game is not hovering
-    /// at all and give no sign of the difference (2246).
+    /// The published GameObject mouseover the tooltip reads; the card's own dev pick bypasses the
+    /// publish, so this shows when the two differ.
     hovered_go: Res<'w, crate::target::HoveredObject>,
-    /// The GameObject **animation** readout (decision 1151) — what the state machine's arm
-    /// (`0x5f3930`) is playing right now, for the card's `anim` line. Its own query rather than a
-    /// `collision` member because it needs the model components: they sit on the same entity as
-    /// [`crate::go_anim::GoAnim`], but a GO whose model authors no skeleton renders as a static
-    /// mesh and has none of them.
+    /// What the GameObject state machine's arm (`0x5f3930`) is playing, for the `anim` line. Its
+    /// own query: a GO whose model has no skeleton is a static mesh without these components.
     go_anims: Query<
         'w,
         's,
@@ -180,29 +137,19 @@ pub(super) struct InspectStores<'w, 's> {
             &'static benilla_assets::ModelAnimations,
         ),
     >,
-    /// The **picked submesh's own `MeshTag`** — the per-instance shading payload, decoded by its
-    /// owning module ([`benilla_world::mesh_tag::describe`]).
-    ///
-    /// The `light` line above names which *law* an object is on; this names what its parts are
-    /// actually carrying under that law, and the two together are what settle a "why is this body
-    /// lit wrong?" report. The payload's meaning switches on material state, which a tag alone
-    /// cannot know, so the decode prints BOTH readings of bits 6..=18 side by side — a shade byte
-    /// of 255 (the MCSH-shadowed half-intensity) sits inside a probe slot of 2047, and a writer
-    /// using the wrong law for its material is invisible in either reading alone and obvious in
-    /// the pair. Read off the picked entity itself, not the parent: `WorldObject` and `MeshTag`
-    /// both ride the submesh.
+    /// The picked submesh's own `MeshTag`, its per-instance shading payload. Its meaning depends
+    /// on material state, so [`benilla_world::mesh_tag::describe`] prints both readings of bits
+    /// 6..=18. Read off the submesh itself, not the parent.
     tags: Query<'w, 's, &'static bevy::mesh::MeshTag>,
 }
 
-/// The inspector overlay, drawn only while armed: a weak top-centre "armed" pill (so it's obvious the
-/// mode is on and how to leave it) and, whenever the cursor is over an identified object, a compact
-/// identity card pinned to the cursor. No chrome, no panel — its own lightweight surface.
+/// The inspector overlay while armed: a top-centre "armed" pill and, over an identified object,
+/// an identity card pinned to the cursor.
 pub(super) fn inspect_ui(
     mut contexts: EguiContexts,
     inspect: Res<InspectMode>,
     mouseover: Res<MouseoverTarget>,
-    // The pickable mesh is a child of the net entity; its descriptor store (`ObjectStore`) lives on the
-    // parent, so the readout hops child → parent.
+    // The pickable mesh is a child of the net entity, whose `ObjectStore` is on the parent.
     parents: Query<&ChildOf>,
     stores: InspectStores,
     guids: Query<&crate::net::Guid>,
@@ -212,11 +159,8 @@ pub(super) fn inspect_ui(
     spells: Option<Res<crate::ui_action::Spells>>,
     names: Res<crate::names::NameCache>,
     net_commands: Res<crate::net::NetCommands>,
-    // Bundled into one param (Bevy's system-function arity ceiling): the copy-click button, and
-    // the flag it must yield to — a left press this frame the UI already consumed as a
-    // cursor-payload world drop (0216 §3) must not ALSO land as an inspector copy-click, the same
-    // yield every other world left-press consumer gives it (see `PointerOverUi` above for the
-    // hover-time twin).
+    // Bundled for the arity ceiling: the copy-click button and the flag it yields to, a left
+    // press the UI already consumed as a cursor-payload drop.
     click_input: (
         Res<ButtonInput<MouseButton>>,
         Res<crate::ui_script::PlayerUiClickConsumed>,
@@ -230,7 +174,7 @@ pub(super) fn inspect_ui(
     }
     let ctx = contexts.ctx_mut()?;
 
-    // Armed indicator — small + dim, so it states "inspect is on" without competing with the world.
+    // The armed indicator, small and dim.
     egui::Area::new(egui::Id::new("inspect_armed"))
         .anchor(egui::Align2::CENTER_TOP, egui::vec2(0.0, 8.0))
         .show(ctx, |ui| {
@@ -240,15 +184,14 @@ pub(super) fn inspect_ui(
                 .fill(OVERLAY_FILL)
                 .show(ui, |ui| {
                     overlay_text(ui);
-                    // Spelled out, not ⌃⌘ — egui's default font stack has no glyph for U+2303 and
-                    // would draw tofu.
+                    // Spelled out: egui's default fonts have no glyph for U+2303.
                     ui.label(
                         egui::RichText::new(format!("inspect · {DEV_CHORD}+I to exit")).small(),
                     );
                 });
         });
 
-    // The identity card: only when hovering a picked object, pinned just off the cursor tip.
+    // The identity card, only over a picked object, pinned just off the cursor tip.
     let Some(obj) = mouseover.object.as_ref() else {
         return Ok(());
     };
@@ -256,8 +199,7 @@ pub(super) fn inspect_ui(
         return Ok(());
     };
 
-    // A unit's decoded server vitals from its descriptor store (`ObjectStore`), if the picked mesh's
-    // parent has them — proof the descriptor pipeline (UpdateFields → ObjectValues → ECS) reached it.
+    // The picked mesh's parent, the net entity carrying the descriptor store.
     let net_entity = mouseover
         .entity
         .and_then(|e| parents.get(e).ok())
@@ -268,14 +210,13 @@ pub(super) fn inspect_ui(
     let go_templates = &*stores.go_templates;
     let queued_area = stores.stone.as_deref().map_or(0, |s| s.area);
     let hovered_go = &*stores.hovered_go;
-    // The picked submesh's shading payload — off the hit entity itself (see the field's doc).
+    // The picked submesh's shading payload, off the hit entity itself.
     let tag_line = mouseover
         .entity
         .and_then(|e| stores.tags.get(e).ok())
         .map(|t| format!("tag {}", benilla_world::mesh_tag::describe(t.0)));
-    // The duplicate readout: every live part naming this same object, and how many of them
-    // drew this frame. A doodad has one part per render batch; a doubled placement shows twice
-    // that here — the census the FPS probe prints as `orphan_parts=`, at the cursor.
+    // Every live part naming this object and how many drew; a doodad has one per render batch,
+    // so a doubled placement shows twice that.
     let parts_line = {
         let (mut alive, mut drawn, mut stacked) = (0usize, 0usize, 0usize);
         let mut cards: Vec<String> = Vec::new();
@@ -283,15 +224,12 @@ pub(super) fn inspect_ui(
             if w.kind == obj.kind && w.id == obj.id {
                 alive += 1;
                 drawn += usize::from(vv.get());
-                // A part whose `VisibilityClass` lists its mesh class more than once is queued
-                // that many times — drawn stacked on itself (`model_render::park`'s dedup).
+                // A `VisibilityClass` listing its mesh class twice is queued, and drawn, twice.
                 stacked += usize::from(class.is_some_and(|c| c.len() > 1));
                 if card {
-                    // One glow card, as the draw sees it: its live world scale (the placement
-                    // scale times the bone's pulse), its tag alpha, and the bound material's
-                    // marker word — ADDITIVE is `clutter_fade.z` bit 2, the bit `specialize`
-                    // keys the (ONE, ONE) blend on and the shader keys the alpha fold on; a card
-                    // whose material lost it draws its texture unweighted, a hard bright disc.
+                    // A glow card as drawn: world scale (placement times the bone's pulse), tag
+                    // alpha, and the material word. Additive is `clutter_fade.z` bit 2, which keys
+                    // the (ONE, ONE) blend and the shader's alpha fold.
                     let scale = gt.compute_transform().scale.x;
                     let alpha = tag.map_or(-1.0, |t| benilla_world::mesh_tag::alpha_of(t.0));
                     let m = mat.and_then(|m| stores.model_mats.get(&m.0));
@@ -350,27 +288,20 @@ pub(super) fn inspect_ui(
         &stores.go_anims,
     );
     let store = net_entity.and_then(|p| stores.get(p).ok());
-    // The unit's server name through the query cache — asks on first hover, fills on a later frame
-    // (the same ask-once path the unit frames use).
+    // The unit's name through the ask-once cache; it fills on a later frame.
     let name_line = net_entity
         .and_then(|p| guids.get(p).ok())
         .and_then(|g| names.resolve_unit(g.0, store, &net_commands))
         .map(str::to_string);
-    // Line gates go by the entity's KIND, not field presence: a create-seeded store answers every
-    // field (absent = 0, the descriptor truth), so "is the health field there" stopped meaning
-    // "is this a unit".
+    // Gate by kind, not field presence: a create-seeded store answers every field (absent is 0).
     let kind = net_entity.and_then(|p| kinds.get(p).ok()).map(|n| n.kind);
     let is_unit = matches!(
         kind,
         Some(benilla_protocol::EntityKind::Unit | benilla_protocol::EntityKind::Player)
     );
     let is_player = kind == Some(benilla_protocol::EntityKind::Player);
-    // The GameObject collision + state readout (decision 0763) — the line that closes the loop on
-    // "this door is drawn open but I can't walk through it". It answers, for the object under the
-    // cursor, the three facts the passability gate turns on: the client's stored `GAMEOBJECT_STATE`
-    // (`go_anim::go_state`, i.e. what we believe open/closed is), whether a collision hull exists at
-    // all, and whether it is currently disabled. A door reading `state 0 open · SOLID` is the bug
-    // live on screen; `state 0 open · passable` says the gate ran and something else is blocking.
+    // A GameObject's stored `GAMEOBJECT_STATE` and its hull, the passability gate's inputs: a door
+    // reading `state 0 open · SOLID` is the gate failing.
     let go_line = store
         .filter(|_| kind == Some(benilla_protocol::EntityKind::GameObject))
         .map(|s| {
@@ -406,14 +337,9 @@ pub(super) fn inspect_ui(
             } else {
                 format!(" [{}]", named.join("|"))
             };
-            // The **interact gate**, stated rather than inferred (`0x5f2f80`): the
-            // strategy vtable's `+0x14` **highlightable** slot is the single predicate behind the
-            // cursor, the +64 brighten, the right-click USE and the pick priority — so a GO reading
-            // `interact ✗` is saying all four are off *by design*, and one reading `interact ✓` while
-            // showing no gear says the fault is downstream in the cursor naming. That distinction is
-            // exactly what the type-8 anvil report cost a hand-derivation to make: an anvil hovers
-            // (this card is up) and must still read `interact ✗`, because SPELL_FOCUS is one of the
-            // types whose `+0x14` is a constant `xor al,al`.
+            // The interact gate (`0x5f2f80`): the strategy vtable's `+0x14` highlightable slot is
+            // the one predicate behind the cursor, the +64 brighten, right-click USE and pick
+            // priority. SPELL_FOCUS's slot is a constant `xor al,al`, so an anvil reads `✗`.
             let reaction =
                 crate::target::cursor_mode::go_reaction(factions, s.0.gameobject_faction(), self_store);
             let go_guid = net_entity.and_then(|p| guids.get(p).ok()).map(|g| g.0);
@@ -431,24 +357,13 @@ pub(super) fn inspect_ui(
             } else {
                 "interact ✗"
             };
-            // **The TOOLTIP's own ladder** (decision 2246), which `interact` above is not and is
-            // routinely mistaken for. "No tooltip on this" has three possible stages and the card
-            // could name none of them, so every report of it cost a session of code reading:
-            //
-            //  · `hover ✗` — the **mouseover-eligibility** slot `+0x54`
-            //    ([`crate::target::cursor_mode::mouseover_eligible`]) said no, so the reference
-            //    publishes the NULL mouseover and there is no tooltip *by design*. For a
-            //    GENERIC(5) signpost this is the template's `data[1]` highlight column, which is
-            //    why the `tmpl` field sits beside it.
-            //  · `hover ✓` but `shown ✗` — eligible, and the publish still did not take it: the
-            //    pick lost to the occlusion verdict, to a nearer unit, or to the pointer being
-            //    over UI. The fault is in the pick, not the gate.
-            //  · `shown ✓` and still no plate on screen — the fault is downstream in
-            //    [`crate::ui_tooltip`], and `tmpl` says whether the name it needs has arrived.
-            //
-            // `tmpl —` is the one that looks like a bug and is not: the template query is
-            // ask-once and answers a frame or two later, and until it does the tooltip has no
-            // name to draw.
+            // The tooltip's own ladder, distinct from `interact`:
+            //  · `hover ✗`: the mouseover-eligibility slot `+0x54` said no, so the reference
+            //    publishes a NULL mouseover; for a GENERIC(5) signpost it is the template's
+            //    `data[1]` highlight column.
+            //  · `hover ✓`, `shown ✗`: the publish lost to occlusion, a nearer unit or UI.
+            //  · `shown ✓` and no tooltip: the fault is in [`crate::ui_tooltip`].
+            // `tmpl —` is the ask-once template query not answered yet.
             let tmpl = go_guid.and_then(|g| go_templates.get(g));
             let hover_gate = crate::target::cursor_mode::mouseover_eligible(
                 s.0.gameobject_type_id(),
@@ -469,11 +384,8 @@ pub(super) fn inspect_ui(
                     Some(t) => format!("{:?}", t.name),
                 }
             );
-            // TEXT (type 9) only: the **readable head** (decision 1105). A book that opens no
-            // window is either "no page in the template" or a fault downstream, and only this
-            // line tells the two apart — the symptom is identical from the chair, and the first
-            // one is the reference behaving correctly. `page —` = the template says none;
-            // `page ?` = its ask-once query hasn't answered yet.
+            // TEXT (type 9) only, the template's page: `page —` means none, so no window opens;
+            // `page ?` means the query has not answered yet.
             let page_text = if s.0.gameobject_type_id() == crate::target::cursor_mode::GO_TYPE_TEXT
             {
                 let go_guid = net_entity.and_then(|p| guids.get(p).ok()).map(|g| g.0);
@@ -488,17 +400,12 @@ pub(super) fn inspect_ui(
             } else {
                 String::new()
             };
-            // The **placement tilt** (decision 1459) — shown only when there is one. A GameObject
-            // is placed by its `GAMEOBJECT_ROTATION` quaternion, and 96.7% of live spawns encode a
-            // plain yaw in it; the rest carry a tilt that swings the model's off-origin geometry
-            // yards from the spawn point. So `tilt 70°` on a prop that looks misplaced says "this
-            // one's pose is quaternion-only" — the question B89 cost a DB round-trip to answer —
-            // and its absence says the placement is a bare facing and the fault is elsewhere.
+            // The tilt of the `GAMEOBJECT_ROTATION` quaternion, shown only when there is one: most
+            // spawns are a plain yaw, and a tilt swings off-origin geometry yards from the spawn.
             let tilt = s
                 .0
                 .gameobject_rotation()
-                // The angle the quaternion leans the model's own up-axis off world up:
-                // `acos(m22)`, i.e. `2·asin(|x, y|)` — zero for every pure-yaw spawn.
+                // The model's up-axis off world up, `acos(m22)`, i.e. `2·asin(|x, y|)`.
                 .map(|q| (2.0 * q[0].hypot(q[1]).min(1.0).asin()).to_degrees())
                 .filter(|deg| *deg >= 0.5)
                 .map(|deg| format!(" · tilt {deg:.0}°"))
@@ -516,8 +423,7 @@ pub(super) fn inspect_ui(
             s.0.unit_level().unwrap_or(0)
         )
     });
-    // Raw bytes (not name-mapped): creature race/class don't share the player-race enum, so a label
-    // would mislead. The character model will name-map these for players specifically.
+    // Raw bytes: creature race and class do not share the player-race enum.
     let appearance_line = store.filter(|_| is_unit).map(|s| {
         format!(
             "race {} · class {} · sex {}",
@@ -526,14 +432,8 @@ pub(super) fn inspect_ui(
             s.0.unit_gender().unwrap_or(0)
         )
     });
-    // **Why this unit does or does not carry a V-plate** — the whole input set of
-    // `vplates::drive_vplates`'s gate on one line, plus the verdict it actually reached this frame
-    // (read out of [`crate::vplates::VPlates`], never re-derived, so the card cannot disagree with
-    // the screen). "These plates shouldn't be here" is otherwise a question no amount of looking
-    // can answer: the plate is drawn from a REACTION rank whose provenance (a reputation standing
-    // vs a faction-template comparison) is invisible, over unit flags nothing displays, and the
-    // two master bits are off-screen state. Reading `reaction 3 neutral(rep)` off a green-looking
-    // city NPC is the entire diagnosis.
+    // Why this unit does or does not carry a plate: every input of `vplates::drive_vplates`'s
+    // gate and the verdict read from [`crate::vplates::VPlates`].
     let plate_line = store.filter(|_| is_unit).map(|s| {
         let rank = crate::target::ring::ring_reaction(factions, reputations, Some(s), self_store);
         let word = match rank {
@@ -546,10 +446,8 @@ pub(super) fn inspect_ui(
             6 => "revered",
             _ => "exalted",
         };
-        // Which branch produced it: a faction WITH a reputation slot colours by our standing
-        // (`0x605fc0` → `0x4d63a0`, before any template comparison), everything else by the
-        // template comparator. The two disagree constantly — a battleground emissary is `friendly`
-        // by template and `neutral` by standing — and only this tag says which one you are seeing.
+        // A faction with a reputation slot reacts by our standing (`0x605fc0` -> `0x4d63a0`),
+        // before any template comparison; everything else by the template comparator.
         let branch = s
             .0
             .unit_faction_template()
@@ -570,8 +468,7 @@ pub(super) fn inspect_ui(
         let verdict = match net_entity {
             Some(p) if plates.contains(&p) => "plate ✓".to_string(),
             _ => {
-                // The category the gate would have put it in, and whether that bit is on — the
-                // first thing to check when a plate is missing (or present) unexpectedly.
+                // The category the gate would have put it in, and whether that bit is on.
                 let (category, bit) = if rank >= 4 {
                     ("friendly", plate_mode.friends)
                 } else {
@@ -590,8 +487,7 @@ pub(super) fn inspect_ui(
             s.0.unit_flags(),
         )
     });
-    // Player-only customization: the compositor's input, shown raw so we can
-    // confirm the PLAYER_BYTES decode against an in-game character.
+    // Player customization, the compositor's input, raw from `PLAYER_BYTES`.
     let customization_line = store.filter(|_| is_player).map(|s| {
         format!(
             "skin {} · face {} · hair {}/{} · facial {}",
@@ -603,21 +499,15 @@ pub(super) fn inspect_ui(
         )
     });
 
-    // A unit mid-cast (`SMSG_SPELL_START` .. GO — the `Casting` wire seam): which spell, by id and
-    // display name. The director's "what is it casting?" answered on hover; the finished cast's
-    // trail lives in the journal.
+    // A unit mid-cast, between `SMSG_SPELL_START` and GO: the spell's id and name.
     let casting_line = net_entity.and_then(|p| castings.get(p).ok()).map(|c| {
         match spells.as_ref().and_then(|s| s.catalog.get(c.spell_id)) {
             Some(d) => format!("casting {} \"{}\"", c.spell_id, d.name),
             None => format!("casting {}", c.spell_id),
         }
     });
-    // **Is it moving, and how fast** ([`MotionReadout`]) — the input the `anim` line below is a
-    // consequence of. A creature riding a server path reports the path's constant speed (its whole
-    // length over its whole duration, the same number the gait selector reads) and how far through
-    // it is, so a unit that looks static is either `still` (no path at all — the server has not
-    // launched one, or the last one expired) or a path so slow it cannot be seen. A remote mover
-    // reports its dead-reckoning speed instead. Units and players only: a GameObject has no mover.
+    // Motion: a server path's constant speed (length over duration, as the gait selector reads
+    // it) and progress, or a remote mover's dead-reckoning speed; `still` means no path at all.
     let motion_line = net_entity
         .filter(|_| is_unit)
         .and_then(|p| motion.get(p).ok())
@@ -640,25 +530,10 @@ pub(super) fn inspect_ui(
                 None => moving,
             }
         });
-    // **Where its feet came from** ([`crate::net::GroundClamped`]) — the ground clamp's own memo,
-    // shown because "that mob is standing inside the hill" is a claim about three numbers and no
-    // screenshot carries them:
-    //
-    //   `ground z 12.34 · seat 12.42 (drop +0.08) · terrain 12.34 · walk hit`
-    //
-    // - **`z`** is where we are drawing it; **`seat`** is the pose the server last wrote, before
-    //   the clamp had its say, and **`drop`** = `seat − z` is the clamp's own correction. A big
-    //   positive drop is *ours*; a `z` far under `terrain` with `drop ≈ 0` is the server's.
-    // - **`terrain`** is the MCNK height under it — so "is it under the world?" reads off the card
-    //   rather than off a guess about what the hill looks like from here.
-    // - **the arm and the probe verdict**: `walk` is the swept step continuing a server path,
-    //   `idle` the settle from the seat, and they answer a MISS differently — an idle miss leaves
-    //   the unit at its seat, a walk miss descends. `MISS` is upper-case because on the `walk` arm
-    //   it is the interesting state, not a neutral one.
-    //
-    // The same three numbers `WOW_GROUND_CENSUS` prints per unit, on the unit the director is
-    // actually pointing at: the census answers "is anything sunk in this scene", this answers "why
-    // is *that* one".
+    // The ground clamp's memo ([`crate::net::GroundClamped`]): `z` is drawn, `seat` the server's
+    // last pose, `drop` = `seat - z` the clamp's correction, `terrain` the MCNK height. `walk` is
+    // the swept step on a server path and `idle` the settle from the seat; an idle miss stays at
+    // the seat, a walk miss descends.
     let ground_line = net_entity
         .filter(|_| is_unit)
         .and_then(|p| motion.get(p).ok())
@@ -676,21 +551,18 @@ pub(super) fn inspect_ui(
                 if c.hit { "hit" } else { "MISS" },
             )
         });
-    // An `AnimationData` id as the card names it — shared by the creature and GameObject anim
-    // lines below, which read the same id space.
+    // An `AnimationData` id by name, for both anim lines.
     let fmt = |id: u16| match anim_data.as_ref().and_then(|a| a.0.name(id)) {
         Some(name) => format!("{name}({id})"),
         None => format!("{id}"),
     };
-    // The animation slots this frame (requested `AnimationData` ids — the selector's choice,
-    // before missing-clip substitution): the full-body base + any masked upper-body overlay.
+    // The requested `AnimationData` ids, before missing-clip substitution: the full-body base and
+    // any masked upper-body overlay.
     let anim_line = net_entity.and_then(|p| drivers.get(p).ok()).map(|d| {
         let (base, overlay) = d.playing();
         let base = base.map(&fmt).unwrap_or_else(|| "—".into());
-        // The base slot's live playback rate (decision 0903) — `speed / (moveSpeed · modelScale)`
-        // on a locomotion clip, a flat 1× on everything else. Shown so a "its walk is too fast"
-        // report is a hover away from a number instead of a hand-worked divisor; suppressed at
-        // exactly 1× so the ordinary case doesn't carry noise.
+        // The base slot's playback rate, `speed / (moveSpeed · modelScale)` on a locomotion clip;
+        // hidden at 1x.
         let rate = d.rate();
         let rate = if (rate - 1.0).abs() > 1e-3 {
             format!(" · rate {rate:.2}×")
@@ -702,12 +574,9 @@ pub(super) fn inspect_ui(
             None => format!("anim {base}{rate}"),
         }
     });
-    // The same line for a **GameObject** (decision 1151), which is driven by `GoAnim` rather than
-    // `AnimDriver` and so never reached the branch above: the sequence the state machine's arm
-    // (`0x5f3930`) is playing, whether it is a transient one (a transition motion / a Custom block
-    // — something the completion advance `0x5f4120` must end) or the state's held rest pose, and
-    // the repeat it is running under. A `transition · loops` reading is the "stuck open/closing"
-    // bug, stated.
+    // A GameObject's line, from `GoAnim`: the sequence the state machine's arm (`0x5f3930`) plays,
+    // a transient one the completion advance `0x5f4120` must end or the held rest pose, and its
+    // repeat. `transition · loops` is a door stuck mid-motion.
     let anim_line = anim_line.or_else(|| {
         let (id, transient, repeat) = net_entity
             .and_then(|p| go_anims.get(p).ok())
@@ -720,8 +589,7 @@ pub(super) fn inspect_ui(
         };
         Some(format!("anim {} · {kind}{repeat}", fmt(id)))
     });
-    // The light lane + the attach that found it (decision 0776). Absent until the classifier has
-    // resolved the anchor once — a freshly streamed object shows no line rather than a wrong one.
+    // The light lane and the attach that found it; absent until the anchor resolves once.
     let light_line = net_entity
         .and_then(|p| lit.get(p).ok())
         .map(|(anchor, containment)| {
@@ -736,7 +604,7 @@ pub(super) fn inspect_ui(
             )
         });
 
-    // The lines shown in the card — also exactly what a left-click copies to the clipboard.
+    // The card's lines, which a left-click copies.
     let mut lines = vec![format!("{:?}", obj.kind), obj.label.clone()];
     if let Some(name) = &name_line {
         lines.push(format!("\"{name}\""));
@@ -783,8 +651,7 @@ pub(super) fn inspect_ui(
     lines.push(parts_line.clone());
     lines.push(format!("{:.1} yd away", mouseover.distance));
 
-    // The inspector owns left-click while armed (player::control suppresses left-orbit during inspect),
-    // so a press over the hovered object copies the whole card to the clipboard.
+    // The inspector owns left-click while armed; `player::control` suppresses left-orbit.
     if buttons.just_pressed(MouseButton::Left) && !click_consumed.0 {
         ctx.copy_text(lines.join("\n"));
         *copied_at = Some(time.elapsed_secs());
@@ -838,7 +705,6 @@ pub(super) fn inspect_ui(
                         egui::RichText::new(format!("{:.1} yd away", mouseover.distance))
                             .color(OVERLAY_TEXT_DIM),
                     );
-                    // Copy affordance, swapped for a brief confirmation after a left-click.
                     if just_copied {
                         ui.label(
                             egui::RichText::new("copied to clipboard")
@@ -857,14 +723,8 @@ pub(super) fn inspect_ui(
     Ok(())
 }
 
-/// The nearest identified thing under the cursor this frame, or `None`. `point`/`distance` are the
-/// world-space hit.
-///
-/// The identity is the resource's own (`object`), not something the consumer looks up off `entity`:
-/// most of the static world draws from a consolidated lane and has **no entity** to look anything
-/// up on (decision 1534). `entity` is `Some` only when one owns the geometry — which is exactly
-/// when the extra per-entity readouts (a unit's descriptor store, a GameObject's collision) mean
-/// anything.
+/// The nearest identified thing under the cursor this frame. `entity` is `Some` only when one
+/// owns the geometry: most of the static world draws from a consolidated lane with none.
 #[derive(Resource, Default)]
 pub struct MouseoverTarget {
     pub object: Option<WorldObject>,
@@ -873,9 +733,8 @@ pub struct MouseoverTarget {
     pub distance: f32,
 }
 
-/// Ray-cast from the cursor into the world and record the nearest [`WorldObject`] hit. Restricted to
-/// entities carrying `WorldObject` (so terrain, particle billboards, and other un-identified meshes are
-/// transparent to the pick), and skipped entirely unless inspection is active.
+/// Ray-cast from the cursor to the nearest [`WorldObject`], only while inspect is armed; terrain
+/// and other unidentified meshes are transparent to it.
 pub(super) fn update_mouseover(
     inspect: Res<InspectMode>,
     pointer_over_ui: Res<PointerOverUi>,
@@ -883,8 +742,7 @@ pub(super) fn update_mouseover(
     window: Query<&Window, With<PrimaryWindow>>,
     camera: Query<(&Camera, &GlobalTransform), With<WorldCamera>>,
     objects: Query<(Entity, &WorldObject)>,
-    // Everything drawn, entity-owned or not — see [`WorldPick`]: most of the static world draws
-    // from a consolidating lane and would be invisible to a bare `PickParts` cast (1534).
+    // Everything drawn, entity-owned or not.
     pick: WorldPick,
 ) {
     if !inspect.enabled {
@@ -895,9 +753,7 @@ pub(super) fn update_mouseover(
     }
     target.object = None;
     target.entity = None;
-    // The pointer is over the dev UI (e.g. the now-overlaid debug panel), not the world — don't pick
-    // behind it. This replaces the old "is the cursor in the inset world viewport?" test, which no
-    // longer means anything now the panel overlays a full-screen view.
+    // No pick behind UI.
     if pointer_over_ui.0 {
         return;
     }
@@ -908,7 +764,7 @@ pub(super) fn update_mouseover(
         return;
     };
     let Some(cursor) = window.cursor_position() else {
-        return; // cursor left the window, or we're in mouselook (hidden)
+        return; // outside the window, or hidden in mouselook
     };
     let identified: HashSet<Entity> = objects.iter().map(|(e, _)| e).collect();
     if let Some(hit) = pick.at_cursor(cursor, camera, cam_tf, &identified) {
diff --git a/crates/benilla-app/src/debug_panel/journal.rs b/crates/benilla-app/src/debug_panel/journal.rs
index fcae929c..6586e37c 100644
--- a/crates/benilla-app/src/debug_panel/journal.rs
+++ b/crates/benilla-app/src/debug_panel/journal.rs
@@ -1,15 +1,6 @@
-//! The cast journal — *what was that spell?*
-//!
-//! The inspector card answers the spatial question (what is this thing under my cursor?); a spell
-//! is **temporal** — its visual is often gone before anyone could point at it. So the journal
-//! records every cast edge as it flows past and the I-toggled inspect overlay shows the recent
-//! rows, each a click-to-copy identity block (spell id + name, caster, visual id, missile speed)
-//! ready to paste into a bug report or a session chat.
-//!
-//! Recording is **always on** (the whole point is that the question comes *after* the event —
-//! see the spell, then arm inspect and it's already there); only the drawing gates on
-//! [`InspectMode`]. The buffer is deliberately tiny ([`KEPT`]): this answers "that spell just
-//! now", not history.
+//! The cast journal: every recent cast edge, shown in the inspect overlay as click-to-copy rows.
+//! Recording is always on so a spell seen before inspect was armed is already there; only the
+//! drawing gates on [`InspectMode`].
 
 use std::collections::VecDeque;
 
@@ -28,31 +19,30 @@ const KEPT: usize = 24;
 /// Rows drawn in the overlay, newest first.
 const SHOWN: usize = 10;
 
-/// Where a recorded cast currently stands (the wire edges of decision 0099 phase 1).
+/// Where a recorded cast stands on its wire edges.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum CastState {
-    /// `SMSG_SPELL_START` seen, no GO yet — in flight (or the row went stale on a missed edge).
+    /// `SMSG_SPELL_START` seen, no GO yet (or the row went stale on a missed edge).
     Casting,
-    /// `SMSG_SPELL_GO` — the cast went off.
+    /// `SMSG_SPELL_GO`: the cast went off.
     Went,
-    /// The cast died without a release (`SMSG_SPELL_FAILED_OTHER` / our failed `CAST_RESULT`).
+    /// The cast died without a release (`SMSG_SPELL_FAILED_OTHER` or our failed `CAST_RESULT`).
     Failed,
 }
 
-/// One observed cast, resolved at record time against the `Spell.dbc` display catalog (name /
-/// visual / speed); the caster's *name* stays a guid here and resolves at draw time through the
-/// ask-once [`crate::names::NameCache`] (so a name that fills late still shows).
+/// One observed cast, its `Spell.dbc` display resolved at record time; the caster stays a guid
+/// and resolves at draw time, so a name that fills late still shows.
 struct CastRecord {
     caster: u64,
     spell_id: u32,
     name: Option<String>,
     visual: u32,
     speed: f32,
-    /// `Time::elapsed_secs_f64` of the latest edge (a GO refreshes it — age reads "went off").
+    /// `Time::elapsed_secs_f64` of the latest edge; a GO refreshes it.
     at: f64,
     state: CastState,
-    /// Missile arrivals credited back to this row (`CastEventKind::Impact` carries the *target*,
-    /// so impacts match by spell id against the newest launched row).
+    /// Missile arrivals, matched by spell id to the newest launched row: an impact carries the
+    /// target, not the caster.
     impacts: u32,
 }
 
@@ -63,8 +53,7 @@ pub(super) struct CastJournal {
 }
 
 impl CastJournal {
-    /// The newest record matching `caster` + `spell_id` in the `Casting` state — the row a
-    /// GO/fail edge upgrades (an instant's START and GO arrive the same frame and share one row).
+    /// The newest `Casting` row for `caster` and `spell_id`, the one a GO or fail edge upgrades.
     fn open_cast(&mut self, caster: u64, spell_id: u32) -> Option<&mut CastRecord> {
         self.records
             .iter_mut()
@@ -80,9 +69,7 @@ impl CastJournal {
     }
 }
 
-/// Record every cast edge into the journal (always on — the drawing, not the recording, gates on
-/// inspect mode). Reads the same [`CastEvent`] stream the visual router consumes; the spell's
-/// display row resolves here, once, so the draw pass is pure formatting.
+/// Record every cast edge into the journal, resolving the spell's display row once.
 pub(super) fn record_casts(
     mut casts: MessageReader<CastEvent>,
     mut journal: ResMut<CastJournal>,
@@ -94,7 +81,7 @@ pub(super) fn record_casts(
     for ev in casts.read() {
         match ev.kind {
             CastEventKind::Start | CastEventKind::Go | CastEventKind::Fail => {
-                // The caster's guid off its net entity; a despawned-same-frame caster just drops.
+                // A caster despawned the same frame drops.
                 let Ok(&Guid(caster)) = guids.get(ev.entity) else {
                     continue;
                 };
@@ -103,8 +90,8 @@ pub(super) fn record_casts(
                     CastEventKind::Go => CastState::Went,
                     _ => CastState::Failed,
                 };
-                // A GO/fail closes its own START row; without one (a triggered proc's bare GO,
-                // or a failed instant) it gets a fresh row — every edge stays visible.
+                // A GO or fail closes its START row; without one (a proc's bare GO, a failed
+                // instant) it gets a fresh row.
                 if state != CastState::Casting {
                     if let Some(open) = journal.open_cast(caster, ev.spell_id) {
                         open.state = state;
@@ -124,9 +111,8 @@ pub(super) fn record_casts(
                     impacts: 0,
                 });
             }
-            // The arrival edges: credit the newest launched row for this spell (the caster isn't
-            // on the unit hand-off's message — decision 0099 phase 4). A ground arrival is an
-            // arrival too — a pure dest cast's only one, and the journal's proof it landed.
+            // Arrivals credit the newest launched row for the spell; a ground arrival counts, as
+            // a pure dest cast has no other.
             CastEventKind::Impact { .. } | CastEventKind::GroundImpact { .. } => {
                 if let Some(row) = journal
                     .records
@@ -153,9 +139,8 @@ fn age(now: f64, at: f64) -> String {
     }
 }
 
-/// The journal overlay: while inspect is armed, the recent casts as a top-left column, newest
-/// first — click a row to copy its one-line identity block. Shares the inspector card's style
-/// (decision 0025's one overlay look).
+/// The journal overlay: while inspect is armed, recent casts top-left, newest first; a click
+/// copies a row.
 pub(super) fn journal_ui(
     mut contexts: EguiContexts,
     inspect: Res<InspectMode>,
@@ -164,8 +149,7 @@ pub(super) fn journal_ui(
     names: Res<crate::names::NameCache>,
     net_commands: Res<NetCommands>,
     time: Res<Time>,
-    // The copied row's edge stamp (`CastRecord::at` is unique per row) + when the copy happened,
-    // for the per-row confirmation flash.
+    // The copied row's `at` (unique per row) and when it was copied, for the confirmation flash.
     mut copied: Local<Option<(f64, f32)>>,
 ) -> Result {
     if !inspect.enabled || journal.records.is_empty() {
@@ -189,7 +173,6 @@ pub(super) fn journal_ui(
                             .color(OVERLAY_TEXT_DIM),
                     );
                     for (i, r) in journal.records.iter().rev().take(SHOWN).enumerate() {
-                        // The caster: "you", the ask-once name cache, or the raw guid.
                         let caster = if self_guid.0 == Some(r.caster) {
                             "you".to_string()
                         } else {
@@ -274,7 +257,6 @@ pub(super) fn journal_ui(
                             ));
                             *copied = Some((r.at, time.elapsed_secs()));
                         }
-                        // The same confirmation the card gives, per row.
                         if copied.is_some_and(|(at, t)| {
                             at == r.at && time.elapsed_secs() - t < super::inspect::COPY_FLASH_SECS
                         }) {
diff --git a/crates/benilla-app/src/debug_panel/mod.rs b/crates/benilla-app/src/debug_panel/mod.rs
index de2166a8..a7e6ffe5 100644
--- a/crates/benilla-app/src/debug_panel/mod.rs
+++ b/crates/benilla-app/src/debug_panel/mod.rs
@@ -1,31 +1,7 @@
-//! Standardized in-window debug panel (egui).
-//!
-//! The panel is a rounded, translucent **window floated off the top-right corner** (a gap from the
-//! edges, like the perf pill) — it overlays the 3D view, which renders full-screen underneath and is
-//! never letterboxed. Fixed width (no resize handle). [`DEV_CHORD`]+`D` shows/hides it (1043, 1048).
-//! Its look (translucent dark backing + crisp text) is shared with the perf pill and the inspector card
-//! via [`OVERLAY_FILL`] / [`overlay_text`], so the dev overlays read as one family.
-//!
-//! ## How it's wired (so future subsystems slot in cleanly)
-//! - [`DebugState`] is one resource grouped into per-subsystem sections ([`ModelDebug`],
-//!   [`LightingDebug`], …; new subsystems add sibling fields).
-//! - The panel UI ([`debug_panel_ui`]) reads/writes that resource via egui widgets.
-//! - Small **apply** systems turn the resource into world changes (e.g. [`apply_model_visibility`]).
-//!   Each only does work when its slice of the state actually changes (tracked with a `Local`
-//!   snapshot), so leaving the panel open costs nothing. (Lighting is now resolved in `lighting.rs`;
-//!   this section is time controls + a readout, not knobs.)
-//! - [`EguiPointerOver`] publishes "the mouse is talking to the egui overlays" each pass; both it
-//!   and the combined source of truth gameplay reads ([`crate::ui_script::PointerOverUi`]) are
-//!   *defined* by that combiner, and this module only writes them (decisions 0026/1174 — dev
-//!   plugins must be droppable without breaking gameplay reads, so gameplay may not name a
-//!   dev-owned type).
-//!
-//! Adding a section for a new subsystem is therefore: a `FooDebug` field, a few widgets in the
-//! panel, and one `apply_foo` system — no plumbing changes. (Weather is the worked example.)
-//!
-//! Rendering uses bevy_egui's manual-context mode: auto-creation is disabled in [`DebugPanelPlugin`]
-//! and a dedicated full-window overlay camera composites egui over the finished frame (a transparent
-//! canvas, premultiplied over the swapchain). See bevy_egui's `side_panel` example.
+//! The in-window egui debug panel, floated top-right over the full-screen world and toggled by
+//! [`DEV_CHORD`]+`D`. It edits [`DebugState`]; apply systems elsewhere turn that into world
+//! changes. [`EguiPointerOver`] is owned by `ui_script` and only written here, so gameplay never
+//! names a dev-owned type. egui runs in manual-context mode on its own overlay camera.
 
 use bevy::camera::visibility::RenderLayers;
 use bevy::camera::CameraOutputMode;
@@ -42,58 +18,37 @@ use benilla_world::lighting::{ClockSource, GameClock, WowLighting};
 use benilla_world::model_render::{ModelKind, ModelPart};
 use benilla_world::modkeys::{dev_chord, DEV_CHORD};
 
-/// The egui half of the pointer arbitration: this panel *writes* it, `ui_script` owns it —
-/// so a build without these overlays still compiles gameplay's reads (decision 1174; the
-/// module-doc note above). `InspectMode`, the other half of 0026's named pair, lives there too
-/// and is imported by the two files that touch it (`inspect`, `journal`).
+/// The egui half of the pointer arbitration: written here, owned by `ui_script`.
 use crate::ui_script::EguiPointerOver;
 
 mod inspect;
 mod journal;
 
-/// The dev state this panel edits — resource-only, faithful defaults (decision 0026: the
-/// always-present config layer; this module is only its editor). The engine owns and inits it,
-/// and the per-frame model-visibility apply system that reads its toggles is `model_render`'s.
+/// The dev state this panel edits; the engine owns and inits it.
 use benilla_world::dev_state::DebugState;
 use benilla_world::model_render::{blend_index, kind_index};
 
-/// The World section — identity/map/zone/position readout + the copy-`.go xyz` affordance.
+/// The World section: identity, map, zone and position, and the `.go xyz` copy.
 mod world;
 use world::{world_section, WorldReadout};
 
-/// Shared look for the floating dev overlays — this panel, the perf pill, the inspector card — so they
-/// read as one family. The backing is a **near-solid dark** so the bright text keeps strong contrast
-/// *no matter the scene behind it*: a lightly-translucent box let bright terrain/sky bleed through and
-/// washed the text out, making legibility depend on the view. [`overlay_text`] sets the bright primary
-/// tone; [`OVERLAY_TEXT_DIM`] the readable secondary one. (Lower the alpha for a more see-through box —
-/// at the cost of view-independent contrast.)
+/// The dev overlays' shared backing, near-solid so the text contrast does not depend on the scene.
 pub(crate) const OVERLAY_FILL: egui::Color32 = egui::Color32::from_black_alpha(224);
-/// Primary overlay text — a crisp near-white that reads over the translucent fill (egui's dark default
-/// is only `gray(140)`). Set as the ui's `override_text_color`; explicit `.color(...)` calls still win.
+/// Primary overlay text, set as `override_text_color`; an explicit `.color(...)` still wins.
 pub(crate) const OVERLAY_TEXT: egui::Color32 = egui::Color32::from_gray(235);
-/// De-emphasised overlay text (ids, distances, hints): dimmer than [`OVERLAY_TEXT`] but still crisp on
-/// the translucent backing.
+/// De-emphasised overlay text: ids, distances, hints.
 pub(crate) const OVERLAY_TEXT_DIM: egui::Color32 = egui::Color32::from_gray(180);
 
-/// Apply the shared overlay text treatment for the **compact, fixed-size** surfaces (perf pill,
-/// inspector card): brighten to [`OVERLAY_TEXT`] and disable wrapping. No-wrap also kills the
-/// first-frame layout flash where a fresh auto-sized container hasn't cached its width yet and a label
-/// like "60 fps" briefly breaks across two lines. (The resizable debug panel brightens the same way but
-/// keeps wrapping, so its labels reflow instead of clipping when narrowed.)
+/// Overlay text for the compact fixed-size surfaces: [`OVERLAY_TEXT`], no wrapping, which also
+/// stops a fresh auto-sized container breaking a label across lines on its first frame.
 pub(crate) fn overlay_text(ui: &mut egui::Ui) {
     let style = ui.style_mut();
     style.visuals.override_text_color = Some(OVERLAY_TEXT);
     style.wrap_mode = Some(egui::TextWrapMode::Extend);
 }
 
-/// Strip the **Tab** key from egui's per-frame input so egui never treats it as focus navigation.
-///
-/// Tab is a bound game key — `TargetNearestEnemy` (decision 0166). Left to itself, egui reads Tab at
-/// `begin_pass` (`Focus::begin_pass`) and pulls keyboard focus into whatever focusable widget is on
-/// screen — the always-on perf pill — ringing it and then owning the keyboard. Our egui surfaces are
-/// mouse-driven dev overlays with no tab-to-next-field need, so we drop Tab before the pass sees it.
-/// Bevy's own `ButtonInput<KeyCode>` (what `target::scan` reads) is populated independently from the
-/// same winit events, so TAB targeting still fires — this only removes the phantom egui focus.
+/// Strip Tab from egui's input: it is bound to `TargetNearestEnemy`, and egui would take it as
+/// focus navigation and grab the keyboard. Bevy's `ButtonInput<KeyCode>` still sees it.
 fn strip_egui_tab_focus(mut inputs: Query<&mut EguiInput>) {
     for mut input in &mut inputs {
         input.events.retain(|e| {
@@ -114,10 +69,7 @@ fn track_pointer_over_ui(mut contexts: EguiContexts, mut over: ResMut<EguiPointe
     Ok(())
 }
 
-/// The panel's display order for [`ModelKind`], and the label it writes. Free functions rather
-/// than an inherent `impl`: the type is engine vocabulary now (`model_render`) and an inherent impl
-/// cannot follow it across the crate boundary decision 1160 is drawing — the *panel's* opinion
-/// about how to present it belongs to the panel either way.
+/// The panel's display order for [`ModelKind`].
 const MODEL_KINDS: [ModelKind; 4] = [
     ModelKind::Doodad,
     ModelKind::Wmo,
@@ -155,56 +107,44 @@ fn source_label(s: ClockSource) -> &'static str {
     }
 }
 
-/// Adds the egui plugin, the debug-state resource, the panel UI, and the apply systems.
 pub(crate) use inspect::MouseoverTarget;
 
+/// Adds the egui plugin, the panel UI, the inspector and the cast journal.
 pub struct DebugPanelPlugin;
 
 impl Plugin for DebugPanelPlugin {
     fn build(&self, app: &mut App) {
         app.add_plugins(EguiPlugin::default());
-        // Manual context mode: we host egui on a dedicated overlay camera (below) so we can inset the
-        // *world* camera's viewport without clipping the panel. Disable right after adding the plugin
-        // (the resource exists by then) — before the auto-create system runs at startup.
+        // Manual context mode, egui hosted on its own overlay camera: disable auto-creation right
+        // after adding the plugin, before its startup system runs.
         {
             let mut egui = app.world_mut().resource_mut::<EguiGlobalSettings>();
             egui.auto_create_primary_context = false;
-            // Don't let egui drive the OS cursor icon. The player hides the OS cursor and draws its
-            // own `Point.blp` sprite, so egui's per-hover `CursorIcon::System` inserts are pointless
-            // churn (and a dev panel doesn't need resize/text cursors).
+            // The player hides the OS cursor and draws `Point.blp`, so egui must not drive it.
             egui.enable_cursor_icon_updates = false;
         }
 
-        // `DebugState` itself is `benilla_world::dev_state`'s and the engine inits it — this panel is only
-        // its editor (decision 0026), and eight other subsystems read it whether or not the panel
-        // is installed.
-        // The inspector surface and the cast journal — the two instruments that stood on
-        // `interact` and were registered by it until decision 1160's stage zero. The mouseover
-        // pick comes with them: it never ran except while the inspector was armed, so it was never
-        // the engine's picking, only this overlay's. (`InspectMode` and `EguiPointerOver`, which
-        // this panel writes, are inited by their owner `UiScriptPlugin` — 1174.)
+        // The inspector, its mouseover pick and the cast journal. `DebugState`, `InspectMode` and
+        // `EguiPointerOver` are inited by their owners.
         app.init_resource::<MouseoverTarget>()
             .init_resource::<journal::CastJournal>()
-            // After the UI keyboard feed because `update_mouseover` reads `PointerOverUi`, whose
-            // player-UI half `UiInput` writes — the pick must see this frame's hover, not last
-            // frame's. (`toggle_inspect` itself no longer needs the ordering: its dev chord can't be
-            // typed text, so it reads no keyboard-capture flag — decision 0585.)
+            // After `UiInput`: `update_mouseover` reads `PointerOverUi`, whose player-UI half it
+            // writes, and must see this frame's hover.
             .add_systems(
                 Update,
                 (inspect::toggle_inspect, inspect::update_mouseover)
                     .chain()
                     .after(crate::ui_script::UiInput),
             )
-            // Always recording (messages persist two frames — no ordering constraint needed).
+            // Always recording; messages persist two frames, so no ordering is needed.
             .add_systems(Update, journal::record_casts)
             .add_systems(
                 EguiPrimaryContextPass,
                 (inspect::inspect_ui, journal::journal_ui),
             )
             .add_systems(Startup, spawn_egui_camera)
-            // Keep Tab out of egui: it's a bound game key, never focus-navigation for our overlays.
-            // Runs after bevy_egui fills `EguiInput` and before egui's pass consumes it (the seam
-            // bevy_egui documents for input edits).
+            // Between bevy_egui filling `EguiInput` and the pass consuming it, the seam bevy_egui
+            // documents for input edits.
             .add_systems(
                 PreUpdate,
                 strip_egui_tab_focus
@@ -215,12 +155,10 @@ impl Plugin for DebugPanelPlugin {
                 EguiPrimaryContextPass,
                 (debug_panel_ui, track_pointer_over_ui),
             )
-            // No ordering against the UI keyboard feed: the toggle is a dev chord (1043), which no
-            // focused EditBox can consume and which needs no capture gate — the same reason `perf`'s
-            // and `sound`'s toggles never needed one.
+            // No ordering against `UiInput`: a dev chord cannot be typed text.
             .add_systems(Update, (toggle_panel, gate_egui_lane).chain())
-            // The gate's other half: a gated frame still owes bevy_egui a prepared (empty) pass —
-            // between the end-pass it skipped and the output consumer that doesn't (1452).
+            // A gated frame still owes bevy_egui a prepared empty output, between the end pass it
+            // skipped and the output consumer that still runs.
             .add_systems(
                 PostUpdate,
                 feed_gated_egui_output
@@ -230,29 +168,13 @@ impl Plugin for DebugPanelPlugin {
     }
 }
 
-/// The 1445 gate's missing half (decision 1452). Upstream, `run_manually` means "the app will run
-/// the egui pass itself this frame" — never "off": `process_output_system` still `take()`s an
-/// output from every context every frame and logs at ERROR when none was prepared (bevy_egui
-/// 0.39 and 0.41 alike, `output.rs`). With the lane gated that was one ERROR per frame — a red
-/// herring beside any real failure, and gate-fatal severity for a by-design idle state (ERROR
-/// means "the client is broken": 1450).
-///
-/// So a gated frame *runs the empty pass itself* — `Context::run` with default input and no UI,
-/// exactly what the error message prescribes for manual mode. Zero widgets means zero shapes:
-/// the consumer tessellates nothing, uploads nothing, and the sleeping camera draws nothing —
-/// the lane keeps costing what 1445 bought, and bevy_egui's output contract holds. A context
-/// that genuinely ran (gate open, or a true manual runner) has `Some` output by now and is left
-/// alone.
-///
-/// Not hand-built `FullOutput::default()`: `process_output_system` tessellates whatever it is
-/// given, and tessellating a context that never began a pass panics `No fonts loaded` (measured
-/// here — fonts only initialize inside a real begin-pass). `run` is the initialization path.
+/// Feed each gated context an empty output: `run_manually` is not "off", and bevy_egui's
+/// `process_output_system` logs an ERROR every frame a context has none. The first feed is a real
+/// `Context::run`, because tessellating a context that never began a pass panics `No fonts loaded`.
 fn feed_gated_egui_output(
     mut contexts: Query<(&mut EguiContext, &mut EguiFullOutput, &EguiContextSettings)>,
-    // The empty pass's output after its first run, with the one-time texture delta (the font
-    // atlas) already delivered: every later gated frame feeds this clone instead of running a
-    // real begin/end pass — memory GC, a fresh `FullOutput`, a tessellation of nothing —
-    // 1.4 % of a parked frame's main thread for a panel that is closed (decision 1979).
+    // The empty pass's output minus its one-time texture delta, fed on every later gated frame
+    // instead of running a real pass.
     mut cached: Local<Option<egui::FullOutput>>,
 ) {
     for (mut ctx, mut full_output, settings) in &mut contexts {
@@ -260,10 +182,8 @@ fn feed_gated_egui_output(
             full_output.0 = Some(match &*cached {
                 Some(out) => out.clone(),
                 None => {
-                    // `get_mut`, not `get`: the immutable getter sits behind bevy_egui's
-                    // `immutable_ctx` feature, off in our build. The first run is fed whole
-                    // (its texture delta carries the fonts); the cache keeps everything but
-                    // that delta, which must reach the GPU exactly once.
+                    // `get_mut`: `get` needs bevy_egui's `immutable_ctx` feature. The font
+                    // texture delta must reach the GPU exactly once, so the cache drops it.
                     let out = ctx.get_mut().run(egui::RawInput::default(), |_| {});
                     let mut keep = out.clone();
                     keep.textures_delta = Default::default();
@@ -276,54 +196,26 @@ fn feed_gated_egui_output(
     }
 }
 
-/// A full-window overlay camera that hosts the primary egui context and composites it over the 3D
-/// scene (higher order, alpha blend, no clear). Renders no world geometry (`RenderLayers::none`).
-/// Order 2 — above the player-UI quad pass (`ui_pass::PlayerUiPlugin`, order 1), which itself sits
-/// above the order-0 world camera. Per decision 0025's overlay arbitration ("dev overlays composite
-/// over" everything else) and 0068 §2: dev overlays always stay on top of the player UI.
+/// The full-window overlay camera hosting the primary egui context, order 2: above the player-UI
+/// pass (order 1) and the world camera (order 0), so dev overlays always sit on top.
 fn spawn_egui_camera(mut commands: Commands) {
     commands.spawn((
         PrimaryEguiContext, // `#[require(EguiContext)]` ⇒ this camera carries EguiContext
-        // Named so [`crate::preflight`]'s MSAA check can say WHICH cameras disagree — an
-        // entity id in that error is a lookup, a name is the answer (decision 1659).
+        // Named for [`crate::preflight`]'s MSAA check, which reports cameras by name.
         Name::new("egui dev-overlay camera"),
         Camera2d,
-        // **No MSAA — and saying so is what keeps the panel openable at all** (decision 1659).
-        // Silence here does not mean "none": `Camera` requires `Msaa`, whose `Default` is
-        // `Sample4`, so this camera used to carry four samples without ever naming them. That was
-        // invisible while the player-UI camera silently carried four too — and became a fatal
-        // `Attachments have differing sample counts` the moment 1628 gave that one `Msaa::Off`,
-        // because Bevy's two prepare passes disagree about whether MSAA is part of a texture's
-        // identity: `prepare_view_targets` keys the COLOUR target on `(target, usage, hdr, msaa)`,
-        // while `core_2d::prepare_core_2d_depth_textures` keys the DEPTH texture on the target
-        // ALONE (`core_3d`'s equivalent does include it — the asymmetry is 2D-only). Two
-        // `Camera2d`s on one window then share one depth texture at whichever sample count the
-        // first-iterated camera stamped on it, and the other one's pass is invalid.
-        //
-        // Off is also simply right here: egui feathers its own edges in the tessellator, so
-        // multisampling this overlay buys nothing and costs a full-window 4× colour texture and 4×
-        // the fill — the same arithmetic as 1628. [`crate::preflight`] now checks the agreement
-        // every run, so the next camera that stays silent is named in the log instead of in a wgpu
-        // validation error that names no camera at all.
+        // Set explicitly: `Camera` requires `Msaa`, default `Sample4`, and Bevy keys the 2D depth
+        // texture on the target alone, so this must match the player-UI camera's `Msaa::Off` or a
+        // pass fails validation. egui feathers its own edges anyway.
         bevy::render::view::Msaa::Off,
         RenderLayers::none(),
         Camera {
             order: 2,
-            // **An overlay composites only its own pixels** — the law the player-UI camera's
-            // clear already states. egui paints onto a transparent canvas, and the output blit
-            // lays that canvas over the finished frame in the swapchain. bevy_egui's own pass
-            // blends PREMULTIPLIED (`egui::Color32` is premultiplied, and its pipeline says so),
-            // so the canvas holds premultiplied colour with coverage in alpha, and the blit has
-            // to compose it as such — `SrcAlpha` would weight it by alpha twice.
-            //
-            // It used to load the shared main texture instead (`ClearColorConfig::None`), which
-            // happened to hold the player-UI camera's decoded frame: two cameras on one window
-            // share bevy's main textures, and that camera's decode flipped them. The blit then
-            // re-emitted the whole frame over itself. Since decision 2206 the player-UI camera
-            // writes the swapchain directly and leaves its main texture un-decoded, so an
-            // overlay that loaded it would present the UI ~2.2× bright whenever the panel was
-            // open. Clearing is what an overlay should have done all along; and, like the
-            // player-UI camera, it never touches the world image, so writeback is off.
+            // An overlay composites only its own pixels: egui paints a cleared transparent canvas
+            // in premultiplied colour, so the blit over the swapchain blends premultiplied
+            // (`SrcAlpha` would weight it twice). Loading the shared main texture instead would
+            // re-present the player-UI camera's un-decoded frame. It never touches the world
+            // image, so writeback is off.
             output_mode: CameraOutputMode::Write {
                 blend_state: Some(BlendState::PREMULTIPLIED_ALPHA_BLENDING),
                 clear_color: ClearColorConfig::None,
@@ -335,17 +227,9 @@ fn spawn_egui_camera(mut commands: Commands) {
     ));
 }
 
-/// Demand-gate the whole egui lane (decision 1445): when no dev overlay is open — panel closed,
-/// inspect off (the perf HUD's pill is quads on the player-UI pass and never needs this lane;
-/// 1453/1454) — the primary context goes `run_manually` (which
-/// `bevy_egui`'s context-pass loop honors by skipping it outright: no begin/end pass, no
-/// tessellate, no `EguiPrimaryContextPass` run) and the overlay camera sleeps (no Core2d graph
-/// run, no composite, no render-side prep). A hidden dev surface then costs what a player build
-/// pays — nothing; before the gate the lane drew an EMPTY overlay for ~0.33 traced ms/frame
-/// (the 1445 trace). One-frame lag behind the toggles, invisible on a chord press.
-///
-/// `EguiPointerOver` clears on the way down: its writer ([`track_pointer_over_ui`]) lives inside
-/// the gated pass and would hold the last hover forever.
+/// Demand-gate the egui lane: with the panel closed and inspect off, the primary context goes
+/// `run_manually` (bevy_egui skips its pass) and the overlay camera sleeps, so a hidden dev surface
+/// costs nothing. `EguiPointerOver` clears on the way down: its writer runs inside the gated pass.
 fn gate_egui_lane(
     debug: Res<DebugState>,
     inspect: Res<crate::ui_script::InspectMode>,
@@ -367,20 +251,13 @@ fn gate_egui_lane(
 }
 
 fn toggle_panel(keys: Res<ButtonInput<KeyCode>>, mut debug: ResMut<DebugState>) {
-    // The dev chord + `D` (decision 1048). It was a *bare* backtick until 1043 — backtick reads as
-    // "not a game key", but it is one ([`crate::bindings::chord`] gives it the token `` ` ``, so the
-    // reference's binding UI can bind it like any other), which made a bare toggle here exactly the
-    // squat 0585 moved the perf HUD off `P` for. 1043 put it on the chord; `` ` `` is a bad key to
-    // hold a chord on, so it became a letter like the rest of the fleet. The chat-bar/EditBox gate
-    // the bare key needed is gone either way: a chord can't be mistaken for typed text.
+    // The dev chord + `D`: a bare key would squat on a bindable game key.
     if dev_chord(&keys, KeyCode::KeyD) {
         debug.open = !debug.open;
     }
 }
 
-/// Draw the panel as a translucent **overlay** on the right — the world renders full-screen
-/// underneath (no viewport inset). `ui_script::PointerOverUi` keeps the cursor's panel
-/// interactions from leaking into gameplay mouse-look.
+/// Draw the panel as an overlay on the right over the full-screen world.
 fn debug_panel_ui(
     mut contexts: EguiContexts,
     stamp: Res<benilla_world::build_id::BuildId>,
@@ -412,8 +289,7 @@ fn debug_panel_ui(
     }
 
     let ctx = contexts.ctx_mut()?;
-    // Full height: the window spans the view (an 8 px gap top and bottom), rather than auto-sizing to
-    // however much content the open sections happen to have.
+    // Full height, rather than auto-sized to the open sections.
     let panel_h = (ctx.content_rect().height() - 32.0).max(120.0);
     egui::Window::new("benilla_debug")
         .title_bar(false)
@@ -428,17 +304,14 @@ fn debug_panel_ui(
                 .inner_margin(egui::Margin::symmetric(10, 8)),
         )
         .show(ctx, |ui| {
-            // Brighten to match the overlays; keep egui's default wrapping so labels reflow, not clip.
+            // Brighten like the overlays but keep wrapping, so labels reflow rather than clip.
             ui.visuals_mut().override_text_color = Some(OVERLAY_TEXT);
-            ui.set_width(280.0); // fixed width — no resize handle
+            ui.set_width(280.0); // fixed width, no resize handle
             ui.set_height(panel_h); // fill the height; sections scroll within it
 
             egui::ScrollArea::vertical()
                 .auto_shrink([false, false])
-                // Leave room under the scroll for the pinned footer below (hotkey map + build id).
-                // Three lines' worth: the footer keeps the panel's default wrapping, so a font
-                // whose metrics run wider than ours reflows the hotkey map instead of having its
-                // second line clipped away.
+                // Room for the pinned footer: three lines, as a wider font wraps the hotkey map.
                 .max_height(panel_h - 56.0)
                 .show(ui, |ui| {
                     // Disjoint borrows of the sections so each can drive its own widgets.
@@ -449,9 +322,6 @@ fn debug_panel_ui(
                         weather: w,
                         ..
                     } = &mut *debug;
-                    // WHERE AM I — the `.gps` of the panel: identity, map, zone, position, tile
-                    // residency, and the click-to-copy `.go xyz` teleport line that feeds the
-                    // headless probes (`WOW_PROBE_CHAT`) and the FPS-journal loop.
                     egui::CollapsingHeader::new("World")
                         .default_open(true)
                         .show(ui, |ui| world_section(ui, &mut world));
@@ -475,19 +345,12 @@ fn debug_panel_ui(
                                     format!("{}  ·  {}", kind_label(k), kind_counts[kind_index(k)]),
                                 );
                             }
-                            // The doodad-animation cost meter (decision 0130): how many placed
-                            // doodads carry an anim host, how many are ticking right now (the
-                            // draw gate pauses hidden ones), how many batches sample a
-                            // material-alpha loop (phase 2), and how many materials scroll their
-                            // UVs (phase 3 — waterfalls).
+                            // Doodad animation cost: anim hosts, ticking ones (hidden ones pause),
+                            // material-alpha samplers and UV-scrolling materials.
                             let ticking = anim_hosts.iter().filter(|h| h.active).count();
-                            // Of the material samplers, how many resolve to **0 right now** — the
-                            // batches the reference culls this frame (`A <= 0`,
-                            // `0x707b3a`–`0x707b5c`). Non-zero as soon as a voidwalker/banshee/
-                            // slime/infernal is in view: those models author geometry that only
-                            // appears on death, and this counter is what says we are hiding it
-                            // rather than drawing it. `dim` counts the partial factors — a batch
-                            // drawn, but not at full strength.
+                            // Samplers at 0 are batches the reference culls (`A <= 0`,
+                            // `0x707b3a`-`0x707b5c`), such as a voidwalker's death-only geometry;
+                            // `dim` counts batches drawn below full strength.
                             let (mut hidden, mut dim) = (0usize, 0usize);
                             for m in &mat_anims {
                                 if m.current <= 0.0 {
@@ -505,17 +368,12 @@ fn debug_panel_ui(
                             ));
 
                             ui.add_space(6.0);
-                            // WMO portal cull A/B (decision 0031): off ⇒ every building group always
-                            // draws (the cathedral reappears from the Trade District).
+                            // WMO portal cull A/B: off, every building group always draws.
                             ui.checkbox(&mut m.portal_cull, "WMO portal visibility cull");
-                            // The cull probe (decision 0022): a one-click full trace dump — stand where a
-                            // room vanishes, click, and the exact seed evidence + per-portal verdicts land
-                            // in a file.
+                            // Dumps the seed and per-portal verdicts to a file.
                             if ui.button("dump WMO cull trace").clicked() {
-                                // Under the one folder (0954/1486), beside the crash reports and
-                                // the stall samples. The world crate is handed the path because
-                                // it has no `local_state` of its own; a hermetic run has no
-                                // folder, and the click says so instead of writing into the cwd.
+                                // Into the diagnostics folder; the world crate has no
+                                // `local_state`, and a hermetic run has no folder at all.
                                 match crate::local_state::diagnostics_dir() {
                                     Some(dir) => {
                                         cull_probe.dump_to = Some(dir.join("wmo-cull-trace.txt"));
@@ -531,7 +389,7 @@ fn debug_panel_ui(
                     egui::CollapsingHeader::new("Lighting")
                         .default_open(false)
                         .show(ui, |ui| {
-                            // Time of day — drives the DBC-sampled colors + the sun's day-arc.
+                            // Time of day drives the Light.dbc colours and the sun's arc.
                             ui.strong(format!(
                                 "Time of day: {}  ({})",
                                 hhmm(clock.minute),
@@ -545,8 +403,7 @@ fn debug_panel_ui(
                                             .text("scrub time")
                                             .custom_formatter(|n, _| hhmm(n as u32)),
                                     );
-                                    // Exact per-minute entry: drag/scroll ±1 min, or click to type a raw
-                                    // minute (0..1439) or an `HH:MM` time — for landing on an exact moment.
+                                    // Exact entry: drag by one minute, or type a minute or `HH:MM`.
                                     ui.add(
                                         egui::DragValue::new(&mut l.manual_minute)
                                             .range(0..=1439)
@@ -568,19 +425,18 @@ fn debug_panel_ui(
 
                             ui.add_space(6.0);
                             ui.strong("Resolved (Light.dbc, this time)");
-                            // 0..255 bytes (eyedrop-friendly vs the reference client) + a swatch.
+                            // 0..255 bytes, for eyedropping against the reference, and a swatch.
                             let byte = |v: f32| (v.clamp(0.0, 1.0) * 255.0).round() as i32;
                             let swatch = |ui: &mut egui::Ui, name: &str, c: [f32; 3]| {
                                 let (r, g, b) = (byte(c[0]), byte(c[1]), byte(c[2]));
                                 let col = egui::Color32::from_rgb(r as u8, g as u8, b as u8);
-                                // The label text is tinted the resolved color (a swatch the font always
-                                // renders); the [r,g,b] are the exact 0..255 values for eyedrop A/Bs.
+                                // The label is tinted the resolved colour, as its own swatch.
                                 ui.colored_label(col, format!("{name}  [{r}, {g}, {b}]"));
                             };
                             swatch(ui, "ambient (row 1)", lighting.ambient);
                             swatch(ui, "diffuse (row 0)", lighting.diffuse);
                             swatch(ui, "specular (row 9)", lighting.spec);
-                            // The backdrop / fog colour (row 7) — what `ClearColor` shows behind the dome.
+                            // The fog colour (row 7) is also `ClearColor` behind the dome.
                             swatch(ui, "fog / backdrop (row 7)", lighting.fog_color);
                             let d = lighting.sun_dir;
                             ui.label(
@@ -598,7 +454,7 @@ fn debug_panel_ui(
                     egui::CollapsingHeader::new("Weather")
                         .default_open(false)
                         .show(ui, |ui| {
-                            // Live state readout (the two ramped channels, decision 0302).
+                            // The two ramped channels.
                             if let Some(ws) = weather_state.as_ref() {
                                 ui.strong(format!(
                                     "{:?}  ·  effect {:.2}  ·  sky {:.2}  ·  storm blend {:.2}",
@@ -608,10 +464,8 @@ fn debug_panel_ui(
                                     benilla_world::weather::storm_blend(ws.sky_density),
                                 ));
                             }
-                            // The `weatherDensity` setting (video-options Weather Intensity 0–3)
-                            // — the real game setting, not a tuning knob. Scales the rain/snow/
-                            // mist spawn gain via the `0x67b870` quality table; default 3 matches
-                            // the reference install's Config.wtf.
+                            // The `weatherDensity` CVar (Weather Intensity 0-3), scaling spawn
+                            // gain through the `0x67b870` quality table.
                             if let Some(ws) = weather_state.as_mut() {
                                 let mut wd = ws.weather_density;
                                 ui.horizontal(|ui| {
@@ -624,7 +478,7 @@ fn debug_panel_ui(
                                     ws.weather_density = wd;
                                 }
                             }
-                            // The override scrub — drives the same apply path as the wire.
+                            // The override drives the same apply path as the wire.
                             let before = (w.force, w.kind, w.grade.to_bits(), w.instant);
                             ui.checkbox(&mut w.force, "override server weather");
                             ui.add_enabled_ui(w.force, |ui| {
@@ -643,8 +497,6 @@ fn debug_panel_ui(
                             }
                         });
 
-                    // The object inspector is its own dev-chord `I` surface (see `interact.rs`), not a
-                    // section here — identifying a thing shouldn't need the whole panel open.
                     egui::CollapsingHeader::new("Sound")
                         .default_open(false)
                         .show(ui, |ui| {
@@ -674,15 +526,11 @@ fn debug_panel_ui(
                             }
                         });
 
-                    // The wire-coverage section: connection state + the dropped-packet tally
-                    // (every opcode the codec ignored or failed to parse, by count — a silent
-                    // gap in wire coverage made visible; decision 0022's instrument disposition).
+                    // Connection state and every opcode the codec ignored or failed to parse.
                     egui::CollapsingHeader::new("Net")
                         .default_open(false)
                         .show(ui, |ui| {
-                            // The LAST sample, not the ring average the meter shows: the panel
-                            // is the instrument, and "what did the most recent pong measure" is
-                            // the question a stuck or spiking meter needs answered.
+                            // The last sample, not the meter's ring average.
                             let last_rtt = ping.0.lock_recover().last_rtt_ms;
                             ui.label(if net_status.connected {
                                 match last_rtt {
@@ -722,11 +570,8 @@ fn debug_panel_ui(
                                 }
                             }
                         });
-                    // The step-up probe's last blocked-frame report (`crate::player::step_probe`).
-                    // On the panel *because a capture has to be steerable*: the director walks into
-                    // the kerb that will not climb and watches the `t=` stamp tick and the ladder
-                    // fill in, instead of finding out afterwards that the probe never fired at the
-                    // spot they meant (method §6 — prove the run before reading the result).
+                    // The step-up probe's last blocked-frame report, live, so a run can be seen
+                    // to fire at the intended spot.
                     egui::CollapsingHeader::new("Step-up")
                         .default_open(false)
                         .show(ui, |ui| {
@@ -756,11 +601,9 @@ fn debug_panel_ui(
                                     }
                                 });
                         });
-                    // Future sections add their own CollapsingHeader here.
                 });
 
-            // The pinned footer: the dev-surface hotkey map, so the other overlays are
-            // discoverable from the one surface people find first.
+            // The pinned footer: the dev-surface hotkey map.
             ui.separator();
             ui.label(
                 egui::RichText::new(format!(
@@ -769,9 +612,7 @@ fn debug_panel_ui(
                     .small()
                     .color(OVERLAY_TEXT_DIM),
             );
-            // …and which build this is (`benilla_world::build_id`). Bottom line of the surface a reader is
-            // already on when something looks wrong: a click copies the full sha, so "it looks like
-            // this here" can name the code it happened on.
+            // The build; a click copies the full sha.
             let build = ui.add(
                 egui::Label::new(
                     egui::RichText::new(format!("build {}", stamp.summary()))
diff --git a/crates/benilla-app/src/debug_panel/world.rs b/crates/benilla-app/src/debug_panel/world.rs
index b7d26a01..b9e3a834 100644
--- a/crates/benilla-app/src/debug_panel/world.rs
+++ b/crates/benilla-app/src/debug_panel/world.rs
@@ -1,20 +1,6 @@
-//! The panel's **World** section — the `.gps` of the client: who you are, which map/zone you're
-//! in (and whether the zone system calls it indoors), the exact WoW-space position + facing, and
-//! the terrain stream's tile residency. Pure readout except two affordances:
-//!
-//! - **copy `.go xyz`** — a click puts the vmangos teleport line for the current spot on the
-//!   clipboard (`.go xyz x y z [mapid]`, verified against vmangos `HandleGoXYZCommand`), so "it
-//!   looks wrong *here*" becomes a pasteable coordinate for the headless probes
-//!   (`WOW_PROBE_CHAT`, live-shot runs) and the FPS-journal loop closes without hand-copying
-//!   numbers.
-//! - **land here** — the button half of [`crate::player::land`] (whose chord is the dev chord + `G`),
-//!   shown only while free-flying.
-//!
-//! **While free-flying, the spot is the CAMERA's** — the section gains a `camera` line and the
-//! copy button switches to it. The subject here is "where you are", and detached that is where you
-//! flew to; the frozen avatar is not it. Copying the body's coordinates was the old behaviour, and
-//! it was wrong at exactly the moment the button is worth pressing: you fly out to a spot
-//! precisely *because* you want its number.
+//! The panel's World section: who you are, map and zone, WoW-space position and facing, and tile
+//! residency, plus a copy of the vmangos `.go xyz` line and, while free-flying, a land-here
+//! button. While free-flying the spot is the camera's, not the frozen avatar's.
 
 use benilla_assets::coords::bevy_to_wow;
 use benilla_formats::world_to_tile;
@@ -25,10 +11,7 @@ use bevy_egui::egui;
 use super::OVERLAY_TEXT_DIM;
 use crate::player::land::LandHere;
 
-/// The World section's read side, bundled (the 16-param ceiling of `debug_panel_ui`): where the
-/// player is — map, zone leaf, indoor claim, tile residency — and who they are (guid + the
-/// ask-once name cache the unit frames use). Plus the free-fly pair: the camera's own transform
-/// (the detached spot) and the land-here ask the button writes.
+/// The World section's inputs, bundled to stay under `debug_panel_ui`'s 16-param ceiling.
 #[derive(SystemParam)]
 pub(super) struct WorldReadout<'w, 's> {
     player: Option<Res<'w, crate::player::Player>>,
@@ -37,8 +20,8 @@ pub(super) struct WorldReadout<'w, 's> {
     area: Res<'w, benilla_world::terrain_stream::CurrentArea>,
     areas: Option<Res<'w, crate::area::AreaTableRes>>,
     interior: Res<'w, benilla_world::wmo_portal::CurrentAreaInterior>,
-    /// The camera's own WMO room claim + the exterior-window worklist it produces — the two inputs
-    /// [`benilla_world::exterior_cull`] runs on. See the readout below for why they are worth a line.
+    /// The camera's WMO room claim and the exterior windows it produces, the two inputs of
+    /// [`benilla_world::exterior_cull`].
     room: Res<'w, benilla_world::wmo_portal::CameraInteriorClaim>,
     windows: Res<'w, benilla_world::wmo_portal::ExteriorWindows>,
     skybox: Res<'w, benilla_world::skybox::CameraSkybox>,
@@ -51,11 +34,8 @@ pub(super) struct WorldReadout<'w, 's> {
     land: MessageWriter<'w, LandHere>,
 }
 
-/// Render the section: readout lines top-down (who → map → zone → position → tiles), the copy
-/// affordance last.
+/// Render the section: who, map, zone, position and tiles, the buttons last.
 pub(super) fn world_section(ui: &mut egui::Ui, world: &mut WorldReadout) {
-    // Who: the character name through the ask-once cache (fills a frame later, like the unit
-    // frames), or a plain offline line.
     match world.self_guid.0 {
         Some(guid) => {
             let name = world
@@ -71,7 +51,7 @@ pub(super) fn world_section(ui: &mut egui::Ui, world: &mut WorldReadout) {
         }
     }
 
-    // Map: id + Map.dbc name (the directory is the asset path, the name is the human one).
+    // Map: id and `Map.dbc` name.
     let map_id = world.map.as_ref().map(|m| m.0);
     if let Some(id) = map_id {
         let name = world
@@ -82,9 +62,8 @@ pub(super) fn world_section(ui: &mut egui::Ui, world: &mut WorldReadout) {
         ui.label(format!("map {id} · {name}"));
     }
 
-    // Zone: the leaf area and its top zone (one line when they coincide), plus the zone-text
-    // indoor claim — the same authorities the splash/minimap text reads, so this readout and
-    // the player-facing text can never disagree.
+    // Zone: top zone and leaf area, and the indoor claim, from the same sources the zone text
+    // reads, so the two cannot disagree.
     if let Some(leaf) = world.area.0 {
         let (leaf_name, zone_name) = match world.areas.as_ref() {
             Some(a) => (a.0.name(leaf), a.0.top_zone(leaf).and_then(|z| a.0.name(z))),
@@ -98,13 +77,9 @@ pub(super) fn world_section(ui: &mut egui::Ui, world: &mut WorldReadout) {
         if world.interior.0.is_some() {
             line.push_str("  ·  indoors");
         }
-        // The WMO skybox engagement, right beside the interior claim it derives from: both come off
-        // the camera's down-ray seed, so when the backdrop flips between the building's painted sky
-        // and the Light.dbc gradient, this is the line that says which — and whether the claim moved
-        // under it. From the chair the two are only distinguishable by colour. The weight is the
-        // 4-second crossfade (== the interior-fog blend, one number): `w 0.00` beside a name means
-        // the flood published a skybox the crossfade hasn't engaged — faithful standing outside
-        // the gate, not a resolve bug.
+        // The WMO skybox or the Light.dbc gradient, from the same down-ray as the interior claim.
+        // The weight is the 4-second crossfade: `w 0.00` beside a name is a published skybox not
+        // yet engaged, which is correct standing outside the gate.
         match world.skybox.0.as_deref() {
             Some(path) => {
                 let leaf = path.rsplit('\\').next().unwrap_or(path);
@@ -119,20 +94,12 @@ pub(super) fn world_section(ui: &mut egui::Ui, world: &mut WorldReadout) {
         ui.label(egui::RichText::new(format!("leaf area {leaf}")).color(OVERLAY_TEXT_DIM));
     }
 
-    // The exterior-scene gate, in the two terms that decide it (decision 0774): which WMO ROOM the
-    // camera's own down-ray claims, and how many portal windows that room's flood left onto the
-    // outdoor world. Terrain draws iff a window admits it, so "why can I still see the ground from
-    // in here?" has exactly three answers and this line says which:
-    //   * `room —` — no claim at all. We are on the OUTSIDE leg and draw the whole exterior, which
-    //     is correct *if* the reference is too (a `0x8`-flagged group claims nothing — Stratholme's
-    //     entrance hall is EXTERIOR, and the reference draws the world there as well).
-    //   * `windows N` with N large, or a window covering most of the screen — we are indoors and the
-    //     doorway rects are too generous.
-    //   * `windows 0` — sealed, nothing exterior may draw; terrain visible anyway means something
-    //     is reaching the screen that is not tagged `ExteriorScene`. Every exterior bucket is
-    //     tagged now — WMO placements since 0784, open-world liquid since 1652 — so at `windows 0`
-    //     the honest reading of anything still drawn is a bug, not a known gap.
-    // Two numbers is the whole diagnosis, and neither was readable from the chair before.
+    // The exterior-scene gate: the WMO room the camera's down-ray claims and the portal windows
+    // its flood leaves onto the outdoors; terrain draws only through a window.
+    //   * `room —`: no claim, the whole exterior draws (a `0x8`-flagged group claims nothing, and
+    //     the reference draws the world there too).
+    //   * many windows, or one covering most of the screen: the doorway rects are too generous.
+    //   * `windows 0`: sealed; anything exterior still drawn is not tagged `ExteriorScene`, a bug.
     let room_line = match world.room.0 {
         Some(claim) => format!("room g{:02}", claim.room.group),
         None => "room —".to_string(),
@@ -155,8 +122,7 @@ pub(super) fn world_section(ui: &mut egui::Ui, world: &mut WorldReadout) {
     };
     ui.label(egui::RichText::new(format!("{room_line}  ·  {window_line}")).color(OVERLAY_TEXT_DIM));
 
-    // Position + facing, raw WoW coords (what the wire and every probe speak); the tile the
-    // feet are on and how much of the stream window is spawned.
+    // Position and facing in raw WoW coords; the tile underfoot and the stream's residency.
     let Some(player) = world.player.as_ref().filter(|p| p.active) else {
         return;
     };
@@ -176,9 +142,8 @@ pub(super) fn world_section(ui: &mut egui::Ui, world: &mut WorldReadout) {
             .color(OVERLAY_TEXT_DIM),
     );
 
-    // Free-flying: the camera is the spot (the lines above are the frozen body, kept — knowing
-    // where you left it is exactly what you fly back to). This line, and the copy/land pair below,
-    // all speak the camera's coordinates while detached.
+    // Free-flying: the lines above stay the frozen body; this line and the buttons below use
+    // the camera's coordinates.
     let detached_at = detached
         .then(|| {
             world
@@ -197,8 +162,7 @@ pub(super) fn world_section(ui: &mut egui::Ui, world: &mut WorldReadout) {
         );
     }
 
-    // The teleport line: `.go xyz x y z [mapid]` (vmangos argument order). Copied, not shown —
-    // the readout above already displays every number.
+    // `.go xyz x y z [mapid]`, vmangos's argument order (`TeleportCommands.cpp:854`).
     let [gx, gy, gz] = detached_at.unwrap_or([x, y, z]);
     let copy_label = if detached_at.is_some() {
         "copy .go xyz (camera)"
@@ -212,8 +176,8 @@ pub(super) fn world_section(ui: &mut egui::Ui, world: &mut WorldReadout) {
         };
         ui.ctx().copy_text(line);
     }
-    // Land here — the button half of the dev chord's `G`. Only while detached, because
-    // attached the camera sits behind the avatar and "land at the camera" means a step backwards.
+    // The button form of the dev chord's `G`, only while detached: attached, the camera sits
+    // behind the avatar.
     if detached_at.is_some() && ui.button("land here").clicked() {
         world.land.write(LandHere);
     }
diff --git a/crates/benilla-app/src/dev.rs b/crates/benilla-app/src/dev.rs
index b1532881..053f7a9d 100644
--- a/crates/benilla-app/src/dev.rs
+++ b/crates/benilla-app/src/dev.rs
@@ -1,57 +1,35 @@
-//! **The dev/player seam** — the two instrument groups, and the one rule that governs them
-//! (decision 0026 set the target, 1173 mandated the build, 1174 is what got built).
+//! The dev/player seam and its two instrument groups. Dev may see anything; nothing may depend on
+//! dev. The player build (`cargo build -p benilla --no-default-features` in `scripts/gates.sh`)
+//! holds the direction: a fact gameplay needs from an instrument goes to [`crate::run_mode`], never
+//! through a `use` from gameplay.
 //!
-//! ```text
-//! Dev may see anything; nothing may depend on dev.
-//! ```
-//!
-//! That is the whole boundary, and it is one-directional on purpose. An instrument's job *is* to
-//! see everything — 1160 measured 266 references from the instruments into 63 of the app's 142
-//! modules — so a crate wall here would mean publishing hundreds of internals as permanent public
-//! API shaped by whatever a panel wanted to poke at. A `cfg` seam has the opposite property: the
-//! instruments keep reaching in exactly as far as they like, and only the *direction* is
-//! constrained.
-//!
-//! **The mechanism is not this comment.** It is `cargo build -p benilla --no-default-features` in
-//! `scripts/gates.sh`. 0026 wrote this same rule down in June 2026 with no failing build behind
-//! it, and by August there were 24 references from non-dev code into the instruments across 12
-//! files (1173) — not through carelessness, but because a rule with no failing test is a wish.
-//! When gameplay needs a fact an instrument happens to know, the fact goes to
-//! [`crate::run_mode`] (always present, player-faithful default) and the instrument writes it
-//! there. It does not get a `use` line from gameplay.
-//!
-//! **What is deliberately NOT in here:** `benilla_world::dev_state` (the always-present config
-//! layer — its defaults *are* the player behaviour, so it ships), `pipe_warm` (a player on macOS
-//! eats every synchronous pipeline stall without it — 0837/1116), and `art_scope` (within-map art
-//! residency: engine, and it travels with `WorldPlugins` — 0729).
+//! Not here, because they ship: `benilla_world::dev_state` (its defaults are the player behaviour),
+//! `pipe_warm` (without it a player on macOS eats every synchronous pipeline stall) and `art_scope`
+//! (engine, it travels with `WorldPlugins`).
 
 use bevy::prelude::*;
 
-/// `WOW_CAPTURE=list` — the harness scenario names `scripts/visual.sh` reads, printed before any
-/// window or asset setup. Answers nothing in a player build, which has no scenarios.
+/// `WOW_CAPTURE=list`: prints the harness scenario names `scripts/visual.sh` reads, before any
+/// window or asset setup; nothing in a player build.
 pub(crate) fn print_scenario_names() {
     #[cfg(feature = "dev")]
     crate::capture::print_scenario_names();
 }
 
-/// `WOW_PROBE=list` — the probe fleet's environment registry (`capture::probe_env`): every
-/// `WOW_PROBE*` variable, whether it arms the un-occludable window, and `WOW_PROBE`'s own named
-/// values — printed before any window or asset setup. Answers nothing in a player build, which
-/// has no probes.
+/// `WOW_PROBE=list`: prints the probe environment registry (`capture::probe_env`) before any window
+/// or asset setup; nothing in a player build.
 pub(crate) fn print_probe_vars() {
     #[cfg(feature = "dev")]
     crate::capture::probe_env::print();
 }
 
-/// `WOW_HOVER_LOG_REPORT=<csv>` — re-read a recorded run and print its report, no window, no game.
-/// New analysis lands on runs already captured (see `hover_log`).
+/// `WOW_HOVER_LOG_REPORT=<csv>`: prints a recorded hover-log run's report, with no window or game.
 pub(crate) fn report_recorded_hover_log(_path: &str) {
     #[cfg(feature = "dev")]
     crate::hover_log::report_recorded_file(_path);
 }
 
-/// **The instruments.** One group, added where the debug panel has always sat — first among them,
-/// because `PerfPlugin` needs the egui plugin and context it sets up.
+/// The instruments, debug panel first: `PerfPlugin` needs the egui plugin and context it sets up.
 pub(crate) struct DevToolsPlugin;
 
 impl Plugin for DevToolsPlugin {
@@ -61,30 +39,24 @@ impl Plugin for DevToolsPlugin {
         {
             app.add_plugins(crate::debug_panel::DebugPanelPlugin)
                 .add_plugins(crate::perf::PerfPlugin)
-                // `WOW_FX_CENSUS=1`: where this frame's particle draws are addressed, and whether
-                // the view they name is switched on (decision 0775). An instrument, and one that
-                // reads the portrait booths — so it belongs on this side of the line.
+                // `WOW_FX_CENSUS=1`: where particle draws are addressed, and whether their view is
+                // on.
                 .add_plugins(crate::capture::fx_draw_census_plugin)
-                // The hover-cost recorder (`WOW_HOVER_LOG`) and the asset-churn meter
-                // (`WOW_ASSET_CHURN`) — both no-ops without their variable.
+                // `WOW_HOVER_LOG` and `WOW_ASSET_CHURN`: no-ops without their variable.
                 .add_plugins(crate::hover_log::HoverLogPlugin)
                 .add_plugins(crate::asset_churn::AssetChurnPlugin)
-                // The session preflight (decision 0649): one banner per world entry naming the body
-                // we logged into, and loud warnings for the states — dead/ghost, GM mode,
-                // server-blocked movement — that silently invalidate a session's readings. Never
-                // env-gated; a warning nobody switches on isn't one.
+                // A banner per world entry naming the body, warning on states that invalidate a
+                // reading (dead, GM mode, server-blocked movement); never env-gated.
                 .add_plugins(crate::preflight::PreflightPlugin)
-                // The probe shield (decision 0677): a body on a probe account is put into vmangos's
-                // `.cheat god` on every world entry — damage clamps at 1 hp instead of killing —
-                // and GM mode is turned OFF, because the shield replaces the only reason it was
-                // ever on. Inert on any other account.
+                // A probe account's body gets vmangos `.cheat god` (damage stops at 1 hp) and GM
+                // mode off on every world entry; inert on any other account.
                 .add_plugins(crate::probe_shield::ProbeShieldPlugin);
         }
     }
 }
 
-/// **The probe fleet** — the capture harness and every scripted live probe, each armed by its own
-/// environment variable and inert without it. Added last so they observe the fully-built app.
+/// The probe fleet: the capture harness and every scripted live probe, each inert without its own
+/// environment variable. Added last so they observe the fully-built app.
 pub(crate) struct DevProbesPlugin;
 
 impl Plugin for DevProbesPlugin {
@@ -92,44 +64,28 @@ impl Plugin for DevProbesPlugin {
     fn build(&self, app: &mut App) {
         #[cfg(feature = "dev")]
         {
-            // The capture harness drives one deterministic screenshot then exits — added last so it observes
-            // the fully-built app. Inert unless `$WOW_CAPTURE` is set.
+            // `$WOW_CAPTURE`: one deterministic screenshot, then exit.
             if crate::run_mode::scenario_active() {
                 app.add_plugins(crate::capture::CapturePlugin);
             }
-            // The LIVE probe shot (orthogonal to the harness): `WOW_LIVE_SHOT=<png>` on a NORMAL connected
-            // run writes one screenshot `WOW_LIVE_SHOT_AT` seconds (default 12) after startup and keeps
-            // running — the agent-side instrument for seeing a live server scene (NPCs, GameObjects, event
-            // spawns) without a scenario. Pair with `WOW_USER`/`WOW_CHAR` + an outer `timeout`.
+            // `WOW_LIVE_SHOT=<png>`: one live-run screenshot at `WOW_LIVE_SHOT_AT` s (default 12).
             if std::env::var("WOW_LIVE_SHOT").is_ok() {
                 app.add_plugins(crate::capture::LiveShotPlugin);
             }
-            // The probe RIG (decision 0651): `WOW_RIG="tauren druid 60 gear:heal-preraid-bis"` finds-or-
-            // creates that body on this slot's probe account, logs in as it, and applies level/spells/gear/
-            // spec/place — the one verb that replaces the hand-assembled GM recipe every session used to
-            // re-derive (see `capture::ProbeRigPlugin`).
+            // `WOW_RIG="tauren druid 60 gear:heal-preraid-bis"`: finds or creates that body on the
+            // probe account, logs in as it and applies level, spells, gear, spec and place.
             if std::env::var("WOW_RIG").is_ok() {
                 app.add_plugins(crate::capture::ProbeRigPlugin);
             }
-            // Any scripted probe keeps its window un-occludable: a fully covered macOS window drops to
-            // ~1 fps drawables, and every probe schedule is wall-clock — a throttled run doesn't measure
-            // slowly, it runs the wrong script (see `capture::ProbeFocusPlugin`, decision 0906).
-            // Which probe variables count is the registry's `wall_clock` column
-            // (`capture::probe_env::PROBE_VARS`), not a list kept here: this list was hand-kept
-            // and had drifted to ten of the twenty-five wall-clock variables when 2265 §A5 read
-            // it against the code, so a mail or auction probe ran covered. The four below are the
-            // non-probe instruments that schedule on the wall clock too.
-            // (`WOW_LIVE_FPS` is in the list because an occluded SETTLE phase streams the world at ~1 fps
-            // and under-warms the scene before sampling even starts — the assertion has to be live from
-            // the first tick, not at the uncap.)
+            // A covered macOS window drops to about 1 fps and probe schedules are wall-clock, so
+            // these keep the window un-occludable: the `wall_clock` column of
+            // `capture::probe_env::PROBE_VARS` plus four instruments. `WOW_LIVE_FPS` needs it from
+            // the first tick, or an occluded settle under-warms the scene.
             if crate::capture::probe_env::wall_clock_vars()
                 .chain([
                     "WOW_RIG",
                     "WOW_LIVE_FPS",
-                    // A screenshot burst and a pick burst are wall-clock schedules too, and on an
-                    // occluded window they capture the same stale drawable over and over: a whole
-                    // day of lamppost A/Bs on the Air read identical to the decimal because every
-                    // frame in every burst was one frame (the halo record).
+                    // On an occluded window a burst captures one stale drawable over and over.
                     "WOW_LIVE_SHOT",
                     "WOW_PICK",
                 ])
@@ -137,319 +93,200 @@ impl Plugin for DevProbesPlugin {
             {
                 app.add_plugins(crate::capture::ProbeFocusPlugin);
             }
-            // The probe-chat one-shot: `WOW_PROBE_CHAT=".go xyz …"` sends GM/chat lines once in-world —
-            // the "park the probe character anywhere" instrument (see `capture::ProbeChatPlugin`).
+            // `WOW_PROBE_CHAT=".go xyz …"`: sends GM or chat lines once in-world.
             if std::env::var("WOW_PROBE_CHAT").is_ok() {
                 app.add_plugins(crate::capture::ProbeChatPlugin);
             }
-            // The probe-lua driver: `WOW_PROBE_LUA="CastSpell(…)"` runs a chunk in the live UI VM once
-            // per world entry — the "press the button headlessly" instrument, re-armed across a relog
-            // so a probe can read the same value on both sides of one (see `capture::ProbeLuaPlugin`).
+            // `WOW_PROBE_LUA`: runs a chunk in the live UI VM once per world entry, across relogs.
             if std::env::var("WOW_PROBE_LUA").is_ok() {
                 app.add_plugins(crate::capture::ProbeLuaPlugin);
             }
-            // The probe-drag driver: `WOW_PROBE_DRAG="RaidGroupButton7>RaidGroup6Slot1"` drags one
-            // named frame onto another through the real pointer path, one gesture step per frame —
-            // the "do what the hand on the mouse does" instrument (see `capture::ProbeDragPlugin`).
+            // `WOW_PROBE_DRAG="A>B"`: drags frame A onto B through the real pointer path.
             if std::env::var("WOW_PROBE_DRAG").is_ok() {
                 app.add_plugins(crate::capture::ProbeDragPlugin);
             }
-            // The probe-hover sweep: `WOW_PROBE_HOVER="ActionButton1;ActionButton2;…"` crosses each
-            // named frame's centre through the real pointer path, pressing nothing — the "hand on
-            // the mouse" `WOW_HOVER_LOG` was built to record and could not supply itself.
+            // `WOW_PROBE_HOVER="A;B;…"`: crosses each frame's centre by the real pointer path.
             if std::env::var("WOW_PROBE_HOVER").is_ok() {
                 app.add_plugins(crate::capture::ProbeHoverPlugin);
             }
-            // The probe-key taps: `WOW_PROBE_KEY="Space@14"` presses keys once in-world — the "press
-            // space headlessly" instrument for input-gated behavior (see `capture::ProbeKeyPlugin`).
+            // `WOW_PROBE_KEY="Space@14"`: presses keys once in-world.
             if std::env::var("WOW_PROBE_KEY").is_ok() {
                 app.add_plugins(crate::capture::ProbeKeyPlugin);
             }
-            // The probe self-termination: `WOW_PROBE_EXIT_AT=<secs>` bounds any scripted live probe's
-            // lifetime — its own knob, not a rider on the Lua probe (see `capture::ProbeExitPlugin`).
+            // `WOW_PROBE_EXIT_AT=<secs>`: bounds any scripted live probe's lifetime.
             if std::env::var("WOW_PROBE_EXIT_AT").is_ok() {
                 app.add_plugins(crate::capture::ProbeExitPlugin);
             }
-            // The ray pick: `WOW_PICK="<x>,<y>"` names every surface along the ray through a screenshot
-            // pixel, nearest first — "what is at the spot `benilla-visual hotspot` flagged, and what is
-            // right behind it" (see `capture::PickProbePlugin`).
+            // `WOW_PICK="<x>,<y>"`: every surface on the ray through a pixel, nearest first.
             if std::env::var("WOW_PICK").is_ok() {
                 app.add_plugins(crate::capture::PickProbePlugin);
             }
-            // The render-phase census: `WOW_PHASE=<uniqueId>` reports, per frame, which phase each of one
-            // placement's batches landed in and where in the draw order — the one thing every scene-side
-            // instrument is blind to, namely whether a surface was submitted at all (see
-            // `capture::PhaseProbePlugin`).
+            // `WOW_PHASE=<uniqueId>`: per frame, the render phase and draw order of one placement.
             if std::env::var("WOW_PHASE").is_ok() {
                 app.add_plugins(crate::capture::PhaseProbePlugin);
             }
-            // The depth readback: `WOW_DEPTH="<x>,<y>"` reports what depth actually won each named pixel,
-            // per frame, as a distance in yards — the link past submission that decides the pixel. Pair it
-            // with `WOW_PICK` at the same pixels to turn "what won" into "whose it was" (see
-            // `capture::DepthProbePlugin`).
-            // `WOW_DEPTH_QUADS=<bone>…` is the same readback taken at a particle quad's OWN pixels — the
-            // moving-subject form, which no hand-written pixel list can hold (see `capture::depth_probe`).
+            // `WOW_DEPTH="<x>,<y>"`: the winning depth at each pixel, in yards; `WOW_DEPTH_QUADS`
+            // takes it at a particle quad's own pixels.
             if std::env::var("WOW_DEPTH").is_ok() || std::env::var("WOW_DEPTH_QUADS").is_ok() {
                 app.add_plugins(crate::capture::DepthProbePlugin);
             }
-            // The bevy_ui node census — "who owns this rectangle" for UI outside the FrameXML quad pass
-            // (see `capture::NodeProbePlugin`).
+            // `WOW_NODE_PROBE`: which bevy_ui node owns a rectangle outside the FrameXML quad pass.
             if std::env::var("WOW_NODE_PROBE").is_ok() {
                 app.add_plugins(crate::capture::NodeProbePlugin);
             }
-            // The mid-run window resize: `WOW_PROBE_RESIZE="<secs>:<W>x<H>"` — the headless fullscreen-
-            // toggle stand-in for resize-reactive layout (see `capture::ProbeResizePlugin`).
+            // `WOW_PROBE_RESIZE="<secs>:<W>x<H>"`: a mid-run resize, standing in for fullscreen.
             if std::env::var("WOW_PROBE_RESIZE").is_ok() {
                 app.add_plugins(crate::capture::ProbeResizePlugin);
             }
-            // The particle census: `WOW_PARTICLE_CENSUS=<secs>` prints per-emitter live counts once —
-            // the trace-comparable coverage number (see `capture::ParticleCensusPlugin`).
+            // `WOW_PARTICLE_CENSUS=<secs>`: per-emitter live counts, once.
             if std::env::var("WOW_PARTICLE_CENSUS").is_ok() {
                 app.add_plugins(crate::capture::ParticleCensusPlugin);
             }
-            // The under-floor census: `WOW_GROUND_CENSUS=<secs>[,<every>]` prints one line per
-            // streamed unit near the body — the server's Z for it, the Z we drew it at, the drop
-            // between them, and the floor over its head. The instrument B197 was missing: it says
-            // whether a unit below a floor was put there by the server or pulled there by us (see
-            // `capture::GroundCensusPlugin`).
+            // `WOW_GROUND_CENSUS`: per nearby unit, the server's Z, our drawn Z, the floor above.
             if std::env::var("WOW_GROUND_CENSUS").is_ok() {
                 app.add_plugins(crate::capture::GroundCensusPlugin);
             }
-            // The transport census: `WOW_LIFT_CENSUS=<secs>[,<every>]` prints one line per
-            // type-11/15 transport GameObject on the map — its arm stage, its cycle, its
-            // visibility pair and its render-descendant count. The instrument B168 was missing: a
-            // lift that isn't on screen is either unsent, unarmed (and so still wearing its spawn
-            // hide), model-less, or simply elsewhere in its cycle, and only numbers tell those
-            // four apart (see `capture::LiftCensusPlugin`).
+            // `WOW_LIFT_CENSUS`: per type-11/15 transport, its arm stage, cycle and visibility.
             if std::env::var("WOW_LIFT_CENSUS").is_ok() {
                 app.add_plugins(crate::capture::LiftCensusPlugin);
             }
-            // The frame-stall injector: `WOW_STALL="<ms>[,<every_s>[,<after_s>]]"` blocks the
-            // main loop on a schedule — the reproduction for "I tabbed away and came back to X",
-            // which no probe can otherwise stage (every scripted probe asserts `AlwaysOnTop`
-            // precisely so the OS cannot throttle it). `WOW_STALL=0` injects nothing and leaves
-            // the frame-delta/occlusion monitor, which is how the premise gets checked rather
-            // than assumed (see `capture::StallPlugin`).
+            // `WOW_STALL="<ms>[,<every_s>[,<after_s>]]"`: blocks the main loop on a schedule to
+            // stage a tab-away; `0` only runs the frame-delta and occlusion monitor.
             if std::env::var("WOW_STALL").is_ok() {
                 app.add_plugins(crate::capture::StallPlugin);
             }
-            // The ribbon-trail census: `WOW_TRAIL_CENSUS=<secs>[,<every>]` prints one line per live
-            // weapon/spell streak — its committed extent in WORLD space, which is the observable:
-            // a rider standing still on a moving deck must draw a SHORT streak, because its edges
-            // are stored on the deck and re-projected through the deck's live pose. A long one is
-            // a streak drawn against the world while its owner stands still (see
-            // `capture::TrailCensusPlugin`).
+            // `WOW_TRAIL_CENSUS`: each ribbon streak's world extent; a rider on a moving deck must
+            // draw a short one, since its edges are stored on the deck.
             if std::env::var("WOW_TRAIL_CENSUS").is_ok() {
                 app.add_plugins(crate::capture::TrailCensusPlugin);
             }
-            // The unit-visual census: `WOW_UNIT_VISUALS=<secs>[,<every>]` prints one line per
-            // streamed entity near the body — whether it got a debug cube, real geometry, or
-            // nothing at all. The instrument B13 was missing: a black slab in a screenshot cannot
-            // say whether the display named no model (our gap) or named one that draws nothing
-            // (an invisible trigger creature — see `capture::UnitVisualsPlugin`, decision 1403).
+            // `WOW_UNIT_VISUALS`: per nearby entity, a debug cube, real geometry or nothing.
             if std::env::var("WOW_UNIT_VISUALS").is_ok() {
                 app.add_plugins(crate::capture::UnitVisualsPlugin);
             }
-            // The motion-jitter meter: `WOW_JITTER=<name-substr>[,<start_s>]` prints one line per
-            // frame for the nearest matching unit — the camera, root and pose terms of its
-            // rendered position, each as a first AND second difference, in mm and in pixels at
-            // its own distance. Δ alone cannot tell a slow idle from noise; Δ² can, and Δ²/dt²
-            // says whether a ragged Δ is bad arithmetic or merely uneven frame times (see
-            // `capture::JitterMeterPlugin`).
+            // `WOW_JITTER=<name>[,<start_s>]`: per frame, the camera, root and pose terms of the
+            // nearest match's position as first and second differences, in mm and pixels.
             if std::env::var("WOW_JITTER").is_ok() {
                 app.add_plugins(crate::capture::JitterMeterPlugin);
             }
-            // The dress census: `WOW_DRESS_CENSUS=<secs>[,<every>]` prints one line per streamed
-            // PLAYER — what the wire asked for (`PLAYER_FLAGS`' hide bits), what we resolved
-            // (helm/cloak display ids) and what is actually attached — plus a `contradictions=`
-            // count for a body dressed in a piece its own preference asked us to hide. B123's
-            // instrument (see `capture::DressCensusPlugin`, decision 1472).
+            // `WOW_DRESS_CENSUS`: per player, `PLAYER_FLAGS` hide bits against what is worn.
             if std::env::var("WOW_DRESS_CENSUS").is_ok() {
                 app.add_plugins(crate::capture::DressCensusPlugin);
             }
-            // The reveal audit: `WOW_REVEAL=<frames>` prints one line per frame from a snap —
-            // the cover, every residency term behind `presentable()`, the settle hold and the
-            // retained pass's collected-vs-published regions. The instrument for "the teleport
-            // showed me a world with no buildings in it" (see `capture::RevealAuditPlugin`).
+            // `WOW_REVEAL=<frames>`: per frame after a snap, the cover and each residency term.
             if std::env::var("WOW_REVEAL").is_ok() {
                 app.add_plugins(crate::capture::RevealAuditPlugin);
             }
-            // The entity census: `WOW_ENTITY_CENSUS=<secs>` prints per-archetype entity counts once —
-            // what the resident entity count is made of (see `capture::EntityCensusPlugin`).
+            // `WOW_ENTITY_CENSUS=<secs>`: per-archetype entity counts, once.
             if std::env::var("WOW_ENTITY_CENSUS").is_ok() {
                 app.add_plugins(crate::capture::EntityCensusPlugin);
             }
-            // The schedule census: `WOW_SCHED_CENSUS=1` prints every schedule's systems with their
-            // executor-relevant flags, both worlds, then exits — the structural inventory under
-            // the orchestration bands (see `capture::SchedCensusPlugin`, decision 1437).
+            // `WOW_SCHED_CENSUS=1`: every schedule's systems in both worlds, then exit.
             if std::env::var("WOW_SCHED_CENSUS").is_ok() {
                 app.add_plugins(crate::capture::SchedCensusPlugin);
             }
-            // The melee live probe: `WOW_PROBE=melee` auto-fights the nearest enemy so the dbg-trace
-            // sink can record the combat-text timeline (see `capture::ProbeMeleePlugin`).
+            // `WOW_PROBE=melee`: fights the nearest enemy for the combat-text trace.
             if std::env::var("WOW_PROBE").as_deref() == Ok("melee") {
                 app.add_plugins(crate::capture::ProbeMeleePlugin);
             }
-            // The partner live probe: `WOW_PROBE=partner` auto-accepts group invites — the party arc's
-            // second-client instrument (decision 0434; see `capture::ProbePartnerPlugin`).
+            // `WOW_PROBE=partner`: accepts group invites, as the party's second client.
             if std::env::var("WOW_PROBE").as_deref() == Ok("partner") {
                 app.add_plugins(crate::capture::ProbePartnerPlugin);
             }
-            // The sea-crossing live probe: `WOW_PROBE=crossing` boards a cross-continent boat and reports
-            // the map seam surviving — decision 0455's instrument (see `capture::ProbeCrossingPlugin`).
+            // `WOW_PROBE=crossing`: boards a cross-continent boat and reports the map seam.
             if std::env::var("WOW_PROBE").as_deref() == Ok("crossing") {
                 app.add_plugins(crate::capture::ProbeCrossingPlugin);
             }
-            // The taxi-flight live probe: `WOW_PROBE=taxi` opens the flight-master menu on the real wire
-            // and rides Stormwind → Sentinel Hill to a measured verdict — decision 0484's end-to-end
-            // instrument (see `capture::ProbeTaxiPlugin`).
+            // `WOW_PROBE=taxi`: flies Stormwind to Sentinel Hill on the real wire.
             if std::env::var("WOW_PROBE").as_deref() == Ok("taxi") {
                 app.add_plugins(crate::capture::ProbeTaxiPlugin);
             }
-            // The guard-directions live probe: `WOW_PROBE=guardpoi` asks a Stormwind guard where the
-            // weapons trainer is and reports the marker `SMSG_GOSSIP_POI` left on the map, checked
-            // field by field against the server's own row (see `capture::ProbeGuardPoiPlugin`).
+            // `WOW_PROBE=guardpoi`: checks a guard's `SMSG_GOSSIP_POI` against the server row.
             if std::env::var("WOW_PROBE").as_deref() == Ok("guardpoi") {
                 app.add_plugins(crate::capture::ProbeGuardPoiPlugin);
             }
-            // The battleground-queue live probe: `WOW_PROBE_BGQUEUE=1` levels past the bracket
-            // floor, greets Stormwind's Warsong Gulch battlemaster on the real wire and queues
-            // through the guid his list carried — the fixture that makes "log in while queued"
-            // reproducible (decision 2232's unexercised shape; see `capture::ProbeBgQueuePlugin`).
+            // `WOW_PROBE_BGQUEUE=1`: queues at Stormwind's Warsong Gulch battlemaster.
             if std::env::var("WOW_PROBE_BGQUEUE").is_ok() {
                 app.add_plugins(crate::capture::ProbeBgQueuePlugin);
             }
-            // The inside-a-battleground live probe: `WOW_PROBE_BG=wsg|ab|av` walks the whole
-            // player road — level, greet, queue, take the port through the stock
-            // `AcceptBattlefieldPort` — and then censuses the battleground from inside. The
-            // interface arc (1963/1972/1974/1980) built everything up to the port button and
-            // nothing past it; this is the first instrument that looks (see `capture::ProbeBgPlugin`).
+            // `WOW_PROBE_BG=wsg|ab|av`: queues, ports by `AcceptBattlefieldPort`, takes a census.
             if std::env::var("WOW_PROBE_BG").is_ok() {
                 app.add_plugins(crate::capture::ProbeBgPlugin);
             }
-            // The mail-arc live probe: `WOW_PROBE_MAIL=1` GM-mails the probe's own character, opens the
-            // Goldshire mailbox on the real wire, and drives the inbox/take/send/delete surface through
-            // the live Lua VM — decisions 0544/0548's end-to-end instrument (see `capture::ProbeMailPlugin`).
+            // `WOW_PROBE_MAIL=1`: inbox, take, send and delete at the Goldshire mailbox.
             if std::env::var("WOW_PROBE_MAIL").is_ok() {
                 app.add_plugins(crate::capture::ProbeMailPlugin);
             }
-            // The auction-arc live probe: `WOW_PROBE_AUCTION=1` GM-hops to a Stormwind auctioneer,
-            // greets it on the wire and drives browse/throttle/sell/owner-list/cancel through the
-            // live Lua VM — decision 1511's end-to-end instrument (see `capture::ProbeAuctionPlugin`).
+            // `WOW_PROBE_AUCTION=1`: browse, sell, owner list and cancel at a Stormwind auctioneer.
             if std::env::var("WOW_PROBE_AUCTION").is_ok() {
                 app.add_plugins(crate::capture::ProbeAuctionPlugin);
             }
-            // The bank-arc live probe: `WOW_PROBE_BANK=1` GM-hops to a pure banker, drives the whole
-            // six-opcode bank wire (activate/deposit/withdraw/buy-slot/refusal) — decision 0604's
-            // end-to-end instrument (see `capture::ProbeBankPlugin`).
+            // `WOW_PROBE_BANK=1`: the six-opcode bank wire at a banker.
             if std::env::var("WOW_PROBE_BANK").is_ok() {
                 app.add_plugins(crate::capture::ProbeBankPlugin);
             }
-            // The innkeeper-bind live probe: `WOW_PROBE_BINDER=1` GM-hops to Innkeeper Keldamyr, asserts
-            // the bind row's icon reads "binder", selects it, and answers the server's confirm through the
-            // live VM's own `ConfirmBinder()` — decision 1331's end-to-end instrument, the evidence that
-            // closes B249 (see `capture::ProbeBinderPlugin`).
+            // `WOW_PROBE_BINDER=1`: binds at Innkeeper Keldamyr via `ConfirmBinder()`.
             if std::env::var("WOW_PROBE_BINDER").is_ok() {
                 app.add_plugins(crate::capture::ProbeBinderPlugin);
             }
-            // The NPC-service ladder live probe: `WOW_PROBE_SERVICE=1` walks four real NPCs, one per
-            // interesting `UNIT_NPC_FLAGS` shape, and reports the arm the shipped ladder takes and the
-            // window that actually opened — decision 1861's end-to-end instrument, and the standing
-            // answer to "does right-clicking a trainer open the trainer window or a gossip menu?"
-            // (see `capture::ProbeServicePlugin`).
+            // `WOW_PROBE_SERVICE=1`: per `UNIT_NPC_FLAGS` shape, the window an NPC's click opens.
             if std::env::var("WOW_PROBE_SERVICE").is_ok() {
                 app.add_plugins(crate::capture::ProbeServicePlugin);
             }
-            // The vendor-swap live probe: `WOW_PROBE_VENDOR_SWAP=1` stands between the Goldshire
-            // inn's two vendors, opens one over the other's window, and reads the `"npc"` token,
-            // the title and the round portrait at the `MERCHANT_SHOW` dispatch itself — decision
-            // 2022's instrument (see `capture::ProbeVendorSwapPlugin`).
+            // `WOW_PROBE_VENDOR_SWAP=1`: one Goldshire vendor opened over the other's window.
             if std::env::var("WOW_PROBE_VENDOR_SWAP").is_ok() {
                 app.add_plugins(crate::capture::ProbeVendorSwapPlugin);
             }
-            // The `<Model>` perspective-leg live probe: `WOW_PROBE_MODEL_CAMERA=1` builds a plain
-            // pane on a camera-bearing file and reads the renderer's own camera and root back to
-            // check the three cancellations against an orthographic control (decision 2027's
-            // instrument; see `capture::ProbeModelCameraPlugin`, whose module doc is the recipe).
+            // `WOW_PROBE_MODEL_CAMERA=1`: a `<Model>` pane's camera against an ortho control.
             if std::env::var("WOW_PROBE_MODEL_CAMERA").is_ok() {
                 app.add_plugins(crate::capture::ProbeModelCameraPlugin);
             }
-            // The GM trouble-ticket live probe: `WOW_PROBE_GMTICKET=1` drives the whole five-opcode
-            // ticket wire through the live VM's own bindings — queue status, clean slate, file, edit,
-            // abandon — and prints the row the server must have stored so the operator can check the
-            // map/position the client never reads back (decision 1673's end-to-end instrument; see
-            // `capture::ProbeGmTicketPlugin`).
+            // `WOW_PROBE_GMTICKET=1`: the five-opcode ticket wire through the live VM.
             if std::env::var("WOW_PROBE_GMTICKET").is_ok() {
                 app.add_plugins(crate::capture::ProbeGmTicketPlugin);
             }
-            // The guild-charter live probe: `WOW_PROBE_CHARTER=1` GM-hops to the Stormwind guild
-            // registrar, asserts the charter row's icon reads "petition", buys a charter through the
-            // registrar's own window, opens it with a real bag right-click and renames it — decision
-            // 1672's end-to-end instrument (see `capture::ProbeCharterPlugin`).
+            // `WOW_PROBE_CHARTER=1`: buys, opens and renames a charter at a guild registrar.
             if std::env::var("WOW_PROBE_CHARTER").is_ok() {
                 app.add_plugins(crate::capture::ProbeCharterPlugin);
             }
-            // The world-book live probe: `WOW_PROBE_BOOK=1` teleports to the Old Town plaque and
-            // measures what having the item-text reader open costs per frame, closed vs open —
-            // B240's instrument (see `capture::ProbeBookPlugin`).
+            // `WOW_PROBE_BOOK=1`: the item-text reader's per-frame cost at the Old Town plaque.
             if std::env::var("WOW_PROBE_BOOK").is_ok() {
                 app.add_plugins(crate::capture::ProbeBookPlugin);
             }
-            // The meeting-stone live probe: `WOW_PROBE_STONE=1` parks at a real stone, clicks it
-            // on the click's own route below and inside its level band, and reads the queue back
-            // out of the live VM — decision 2283's instrument, the end-to-end answer to "can a
-            // player get into the LFG queue" (see `capture::ProbeStonePlugin`).
+            // `WOW_PROBE_STONE=1`: clicks a meeting stone and reads the LFG queue back.
             if std::env::var("WOW_PROBE_STONE").is_ok() {
                 app.add_plugins(crate::capture::ProbeStonePlugin);
             }
-            // The chest live probe: `WOW_PROBE_CHEST=1` parks at a real chest spawn, opens it on the
-            // click's own route and reports the self unit's base anim id before/during/after — B84's
-            // instrument, the numeric answer to "does the player kneel at a chest" (decision 1471;
-            // see `capture::ProbeChestPlugin`).
+            // `WOW_PROBE_CHEST=1`: the self unit's base anim id around opening a chest.
             if std::env::var("WOW_PROBE_CHEST").is_ok() {
                 app.add_plugins(crate::capture::ProbeChestPlugin);
             }
-            // The GameObject-questgiver live probe: `WOW_PROBE_GOQUEST=1` parks at the Goldshire
-            // wanted poster and reports the dialog status the server answers for it, below and
-            // above the quest's own MinLevel — the numeric answer to "quest objects are never
-            // status-queried" (decision 1872; see `capture::ProbeGoQuestPlugin`).
+            // `WOW_PROBE_GOQUEST=1`: a quest poster's status below and above its MinLevel.
             if std::env::var("WOW_PROBE_GOQUEST").is_ok() {
                 app.add_plugins(crate::capture::ProbeGoQuestPlugin);
             }
-            // The openable-item live probe: `WOW_PROBE_CLAM=1` stocks a clam, right-clicks it
-            // through the live VM's own `UseContainerItem` and reports whether a loot window opens
-            // on the item's own guid — the numeric answer to the director's "clams don't open"
-            // (decision 1531; see `capture::ProbeClamPlugin`).
+            // `WOW_PROBE_CLAM=1`: whether using a clam opens loot on the item's own guid.
             if std::env::var("WOW_PROBE_CLAM").is_ok() {
                 app.add_plugins(crate::capture::ProbeClamPlugin);
             }
-            // The cast-cancel live probe: `WOW_PROBE=castcancel` hearths and presses W mid-cast — the
-            // local self-cancel's end-to-end timing instrument (see `capture::ProbeCastCancelPlugin`).
+            // `WOW_PROBE=castcancel`: hearths and presses W mid-cast, timing the local self-cancel.
             if std::env::var("WOW_PROBE").as_deref() == Ok("castcancel") {
                 app.add_plugins(crate::capture::ProbeCastCancelPlugin);
             }
-            // The char-create live probe: `WOW_PROBE_CHARCREATE="<name>[,race,class,gender,…]"` creates (and
-            // cleans up) a character at select to verify the char-create/delete wire (decision 0423 phase 1;
-            // see `capture::ProbeCharCreatePlugin`).
+            // `WOW_PROBE_CHARCREATE="<name>[,race,class,gender,…]"`: creates, then deletes it.
             if std::env::var("WOW_PROBE_CHARCREATE").is_ok() {
                 app.add_plugins(crate::capture::ProbeCharCreatePlugin);
             }
-            // The live FPS probe: `WOW_LIVE_FPS=<frames>` samples frame times on a NORMAL connected run
-            // and exits — the harness probe's numbers with the live world in (see `capture::LiveFpsPlugin`).
+            // `WOW_LIVE_FPS=<frames>`: samples frame times on a live run, then exits.
             if std::env::var("WOW_LIVE_FPS").is_ok() {
                 app.add_plugins(crate::capture::LiveFpsPlugin);
             }
-            // The scripted probe drivers that live beside `capture` rather than in `player/`
-            // (decision 1174) — the mouse-turn (`WOW_PROBE_LOOK`, decision 0621), the swim-pitch aim
-            // (`WOW_PROBE_PITCH`) and the camera park (`WOW_PROBE_CAM`, decision 0653). Added
-            // unconditionally because each plugin's own `from_env` is its gate, so the variable's name is
-            // spelled in exactly one place; all three order themselves before `player::PlayerControlSet`.
+            // `WOW_PROBE_LOOK`, `WOW_PROBE_PITCH`, `WOW_PROBE_CAM`: each gated by its own
+            // `from_env`, all ordered before `player::PlayerControlSet`.
             app.add_plugins(crate::capture::ProbeLookPlugin);
             app.add_plugins(crate::capture::ProbePitchPlugin);
             app.add_plugins(crate::capture::ProbeCamPlugin);
-            // (The FPS journal — `WOW_FPS_JOURNAL=<csv>`, or the `fpsJournal` CVar — is
-            // registered from `lib.rs` in every build since 2008: it is the one instrument a
-            // player runs for us.)
+            // The FPS journal (`WOW_FPS_JOURNAL`) is registered from `lib.rs` in every build.
         }
     }
 }
diff --git a/crates/benilla-app/src/doodad_events.rs b/crates/benilla-app/src/doodad_events.rs
index ed4cc502..c95b847a 100644
--- a/crates/benilla-app/src/doodad_events.rs
+++ b/crates/benilla-app/src/doodad_events.rs
@@ -1,70 +1,24 @@
-//! The **placed-doodad** animation-event scanner — the third and last producer feeding the
-//! [`AnimSoundEvent`] stream, beside the creature scanner ([`crate::creature_anim`]) and the
-//! GameObject one ([`crate::go_anim`]).
+//! The placed-doodad animation-event scanner, the third producer of [`AnimSoundEvent`] beside
+//! [`crate::creature_anim`] and [`crate::go_anim`]: a lamp's hum or a campfire's crackle is a
+//! `$DSL`/`$DSO`/`$SND` key on the doodad's own idle sequence.
 //!
-//! Bug B345 ("every world-placed M2 doodad is silent") was this hole: a lamp's hum, a campfire's
-//! crackle, a waterfall, a windmill and a gnome machine are all authored as `$DSL`/`$DSO`/`$SND`
-//! keys on the model's own idle sequence — and **nothing in benilla ever wrote a doodad's events
-//! into the stream**. The routing end ([`crate::sound::anim_events`]) has handled those tags since
-//! decision 0070 slice 3; it simply never received one from a doodad, because the only two
-//! scanners gate on `AnimDriver` (units) and `GoAnim` (server-sent GameObjects), neither of which a
-//! terrain-stream placement ever gets.
+//! The reference arms every placed doodad (`0x695100`) but scans an event track (`0x719370`) only
+//! from the per-frame M2 worklist `[CM2Scene+0x20]` (`0x7074b0`), refilled each frame through
+//! `0x710b90` by the terrain doodad drain (`0x683f80`) with what the scene-walk cull (`0x683700`)
+//! passed: frustum, horizon occlusion, and a distance fade above zero. A doodad outside that set
+//! fires nothing and holds none of the emitter pool's 32 entries; scanning every resident doodad
+//! would let far, inaudible ones take the pool's channels by claim order. A bind-posed model with
+//! a sound marker gets a clock-only host (`doodad_anim::spawn_anim_host`).
 //!
-//! **Why it is not enough to scan the hosts that already exist.** The corpus says 273 models author
-//! a doodad sound marker (`benilla-extract soundeventscan`); only 165 of them are the `FirstSeq`
-//! tier that carries an `AnimationPlayer`. The other 108 — including the reported lamp,
-//! `KalidarStreetLamp01.m2`, one looping 3.333 s Stand that keys no bone at all and carries exactly
-//! one `$DSL` → `NightElfStreetLampLoop` — are bind-posed, and decision 0130's content gate
-//! deliberately builds them no rig. That gate is right about pixels and was never a claim about the
-//! clock: the reference arms **every** placed doodad it creates and cycles it whenever the doodad is
-//! in the frame's animate set (`0x695100` — see the gate below). So
-//! `doodad_anim::spawn_anim_host` gives a sound-carrying model a clock-only host —
-//! the arm bookkeeping, no player — and this scanner reads that arm.
+//! A registration is released only by `$DSE`, a `$DSL` naming another id, or the doodad's
+//! teardown (`0x6951e0`, `0x6a0840`), so a campfire behind the camera keeps sounding.
 //!
-//! **The scan is gated on the frame's ANIMATE SET, and that gate is the whole mechanism** — not a
-//! budget, and not an optimisation (decision 2059). The reference's event scan `0x719370` is
-//! reached from exactly one place: `0x7074b0`'s walk of the per-frame M2 scene worklist
-//! `[CM2Scene+0x20]`, which is **emptied every frame** and refilled only by `0x710b90(model, 1)`
-//! from the terrain doodad drain `0x683f80` — and the drain walks only the bucket the scene-walk
-//! cull `0x683700` appended to, i.e. a doodad that passed frustum + horizon-occlusion **and** came
-//! out of the radius-tiered horizontal distance fade with `alpha > 0`. A doodad that fails any of
-//! those is not in the worklist, so its event track is never scanned, so **its `$DSL` never
-//! fires and it never takes one of the emitter pool's 32 entries**.
+//! The clock is [`DoodadAnimHost::arm_clock`]'s, which the gate's resume seeks the player to.
 //!
-//! Ungated, this scanner registered **every resident doodad in the streaming radius**, and with the
-//! pool's four channels arbitrated by claim order (`super::sound::emitter_pool`) that is not a
-//! harmless surplus — it is silence. Measured at the director's Stratholme pin
-//! (`.go xyz 3471.91 -3366.89 136.85 329`, 2026-09-07): all four channels held by
-//! `UndeadCampfireSmall` / `CauldronLoop` / `TorchLoop` / `SlimeWaterfall`, **every one of them
-//! past its own `DistanceCutoff` and therefore inaudible**, while the fifth entitled entry —
-//! `StratholmeFireSmokeEmberSLoop`, the burning-building layer the director reported missing, with
-//! 88 emitters right there — was withheld by the cap. `0 sounding`, on the same frame that reported
-//! `parked=1004`: a thousand hosts outside the animate set, each still holding its registration.
-//!
-//! **"A campfire behind you keeps crackling" is still true, and this gate does not break it** — but
-//! by the other mechanism. A registration is released by `$DSE`, by a `$DSL` naming a different id,
-//! or by the doodad's own teardown, and by nothing else (the handler `0x6951e0`, the teardown
-//! `0x6a0840`): turning away stops the *marker firing*, never the entry. The prose this module and
-//! [`DoodadAnimHost::arm_clock`] used to carry — "the reference gates the cycle on residency, not
-//! the draw" — read *linkage* as "loaded" when it means spliced into `[scene+0x20]`, which **is**
-//! the drawn/faded set: a doodad culled out of the drain stops advancing and resumes on re-link.
-//!
-//! The clock stays [`DoodadAnimHost::arm_clock`]'s shared one rather than the `AnimationPlayer`'s:
-//! while a host is in the animate set the two agree by construction (the gate's resume seeks the
-//! player to exactly this value), and the clock-only tier has no player to read at all.
-//!
-//! **Across a park the memory is DROPPED, not carried** — because the reference's scan window is
-//! one frame wide and it never replays. `0x719370` computes `prev = max(windowLo, now − dt)` and
-//! `cur = now` (`0x71950f`, for a looping sequence), **both off the absolute scene clock**, which
-//! `0x7074c2` advances every frame whether or not the model is linked; a write census over the
-//! whole function finds no persisted cursor. So the markers a culled doodad crossed are **lost**,
-//! and what actually fires on re-link is the completion watchdog re-arming at `startOffset = 0`
-//! (`0x6951b0`, as decision 2065 records). Keeping [`advance_track`]'s entry across the park
-//! would hand the resume frame a `prev` from seconds ago and fire the whole span at once —
-//! harmless for a `$DSL` (its re-reach only repositions) and a burst of one-shots for
-//! `$DSO`/`$SND`. Dropping it makes the resume an **arm frame**, which fires nothing, and the
-//! frame after opens the head window `[0, cur]` — the re-arm, in the shape this scanner already
-//! has.
+//! The scan window (`0x71950f`) is one frame wide off the absolute scene clock, which `0x7074c2`
+//! advances whether or not the model is linked, with no persisted cursor: markers crossed while
+//! culled are lost, and on re-link the watchdog re-arms at offset 0 (`0x6951b0`). So a parked
+//! host's track memory is dropped and its resume is an arm frame.
 
 use bevy::prelude::*;
 
@@ -74,8 +28,7 @@ use benilla_world::schedule::WorldStage;
 use crate::creature_anim::{advance_track, scan_events, AnimSoundEvent, TrackMemory};
 use benilla_assets::ModelAnimations;
 
-/// What the placed-doodad event scanner reads per host: its clock and the frame its fired keys
-/// resolve in ([`crate::creature_anim::EventFrame`]).
+/// Per host: its clock and the frame its fired keys resolve in.
 type ScannedDoodad = (
     Entity,
     &'static DoodadAnimHost,
@@ -84,13 +37,8 @@ type ScannedDoodad = (
     Option<&'static benilla_world::rig_anim::RigPose>,
 );
 
-/// Fire the event keyframes each placed doodad's armed clip crossed this frame.
-///
-/// The arming rules are the shared [`advance_track`]/[`scan_events`] ones the other two scanners
-/// use — an arm frame fires nothing, the frame after it opens the clip's `t = 0` head (which is
-/// where essentially every doodad sound key sits), and a loop wrap fires tail-then-head. A
-/// variation re-roll ([`benilla_world::doodad_anim`]'s self-sustaining re-arm) changes the node, so
-/// [`advance_track`] sees a fresh arm and never scans across the seam.
+/// Fires the event keys each placed doodad's armed clip crossed this frame. A variation re-roll
+/// changes the node, so [`advance_track`] sees a fresh arm and never scans across it.
 fn fire_doodad_anim_events(
     time: Res<Time>,
     hosts: Query<ScannedDoodad>,
@@ -100,31 +48,22 @@ fn fire_doodad_anim_events(
 ) {
     let now = time.elapsed_secs();
     for (entity, host, anims, world, pose) in &hosts {
-        // The worklist gate (module docs): a host outside this frame's animate set is not in
-        // `[CM2Scene+0x20]`, so the reference never scans its event track. `active` is benilla's
-        // one spelling of that membership — `gate_doodad_anim` writes it from the composed
-        // far-clip + distance-fade + portal verdict on the placement's submeshes, or, for a
-        // meshless (particles-only) model, from the same fade-sphere + frustum law its emitters
-        // gate on. It is a `PostUpdate` write and this reads it in `Update`, so the verdict is
-        // one frame old — the same accepted lag the interior and billboard laws carry, and
-        // nothing here can tell a 16 ms-late ambience from an on-time one.
+        // The worklist gate: `active` is `gate_doodad_anim`'s animate-set verdict, written in
+        // `PostUpdate`, so it is one frame old here.
         if !host.active {
-            // …and forget where its clip stood. See the module docs: the reference's window is one
-            // frame wide off a clock that never stops, so a resume must re-arm rather than replay
-            // everything the park skipped.
+            // A resume re-arms rather than replaying what the park skipped.
             last.remove(&entity);
             continue;
         }
         let Some((node, cur)) = host.arm_clock(now) else {
-            continue; // gseq-only host with no sound arm: nothing is armed, so nothing fires
+            continue; // a gseq-only host with no sound arm
         };
         let Some(clip) = anims.clips.iter().find(|c| c.node == node) else {
             continue;
         };
         if let Some(prev) = advance_track(&mut last, entity, node, cur) {
-            // The clock-only tier carries no rig at all, which is not a shortfall here: with no
-            // bone matrices the kernel's product is the placement alone, and the corpus says no
-            // `$DSL` record rides an animated bone. The lamp's hum lands on the lamp.
+            // A clock-only host has no rig, so keys resolve at the placement; no `$DSL` record
+            // rides an animated bone.
             let frame = crate::creature_anim::EventFrame {
                 world,
                 rig: pose.and_then(|p| Some((p, globals.get(p.joints_root).ok()?))),
@@ -132,12 +71,7 @@ fn fire_doodad_anim_events(
             scan_events(clip, entity, prev, cur, &frame, &mut out);
         }
     }
-    // Drop memory for hosts that no longer exist. The other two scanners leave their `Local` to
-    // grow — a unit or GameObject population churns with the session — but placements do not:
-    // crossing a continent streams tens of thousands of them in and out, and an unreaped entry per
-    // placement is an unbounded leak on the one lane where it actually bites. `Query::contains` is
-    // a lookup, so this is one pass over a map sized by the live sound-host count. It lives here
-    // rather than in its own system because a `Local` belongs to exactly one system.
+    // Reap despawned hosts: placements stream in and out by the tens of thousands.
     last.retain(|e, _| hosts.contains(*e));
 }
 
diff --git a/crates/benilla-app/src/fishing_line.rs b/crates/benilla-app/src/fishing_line.rs
index 984c0789..6dd127ce 100644
--- a/crates/benilla-app/src/fishing_line.rs
+++ b/crates/benilla-app/src/fishing_line.rs
@@ -1,27 +1,18 @@
-//! The engine-drawn **fishing line**: rod tip → bobber while a unit channels Fishing.
+//! The engine-drawn fishing line, rod tip to bobber, while a unit channels Fishing.
 //!
-//! The reference draws this as a per-UNIT effect, not a GO one — one line object per unit
-//! (`[unit+0xb4c]`, ctor `0x61f490`), created when the unit's `UNIT_FIELD_CHANNEL_OBJECT`
-//! resolves to a live **FISHINGNODE** GameObject, `UNIT_CHANNEL_SPELL` ≠ 0, and the mainhand is a
-//! fishing pole whose model is loaded; torn down when any of that ceases (the server clears the
-//! channel fields at finish/interrupt). **No local-player gate** — every visible fisher shows a
-//! line. Benilla draws it immediate-mode per frame from exactly those conditions, so the
-//! reference's create/watcher/teardown lifecycle falls out as the condition holding or not.
+//! The reference keeps one line per unit (`[unit+0xb4c]`, ctor `0x61f490`) while its
+//! `UNIT_FIELD_CHANNEL_OBJECT` is a live FISHINGNODE GameObject, `UNIT_CHANNEL_SPELL` is nonzero
+//! and the mainhand is a loaded fishing pole, for every visible fisher, not only the player. Here
+//! it is drawn each frame those conditions hold.
 //!
-//! The geometry (`0x61f780`): **65 vertices**, straight
-//! lerp near → far, then a fixed half-sine sag — `z −= 0.5 × sin(π·t)`, 0.5 world-units at the
-//! midpoint, not length- or physics-scaled. Near = the pole M2's `$CCH` event marker (the bobber
-//! authors one too and the reference NEVER reads it — its far end is the bobber's position with
-//! `z += scale × bboxHeight × 0.5`). One flat color for the whole strip = the pole's
-//! light-collector accumulated ambient, alpha opaque, GL_LIGHTING forced off, drawn as a plain
-//! line strip in scene state.
+//! The geometry (`0x61f780`): 65 vertices lerped near to far with a fixed sag of
+//! `0.5 * sin(pi * t)` world units, not scaled by length. Near is the pole's `$CCH` marker (the
+//! bobber's own `$CCH` is never read); far is the bobber's position plus half its scaled bbox
+//! height. One flat color, the pole's light-collector ambient, opaque and unlit.
 //!
-//! Named deviations (same class as the bowstring's, decision 1099): the anchor rides the static
-//! prop frame (the pole's bone 1 is not posed — item props rest at bind pose here); the color
-//! samples the scene ambient ([`benilla_world::lighting::WowLighting`]) rather than a per-model light
-//! collector; gizmo lines are unfogged. The reference's sheath side-trigger (`0x60d2f0` calls
-//! `SetSheatheState(1)` when the watcher finds the pole on the back) and the FishingCast→
-//! FishingLoop anim handoff (`0x5fc3f0` case 0x85) are the channel-anim family's, not drawn here.
+//! Here the anchor rides the unposed prop frame, the color is the scene ambient rather than the
+//! pole's light collector, and the line is unfogged. The sheathe trigger (`0x60d2f0`) and the
+//! FishingCast to FishingLoop handoff (`0x5fc3f0` case 0x85) belong to the channel animations.
 
 use bevy::prelude::*;
 
@@ -30,24 +21,22 @@ use benilla_protocol::EntityKind;
 use crate::entities::OverheadFallback;
 use crate::net::{GuidIndex, NetEntity, ObjectStore};
 
-/// Marks a spawned **mainhand prop** whose model authors the `$CCH` line anchor — the fishing
-/// pole (exactly one weapon model in the 5875 chain authors it: the `scan_events` sweep, so
-/// presence is the reference's `{class 2, subclass 20}` ItemCache check data-equivalently).
-/// Inserted by the held-item attach; despawned with the prop, which is the clear.
+/// Marks a mainhand prop whose model authors `$CCH`, which only the fishing pole does, standing
+/// in for the reference's `{class 2, subclass 20}` item check. Despawned with the prop.
 #[derive(Component)]
 pub(crate) struct FishingPoleTip {
-    /// The unit holding the pole — its channel fields decide whether a line draws.
+    /// The unit holding the pole, whose channel fields decide whether a line draws.
     pub(crate) owner: Entity,
     /// `$CCH` in the prop's mesh frame (Bevy space).
     pub(crate) tip: Vec3,
 }
 
-/// 64 segments / 65 vertices — the reference's `t = i/64` (const `0x80a92c` = 0.015625).
+/// 64 segments, 65 vertices: `t = i/64` (const `0x80a92c` = 0.015625).
 const SEGMENTS: usize = 64;
-/// The fixed half-sine sag amplitude (const `0x80c9a8` = −0.5, applied to `sin(π·t)`).
+/// The half-sine sag amplitude (const `0x80c9a8` = -0.5, applied to `sin(pi * t)`).
 const SAG: f32 = 0.5;
 
-/// Draw every visible fisher's line (per frame, post-propagation so the prop frame is current).
+/// Draws every visible fisher's line from this frame's prop frame.
 fn draw_fishing_lines(
     poles: Query<(&FishingPoleTip, &GlobalTransform, &InheritedVisibility)>,
     owners: Query<&ObjectStore>,
@@ -65,8 +54,7 @@ fn draw_fishing_lines(
         if !vis.get() {
             continue;
         }
-        // The reference's create conditions, checked live: a channel spell, aimed at a streamed
-        // FISHINGNODE. (`0x612650`; the GO-type read is the strategy's own `descr+0x3c`.)
+        // The create conditions (`0x612650`): a channel spell aimed at a streamed FISHINGNODE.
         let Ok(store) = owners.get(pole.owner) else {
             continue;
         };
@@ -89,11 +77,9 @@ fn draw_fishing_lines(
             continue;
         }
         let near = prop.transform_point(pole.tip);
-        // Far = bobber base + half its scaled bbox height (`0x5f9f50`: `z += scale × [go+0xbc] ×
-        // 0.5`) — the float's waterline center, whatever the model's pivot does.
+        // Bobber base plus half its scaled bbox height (`0x5f9f50`).
         let far = go_tf.translation() + Vec3::Y * (net.scale * height.map_or(0.0, |h| h.0) * 0.5);
-        // The flat strip color: accumulated ambient clamped [0,1], opaque (the scene-ambient
-        // stand-in for the pole's collector — module doc).
+        // The scene ambient clamped to [0, 1], opaque.
         let color = lighting.as_deref().map_or(Color::srgb(0.5, 0.5, 0.5), |l| {
             Color::srgb(
                 l.ambient[0].clamp(0.0, 1.0),
@@ -111,8 +97,7 @@ fn draw_fishing_lines(
     }
 }
 
-/// Registers the line drawer beside the bowstring's — after propagation, so both weapon-prop
-/// spans read this frame's frames.
+/// Registers the line drawer after transform propagation.
 pub(crate) struct FishingLinePlugin;
 
 impl Plugin for FishingLinePlugin {
@@ -128,9 +113,8 @@ impl Plugin for FishingLinePlugin {
 mod tests {
     use super::*;
 
-    /// The polyline the reference builds (`0x61f780`): 65 vertices, straight lerp, and the fixed
-    /// half-sine sag — zero at both ends, exactly −0.5 in world Z (Bevy Y) at the midpoint,
-    /// independent of the span's length.
+    /// The reference's polyline (`0x61f780`): zero sag at both ends, -0.5 in world Z (Bevy Y) at
+    /// the midpoint.
     #[test]
     fn the_sag_is_a_fixed_half_sine() {
         let near = Vec3::new(0.0, 5.0, 0.0);
@@ -146,7 +130,7 @@ mod tests {
         assert!((pts[64] - far).length() < 1e-5);
         let mid = near.lerp(far, 0.5);
         assert!((pts[32].y - (mid.y - SAG)).abs() < 1e-4);
-        // The sag never scales with length: a 200-yard span dips the same 0.5.
+        // A 200 yd span dips the same 0.5.
         let long = near.lerp(Vec3::new(200.0, 5.0, 0.0), 0.5);
         let dip = SAG * (std::f32::consts::PI * 0.5).sin();
         assert!((dip - SAG).abs() < 1e-6);
diff --git a/crates/benilla-app/src/footprints.rs b/crates/benilla-app/src/footprints.rs
index 92b3f120..71d7478d 100644
--- a/crates/benilla-app/src/footprints.rs
+++ b/crates/benilla-app/src/footprints.rs
@@ -1,49 +1,26 @@
-//! **Footprint decals** — the prints a walking unit leaves on snow and sand (B212, decisions
-//! 1006/1012): the fourth client of the shared surface-decal projector ([`benilla_world::decal`]), drawn
-//! on the shared effect stream like the blob shadow, but **spawn-once**: a print is projected the
-//! frame its foot plants and the cached triangles replay every frame until the fade retires it —
-//! exactly the reference's own shape (baked once at spawn over collector-gathered ground
-//! triangles; the per-frame draw `0x69a3e0` only re-copies with the current alpha).
+//! Footprint decals on snow and sand, through the shared decal projector
+//! ([`benilla_world::decal`]). A print is projected once when its foot plants and its triangles
+//! replay with the current alpha until it fades, as the reference's per-frame draw `0x69a3e0` does.
 //!
-//! **The mechanism** (decision 1012):
-//! - **Surface gate**: `TerrainType.Flags & 1` (`0x699eb6`) — set on exactly **Snow** and
-//!   **Sand** — on the surface [`benilla_world::surface`] resolves under the unit, the *same* value the
-//!   footstep sound uses. The reference resolves it once per unit into `CGUnit+0xc60` and the
-//!   decal, the spray and `$FSD` all read that one dword (`0x5fc06e`, `0x5fc20f`, `0x62341d`), so
-//!   indoors the gate reads the building's own floor: a tavern's floorboards take no prints while
-//!   the snow outside its door does (decision 1161).
-//! - **Trigger**: each per-foot animation event tag (`$xL*`/`$xR*`; the same [`AnimSoundEvent`]
-//!   stream the sounds read). **`$FSD` is sound-only** — a quadruped whose run authors only
-//!   `$FSD` leaves no prints, faithfully. Position = the event record's authored offset through
-//!   the live bone matrix ([`BoneAttach::markers`], `0x7196df`); yaw = the unit's facing.
-//! - **Ink + size**: `CreatureModelData.FootprintTextureID` → `FootprintTextures.dbc` →
-//!   `textures\Footsteps\*` (32×32 pure-black-RGB under soft alpha), sized Length/Width ×(1/36)
-//!   inches→yards (`0x5fc310`/`0x607a00`) × the unit's wire `OBJECT_FIELD_SCALE_X` **only**
-//!   (`0x469f10` — no display scale multiplies in). `0xFFFFFFFF` = printless (133 of 430
-//!   models). A mounted composite prints the MOUNT's ink/dims (the mount model's own event
-//!   stream) at the RIDER's scale. **The texture is authored as the LEFT foot** — right-foot
-//!   prints mirror (`0x5fc07f`, scale(−1,1,1) before the yaw).
-//! - **Fade**: lifetime **6000 ms**, `t = 1 − age/6000`, `alpha = min(127, ⌊255·t⌋)` — ≈3.0 s
-//!   hold at ~50 % opacity then a ≈3.0 s linear fade, no fade-in ([`fade`], `0x69a3e0`).
-//! - **Caps**: ring pools of **64 local-player + 512 everyone-else** slots, unconditional
-//!   rotation (ring-select = GUID == local player, `0xca05f0`).
-//! - **Suppressions**: hover (`MOVEFLAG 0x4000_0000`) · stealth (`BYTES_1` byte 3 bit 0x2 —
-//!   NOT death) · player ghost (`PLAYER_FLAGS & 0x10`) · farther than **50 yd** from the
-//!   **camera eye** ([`footfall_culls`] — the handler's own gate, shared with the footstep
-//!   camera shake, and applied to the local player's feet like anyone else's; decision 1856) ·
-//!   the terrain flag / printless id / no ground triangles. Water does NOT suppress
-//!   the decal (only the spray branch wades). The reference's `showfootprints` cvar (default on)
-//!   is the **decal's** toggle and only the decal's: `0x5fc023` skips the decal block alone, so
-//!   the footstep camera shake and the spray branch both still run with prints switched off. We
-//!   are always-on until a settings page wires the knob (the cvar-policy line, like the blob
-//!   shadow's `shadowLOD`).
+//! - Surface: `TerrainType.Flags & 1` (`0x699eb6`, Snow and Sand) on the unit's one resolved
+//!   surface (`CGUnit+0xc60`), which the decal, the spray and `$FSD` share (`0x5fc06e`,
+//!   `0x5fc20f`, `0x62341d`); indoors it is the building's floor.
+//! - Trigger: the per-foot tags `$xL*`/`$xR*` of [`AnimSoundEvent`], placed at the event's
+//!   authored offset through the live bone (`0x7196df`); `$FSD` is sound-only.
+//! - Ink and size: `CreatureModelData.FootprintTextureID` to `FootprintTextures.dbc`, Length and
+//!   Width in inches (1/36 yd, `0x5fc310`, `0x607a00`) times the wire `OBJECT_FIELD_SCALE_X` alone
+//!   (`0x469f10`); `0xFFFFFFFF` is printless. A mount prints its own ink at the rider's scale. The
+//!   texture is a left foot; right prints mirror (`0x5fc07f`).
+//! - Caps: ring pools of 64 for the local player and 512 for everyone else (`0xca05f0`).
+//! - Suppressed by hover, stealth (not death), a player ghost and more than 50 yd from the camera
+//!   eye ([`footfall_culls`], the local player's feet included); water does not suppress it.
+//! - The reference's `showfootprints` cvar (default on, `0x5fc023`) skips the decal block alone,
+//!   so the footstep shake and the spray still run; it is not wired here, so prints are always on.
 //!
-//! Draw state per the reference: src-alpha blend, depth-write off, unlit, white vertex RGB with the
-//! fade in vertex alpha — the ink darkness lives in the texture. Still open (none
-//! load-bearing): the forward-axis sign convention inside the shared UV basis, the
-//! uv1 64×8 edge-fade ramp's combine mode (not modeled here — prints are small; the blob
-//! shadow's vertical trapezoid is that ramp's other consumer), and the frame order vs the blob
-//! shadow (our rung 2048 under its 4096 is a deterministic stand-in).
+//! Draw state, as the reference's: src-alpha blend, no depth write, unlit, white vertex RGB with
+//! the fade in alpha; the ink's darkness is the texture's.
+//! Untraced: the forward-axis sign, the uv1 64x8 edge-fade ramp (not modelled) and the order
+//! against the blob shadow (our rung sits below it).
 
 use std::collections::VecDeque;
 
@@ -62,45 +39,37 @@ use benilla_world::particles::buffer::{begin_effect_frame, EffectVertex};
 use benilla_world::schedule::WorldStage;
 use benilla_world::view::WorldCamera;
 
-/// Print lifetime, spawn to gone — the reference's 6000 ms (`0x69a3e0`: `t = 1 − age/6000`, die
-/// at `t < 0`).
+/// 6000 ms (`0x69a3e0`).
 const LIFETIME: f32 = 6.0;
-/// The local player's own ring pool: 64 slots (the reserved head of the reference's 576-slot
-/// table @`0xca05f0`), unconditional rotation.
+/// The local player's ring: the head of the reference's 576-slot table at `0xca05f0`.
 const OWN_CAP: usize = 64;
-/// Everyone else shares 512 slots (the table's tail), same rotation.
+/// Everyone else's ring, the table's tail.
 const SHARED_CAP: usize = 512;
-/// Vertical reach of the projection slab about the planted foot: enough to catch the ground
-/// through a slightly-lifted foot bone and drape a step edge, small enough not to paint a
-/// terrace below (the blob shadow's slab is the model box; a print has no box to read).
+/// Half-height of the projection slab about the foot: reaches the ground under a lifted foot
+/// bone without painting a terrace below.
 const SLAB_HALF_HEIGHT: f32 = 1.0;
 
-/// One live print: the projected world-space triangles (vertex alpha 1.0 — the fade multiplies
-/// at push time), its spawn stamp, and its ink texture.
+/// One live print; `verts` carry alpha 1.0 and the fade multiplies in at push time.
 struct Print {
     verts: Vec<EffectVertex>,
     spawned: f32,
     texture: AssetId<Image>,
-    /// The draw's sort anchor (the planted-foot spot).
+    /// The draw's sort anchor.
     anchor: Vec3,
 }
 
-/// The live prints — the reference's two ring pools ([`OWN_CAP`] local player /
-/// [`SHARED_CAP`] everyone else), each spawn-ordered (front = oldest; spawn order is expiry
-/// order — one shared lifetime). Resources, not per-print entities: prints are inert after
-/// spawn — no identity, queries, or despawn wiring needed.
+/// The two ring pools, oldest first; with one lifetime, spawn order is expiry order.
 #[derive(Resource, Default)]
 struct Footprints {
     own: VecDeque<Print>,
     shared: VecDeque<Print>,
 }
 
-/// The lane's one identity entity — the phase probe's `main_entity` for every print draw (prints
-/// have no entity of their own; a probe line still needs a producer to name).
+/// The entity every print draw names as its owner, since prints have no entity.
 #[derive(Resource)]
 struct FootprintLane(Entity);
 
-/// `FootprintTextures.dbc` id → the loaded ink texture. Loaded once at startup (six rows).
+/// `FootprintTextures.dbc` id to its ink texture.
 #[derive(Resource, Default)]
 struct FootprintInk(HashMap<u32, Handle<Image>>);
 
@@ -110,14 +79,12 @@ impl Plugin for FootprintsPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<Footprints>()
             .add_systems(Startup, load_ink.after(AssetSet::Open))
-            // Present, like the footstep sounds: the same event stream, after the frame's
-            // animation drive + transforms have settled the foot bones.
+            // Present: after animation and transforms settle the foot bones.
             .add_systems(Update, spawn_footprints.in_set(WorldStage::Present))
             .add_systems(PostUpdate, push_footprints.after(begin_effect_frame));
     }
 }
 
-/// Read `FootprintTextures.dbc` and start the six ink textures loading.
 fn load_ink(
     mut commands: Commands,
     assets: Option<Res<WorldAssets>>,
@@ -135,8 +102,7 @@ fn load_ink(
             let ink = table
                 .into_iter()
                 .map(|(id, path)| {
-                    // DBC paths are extensionless (`textures\Footsteps\BaseFootprint`); the
-                    // `mpq://` source wants forward slashes + the `.blp`.
+                    // DBC paths are extensionless, with backslashes.
                     let url = format!("mpq://{}.blp", path.replace('\\', "/"));
                     (id, asset_server.load::<Image>(url))
                 })
@@ -147,7 +113,7 @@ fn load_ink(
     }
 }
 
-/// The spawner's ROOT-unit reads (see [`spawn_footprints`]'s `roots` param).
+/// The root unit's reads (the rider, for a mount).
 type RootState = (
     Has<Embodied>,
     Option<&'static NetEntity>,
@@ -155,17 +121,12 @@ type RootState = (
     Option<&'static MovementState>,
 );
 
-/// Spawn a print for each per-foot plant on a footprint surface: the state gates (hover /
-/// stealth / ghost / distance), the terrain-flags gate, the unit's ink + params, the event
-/// marker's live bone position, yaw to the facing, project once, cache the triangles.
+/// Spawns and caches a print for each gated per-foot plant.
 fn spawn_footprints(
     mut events: MessageReader<AnimSoundEvent>,
     time: Res<Time>,
-    // GlobalTransform for the same reason as the footstep sounds (0441): a mounted unit's steps
-    // are the MOUNT child's tags, whose local Transform is the seat-relative ~origin.
+    // Global: a mount's tags come from a child whose local Transform is seat-relative.
     units: Query<(&NetEntity, &GlobalTransform)>,
-    // The spawner's ROOT (the rider for a mount child): the pool select, the print scale (the
-    // rider's SCALE_X, `0x469f10`), and the state gates all read the root.
     parents: Query<&ChildOf>,
     roots: Query<RootState>,
     camera: Query<&GlobalTransform, With<WorldCamera>>,
@@ -182,25 +143,18 @@ fn spawn_footprints(
     let (Some(footsteps), Some(creatures), Some(ink)) = (footsteps, creatures, ink) else {
         return;
     };
-    // The distance gate's origin — the same read `camera_shake::fire_shakes` makes for the same
-    // gate. No world camera, no world to print into.
     let Ok(eye) = camera.single().map(|t| t.translation()) else {
         return;
     };
     let now = time.elapsed_secs();
     for ev in events.read() {
-        // The VISUAL footfall channel: the per-foot side tags only (`$FSD` is the sound handler's,
-        // decision 1080). **Right** prints get the mirrored texture — the shipped art is the left
-        // foot (the `0x5fc07f` `side==0` mirror, corrected from 1006's guess in 1012).
         let Some(side) = footfall_side(&ev.ident) else {
             continue;
         };
         let Ok((net, transform)) = units.get(ev.entity) else {
             continue;
         };
-        // The ink + dims come from the EVENT's model (the mount for a mounted composite); the
-        // scale and every state gate from the ROOT unit (the rider) — the reference's split
-        // (`0x607920`).
+        // Ink and size from the event's model, scale and gates from the root unit (`0x607920`).
         let Some(params) = net.display_id.and_then(|d| creatures.footprint(d)) else {
             continue;
         };
@@ -215,7 +169,6 @@ fn spawn_footprints(
             Ok(r) => r,
             Err(_) => continue,
         };
-        // The state gates (each byte-verified, module docs): hover · stealth · player ghost.
         if movement.is_some_and(|m| m.flags & move_flags::HOVER != 0) {
             continue;
         }
@@ -224,21 +177,13 @@ fn spawn_footprints(
                 continue;
             }
         }
-        // The planted foot: the FIRED key's own point, resolved once by the scanner as the kernel
-        // snapshots it (decision 1904). It used to be a by-4CC re-find of the marker table, which
-        // is the *launch-point* mechanism (`0x7130e0`, first match) and not this one — a model that
-        // authors a side tag twice would have printed both feet at the first record's bone.
+        // The fired key's own point, not a first-match marker lookup (`0x7130e0`), which a model
+        // authoring a side tag twice would resolve to the wrong foot.
         let foot = ev.pos.unwrap_or_else(|| transform.translation());
-        // The handler's own 50 yd radius about the CAMERA EYE — every unit's feet, the
-        // player's included ([`footfall_culls`]).
         if footfall_culls(eye, foot) {
             continue;
         }
-        // The surface gate, on the SAME terrain type the footstep sound used: the reference
-        // resolves it once per unit (`CGUnit+0xc60`) and the decal, the spray and `$FSD` all read
-        // that one dword (`0x5fc06e`, `0x5fc20f`, `0x62341d`). So this reads the UNIT's surface,
-        // not a per-foot sample of the ground — indoors that is the building's own floor, which is
-        // why a tavern's floorboards take no prints while the snow outside its door does.
+        // The unit's surface, not a per-foot sample (`CGUnit+0xc60`, module doc).
         let terrain = world.terrain_type(
             &footsteps.0,
             benilla_world::world_point::Subject::Unit(ev.entity),
@@ -247,17 +192,13 @@ fn spawn_footprints(
         if !terrain.is_some_and(|t| footsteps.0.terrain_leaves_footprints(t)) {
             continue;
         }
-        // Print frame: length along the unit's facing, width across, yawed to the facing.
-        // With `(sin, cos) = (sin θ, cos θ)` the facing maps to the frame's −z′ axis, so v = 0
-        // is the toe end (the absolute sign convention is still open — a backwards-pointing
-        // print flips one sign here).
+        // The facing maps to the frame's -z axis, so v = 0 is the toe; the reference's sign is
+        // untraced, and a backwards print flips one sign here.
         let yaw = transform
             .to_scale_rotation_translation()
             .1
             .to_euler(EulerRot::YXZ)
             .0;
-        // The rider's wire SCALE_X for a mounted composite, the unit's own otherwise (`0x469f10`:
-        // the print scale is SCALE_X alone — display scales never multiply in).
         let scale = root_net.unwrap_or(net).scale.max(0.0);
         let (half_len, half_wid) = (params.length * scale * 0.5, params.width * scale * 0.5);
         if half_len <= 0.0 || half_wid <= 0.0 {
@@ -286,7 +227,7 @@ fn spawn_footprints(
             },
         );
         if !projected {
-            continue; // no receiving surface under the foot (the projector's no-ground gate)
+            continue; // no ground under the foot
         }
         let n_verts = verts.len();
         let (pool, cap) = if is_self {
@@ -295,7 +236,7 @@ fn spawn_footprints(
             (&mut prints.shared, SHARED_CAP)
         };
         if pool.len() >= cap {
-            pool.pop_front(); // the reference's unconditional ring rotation
+            pool.pop_front(); // unconditional ring rotation
         }
         pool.push_back(Print {
             verts,
@@ -303,9 +244,6 @@ fn spawn_footprints(
             texture: texture.id(),
             anchor: foot,
         });
-        // The lane's census line (`RUST_LOG=benilla_app::footprints=debug`): every spawn names
-        // its tag, ink, spot and triangle count — the first question of any "no prints under X"
-        // report, answerable from a log (the blob shadow census pattern).
         debug!(
             "footprint: {} ink {} at ({:.2}, {:.2}, {:.2}), {} verts ({} own + {} shared live)",
             ev.ident.map(char::from).iter().collect::<String>(),
@@ -320,9 +258,8 @@ fn spawn_footprints(
     }
 }
 
-/// The reference's fade at age seconds (`0x69a3e0`):
-/// `t = 1 − age/6 s`, `alpha_byte = min(127, ⌊255·t⌋)` — ≈3.0 s hold at 127/255 (~50 %
-/// opacity), then linear to 0; no fade-in; dead past [`LIFETIME`].
+/// The reference's fade (`0x69a3e0`): `t = 1 - age/6 s`, alpha byte `min(127, floor(255 t))`,
+/// so a 3 s hold at half opacity, then linear to 0, with no fade-in.
 fn fade(age: f32) -> f32 {
     let t = 1.0 - age / LIFETIME;
     if t <= 0.0 {
@@ -331,9 +268,7 @@ fn fade(age: f32) -> f32 {
     (255.0 * t).floor().min(127.0) / 255.0
 }
 
-/// Retire expired prints, then replay every live print's cached triangles onto the effect
-/// stream — src-alpha blend of the black-RGB ink, the fade multiplied into the vertex alpha at
-/// push time (the cache stays untouched).
+/// Retires expired prints and replays the live ones with the fade in vertex alpha.
 fn push_footprints(
     time: Res<Time>,
     cam: Query<Entity, With<WorldCamera>>,
@@ -375,17 +310,14 @@ fn push_footprints(
 mod tests {
     use super::*;
 
-    /// The byte-verified ramp: no fade-in — 127/255 from age 0, held while `255·t ≥ 127`
-    /// (through age = 6·(1 − 127/255) ≈ 3.012 s), then the raw `⌊255·t⌋/255` line to zero at
-    /// 6 s, dead after.
     #[test]
     fn fade_matches_the_reference_ramp() {
         assert_eq!(fade(0.0), 127.0 / 255.0);
         assert_eq!(fade(1.0), 127.0 / 255.0);
         assert_eq!(fade(3.0), 127.0 / 255.0);
-        // Past the hold knee: the raw line. age 4.5 → t = 0.25 → ⌊63.75⌋ = 63.
+        // t = 0.25, floor(63.75) = 63.
         assert_eq!(fade(4.5), 63.0 / 255.0);
-        // age 5.988 → t = 0.002 → ⌊0.51⌋ = 0 — the line reaches the floor before death.
+        // t = 0.002 reaches 0 before death.
         assert_eq!(fade(5.988), 0.0);
         assert_eq!(fade(6.0), 0.0);
         assert_eq!(fade(7.0), 0.0);
diff --git a/crates/benilla-app/src/game_plugins.rs b/crates/benilla-app/src/game_plugins.rs
index d4faff83..770cf59a 100644
--- a/crates/benilla-app/src/game_plugins.rs
+++ b/crates/benilla-app/src/game_plugins.rs
@@ -1,26 +1,14 @@
-//! **[`GamePlugins`] — the game, as one name** (decision 2279, 2265 §C2).
+//! [`GamePlugins`]: the game as one plugin group, on top of the engine's
+//! `benilla_world::world_plugins::WorldPlugins`. `schedule_tests` builds it headless and checks
+//! the schedule for undeclared orders.
 //!
-//! `benilla_world::world_plugins::WorldPlugins` is the engine as one name (1164); this is the
-//! client on top of it: every plugin the game adds, in the order `run()` always added them.
-//! Until 2279 that chain lived inline in `run()` — 616 lines, the crate's only public function,
-//! ~150 `add_plugins` — so nothing could build the game's schedule except the binary, and no
-//! test could ask the one question Bevy can answer about a schedule: which conflicting pairs
-//! have no declared order (the instrument that would have caught 2220 and B354 at the line).
-//! `schedule_tests` below builds it headless and asks.
+//! The order is load-bearing. Some plugins read a resource an earlier one inserts at build time
+//! (`VideoPlugin` and `RealmlistPlugin` before `CvarPlugin`, `WorldBackdropPlugin` after
+//! `PlayerUiPlugin`, the `UiActionPlugin` family), and registration order is the executor's
+//! tie-break between systems with no declared order, so reordering members changes behaviour.
 //!
-//! **The order is load-bearing and is preserved from `run()` as-is.** Two kinds of edge live in
-//! it: documented dependencies (a plugin that reads a resource an earlier one inserts at build
-//! time — `VideoPlugin` and `RealmlistPlugin` before `CvarPlugin`, `WorldBackdropPlugin` after
-//! `PlayerUiPlugin`, the `UiActionPlugin` family), and registration order, which is the
-//! executor's tie-break between systems with no declared order. The second kind is exactly
-//! what the ambiguity count measures; until it is zero, reordering members is a behaviour
-//! change.
-//!
-//! **What is NOT here:** the engine (`WorldPlugins`), the three process plugins (`ThreadQos`,
-//! `BgWin`, `MacQuit`), the instruments that sit above the stack (`dev::DevToolsPlugin`,
-//! `perf::FpsJournalPlugin`, `dev::DevProbesPlugin`) — all still `run()`'s, in their places
-//! around this group. `pipe_warm` is inside, at its old position: a client instrument, but one
-//! that warms the *game's* pipeline set and has always been added among them.
+//! Not here, and added by `run()` around this group: the engine, the three process plugins
+//! (`ThreadQos`, `BgWin`, `MacQuit`) and the dev instruments above the stack.
 
 use bevy::app::PluginGroupBuilder;
 use bevy::prelude::*;
@@ -106,8 +94,8 @@ use crate::world_backdrop::WorldBackdropPlugin;
 
 /// The game, as one plugin group. The two fields are the two plugins `run()` parameterises.
 pub(crate) struct GamePlugins {
-    /// [`NetPlugin::connect`]: `false` in capture mode — the channel resources exist, no IO
-    /// thread runs, so captures are deterministic regardless of whether a server is up.
+    /// [`NetPlugin::connect`]: `false` in capture mode, where no IO thread runs, so captures are
+    /// deterministic whether or not a server is up.
     pub(crate) connect: bool,
     /// [`crate::char_select::CharSelectPlugin::start`]: the screen this session opens on.
     pub(crate) start: crate::char_select::ClientState,
@@ -116,340 +104,153 @@ pub(crate) struct GamePlugins {
 impl PluginGroup for GamePlugins {
     fn build(self) -> PluginGroupBuilder {
         PluginGroupBuilder::start::<Self>()
-            // The game's own WGSL, compiled into the binary (decision 1175) — before anything that could
-            // ask for one. The engine's seven register themselves inside `WorldPlugins`, which
-            // `run()` adds ahead of this group.
+            // The game's own WGSL, compiled in, before anything that could ask for one.
             .add(crate::shaders::plugin)
             .add(BowstringPlugin)
             .add(crate::weapon_trail::WeaponTrailPlugin)
             .add(FishingLinePlugin)
             .add(QuestMarkersPlugin)
-            // Pipeline-compile counters + the live-compile tripwire (decision 0837: macOS builds every
-            // pipeline synchronously on the render thread, so a live compile is a felt stall).
             .add(crate::pipe_warm::plugin)
-            // Streamed world entities: cube assets + display catalogs at startup, sync each frame.
             .add(EntitiesPlugin)
-            // Creature animation: pick Stand/Walk/Run from each creature's movement state each frame (Milestone C).
-            // The combat log — every combat packet's chat line and floating number, one handler each
-            // (decision 2323); ahead of the animation layer, whose two shared kinds run second.
+            // The combat log, ahead of the animation layer, whose two shared kinds run second.
             .add(crate::combat_log::CombatLogPlugin)
             .add(CreatureAnimPlugin)
-            // The unit blob shadow: the dark ground oval under every unit, sized from the playing
-            // animation's box (`0x6d7920`), on the same
-            // surface-decal projector as the selection ring.
+            // The blob shadow (`0x6d7920`), sized from the Stand box (`playableAnimationLookup[0]`,
+            // fixed per model), never the playing sequence.
             .add(BlobShadowPlugin)
-            // Footprint decals (B212, decision 1006): the prints a walking unit leaves on snow/sand,
-            // spawn-once projections on the same decal projector, fading off the effect stream.
             .add(CameraShakePlugin)
             .add(FootprintsPlugin)
-            // GameObject animation (decision 0242): net-streamed GObjects (doors/chests) play an M2 sequence
-            // on GAMEOBJECT_STATE change — the state-machine sibling of the doodad idle loop above.
             .add(crate::go_anim::plugin)
             .add(crate::doodad_events::plugin)
-            // Avatar + camera + input.
             .add(PlayerPlugin)
-            // Cinematic fly-bys (`SMSG_TRIGGER_CINEMATIC`): the race intro a first login plays, and the
-            // GameObject cameras. Takes the world camera for the duration — hence after PlayerPlugin,
-            // whose `control` it overrides within the same stage (decision 0196's deferred arc).
             .add(crate::screen_fade::ScreenFadePlugin)
+            // After PlayerPlugin, whose `control` it overrides in the same stage.
             .add(CinematicPlugin)
-            // The real client's hardware mouse cursor (native NSCursor on macOS).
             .add(CursorPlugin)
-            // Net↔ECS bridge: spawns the world thread, exposes the snapshot + writer resources. In capture
-            // mode the IO thread is skipped (`connect: false`) so the scene is deterministic.
             .add(NetPlugin {
                 connect: self.connect,
             })
-            // The death arc (decision 0308): the wire-fed death stores + the root/water-walk ack messages.
             .add(crate::death::DeathPlugin)
-            // The shared glue vocabulary both pre-world screens stand on (decision 0465): the ADD-mode UI
-            // material, the client-data art set, the GlueStrings table.
             .add(crate::glue::GluePlugin)
-            // The glue layer (decision 0193): the ClientState machine + the character-select screen
-            // that answers the parked IO thread's pick. A world capture boots straight InWorld (no net,
-            // no picker); a glue capture boots onto the screen it photographs.
             .add(crate::char_select::CharSelectPlugin { start: self.start })
-            // The login screen (decision 0539): the faithful AccountLogin glue + the credential policy
-            // that answers the IO thread's pre-logon park.
             .add(crate::login::LoginPlugin)
-            // The realm list: the faithful RealmList glue + the policy that answers the IO thread's
-            // realm park. The client used to take `realms.first()` and offer no way to say otherwise.
             .add(crate::realm_select::RealmSelectPlugin)
-            // The character-creation screen + its live preview booth (decision 0423).
             .add(crate::char_create::CharCreatePlugin)
-            // Audio: the delegated mixer + WoW's owned selection layer (decision 0070).
             .add(SoundPlugin)
-            // Targeting: left-click a unit to select it (→ CMSG_SET_SELECTION) + draw its ground ring.
             .add(TargetPlugin)
             .add(TransportPlugin)
-            // Faithful world-load splash + progress bar on startup + cross-map teleport (the load latency
-            // streaming can't hide); per-map art via the Map.dbc→LoadingScreens.dbc→BLP chain.
             .add(LoadingScreenPlugin)
-            // The player-UI quad pass (decision 0068 §2): its own composited-above-the-world,
-            // below-the-egui-dev-overlays camera + sorted-quad renderer. `$WOW_UI_DEMO=1` seeds a proof scene.
+            // The player-UI quad pass; `$WOW_UI_DEMO=1` seeds a proof scene.
             .add(PlayerUiPlugin)
-            // The world's frame, rendered off-screen and drawn first in the UI camera's main pass —
-            // the seam that puts the UI-over-world blend back into gamma bytes (0161/0254's last piece,
-            // a pass rather than a quad since 2234). Registered AFTER the UI pass: it points that
-            // plugin's camera at the world camera.
+            // After the UI pass: it points that plugin's camera at the world camera.
             .add(WorldBackdropPlugin)
-            // The HUD minimap (decision 0203 phase 1): fills the `<Minimap>` widget's extracted hole with
-            // the streamed tile window + mask + player arrow, and feeds the zone text.
             .add(crate::minimap::MinimapPlugin)
-            // The pet-bar / spellbook autocast shine, drawn on the append lane from the conversion's
-            // parked sites — zero per-frame script-layout traffic (decision 1383, B282).
-            // The `<Model>` widgets' M2s, rendered as tiles of one atlas and composited at the
-            // callback rank (decision 2008).
             .add(crate::ui_models::UiModelsPlugin)
-            // The shared AreaTable catalog + the ZONE_CHANGED event family / zone-text host globals
-            // behind GetZoneText & co. (the zone-entry splash arc, decision 0287).
             .add(crate::area::AreaPlugin)
             .add(crate::area_poi::AreaPoiPlugin)
             .add(crate::world_state_ui::WorldStateUiPlugin)
-            // The `AreaTrigger.dbc` volumes + the per-frame containment check that reports walking into
-            // one (`CMSG_AREATRIGGER`) — the client's whole part in portals, instance entrances and
-            // explore objectives; the server owns what each trigger means.
             .add(crate::area_trigger::AreaTriggerPlugin)
             .add(crate::ui_world_map::WorldMapUiPlugin)
-            // The guard's directions marker (`SMSG_GOSSIP_POI`) — one landmark record, drawn by the
-            // minimap's landmark pass and the world map's POI child, cleared by arriving at it.
             .add(crate::poi_marker::PoiMarkerPlugin)
-            // The glyph atlas (client TTFs -> baked bitmap) `ui_script`'s extraction draws `FontString`
-            // regions through. Loads at Startup, after the asset chain opens (decision 0068 §2).
             .add(UiTextPlugin)
-            // The one "which NPC am I interacting with" answer, shared by the portrait booth's `"npc"`
-            // token and the interaction face-me (decision 1467) — hence its own plugin, ahead of both.
+            // Ahead of the portrait booth and the interaction face-me, which both read it.
             .add(crate::ui_session::UiSessionPlugin)
-            // Unit-frame portraits: the token -> off-screen-baked-face bridge the UI extract samples for a
-            // `SetPortraitTexture`-bound region (the modern high-res 2D model bake).
             .add(PortraitPlugin)
             .add(TextInputPlugin)
             .add(UiScriptPlugin)
-            // The video knobs the CVar host writes into (today: `gxVSync`). Before CvarPlugin so the
-            // resource exists when `load_config` applies the saved value at Startup.
+            // Before CvarPlugin, so the resource exists when `load_config` applies the saved value.
             .add(crate::video::VideoPlugin)
-            // The realmlist (decision 1667) — the logon address the login screen edits. Same reason as
-            // VideoPlugin above: it is a CVar knob, so its resource has to exist before `load_config`.
+            // A CVar knob too, so before CvarPlugin for the same reason.
             .add(crate::realmlist::RealmlistPlugin)
-            // The CVar host (decision 0954): registration, knob sync, config.toml persistence. After
-            // UiScriptPlugin only for reading order — its systems gate on the VM existing anyway.
             .add(crate::cvars::CvarPlugin)
-            // The console command registry (decision 2303): the reference's `ConsoleCommand` table,
-            // its four CVar commands and `help`; subsystems register their own from their plugins.
             .add(crate::console::ConsolePlugin)
-            // The key-binding engine (decision 0997): the chord→command dispatch every rebindable input
-            // runs through, its persistence, and the Key Bindings window's capture seam.
             .add(crate::bindings::BindingsPlugin)
-            // The unit snapshot + event feed (decision 0068 §3): pushes ECS game state into the VM as the
-            // plain data the `Unit*` bindings read, and fires the matching WoW events.
             .add(UiUnitPlugin)
             .add(UiPartyPlugin)
-            // Duels (decision 0633): the wire session, the client-side countdown tick, the four Era
-            // events, and the accept/cancel/challenge intents.
             .add(UiDuelPlugin)
-            // Setting your hearthstone (decision 1331): the innkeeper's SMSG_BINDER_CONFIRM question, the
-            // CONFIRM_BINDER dialog it raises, and the CMSG_BINDER_ACTIVATE its Accept sends — the only
-            // packet in the flow that actually binds anything.
             .add(UiBinderPlugin)
-            // The dialog engine's own verbs (decision 1963): the pet trainer's question, the instance
-            // boot clock, the area spirit healer, the battleground queue, the meeting stone.
             .add(UiDialogVerbsPlugin)
             .add(BattlefieldScorePlugin)
             .add(BattlefieldPlugin)
             .add(BattlefieldPositionsPlugin)
             .add(crate::game_tip::GameTipPlugin)
             .add(crate::text_filter::TextFilterPlugin)
-            // The re-shape a `bevy_ui` text root loses when its last span is despawned
-            // (decision 2212, B383): an upstream change-detection hole whose only symptom is a
-            // panic inside `bevy_text` on the next window resize.
+            // Re-shapes a `bevy_ui` text root whose last span was despawned, an upstream hole
+            // that otherwise panics in `bevy_text` on the next resize.
             .add(crate::text_reshape::TextReshapePlugin)
             .add(TutorialPlugin)
-            // The melee swing refusals (`SMSG_ATTACKSWING_NOTINRANGE`/`_BADFACING`/`_DEADTARGET`/
-            // `_CANT_ATTACK`): the latch the packets set, and the 4 s repeat that shows it while an
-            // attack target stands and no swing lands.
             .add(crate::swing_refusal::SwingRefusalPlugin)
-            // Being summoned (decision 1747): SMSG_SUMMON_REQUEST's latch, the CONFIRM_SUMMON dialog it
-            // raises, and the CMSG_SUMMON_RESPONSE its Accept sends. The binder's twin one line up — a
-            // server-asked question whose only wire answer is yes — and here for that reason.
             .add(UiSummonPlugin)
-            // The GM trouble-ticket flow (decision 1673): the Help window's five sends, the UPDATE_TICKET
-            // answer ticket behind its 10-minute poll, and the GMTicketCategory.dbc list its "page a GM"
-            // rows are built from. Beside the binder because it is the same feed/drain shape, and after it
-            // because both want UiInput ordering and this reads better grouped.
             .add(UiGmTicketPlugin)
-            // Auto-follow's UI seam: the popup's Follow row + `FollowUnit`/`FollowByName` inbound, and
-            // the AUTOFOLLOW_BEGIN/END pair that drives the centre-screen status line outbound.
             .add(UiFollowPlugin)
-            // Instance/raid lockouts (decision 1748): the four CHAT_MSG_SYSTEM lines the client composes
-            // itself out of GlobalStrings, the last-dungeon/ownership bookkeeping behind
-            // `CanShowResetInstances()`, and the SELF menu's one send. Beside the binder family for the
-            // same feed/drain shape; it needs the map catalog, which is up long before Update runs.
             .add(UiInstancePlugin)
-            // Leaving (decision 0674): the game menu's Logout/Exit Game — the request, the server's
-            // 20-second answer narrated as the CAMP/QUIT countdown, and the process exit.
             .add(UiLogoutPlugin)
             .add(UiSocialPlugin)
-            // Guilds (decision 1257): the identity/roster mirror behind the four guild windows, the
-            // membership verbs, and the `ERR_GUILD_*` lines. Right after the social session, whose
-            // FriendsFrame it shares a window with and whose ignore list its sign-on lines consult.
+            // After the social session, whose FriendsFrame and ignore list it uses.
             .add(UiGuildPlugin)
-            // Founding a guild (decision 1672): the guild registrar and the charter window — the slice
-            // 1257 §2 left out. Right after the guild session, whose error channel its refusals ride and
-            // whose roster its success produces.
+            // After the guild session, whose error channel its refusals ride.
             .add(UiPetitionPlugin)
             .add(UiTooltipPlugin)
-            // The character-window feed (decision 0208): the combat-stats/inventory snapshots + events
-            // the paper doll reads, and the paper-doll booth's yaw mirror.
             .add(UiCharPlugin)
-            // The reputation-pane feed: the player's wire faction slots resolved against Faction.dbc into
-            // the pane's snapshot, plus the pane's three outbound verbs. Beside the character feed because
-            // it is the same window's other tab.
             .add(crate::ui_reputation::UiReputationPlugin)
-            // The inspect feed (decision 0631): another player's equipment off their PUBLIC visible-item
-            // entries, plus the "inspect" booth's unit + yaw. Right after the character feed it mirrors.
             .add(crate::ui_inspect::InspectUiPlugin)
-            // The honor feed (decision 1512): the PRIVATE honor descriptor block as the snapshot both
-            // Honor tabs read, plus the inspect-honor round trip. After the inspect feed because it
-            // resolves that feed's target to address its request at.
+            // After the inspect feed, whose target it asks about.
             .add(crate::ui_honor::UiHonorPlugin)
-            // The dressing-room feed (decision 1060): the window's try-on intents → the player's own look
-            // with the tried-on items substituted in, plus the "dressup" booth's yaw. Beside the inspect
-            // feed, whose shape it shares (intents in, a booth look out).
             .add(crate::ui_dressup::DressUpUiPlugin)
             .add(UiActionPlugin)
-            // The spell (2265 §A7's owner): the cast lifecycle's state — the pending cast, the queued
-            // strike, the running channel, the auto-repeat key, the chain outbox — its local cancel,
-            // the cooldown store, the talent modifier tables and the packet handlers (decisions 2324,
-            // 2328). After UiActionPlugin, whose feeds and cast ladder read the state through it.
+            // The cast lifecycle; after UiActionPlugin, whose feeds and cast ladder read it.
             .add(crate::spell::SpellPlugin)
-            // The aura feed (decisions 0255/0257): the player's insertion-ordered buff/debuff cache + the
-            // self-only durations, pushed as the data the `UnitAura` bindings read; fires UNIT_AURA and
-            // drains the right-click cancels. After UiActionPlugin (shares its `Spells` catalog).
+            // After UiActionPlugin, whose `Spells` catalog it shares.
             .add(UiAuraPlugin)
-            // The spellbook window feed (decision 0216 §8, slice 5): builds the book from
-            // PlayerActions.spells through the Spell.dbc/SkillLine.dbc join and drives
-            // SpellBookFrame.xml's snapshot + cast-drain seam — the spell SOURCE for the cursor payload
-            // arc (bags/doll/bars/book). After UiActionPlugin (shares its `Spells` resource + the cast
-            // tail `send_spell_cast`).
+            // After UiActionPlugin, whose `Spells` and `send_spell_cast` it shares.
             .add(UiSpellbookPlugin)
-            // The macro system (decision 0983): the icon chooser's catalog, the `benilla-config/macros/`
-            // files, `UPDATE_MACROS`, and the macro→bound-spell table the action bar's MACRO slots
-            // resolve their cooldown/usability through. After UiSpellbookPlugin — the bound spell is
-            // resolved against the book that feed pushes, by the same law `CastSpellByName` uses.
+            // After UiSpellbookPlugin: a macro's spell resolves against the book it pushes.
             .add(crate::ui_macro::UiMacroPlugin)
-            // The talent window feed (decision 0304): builds the class pages from Talent.dbc × the
-            // known-spell set + PLAYER_CHARACTER_POINTS, drives TalentFrame.xml through the engine's
-            // talent seam, and drains learn clicks into CMSG_LEARN_TALENT. After UiActionPlugin
-            // (shares its `Spells` catalog), beside the spellbook it mirrors.
+            // After UiActionPlugin, whose `Spells` catalog it shares.
             .add(UiTalentPlugin)
-            // Unlearning them again (decision 1580): the class trainer's respec question, its
-            // CONFIRM_TALENT_WIPE dialog, and the answer that is the only packet in the flow which
-            // unlearns anything. Beside UiTalentPlugin for the subject, but it is UiBinderPlugin's twin
-            // in shape — a guid-carrying question over an already-closed gossip menu.
             .add(UiTalentWipePlugin)
-            // The stance/shapeshift bar feed: builds the form list from PlayerActions.spells per
-            // the reference's admission and order (`0x4b25b0`, `0x4b2bb0`), drives the stock
-            // shapeshift bar through the engine's shapeshift seam, and drains its clicks
-            // (cancel-if-active else cast). After UiActionPlugin (shares `Spells`) and SpellPlugin
-            // (the `usable` walk, the cast tail).
+            // The form list by the reference's admission and order (`0x4b25b0`, `0x4b2bb0`); after
+            // UiActionPlugin (`Spells`) and SpellPlugin (the cast tail).
             .add(UiShapeshiftPlugin)
-            // The pet action bar (decision 0982) — the stance bar's mirror image: server-authoritative,
-            // so this renders the ten packed words the last `SMSG_PET_SPELLS` delivered and sends
-            // intents back. After UiActionPlugin (shares `Spells` and the cooldown triple's clock).
+            // After UiActionPlugin, whose `Spells` and cooldown clock it shares.
             .add(UiPetPlugin)
             .add(ChrClassesPlugin)
             .add(UiPetBookPlugin)
-            // The pet's paper-doll stat block (happiness/loyalty/XP/training points). Its own plugin
-            // because it runs off descriptor fields and two DBC tables rather than off `SMSG_PET_SPELLS`.
             .add(UiPetStatsPlugin)
-            // The pet paper doll's SHARED surface (decision 1057) — the combat-stats snapshot under the
-            // `"pet"` token and the page's model booth. Apart from the block above because these values
-            // pass through the character sheet's own bindings and events, with no hunter gate.
             .add(UiPetDollPlugin)
-            // The connection-telemetry feed: the averaged ping RTT behind `GetNetStats()`, which the main
-            // bar's performance meter polls (decision 0658).
             .add(UiNetPlugin)
             .add(UiCastPlugin)
-            // The breath / fatigue bars (decision 0874): server-authoritative mirror timers off the
-            // wire into the transcribed MirrorTimer1/2/3 frames. Beside the cast bar it shares its
-            // feed→drain shape (and its art: the same UI-CastingBar-Border chrome).
             .add(UiMirrorPlugin)
-            // Floating combat text (decision 0137 phase 2): the WORLDTEXTSTRING law — world-anchored
-            // damage numbers/outcome words projected into the UI quad pass each frame.
             .add(crate::combat_text::CombatTextPlugin)
-            // Overhead unit names (nameplates): world-billboard name text over players + NPCs.
             .add(crate::nameplates::NameplatesPlugin)
-            // Raid-target marker billboards (0434 §6): the mark icon over marked units, one line-pitch
-            // above the overhead name; plated units show the plate's raid child instead.
             .add(crate::raid_marks::RaidMarksPlugin)
-            // V-key nameplates (0167): the toggled health-bar plates, a 2-D overlay replacing the
-            // overhead name on plated units.
             .add(crate::vplates::VPlatesPlugin)
-            // Chat speech bubbles (0598): the over-the-head bubble a say/yell/party line spawns, the
-            // plates' 2-D overlay sibling — mutually exclusive with both the plate and the name.
             .add(crate::chat_bubble::ChatBubblePlugin)
-            // TOGGLEUI (`CTRL-Z`/`Cmd-Z`): the whole quad layer goes dark — frames, minimap, plates,
-            // bubbles, combat text — leaving the world and the cursor.
+            // TOGGLEUI (`ALT-Z`): the whole quad layer goes dark, leaving the world and the cursor.
             .add(crate::ui_hide::UiHidePlugin)
             .add(UiItemsPlugin)
-            // The gossip window (decision 0081): fills from the net drain's GossipState and drives
-            // GossipFrame.xml over the Era gossip API.
             .add(UiGossipPlugin)
-            // The merchant window (decision 0081 phase 4): fills from the net drain's MerchantOpen and
-            // drives MerchantFrame.xml over the Era vendor API + the money display.
             .add(UiMerchantPlugin)
-            // The bank window (decision 0604): the SHOW_BANK session (BankOpen) + the purchase row;
-            // the vault's slots ride the container feed as bags −1/5..=10.
-            // The auction house (decision 1511) — an NPC-session window like the bank beside it, but the
-            // only `doublewide` panel in the UI, so it displaces both the left and center seats.
             .add(UiAuctionPlugin)
             .add(UiBankPlugin)
-            // The mail window (decision 0544 P1/P2): the client-side mailbox session (MailOpen), the
-            // NPC-session range guard, and MailFrame.xml over the Era mail API (inbox, open-letter,
-            // send tab).
             .add(UiMailPlugin)
-            // Player-to-player trade (TradeFrame.xml): the two-sided trade window, driven server-side over
-            // the P0 wire; the partner's portrait rides the shared "npc" booth (decision 0592 P1).
             .add(UiTradePlugin)
-            // The item-text reader (ItemTextFrame.xml): right-clicked bag letters (mail-made permanent
-            // copies) read in the reference reader window over the shared ask-once item-text cache.
             .add(UiItemTextPlugin)
             .add(UiSavedPlugin)
             .add(NamePersistPlugin)
             .add(UiStablePlugin)
             .add(TabardUiPlugin)
             .add(UiTrainerPlugin)
-            // The taxi map (decision 0484 phases 1-2): the SMSG_SHOWTAXINODES-fed TaxiState resource, the
-            // NPC-session range guard, and the TaxiFrame.xml window feed/drain (catalogs, node
-            // projection/route computation, the activate send, the UnitOnTaxi ride flag).
             .add(UiTaxiPlugin)
             .add(UiTradeSkillPlugin)
             .add(UiCraftPlugin)
-            // The loot window (decision 0084): fills from the net drain's LootState and drives
-            // LootFrame.xml over the Era loot API (coin + rows, paging).
             .add(UiLootPlugin)
             .add(UiLootRollPlugin)
-            // The questgiver window (decision 0088): fills from the net drain's QuestGiver and drives
-            // the stock questgiver window's four sub-panels over the Era quest API (1944).
             .add(UiQuestPlugin)
-            // The quest-log window (decision 0088's deferred second slice): fills from the self player's
-            // PLAYER_QUEST_LOG descriptor slots + the SMSG_QUEST_QUERY_RESPONSE template cache, and drives
-            // the stock quest log over the Era quest-log API (1944).
             .add(UiQuestLogPlugin)
-            // The party quest-share (decision 1733): the verdict lines on a quest we pushed, and the
-            // escort-quest confirm. Neither is bound to a window, so it is its own plugin rather than a
-            // lodger in either quest plugin above.
             .add(QuestSharePlugin)
             .add(UiChatPlugin)
-            // The layout cache: the geometry of every window the player has dragged or resized, restored
-            // at world entry and written back a quiet second after the last drag
-            // (`benilla-config/layout/<realm>-<character>.txt`). The consumer of the engine's userPlaced
-            // bit, which nothing read before it.
             .add(UiLayoutPlugin)
-            // Print screen (decision 1487): the SCREENSHOT binding's engine half — one PNG per
-            // `Screenshot()` call into `benilla-config/Screenshots/` (never the install — decision 1486),
-            // answered to the UI as SCREENSHOT_SUCCEEDED/FAILED so the status text can never be in the
-            // frame it announces.
             .add(crate::screenshot::ScreenshotPlugin)
     }
 }
@@ -464,12 +265,9 @@ pub(crate) mod schedule_tests {
     use bevy::ecs::schedule::graph::Direction;
     use bevy::ecs::schedule::{LogLevel, NodeId, ScheduleBuildSettings, ScheduleLabel, SystemKey};
 
-    /// **The whole client, built headless.** The tuned `DefaultPlugins` with no window, no
-    /// winit, no logger and no GPU (`backends: None` — bevy then creates no render app), then
-    /// the engine, then the game. Every plugin's `build` and `finish` runs; no schedule does.
-    /// What this yields is the schedule GRAPH — which is fixed once the plugins have built
-    /// (the census probe's own argument, `capture::probes::sched_census`) — so a question
-    /// about ordering can be asked here, in a test, instead of on a login.
+    /// The whole client, built headless: the tuned `DefaultPlugins` with no window, winit, logger
+    /// or GPU (`backends: None`, so no render app), then the engine, then the game. Every
+    /// plugin's `build` and `finish` runs and no schedule does, which fixes the schedule graph.
     pub(crate) fn headless_client() -> App {
         let mut app = App::new();
         app.add_plugins(
@@ -509,26 +307,24 @@ pub(crate) mod schedule_tests {
         pub conditions: Vec<String>,
     }
 
-    /// One schedule, read two ways: the graph before it builds (names, sets, conditions — all
-    /// of which move into the executable when it does), and the conflict list after (which
-    /// only exists once it has).
+    /// One schedule, read two ways: the graph before it builds (names, sets, conditions move
+    /// into the executable when it does), and the conflict list after.
     pub(crate) struct Census {
         pub systems: HashMap<SystemKey, SystemInfo>,
         /// Pairs of systems with conflicting access and no path between them, each with what
         /// they fight over.
         pub conflicts: Vec<(SystemKey, SystemKey, Vec<ComponentId>)>,
         /// Everything any pair fights over, by name (a placeholder in a build without type
-        /// names — [`type_names_available`]).
+        /// names, [`type_names_available`]).
         pub components: HashMap<ComponentId, String>,
-        /// The explained classes, resolved against this world (decision 2287).
+        /// The explained classes, resolved against this world.
         pub classes: Classes,
         /// Every declared `a` runs before `b`, at the system level.
         pub dependencies: Vec<(SystemKey, SystemKey)>,
         /// The systems that must run on the main thread (the VM's, the audio layer's).
         pub non_send: Vec<SystemKey>,
-        /// The systems whose declared access includes the Lua VM — read off each system's
-        /// own access set, not off the conflicts it happens to have (a holder whose every VM
-        /// pair is declared would not show there).
+        /// The systems whose declared access includes the Lua VM, read off each system's own
+        /// access set: a holder whose every VM pair is declared shows in no conflict.
         pub holds_vm: HashSet<SystemKey>,
     }
 
@@ -545,31 +341,21 @@ pub(crate) mod schedule_tests {
         }
     }
 
-    /// Which graph a census reads (decision 2337).
-    ///
-    /// Bevy's build inserts an `ApplyDeferred` barrier between a system with commands and its
-    /// dependents, and it **shares one barrier per "distance"** (the number of barriers between
-    /// a node and the schedule's start — `auto_insert_apply_deferred.rs`, `get_sync_point`).
-    /// Two systems that share a barrier are ordered *through* it, so a pair the graph never
-    /// declared reads as ordered — and one edge added anywhere upstream re-homes whole groups
-    /// onto a different barrier and moves pairs among systems the edit never touched (2333's
-    /// five-out-six-in). Measured on this tree the day it was named: 2,888 actionable pairs
-    /// with the barriers, 5,063 without — the barriers were hiding 43% of the undeclared
-    /// orders behind their accidental placement.
+    /// Which graph a census reads. Bevy's build shares one `ApplyDeferred` barrier per distance
+    /// from the schedule's start (`auto_insert_apply_deferred.rs`, `get_sync_point`), so two
+    /// systems sharing a barrier read as ordered through it, and one upstream edge can re-home
+    /// whole groups and move unrelated pairs.
     #[derive(Clone, Copy, PartialEq, Eq)]
     pub(crate) enum SyncPoints {
-        /// The schedule as it actually runs, barriers included — what an executor census
-        /// wants, since a barrier really is a wave boundary.
+        /// The schedule as it runs, barriers included: a barrier is a real wave boundary.
         Built,
-        /// The **declared** graph only: no auto-inserted barriers, so "no path between two
-        /// systems" means exactly "nobody declared an order", and the count is a function of
-        /// the edges alone. What a ratchet on undeclared orders must read.
+        /// The declared graph only, no barriers: "no path" means "nobody declared an order".
+        /// What a ratchet on undeclared orders must read.
         Declared,
     }
 
-    /// Take the census of one schedule. Initializing it runs every system's param setup, and
-    /// at least one of those inserts `Schedules` itself, so this goes through bevy's own
-    /// take-out-initialize-put-back rather than a `resource_scope` on that resource.
+    /// Take the census of one schedule. Initializing it can insert `Schedules` itself, so this
+    /// goes through bevy's `schedule_scope`, not a `resource_scope` on that resource.
     pub(crate) fn census(app: &mut App, label: impl ScheduleLabel, sync: SyncPoints) -> Census {
         let label = label.intern();
         app.world_mut().schedule_scope(label, |world, schedule| {
@@ -578,9 +364,8 @@ pub(crate) mod schedule_tests {
                 auto_insert_apply_deferred: sync == SyncPoints::Built,
                 ..default()
             });
-            // The systems' access is filled by `initialize`, which the build below would run
-            // anyway (bevy drains one list of uninitialized systems, once). Done first, so pass
-            // 1 can read it while the graph still holds the systems.
+            // `initialize` fills the systems' access (the build would run it anyway); done
+            // first so pass 1 can read it while the graph still holds the systems.
             schedule.graph_mut().systems.initialize(world);
             let vm = world
                 .components()
@@ -641,9 +426,8 @@ pub(crate) mod schedule_tests {
                     },
                 );
             }
-            // Every declared order, at the system level: a `.before`/`.after`/`chain` edge
-            // between sets is an edge between every member of one and every member of the
-            // other.
+            // Every declared order at the system level: an edge between sets is an edge between
+            // every member of one and every member of the other.
             let members = |node: NodeId| -> Vec<SystemKey> {
                 let mut out = Vec::new();
                 let mut stack = vec![node];
@@ -678,8 +462,8 @@ pub(crate) mod schedule_tests {
                 if !system.is_send() {
                     non_send.push(key);
                 }
-                // The build inserts what nobody added: the `ApplyDeferred` sync points between a
-                // system with commands and its dependents. Name them so a census can count them.
+                // The build inserts the `ApplyDeferred` sync points; name them so a census can
+                // count them.
                 systems.entry(key).or_insert_with(|| SystemInfo {
                     name: system.name().to_string(),
                     sets: Vec::new(),
@@ -718,64 +502,34 @@ pub(crate) mod schedule_tests {
         })
     }
 
-    /// **Does this build carry type names?** bevy only does under its `debug` feature, which
-    /// rides with ours (`benilla-world`'s `dev`, decision 1451); a player build names every
-    /// system and resource `<Enable the debug feature …>`. Probed off the census itself rather
-    /// than off a feature flag — a `cfg(feature = "dev")` outside `run_mode` is a seam leak (1179),
-    /// and what these tests need is the capability, not the plane. The name-dependent tests
-    /// announce the skip and return; the name-free ratchets run either way.
+    /// Does this build carry type names? Bevy has them only under its `debug` feature, which
+    /// rides with `benilla-world`'s `dev`. Probed off the census, not a `cfg`, which belongs in
+    /// `run_mode` alone; name-dependent tests skip without them.
     fn type_names_available(c: &Census) -> bool {
         c.systems.values().any(|s| s.name.contains("benilla_app::"))
     }
 
-    /// **The explained classes** (decision 2287) — what an undeclared order may be about
-    /// without anyone declaring it, argued once here instead of by every session that adds a
-    /// system. On 2287's eve three sessions raised the two constants this table replaced,
-    /// each with a paragraph, each through a rebase conflict on the same lines, none declaring
-    /// an order (2281, 2282, 2283) — because for most of what those counts held there was
-    /// nothing to declare:
-    ///
-    /// - **A non-`Send` owner** — the Lua VM, the audio layer's handles. Their systems run on
-    ///   the main thread one at a time under any executor, so no order among them is a race.
-    ///   *Which feed fires its Lua events first* is a real question, answered by the `UiFeed`
-    ///   phase (decision 2304): every push after the drain and before the tick, and among the
-    ///   pushes an order declared where it matters (the chat cascade, the cooldown events),
-    ///   registration order otherwise. Derived, not listed: every registration that is not
-    ///   `Send + Sync`.
-    /// - **A pure cache** — a read is a write because a miss records itself: the ask-once
-    ///   caches mark the key pending and send one query (`NameCache`, the GameObject
-    ///   templates, the page texts), the load-once caches build the entry (`WorldAssets`,
-    ///   `Creatures`' display models). Two misses for one key commute — one query, or one
-    ///   build, whichever runs first — and the answer lands in the net drain, in packet order,
-    ///   inside `WorldStage::Net`. *Pure* is the condition: a resource that is a cache **and**
-    ///   a window's state (`Items`, `MailOpen`, `GuildState`, `QuestLog`, `PetitionState`) is
-    ///   not here, because its other writers do not commute; 2265 §A4 is what lets those
-    ///   split (decision 2288).
-    /// - **An append-only sink** — `ChatLog`, `MessageSounds`, `UiErrorKeys`, `UiErrorTexts`:
-    ///   writers commute, and a drain's order against a writer is one frame of latency, never
-    ///   a loss. (2283's ten pairs were all this shape: a new verb drain against its siblings
-    ///   over the chat and error sinks.)
-    /// - **Not an exclusive edge.** A pair bevy reports with NO component list has an exclusive
-    ///   system on one side (`bevy_ecs` `node.rs:625`: it reports every unordered pair with an
-    ///   exclusive system and never reads its access). 2304 explained that class as the
-    ///   build's barriers; the ratchet reads the declared graph since 2337, which has none, so
-    ///   what it held was only the hand-written exclusive systems — the net drain, whose 143
-    ///   unordered partners read this frame's packets or the last frame's by coin, and
-    ///   `finish_colliders`. Those are undeclared orders like any other: actionable (2343).
-    /// - **A random stream** — `SoundKits`, which every sound system holds to play a kit: a
-    ///   decode cache, a per-kit last-variation memory and one xorshift stream. Any
-    ///   interleaving of draws is a valid draw, and that is the reference's own contract for
-    ///   its single stream, consumed in whatever order its callers happen to run.
-    ///
-    /// A pair is **explained** when everything it fights over is in one of the four, and
-    /// **actionable** otherwise; only the actionable count is ratcheted. Adding a type here is
-    /// the act raising the ceiling used to be — a claim, with its reason, made in review — and
-    /// it is a claim about *every* writer of that resource, which is why the pure caches are
-    /// pure. Resolved by `TypeId`, so the ratchet runs in the player build, which carries no
-    /// names (1451).
     /// One row of the class table: the type's name for the message, and its `TypeId`.
     type ClassRow = (&'static str, fn() -> TypeId);
 
+    /// The explained classes: what an undeclared order may be about with nothing to declare.
+    ///
+    /// - A non-`Send` owner (the Lua VM, the audio handles): its systems run on the main thread
+    ///   one at a time, so no order among them is a race; which feed fires first is the `UiFeed`
+    ///   phase's job. Derived: every registration that is not `Send + Sync`.
+    /// - A pure cache, where a miss records itself (`NameCache`, the GameObject templates, the
+    ///   page texts, `WorldAssets`, `Creatures`' display models): two misses for one key commute.
+    ///   A cache that is also a window's state is not pure, and not here.
+    /// - An append-only sink (`ChatLog`, `MessageSounds`, `UiErrorKeys`, `UiErrorTexts`):
+    ///   writers commute, and a drain's order against a writer is one frame of latency.
+    /// - A random stream (`SoundKits`, `AnimRng`): any interleaving of draws is a valid draw,
+    ///   the reference's contract for its single stream.
+    ///
+    /// Not a class: a pair bevy reports with no component list has an exclusive system on one
+    /// side (`bevy_ecs` `node.rs:625` never reads its access), and is actionable. A pair is
+    /// explained when everything it fights over is in a class; only actionable pairs are
+    /// ratcheted. A row is a claim about every writer of that type, made in review with its
+    /// reason. Resolved by `TypeId`, so it works in the player build, which carries no names.
     pub(crate) struct Classes {
         /// The VM's own id, for the executor census.
         pub vm: Option<ComponentId>,
@@ -804,25 +558,16 @@ pub(crate) mod schedule_tests {
         ];
         const STREAMS: &[ClassRow] = &[
             ("SoundKits", TypeId::of::<crate::sound::SoundKits>),
-            // The client's ONE `rand()` stream (decision 2301). Four lanes draw from it — the
-            // placed-doodad host, the creature driver, the GameObject arm and the portrait booth —
-            // and in the reference they draw from one TLS cell in whatever order the frame runs
-            // them. The interleaving IS the mechanism: a shared sequence is what de-syncs a stand
-            // of identical props, and no consumer can observe which draw it got, only that it got
-            // a fresh one. So an undeclared order here is not a missing `.after`; declaring one
-            // would be inventing a determinism the reference does not have.
-            //
-            // It reduces the count by **nothing** today, and that is not an oversight: the three
-            // Update-side lanes already conflict on `Query<&mut AnimationPlayer>`, which no class
-            // explains, so every pair this row would cover is counted for that instead. It is the
-            // standing claim about the resource — what keeps these pairs from surfacing the day
-            // that other conflict is declared — not a saving.
+            // The client's one `rand()` stream: the doodad host, the creature driver, the
+            // GameObject arm and the portrait booth draw from it in frame order, as the
+            // reference's lanes draw from one TLS cell; declaring an order would invent a
+            // determinism the reference lacks. It removes no pair today: those lanes already
+            // conflict on `Query<&mut AnimationPlayer>`.
             ("AnimRng", TypeId::of::<benilla_assets::AnimRng>),
         ];
 
-        /// Resolve the table against a world whose schedules have initialized (every param
-        /// has registered its resource by then). A row that resolves to nothing is a stale
-        /// row, and the test says which.
+        /// Resolve the table against a world whose schedules have initialized; a row that
+        /// resolves to nothing is stale, and the panic names it.
         fn read(world: &World) -> Self {
             let comps = world.components();
             let resolve = |rows: &[ClassRow]| -> HashSet<ComponentId> {
@@ -854,10 +599,9 @@ pub(crate) mod schedule_tests {
                 || self.streams.contains(&id)
         }
 
-        /// Which class explains this pair — `None` if it is actionable.
+        /// Which class explains this pair; `None` if it is actionable.
         pub fn class_of(&self, what: &[ComponentId]) -> Option<&'static str> {
-            // An exclusive system on one side: bevy cannot see its access, so nothing here can
-            // argue the pair away (see the doc above: not an exclusive edge).
+            // An exclusive system on one side: bevy cannot see its access, so no class applies.
             if what.is_empty() {
                 return None;
             }
@@ -894,134 +638,30 @@ pub(crate) mod schedule_tests {
         assert!(app.world().contains_resource::<Schedules>());
     }
 
-    /// `PostUpdate`, 181 systems: `GlobalTransform` and the particle `EffectQuads` are most of it.
-    /// **371 (decision 2337)** — the declared-graph count, re-measured beside `Update`'s when
-    /// the census stopped reading bevy's barriers as orders (see the ledger below).
+    /// `PostUpdate`'s undeclared-order pairs on the declared graph; `GlobalTransform` and the
+    /// particle `EffectQuads` are most of it.
     const POST_UPDATE_CEILING: usize = 371;
     const POST_UPDATE_SLACK: usize = 20;
-    /// The **actionable** pairs in `Update` — two systems with conflicting access and no
-    /// declared order, where [`Classes`] explains none of what they share, so the executor
-    /// runs them in whatever order the graph around them happens to produce (B354, 2220). Same
-    /// shape as `world_api_wall.rs`: the count may not rise past the ceiling, and the ceiling
-    /// follows the count down. `WOW_AMBIGUITY_DUMP=1` prints every actionable pair with what
-    /// it fights over.
+    /// The actionable pairs in `Update`: conflicting access, no declared order, and nothing
+    /// [`Classes`] explains, so the executor orders them however the graph falls. The count may
+    /// not rise past the ceiling, and the ceiling follows the count down; read on the declared
+    /// graph ([`SyncPoints::Declared`]). `WOW_AMBIGUITY_DUMP=1` prints every pair.
     ///
-    /// **Measured 2026-09-17 (decision 2287), 662 systems:** 16,548 pairs in all, 12,849 of
-    /// them explained — 10,703 on the VM alone, 431 on the other non-`Send` owners, 556 on
-    /// the pure caches, 87 on the sinks, 41 on the stream, 1,031 on a mix of those — and
-    /// 3,699 actionable. The largest part of those is `Transform` on disjoint lanes (716 pairs
-    /// alone): populations that never intersect, which the filter algebra cannot see. A lane
-    /// is not a class — the checker cannot tell a disjoint lane from two writers of the same
-    /// entity — so they stay here, and each new one is a claim made at the registration with
-    /// its reason:
+    /// The largest part is `Transform` on disjoint lanes, populations that never intersect,
+    /// which no class can express. Known pairs accepted with a reason:
+    /// - the ranged prop's two `AnimationPlayer` writers against the booth's and the quest
+    ///   markers';
+    /// - the fx attaches and `entities::update_display_models`/`attach_entity_visuals` against
+    ///   the mat-anim tick over `MatAnimTable`/`UvAnimMaterials`: attach writes the rows a tick
+    ///   would, off the same clock;
+    /// - the area-spirit-healer poll over `Transform` and `NetEntity`: it is level-triggered, so a
+    ///   unit seen a frame early or late is decided again next frame;
+    /// - `ui_models::forget_dead_vm_tiles` against `portrait::glue_booth::sync_glue_scene` over
+    ///   `MatAnimTable`, a slot allocator whose owners touch disjoint slots.
     ///
-    /// - **2281:** the ranged prop's two `AnimationPlayer` writers against the booth's and the
-    ///   quest markers' (four lanes; the held weapon, a booth model, a marker).
-    /// - **2282:** the three fx attaches against the mat-anim tick and its probe, over
-    ///   `MatAnimTable`/`UvAnimMaterials` — immaterial by construction, because attach writes
-    ///   the rows a tick would, off the same clock.
-    /// - **2295:** the same two readers against `entities::update_display_models` and
-    ///   `entities::attach::attach_entity_visuals`, over the same two resources, now that the
-    ///   entity lane registers its own texture transform. **+4**, measured pair by pair on the
-    ///   rebased tree rather than assumed additive — both writers already held
-    ///   `Assets<WowModelMaterial>`, so most of the systems they newly meet were already
-    ///   ambiguous against them for another reason, and `redress_player_looks` takes the
-    ///   identical three resources and adds no pair at all. Immaterial for 2282's reason plus
-    ///   one: a display is built ONCE, the frame its asset lands, and a row left unwritten for
-    ///   a frame reads as the material's own built seed — the batch's authored `t = 0`, not a
-    ///   wrong value — because the same call seeds `sun_scale.zw` at the loop's opening.
-    ///
-    /// **3,280 (decision 2288)** — the one query cache: a read that asks marks its miss through
-    /// `&self`, so a feed that only resolves a name or a template holds the owner shared, and
-    /// its pairs over `Items` (725 → 104, the largest non-class resource in the count) are gone;
-    /// the pairs over the pure caches moved into the VM-only class, where the same systems still
-    /// meet over the VM alone.
-    ///
-    /// **3,288 (decision 2291, corrected)** — the area-spirit-healer poll. Its **four** remaining
-    /// pairs, named one by one because the first version of this paragraph named the wrong ones:
-    /// `portrait::booth::face_booth_billboards`, `quest_markers::bake_seat_scale` and
-    /// `entities::live_display::tick_scale_ease` over `Transform`, and
-    /// `entities::live_display::refresh_live_display` over **`NetEntity`** — a row read, not a
-    /// `Transform` pair at all. All four are the poll seeing a unit one mover early or late, which
-    /// moves a 20 yd acquire decision by at most one frame of walking; the poll is
-    /// **level**-triggered, re-deriving the whole cache every frame, so a boundary case decided
-    /// early is decided again next frame. The target scanner carries the same class for the same
-    /// reason.
-    ///
-    /// **The correction is the part worth keeping.** This paragraph first claimed "+6, all
-    /// `&Transform`", and that the poll's "one write-write pair … is *declared*". Both were wrong,
-    /// and the second one hid a real defect. There were **two** undeclared write-write pairs, and
-    /// the system on the other side of both was `drain_latch_verbs` — the one that turns
-    /// `AcceptAreaSpiritHeal()` into `CMSG_AREA_SPIRIT_HEALER_QUEUE`. It met the poll *and*
-    /// `target::click::act_on_right_click` over `AreaSpiritHealer`, because `.after(UiInput)`
-    /// orders it against neither (`UiInput` precedes `WorldStage::Input`; `TargetUpdate` follows
-    /// it). The drain takes its presses unconditionally and only then reads the healer, so that
-    /// undeclared order decided whether a ghost's Accept became a packet or vanished with no
-    /// message. Declaring `drain_latch_verbs.before(TargetUpdate)` — the reference's own order, the
-    /// dialog's Lua handler running in the UI dispatch ahead of `CGWorldFrame`'s poll and pick —
-    /// removed exactly those two.
-    ///
-    /// **Re-measured at 3,289 on the rebased tree**, not carried across as arithmetic. This branch
-    /// measured 3,290 → 3,288 on its own base; a neighbour landed 3,291 first, and the resolution
-    /// is the number the dump prints on the merged tree — which happens to agree with 3,291 − 2
-    /// this time, and is right for the reason that it was read rather than that it adds up.
-    ///
-    /// A ceiling raised with the wrong reason is a ratchet that has stopped meaning anything. The
-    /// lesson this one cost: **read the dump, do not reason about what the new pairs must be.**
-    ///
-    /// **3,291 (decision 2300)** — the glue create/main-menu scene's material lane: exactly **one**
-    /// new pair, `ui_models::forget_dead_vm_tiles` against `portrait::glue_booth::sync_glue_scene`
-    /// over `MatAnimTable`, measured pair by pair on the tree that lands rather than assumed
-    /// additive (the scene builder's other three new resources add none — it already held
-    /// `RigPalettes` and `Assets<WowModelMaterial>`, so the systems they newly meet were already
-    /// ambiguous against it). Immaterial by construction, and narrowly: `MatAnimTable` is a slot
-    /// **allocator**, one owner per slot. A tile reaping its dead rows and the scene claiming
-    /// fresh ones touch disjoint slots and neither reads the other's; the only thing the order
-    /// decides is *which* free slot the scene is handed, and a slot number is not observable —
-    /// the row behind it is, and it is written by whoever owns it. A scene is also built **once**,
-    /// the frame its model asset lands, against a reaper that fires only when a tile dies.
-    ///
-    /// **2,886 (decision 2330)** — read off the dump on the tree that lands, after the
-    /// `modalNextSpell` outbox's drain retired: `drain_chain_casts` held the whole cast ladder
-    /// (`CastLadder`'s fourteen parameters and `CastTargeting`'s ten) with no declared order
-    /// against anything but `UiInput`, and the cast reply's handler now casts the chain itself,
-    /// as a one-shot outside the schedule. The three targeting systems the same record moved
-    /// from `UiActionPlugin` to `SpellPlugin` kept their orders and their sets.
-    ///
-    /// **2,888 (decision 2333)** — the trainer feed became the state re-evaluator's host and
-    /// reads the pet bar, the player's descriptor and its field edges. Read off the dump on the
-    /// tree that lands: undeclared, the feed met six systems; `.after(UnitFeed)` (the shape the
-    /// demo unit feed already takes) declares five of them, and the one it keeps —
-    /// `entities::evict_display_caches` — is the pair every feed that reads `ItemDisplays` has
-    /// (42 on this tree). So the feed's own count went 6 → 1, and the total went 2,887 → 2,888:
-    /// diffing the two dumps, the edge **re-partitioned** the census — five pairs among unrelated
-    /// systems (`cinematic::*` against `ui_logout::drain_logout`, `arm_loot_fx` against the
-    /// party/social drains, …) left the actionable list and six others (`resolve_equipment`
-    /// against `drain_guild`, `emit_minimap` against `drain_quest`, …) entered it, none of them
-    /// touching anything this record touched. That is the instrument moving under an edge, not
-    /// a new undeclared order; 2333 hands it to this ratchet's owner (2287) as a finding. The
-    /// number is the dump's, not a sum.
-    ///
-    /// **5,063 (decision 2337)** — not a raise: a re-measurement. Until here the census read
-    /// the *built* schedule, barriers included, and bevy shares one `ApplyDeferred` barrier per
-    /// distance from the schedule's start — so 2,175 pairs (43%) were "ordered" only through a
-    /// barrier the build happened to place between them, and moved whenever an edge anywhere
-    /// upstream re-homed a group onto another barrier: that is 2333's five-out-six-in, and it is
-    /// the one build step that can make a pair *enter* when an edge is added. The ratchet reads
-    /// the declared graph now ([`SyncPoints::Declared`]); this is the same tree's count with the
-    /// barriers gone, checked by removing one declared edge and watching exactly its five pairs
-    /// return and nothing else move. The dump prints each pair in canonical order since the same
-    /// record, so two dumps diff by text. The number is the dump's, not a sum.
-    ///
-    /// Raising this ceiling is a claim that a new undeclared order is acceptable; make it with
-    /// the reason, or declare the order instead (`.after`, a set, a `chain`). If the pair is
-    /// about a resource that commutes by construction, the claim belongs in [`Classes`].
-    /// **5,608 (decision 2343)** — not a raise: a re-measurement. The 556 pairs with an
-    /// exclusive system on one side were read as "explained" by a class argued for the build's
-    /// barriers, which the declared graph (2337) no longer has; 413 are `finish_colliders`', 143
-    /// the net drain's. Same tree, the class dropped, nothing else moved: 5,052 + 556.
-    /// **5,554 (decision 2345)** — lowered: the TAB scan stopped reading `Visibility` (the draw
-    /// election's verdict), which ended its pairs with every `Visibility` writer.
+    /// Raising the ceiling is a claim that a new undeclared order is acceptable: make it with the
+    /// reason read off the dump, or declare the order (`.after`, a set, a `chain`). A resource
+    /// that commutes by construction belongs in [`Classes`].
     const UPDATE_ACTIONABLE_CEILING: usize = 5_554;
     const UPDATE_ACTIONABLE_SLACK: usize = 40;
 
@@ -1047,8 +687,7 @@ pub(crate) mod schedule_tests {
     #[test]
     fn the_schedules_have_no_more_undeclared_orders_than_the_ceilings_say() {
         let mut app = headless_client();
-        // The declared graph, not the built one: a barrier bevy placed is not an order anyone
-        // declared, and it moves under unrelated edits (2337; see [`SyncPoints`]).
+        // The declared graph: a barrier bevy placed is not a declared order (`SyncPoints`).
         let update = census(&mut app, Update, SyncPoints::Declared);
         let post = census(&mut app, PostUpdate, SyncPoints::Declared);
         let mut explained: BTreeMap<&str, usize> = BTreeMap::new();
@@ -1079,8 +718,7 @@ pub(crate) mod schedule_tests {
             let mut rows: Vec<String> = actionable
                 .iter()
                 .map(|(a, b, what)| {
-                    // Canonical order within the pair: bevy reports (a, b) in whichever order
-                    // its walk met them, and a diff of two dumps must not see that as movement.
+                    // Canonical order within the pair, so two dumps diff by text.
                     let (x, y) = if update.name(*a) <= update.name(*b) {
                         (*a, *b)
                     } else {
@@ -1121,21 +759,17 @@ pub(crate) mod schedule_tests {
         name == "bevy_ecs::apply_deferred"
     }
 
-    /// **How parallel could `Update` be?** A greedy list schedule with unlimited threads: each
-    /// wave takes every system whose predecessors have run and that shares no undeclared
-    /// conflict with a system already in the wave; non-`Send` systems are pairwise exclusive
-    /// besides (the multi-threaded executor runs them one at a time on the main thread). The
-    /// wave count is the frame's serial depth under that executor; the longest declared chain
-    /// is its floor. Returned as `(waves, critical_path)`.
+    /// How parallel could `Update` be? A greedy list schedule with unlimited threads: each wave
+    /// takes every ready system that shares no undeclared conflict with one already in it, and
+    /// non-`Send` systems are pairwise exclusive. Returns `(waves, critical_path)`: the frame's
+    /// serial depth, and its floor, the longest declared chain.
     fn waves(
         c: &Census,
         keep_conflict: impl Fn(&[ComponentId]) -> bool,
         non_send: &[SystemKey],
     ) -> (usize, usize) {
         use std::collections::{HashMap, HashSet};
-        // The build-inserted sync points are left out: they are exclusive barriers the build
-        // places from the flattened graph, which this model does not see; their count is
-        // reported beside the waves instead.
+        // The build-inserted sync points are left out; their count is reported beside the waves.
         let mut order: Vec<SystemKey> = c
             .systems
             .iter()
@@ -1218,13 +852,8 @@ pub(crate) mod schedule_tests {
         (waves, critical)
     }
 
-    /// The structural half of 2265 §A3's executor question — is the prize of collapsing the VM
-    /// (and the audio layer) to one `Send` owner correctness only, or correctness plus
-    /// parallelism? Prints the serial depth of `Update` today and under each collapse.
-    ///
-    /// An instrument, not a gate: it asserts nothing, so it can only fail by panicking inside the
-    /// census, and it boots a headless client to print four numbers. Ignored for the same reason
-    /// `reference_ui`'s chain reports are (2331); run it by hand when the A3 question is live.
+    /// An instrument, not a gate: prints `Update`'s serial depth as-is and with the VM, then
+    /// the audio layer too, made `Send`-owned. Asserts nothing; run it by hand.
     #[test]
     #[ignore = "instrument: run by hand (2265 §A3's executor census) — cargo test -p benilla-app --lib concurrency_census -- --ignored --nocapture"]
     fn concurrency_census() {
@@ -1297,26 +926,17 @@ pub(crate) mod schedule_tests {
         eprintln!("  declared edges only:   {w3} waves (every conflict ordered, everything Send)");
     }
 
-    /// Why a system that holds the VM in `Update` and is ordered before the tick may stay OUT
-    /// of [`crate::ui_script::UiFeed`] — keyed by a suffix of the system's full name, with the
-    /// reason. Read beside [`every_vm_holder_in_update_declares_its_side_of_the_tick`].
-    /// Empty at 2304: every holder ordered before the tick joined the phase (`ui_session::
-    /// feed_interact_npc`, seated inside `WorldStage::Net` for decision 2022's reason, looked
-    /// like the one exception and is not — it writes a resource the unit feed reads, and
-    /// never holds the VM).
+    /// Why a VM holder in `Update` ordered before the tick may stay out of
+    /// [`crate::ui_script::UiFeed`], keyed by a suffix of the system's full name, with the
+    /// reason.
     const OUTSIDE_THE_FEED_PHASE: &[(&str, &str)] = &[];
 
-    /// **Every system that holds the VM in `Update` declares its side of the tick** (decision
-    /// 2304). The VM ticks once a frame (`extract::tick_script`, in `UiInput`): a push the tick
-    /// must see rides `UiFeed`, which the plugin chains after the net drain and before the
-    /// tick; a drain of what the tick produced is `.after(UiInput)`. Read off the built graph,
-    /// so a membership through a parent set and an order through a chain both count. Three
-    /// things fail here: a holder with no declared path to or from the tick; one ordered
-    /// before the tick without riding the feed phase — so it may run before this frame's
-    /// packets land, the class 2265 §A3 counted as "ordered only against `UiInput`" — unless
-    /// it is argued in [`OUTSIDE_THE_FEED_PHASE`]; and a feed-phase member the graph does not
-    /// actually place after the drain and before the tick, the set's contract checked rather
-    /// than trusted. A row arguing a system the graph places elsewhere fails too.
+    /// The VM ticks once a frame (`extract::tick_script`, in `UiInput`): a push the tick must
+    /// see rides `UiFeed`, chained after the net drain and before the tick; a drain of what it
+    /// produced is `.after(UiInput)`. Read off the built graph. Fails a holder with no path to or
+    /// from the tick, one before the tick outside `UiFeed` and not argued in
+    /// [`OUTSIDE_THE_FEED_PHASE`], a `UiFeed` member the graph does not place between the drain
+    /// and the tick, and a stale row.
     #[test]
     fn every_vm_holder_in_update_declares_its_side_of_the_tick() {
         let mut app = headless_client();
@@ -1428,37 +1048,29 @@ pub(crate) mod schedule_tests {
         assert!(stale.is_empty(), "stale rows:\n  {}", stale.join("\n  "));
     }
 
-    /// The consumer markers 2220's census used: a system that holds the VM and does one of
-    /// these to host state has spent something this frame that nothing can re-spend.
+    /// The consumer markers: a VM holder that does one of these to host state has spent
+    /// something this frame that nothing can re-spend.
     const CONSUMES: &[&str] = &["fire_event(", "mem::take(", ".drain("];
 
-    /// Why a one-shot consumer that holds the VM and is NOT gated on `ingame_ui_up` cannot lose
-    /// anything in 2214's one-frame window — 2232's discriminator, as a type. (In that window
-    /// the wire is in-world and the boot VM is still live and frameless, so a one-shot spent
-    /// then is published to a VM with nothing to show it.)
+    /// Why an ungated one-shot consumer holding the VM loses nothing in the one-frame window
+    /// where the wire is in world and the boot VM is still live and frameless.
     #[derive(Debug, Clone, Copy, PartialEq, Eq)]
     enum Because {
         /// The consumed queue is filled only by Lua asking; a frameless VM asks for nothing.
         FilledByVm,
-        /// Filled only by a server reply to something the player had to click in the interface
-        /// — or, noted in the reason, by another player's act on us, which can share a drain
-        /// with the login burst only by coincidence (the residual 2279 names).
+        /// Filled only by a server reply to a click in the interface, or (noted in the reason)
+        /// another player's act on us, which meets the login burst only by coincidence.
         PlayerRoundTrip,
         /// Consumed in the window or not, the state is re-asked or re-derived once the UI is up.
         SelfHealing,
-        /// The publication is driven by a `VmMemo` diff, so a new VM re-derives and re-fires it
-        /// (decision 2226).
+        /// The publication is driven by a `VmMemo` diff, so a new VM re-derives and re-fires it.
         MemoLatched,
         /// Documented at the line as intentional.
         Deliberate,
     }
 
-    /// Every one-shot consumer that holds the VM, is not gated on `ingame_ui_up` (by its own
-    /// run condition or a set's — read off the real schedule, not off the registration text),
-    /// and is not a memo-diffed `fire_event` — each with the reason it is safe. Keyed
-    /// `(path under src/, fn)`. Audited 2026-09-16 (decision 2279) against the fill sites;
-    /// the reason names them. Adding a consumer the ordinary way (gated) passes; adding one
-    /// ungated fails here, at the line, until it is either gated or argued.
+    /// Every one-shot VM consumer not gated on `ingame_ui_up` (read off the schedule) and not a
+    /// memo-diffed `fire_event`, keyed `(path under src/, fn)`, with the reason it is safe.
     const EXEMPT: &[(&str, &str, Because, &str)] = &[
         ("bindings.rs", "sync_dispatch", Because::MemoLatched,
          "`seen_generation` is a `VmMemo`: a new VM reads `None`, rebuilds and re-fires UPDATE_BINDINGS"),
@@ -1559,15 +1171,11 @@ pub(crate) mod schedule_tests {
         }
     }
 
-    /// **Every one-shot consumer that holds the VM is gated, memo-latched, or argued** (2220's
-    /// proposed test, built on the real schedule rather than on the registration text — which
-    /// is why 2220 refused a mechanical pass: `.run_if(ingame_ui_up)` on a set, on a tuple, or
-    /// on the member all read differently in source and identically here). A consumer is one
-    /// of 2220's census: a system taking `NonSend[Mut]<UiScript>` whose body has a
-    /// [`CONSUMES`] marker. It passes if the schedule shows `ingame_ui_up` on it or on a set
-    /// above it, or if it is a `fire_event` driven by a `VmMemo` parameter, or if it is in
-    /// [`EXEMPT`] with its reason. An `EXEMPT` row for a system that is gated after all, or
-    /// that no longer consumes, fails too — the table describes the tree, not its history.
+    /// A consumer (a system taking `NonSend[Mut]<UiScript>` whose body has a [`CONSUMES`]
+    /// marker) passes if the schedule shows `ingame_ui_up` on it or a set above it, if it is a
+    /// `fire_event` driven by a `VmMemo` parameter, or if [`EXEMPT`] argues it. Read off the
+    /// schedule, where a gate on a set, a tuple or the member all look alike. A stale `EXEMPT`
+    /// row fails too.
     #[test]
     fn every_one_shot_consumer_that_holds_the_vm_is_gated_or_argued() {
         use crate::test_support::{fn_items, rel_path, rust_files, src_dir};
@@ -1645,7 +1253,7 @@ pub(crate) mod schedule_tests {
             } else if exempt.is_some() {
                 argued += 1;
             } else {
-                // Name the sets it is under: the fix is usually a gate on one of them.
+                // Name its sets: the fix is usually a gate on one of them.
                 let where_ = match info {
                     None => " (not found in Update/PostUpdate)".to_string(),
                     Some(i) => {
diff --git a/crates/benilla-app/src/game_tip.rs b/crates/benilla-app/src/game_tip.rs
index 3172491f..e393cd37 100644
--- a/crates/benilla-app/src/game_tip.rs
+++ b/crates/benilla-app/src/game_tip.rs
@@ -1,52 +1,24 @@
-//! The loading screen's **tip of the day** (decision 2077).
+//! The loading screen's tip of the day. 1.12's FrameXML only has the `showGameTips` option, so the
+//! feature is engine-side: `CGlueMgr::EnterWorld` picks a `GameTips.dbc` row for the screen and
+//! writes the next index back to the `gameTip` CVar.
 //!
-//! `showGameTips`' only mention in 1.12's FrameXML is its options row and the tooltip string
-//! "Uncheck this to hide the tip of the day in the load screens", so the whole feature is
-//! engine-side: `CGlueMgr::EnterWorld` picks a row from `GameTips.dbc`, hands it to the loading
-//! screen's text slot, and writes the *next* index back into the `gameTip` CVar.
+//! Selection (`0x46b662`-`0x46b6e3`): `gameTip` holds the next index, not the shown one, so stored
+//! values run 1..=count and never 0. The walk is sequential and wraps by clamping (`i < 0 || i >=
+//! count` gives 0, `0x46b682`), not by modulo; `count <= 0` bails. `showGameTips` off skips the
+//! `CVar::Set` as well as the draw (`0x46b671`/`0x46b678`), so it freezes the index; so does
+//! `[selChar+0x10a]`, which `0x5b42a0` sets when `SMSG_CHAR_ENUM` reports level 0 (unreachable
+//! against vmangos, honoured anyway).
 //!
-//! ## The selection law (`0x46b662`–`0x46b6e3`)
+//! Only the glue-to-world load shows a tip: the setter `0x406630` has one caller, and neither
+//! `SMSG_TRANSFER_PENDING` arm sets it. The tip is picked at the entry raise and cleared only at
+//! the dismiss (`0x407f2b`, inside `0x407e80`), so a later raise such as the
+//! `SMSG_LOGIN_VERIFY_WORLD` snap keeps it.
 //!
-//! **`gameTip` holds the NEXT index, not the one on screen.** The client reads it, shows *that*
-//! row, then stores `read + 1`, so on-disk values run 1..=74 and never 0 — a client that stores the
-//! index it just showed is off by one, and the reference's own `Config.wtf` (`SET gameTip "34"`) is
-//! what a naive reading mis-anchors on.
-//!
-//! **The wrap is a clamp, not a modulo**: `if (i < 0 || i >= count) i = 0` at `0x46b682`–`0x46b68f`.
-//! `count <= 0` bails. The walk is **sequential**, never random.
-//!
-//! Two guards sit in front of it. `showGameTips` off jumps past the `CVar::Set` as well as the
-//! draw (`0x46b671`/`0x46b678`), so **turning tips off freezes the index** rather than advancing it
-//! invisibly. And `[selChar+0x10a]` — a *client-synthesised* flag, set by `0x5b42a0` iff the
-//! `SMSG_CHAR_ENUM` level byte arrived as `0` — suppresses the tip for a character the roster
-//! reported at level zero. vmangos always sends a real level, so that arm is unreachable against
-//! our server; it is honoured anyway because it costs one comparison.
-//!
-//! ## Where it draws
-//!
-//! **Only on the glue→world transition.** The setter `0x406630` (a seven-byte
-//! `mov [0x882e10],ecx; ret`) has exactly one caller, and neither `SMSG_TRANSFER_PENDING` arm sets
-//! it — so an in-world portal or worldport screen carries **no tip**. That is why this module hangs
-//! off the loading screen's `world entry` raise.
-//!
-//! **It comes down with the screen, never with a raise.** `[0x882e10]`'s only other writer
-//! image-wide is `0x407f2b`, inside the dismiss `0x407e80` — so the two edges are *pick at the
-//! entry raise* and *clear at the dismiss*, and nothing that happens mid-load can take a tip away.
-//! This module used to clear on every non-entry raise, which read the same for an in-world screen
-//! (the tip was already down) and was wrong for exactly one case: the login snap
-//! `SMSG_LOGIN_VERIFY_WORLD`, which benilla was treating as a fresh load, wiped the tip a server
-//! round-trip into **every** world entry.
-//!
-//! The reference lays the text out **once per raise** and draws it every frame, between the
-//! background quad and the progress bar. Its placement, in the screen's own `[0,1]` ortho:
-//! `s = 515 / (a · 1024)` where `a = [0x832a4c]` is **aspect × 0.75** (not the aspect — the writer
-//! `0x41ad10` multiplies by `0.75` first, and reading it as W/H inflates the wrap width by a third
-//! at 16:9); position `(0.5 − s·0.5, 0.1 + yoff, 0)`; `justifyH = 0` (left); wrap width `s`; body
-//! `0xd7c8c8c8` ARGB with an opaque black shadow at `(+0.001, −0.001)`.
-//!
-//! **Placing it in the 4:3 box is not an approximation of that — it is the same numbers.** The
-//! reference's `[0,1]` ortho spans the whole window, so its `s` and `left` both carry `a`; ours are
-//! percentages of a box that is `H` tall and `4H/3` wide. Multiply them out and the `a` cancels:
+//! Layout, laid out once per raise and drawn between the background and the progress bar, in the
+//! screen's `[0,1]` ortho: scale and wrap width `s = 515 / (a·1024)`, where `a = [0x832a4c]` is
+//! aspect × 0.75 (`0x41ad10`); position `(0.5 − s·0.5, 0.1 + yoff)`, left-justified; `0xd7c8c8c8`
+//! ARGB with an opaque black shadow at `(+0.001, −0.001)`. In a height-fit 4:3 box the `a` cancels,
+//! so the box gives the reference's numbers at every aspect:
 //!
 //! ```text
 //! ref wrap  = s·W          = 515·W / (a·1024)          = 515·H / (1024·0.75) = 0.6706·H
@@ -55,22 +27,13 @@
 //! our left  = (W − 4H/3)/2 + (0.5 − s₁/2)·(4H/3)              = 0.5·W − 0.3353·H
 //! ```
 //!
-//! …for **every** aspect, not just 4:3 — the reference's own wrap column is a constant multiple of
-//! the window HEIGHT, which is exactly what a height-fit letterboxed box makes it. And `yoff` is
-//! settled rather than dodged: `0x4066b9`'s `fcom; fnstsw; test ah,5; jp` takes the `(1 − a)·0.5`
-//! arm **only for `a < 1`**, so on any window at least 4:3 wide the term is zero and the two
-//! layouts agree bit for bit. Narrower than 4:3 they part — but so does the whole loading screen
-//! there (our box overflows where the reference letterboxes top and bottom), and that is the
-//! screen's difference to answer, not the tip's.
+//! `yoff` is `(1 − a)·0.5` only for `a < 1` (`0x4066b9`), zero on any window at least 4:3 wide.
+//! Narrower than 4:3 the loading screen's box overflows where the reference letterboxes top and
+//! bottom, so the whole screen differs there, the tip with it.
 //!
-//! `TIP_BOTTOM`'s `0.1` is not a round number either: `0x4066ee` builds it as `0.05·0.5 + 0.075`,
-//! which is the bar border's own `halfH·0.5 + cy` — **the tip's baseline IS the top edge of the
-//! progress bar**, so the block always sits directly on it.
-//!
-//! The `|cffffd100Tip:|r ` prefix and the trailing `\r\n` are **in the DBC data**, and the escapes
-//! *are* interpreted (`0x5c28af`, flags bit `0x800` clear), so the gold "Tip:" is markup rather
-//! than literal text — which is why the line is built through [`benilla_ui::markup`] rather than
-//! drawn as one string.
+//! The `|cffffd100Tip:|r ` prefix and trailing `\r\n` are in the DBC data and the escapes are
+//! interpreted (`0x5c28af`, flags bit `0x800` clear), so the line goes through
+//! [`benilla_ui::markup`].
 
 use benilla_ui::markup::{self, TokenKind};
 use bevy::ecs::system::EntityCommands;
@@ -78,37 +41,28 @@ use bevy::prelude::*;
 
 use benilla_formats::GameTipsCatalog;
 
-/// `s = 515 / (a · 1024)` at `a = 1` — the 4:3 case, which is the aspect of the content box this
-/// draws into. It is the text's **scale**, and it doubles as the wrap width in the same `[0,1]`
-/// space (`0x406e18` passes `s` for both).
-///
-/// **Not a FrameXML length.** The reference's idiom here is the FrameXML-unit conversion with one
-/// extra instruction (`0x41ae40` divides `G44` back out), so reusing that helper is off by 1.25 at
-/// 4:3.
+/// `s` at `a = 1`, the 4:3 box this draws into: the text's scale and also its wrap width
+/// (`0x406e18` passes `s` for both). Not a FrameXML length: `0x41ae40` divides `G44` back out, so
+/// the FrameXML-unit helper would be off by 1.25 at 4:3.
 const TIP_SCALE: f32 = 515.0 / 1024.0;
 
-/// `pos.y` — the tip's baseline in the screen's `[0,1]` ortho, measured from the bottom, sitting
-/// just above the progress bar's `cy = 0.075`.
+/// The baseline from the bottom of the `[0,1]` ortho. `0x4066ee` builds it as `0.05·0.5 + 0.075`,
+/// the progress bar's top edge, so the block sits on the bar.
 const TIP_BOTTOM: f32 = 0.1;
 
-/// **The font height is 1.8 % of the viewport HEIGHT**, and the `[0x832a48]` in `0x406659`'s
-/// `0.018 · [0x832a48]` is the unit conversion, not part of the number. `0x41ad10` writes that
-/// slot as `1/√(x²+1)` and its neighbour `[0x832a44]` as `x/√(x²+1)` — height/diagonal and
-/// width/diagonal, i.e. the pair that turns a height- or width-fraction into the diagonal-
-/// normalized units `0x44d040` and the placement round trip both work in (`0x41ae70 = x·[832a48]`
-/// beside `0x41ae60 = x·[832a44]`). Reading the 0.6 the shipped `.data` holds as a factor to apply
-/// would shrink the line to five-eighths of the reference's.
+/// The font height as a fraction of the viewport height. In `0x406659`'s `0.018 · [0x832a48]` the
+/// slot is a unit conversion, not part of the size: `0x41ad10` writes it as height/diagonal and
+/// `[0x832a44]` as width/diagonal, the diagonal-normalized units `0x44d040` works in (`0x41ae70`
+/// and `0x41ae60` multiply by each). Applying its shipped `.data` value, 0.6, would shrink the
+/// line.
 const TIP_FONT_FRACTION: f32 = 0.018;
 
 /// The body colour `0xd7c8c8c8` (ARGB) and its shadow offset, in the same `[0,1]` space.
 const TIP_COLOR: Color = Color::srgba(200.0 / 255.0, 200.0 / 255.0, 200.0 / 255.0, 215.0 / 255.0);
 const TIP_SHADOW_OFFSET: f32 = 0.001;
 
-/// The two CVars, mirrored: `showGameTips` and the `gameTip` cursor.
-///
-/// `next` is an `i64` rather than a `u32` because the CVar is a string a player (or a downgraded
-/// build, or a bigger locale table) can leave anything in, and the reference's own tolerance is a
-/// clamp at read time (`0x46b682`'s `i < 0 || i >= count`), not a validation at write time.
+/// The `showGameTips` switch and the `gameTip` cursor. `next` is an `i64` because the CVar can hold
+/// anything; the reference clamps at read time (`0x46b682`), not at write time.
 #[derive(Resource, Debug, Clone, Copy)]
 pub(crate) struct GameTipSetting {
     pub(crate) show: bool,
@@ -124,29 +78,24 @@ impl Default for GameTipSetting {
     }
 }
 
-/// The tips table plus the one piece of state the reference keeps beside it: which row the screen
-/// currently shows, laid out once per raise.
+/// The tips table and the row the screen shows, laid out once per raise.
 #[derive(Resource, Default)]
 pub(crate) struct GameTips {
-    /// `GameTips.dbc` in file order — the array `[0xc0dcd0]`/`[0xc0dcd4]`.
+    /// `GameTips.dbc` in file order, the array at `[0xc0dcd0]`/`[0xc0dcd4]`.
     catalog: GameTipsCatalog,
-    /// `[0x882e10]` — the row the current screen shows, or `None` for a screen with no tip (tips
-    /// off, an in-world transfer, an empty table).
+    /// `[0x882e10]`: the row on screen; `None` with tips off, in-world, or with an empty table.
     shown: Option<String>,
 }
 
 impl GameTips {
-    /// `EnterWorld`'s tip block: read the stored index, clamp it, take that row, and return the
-    /// index to store back (`shown + 1`).
-    ///
-    /// `None` when the table is empty (`count <= 0` bails at `0x46b684`).
+    /// `EnterWorld`'s tip block: clamps the stored index and returns that row with the index to
+    /// store (`shown + 1`); `None` for an empty table (`count <= 0` bails at `0x46b684`).
     fn take(&self, stored: i64) -> Option<(&str, u32)> {
         let count = self.catalog.len();
         if count == 0 {
             return None;
         }
-        // The clamp IS the wrap — there is no modulo, and the second range test at
-        // `0x46b695`–`0x46b69b` is dead.
+        // The clamp is the wrap; the second range test at `0x46b695`-`0x46b69b` is dead.
         let index = if stored < 0 || stored >= count as i64 {
             0
         } else {
@@ -156,17 +105,13 @@ impl GameTips {
         Some((tip, index as u32 + 1))
     }
 
-    /// The line the screen is showing, if any.
     pub(crate) fn shown(&self) -> Option<&str> {
         self.shown.as_deref()
     }
 }
 
-/// The tip split into coloured runs, ready for a Bevy text tree — `|cAARRGGBB…|r` honoured, the
-/// trailing `\r\n` the data carries dropped rather than drawn as blank lines.
-///
-/// Returns `(text, colour)` pairs against `base`, which is the string's own colour that `|r`
-/// restores (`0x5cce99` restores `FontString+0x2c`).
+/// The tip as coloured runs: `|cAARRGGBB…|r` honoured against `base`, which `|r` restores
+/// (`0x5cce99` restores `FontString+0x2c`), and the trailing `\r\n` dropped.
 pub(crate) fn spans(tip: &str, base: Color) -> Vec<(String, Color)> {
     let mut out: Vec<(String, Color)> = Vec::new();
     let mut colour = base;
@@ -191,14 +136,12 @@ pub(crate) fn spans(tip: &str, base: Color) -> Vec<(String, Color)> {
             TokenKind::LineBreak => run.push('\n'),
             TokenKind::EscapedPipe => run.push('|'),
             TokenKind::Char(c) => run.push(c),
-            // No shipped tip carries a hyperlink; a locale archive that adds one draws its visible
-            // text and loses only the click, which nothing on a loading screen could use anyway.
+            // No shipped tip has a hyperlink; one would draw its text and lose only the click.
             TokenKind::LinkOpen { .. } | TokenKind::LinkClose => {}
         }
     }
     flush(&mut run, colour, &mut out);
-    // The data's trailing `\r\n` (one tip carries two) would otherwise draw as empty lines under
-    // the sentence and push the block off its anchor.
+    // The data's trailing `\r\n` (two on one tip) would draw as blank lines and lift the block.
     if let Some((last, _)) = out.last_mut() {
         while last.ends_with('\n') {
             last.pop();
@@ -208,9 +151,8 @@ pub(crate) fn spans(tip: &str, base: Color) -> Vec<(String, Color)> {
     out
 }
 
-/// The block's geometry as **percentages of the 4:3 content box** — `(left, bottom, width)`.
-/// Percent rather than pixels because the node is laid out once per raise, and a window resize
-/// mid-load must not strand it.
+/// `(left, bottom, width)` as percentages of the 4:3 content box, so a mid-load resize cannot
+/// strand a node laid out once per raise.
 pub(crate) const fn geometry() -> (f32, f32, f32) {
     (
         (0.5 - TIP_SCALE * 0.5) * 100.0,
@@ -219,8 +161,7 @@ pub(crate) const fn geometry() -> (f32, f32, f32) {
     )
 }
 
-/// The two numbers that can only be pixels — the font height and the shadow offset — for a content
-/// box of `width × height` logical pixels.
+/// The font height and shadow offset in pixels, for a `width × height` content box.
 pub(crate) fn layout(width: f32, height: f32) -> TipLayout {
     TipLayout {
         font_size: height * TIP_FONT_FRACTION,
@@ -228,22 +169,20 @@ pub(crate) fn layout(width: f32, height: f32) -> TipLayout {
     }
 }
 
-/// What [`layout`] resolves to, in logical pixels inside the loading screen's 4:3 content box.
+/// [`layout`]'s result, in logical pixels inside the 4:3 content box.
 pub(crate) struct TipLayout {
     pub(crate) font_size: f32,
-    /// `(+x, −y)` in the reference; Bevy's shadow offset is `(+x, +y)` with y growing DOWN, so the
-    /// sign is already right.
+    /// The reference's `(+x, −y)`; Bevy's y grows down, so the sign already matches.
     pub(crate) shadow: Vec2,
 }
 
-/// The body colour the tip's own `|r` restores to.
+/// The body colour the tip's `|r` restores.
 pub(crate) const fn base_color() -> Color {
     TIP_COLOR
 }
 
-/// **The tip node's components, in one place.** The loading screen spawns this under its 4:3
-/// content box; [`drive_game_tip`] queries it back. They were written twice — the tuple in
-/// `loading_screen.rs`, the query here — with nothing tying the two together.
+/// The tip node's components: the loading screen spawns them and [`drive_game_tip`] queries them,
+/// so one definition keeps the two in step.
 pub(crate) fn tip_bundle() -> impl Bundle {
     (
         Text::new(String::new()),
@@ -267,9 +206,8 @@ pub(crate) fn tip_bundle() -> impl Bundle {
 
 pub(crate) struct GameTipPlugin;
 
-/// The tip rows' change callback (decision 2303): the switch, and the cursor — which is not a
-/// preference: a hand-edited or downgraded value lands here verbatim and [`raise`] clamps it,
-/// which is the reference's own tolerance (`0x46b682`).
+/// The tip CVars' change callback. A hand-edited cursor lands verbatim; [`raise`] clamps it, as the
+/// reference does (`0x46b682`).
 pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut setting: ResMut<GameTipSetting>) {
     match ev.key().as_str() {
         "showgametips" => setting.show = ev.flag(),
@@ -282,16 +220,14 @@ impl Plugin for GameTipPlugin {
     fn build(&self, app: &mut App) {
         app.add_observer(on_cvar);
         app.init_resource::<GameTips>()
-            // The CVar knob, init'd HERE and not by the CVar host: [`on_cvar`] takes it as a
-            // plain `ResMut`, so a build that registers the row without the resource panics on
-            // the first write — which is what a live run caught and no unit test could, the
-            // test harness having its own `init_resource` chain.
+            // Initialised here, not by the CVar host: [`on_cvar`] takes it as a plain `ResMut` and
+            // panics without it.
             .init_resource::<GameTipSetting>()
             .add_systems(
                 Startup,
                 load_game_tips.after(benilla_assets::AssetSet::Open),
             )
-            // After the loading screen's own drive, which is what sets the edge this reads.
+            // After the loading screen's drive, which sets the edge this reads.
             .add_systems(
                 Update,
                 drive_game_tip.after(benilla_world::schedule::WorldStage::Present),
@@ -299,30 +235,18 @@ impl Plugin for GameTipPlugin {
     }
 }
 
-/// **Putting the tip line away — one path, because there were two and they had drifted.**
-///
-/// Two callers empty this node and both want the same end state: hidden, childless, and holding no
-/// text. Only the second of them used to clear the ROOT's own run, and that difference crashed the
-/// client (B383, decision 2212). Despawning a `Text` root's last `TextSpan` child does not *change*
-/// `Children` — it REMOVES the component — and bevy 0.18's `detect_text_needs_rerender` watches
-/// `Changed<Children>`, which a removal cannot satisfy. So the dismiss left a two-run shaped buffer
-/// behind a one-run span list, and the first window resize after world entry re-laid-out that
-/// buffer and indexed a run that no longer existed: an out-of-bounds panic inside `bevy_text`, on
-/// a node nobody could see. Re-inserting `Text` is what tells the pipeline the block moved.
-///
-/// [`crate::text_reshape`] nets the same hole app-wide; this is the site being coherent on its own
-/// rather than leaning on the net, and it is the half that also keeps a hidden tip from holding a
-/// stale sentence.
+/// Hides the tip node, drops its spans and re-inserts an empty `Text`. The re-insert matters:
+/// despawning a `Text` root's last `TextSpan` removes `Children` rather than changing it, bevy
+/// 0.18's `detect_text_needs_rerender` misses a removal, and the next resize re-lays-out a stale
+/// buffer and panics in `bevy_text`. [`crate::text_reshape`] guards the same hole app-wide.
 fn empty_tip(e: &mut EntityCommands, vis: &mut Visibility) {
     *vis = Visibility::Hidden;
     e.despawn_related::<Children>();
     e.insert(Text::new(String::new()));
 }
 
-/// Take the raise's tip edge, then paint whatever the screen is showing.
-///
-/// Two jobs in one system because they are one mechanism seen at two moments: the reference picks
-/// the row inside `EnterWorld` and lays it out once per raise, then draws that layout every frame.
+/// Takes the raise's tip edge, then paints what the screen shows: the reference picks the row in
+/// `EnterWorld`, lays it out once per raise and draws it every frame.
 fn drive_game_tip(
     mut screen: ResMut<crate::loading_screen::LoadingScreen>,
     mut tips: ResMut<GameTips>,
@@ -341,8 +265,7 @@ fn drive_game_tip(
     windows: Query<&Window>,
     assets: Res<AssetServer>,
     mut commands: Commands,
-    // The cursor persists through the registry, not the knob alone: a host write there is what
-    // the file is composed from and what the VM's mirror learns (decision 2303).
+    // The cursor persists through the registry, which composes the file and feeds the VM's mirror.
     mut cvars: ResMut<crate::cvars::Cvars>,
 ) {
     let Some(edge) = screen.take_tip_edge() else {
@@ -363,19 +286,15 @@ fn drive_game_tip(
         }
     };
     if let Some(next) = next {
-        // The cursor moves only when a tip was actually shown — a suppressed tip freezes it. This
-        // is `EnterWorld`'s own bookkeeping and belongs to the PICK, not to the draw: it stands
-        // even on a frame the paint below cannot complete.
+        // Only a shown tip moves the cursor, at the pick, even if the paint below fails.
         setting.next = i64::from(next);
         cvars.set("gameTip", &next.to_string());
     }
 
-    // The text is laid out once per raise, not per frame, exactly as the reference does.
+    // Laid out once per raise, not per frame, as the reference does.
     let Ok((entity, mut n, mut font, mut shadow, mut vis)) = node.single_mut() else {
-        // Our own `setup_loading_screen` spawns this node, so a miss is a STRUCTURAL bug — the
-        // bundle no longer answering the shape of this query — and never a state a run can
-        // legitimately be in. It was a silent `return` for one release, and it cost the whole
-        // feature while every other instrument read green (decision 2083).
+        // `setup_loading_screen` spawns this node, so a miss is a structural bug: the bundle no
+        // longer matches this query.
         warn!("loading screen: the tip node is missing — no tip can draw");
         return;
     };
@@ -383,8 +302,7 @@ fn drive_game_tip(
         empty_tip(&mut commands.entity(entity), &mut vis);
         return;
     };
-    // The 4:3 content box is `100vh` tall and `100vh · 4/3` wide, so the window's height is the
-    // box's height and the box's width follows from it.
+    // The 4:3 content box is `100vh` tall, so the window height is the box height.
     let height = windows.iter().next().map_or(768.0, |w| w.height());
     let l = layout(height * 4.0 / 3.0, height);
     let (left, bottom, width) = geometry();
@@ -415,9 +333,7 @@ fn drive_game_tip(
         None => empty_tip(&mut e, &mut vis),
     }
 
-    // The run's own evidence — and it sits HERE, past the query, the layout and the runs, because
-    // the line it replaces sat in front of all three: it reported a row picked over a screen that
-    // drew nothing, and a live smoke run printed it twice while the feature was entirely dead.
+    // Logged only once the line is painted, not merely picked.
     if let (Some(next), true) = (next, painted) {
         info!(
             "loading screen: tip {} of {} on screen",
@@ -427,8 +343,7 @@ fn drive_game_tip(
     }
 }
 
-/// `GameTips.dbc`, once, off the patch chain — the reference's own single linear load, with no
-/// reload path. `.after(AssetSet::Open)` for the reason every DBC load in this tree carries it.
+/// `GameTips.dbc`, loaded once off the patch chain with no reload path, as the reference does.
 fn load_game_tips(mut tips: ResMut<GameTips>, assets: Option<Res<benilla_assets::WorldAssets>>) {
     let Some(assets) = assets else { return };
     use benilla_assets::LockRecover;
@@ -443,10 +358,8 @@ fn load_game_tips(mut tips: ResMut<GameTips>, assets: Option<Res<benilla_assets:
     }
 }
 
-/// Pick the row for a screen that is about to rise, and hand back the index to store.
-///
-/// `show` is `showGameTips`; `level_is_zero` is `[selChar+0x10a]`. Both suppress the tip AND the
-/// advance — the reference jumps past its own `CVar::Set`, so an off switch freezes the index.
+/// Picks the row for a rising screen and returns the index to store. `show` is `showGameTips` and
+/// `level_is_zero` is `[selChar+0x10a]`; either suppresses the tip and the advance.
 pub(crate) fn raise(
     tips: &mut GameTips,
     show: bool,
@@ -469,7 +382,7 @@ pub(crate) fn raise(
     }
 }
 
-/// The dismiss (`0x407f2b`, inside `0x407e80`) — the only thing that takes a tip down.
+/// The dismiss (`0x407f2b`, inside `0x407e80`), the only thing that takes a tip down.
 pub(crate) fn clear(tips: &mut GameTips) {
     tips.shown = None;
 }
@@ -485,9 +398,7 @@ mod tests {
         }
     }
 
-    /// **`gameTip` holds the NEXT index.** A fresh client's registered `"0"` shows row 0 and stores
-    /// 1, so on-disk values run 1..=count and never 0 — the off-by-one a client that stores what it
-    /// just showed would ship.
+    /// A fresh `"0"` shows row 0 and stores 1.
     #[test]
     fn the_stored_index_is_the_next_one_not_the_shown_one() {
         let mut t = tips(&["a", "b", "c"]);
@@ -497,9 +408,7 @@ mod tests {
         assert_eq!(t.shown(), Some("b"));
     }
 
-    /// The wrap is the **clamp**, not a modulo: anything at or past the count restarts at 0, and so
-    /// does a negative. A stored index from a bigger table (a locale archive, a patch) lands on
-    /// row 0 rather than nothing.
+    /// Past the count or negative restarts at row 0.
     #[test]
     fn the_clamp_is_the_wrap() {
         let mut t = tips(&["a", "b", "c"]);
@@ -513,9 +422,7 @@ mod tests {
         assert_eq!(raise(&mut t, true, false, -4), Some(1), "and negative");
     }
 
-    /// Both guards suppress the tip **and the advance** — the reference jumps past its own
-    /// `CVar::Set`, so turning tips off freezes the index rather than burning through the table
-    /// invisibly.
+    /// Both guards suppress the tip and the advance.
     #[test]
     fn a_suppressed_tip_freezes_the_index() {
         let mut t = tips(&["a", "b", "c"]);
@@ -523,7 +430,7 @@ mod tests {
         assert_eq!(t.shown(), None);
         assert_eq!(raise(&mut t, true, true, 1), None, "the level-zero guard");
         assert_eq!(t.shown(), None);
-        // …and the index it would have advanced is untouched: the next armed raise still reads 1.
+        // The next armed raise still reads 1.
         assert_eq!(raise(&mut t, true, false, 1), Some(2));
         assert_eq!(t.shown(), Some("b"));
     }
@@ -536,9 +443,7 @@ mod tests {
         assert_eq!(t.shown(), None);
     }
 
-    /// The `|c…|r` prefix is **markup in the data**, so the gold "Tip:" is its own run and the rest
-    /// falls back to the body colour — and the trailing `\r\n` the DBC carries is dropped rather
-    /// than drawn as blank lines under the sentence.
+    /// The gold "Tip:" is its own run, and the trailing `\r\n` goes.
     #[test]
     fn the_gold_tip_prefix_is_markup_and_the_trailing_newlines_go() {
         let base = base_color();
@@ -550,14 +455,10 @@ mod tests {
         assert_eq!(runs[1].1, base);
     }
 
-    /// The placement, at the one aspect the reference's own `yoff` is zero — a 4:3 content box,
-    /// which is what benilla's loading screen always is. `s = 515/1024`, left-anchored at
-    /// `0.5 − s/2`, wrap width `s`, baseline at `0.1` from the bottom.
+    /// At 4:3, where `yoff` is zero: `s = 515/1024`, left at `0.5 − s/2`, baseline at `0.1`.
     #[test]
     fn the_layout_is_the_reference_numbers_at_four_three() {
         let (left, bottom, width) = geometry();
-        // `s = 515/1024` — a 515 px column in a 1024-wide box, centred, and the baseline a tenth of
-        // the box's height up, just clear of the progress bar's `cy = 0.075`.
         assert!(
             (width * 0.01 * 1024.0 - 515.0).abs() < 0.01,
             "s·width = 515 px"
@@ -574,9 +475,8 @@ mod tests {
         );
     }
 
-    /// An app holding the real node and the real system, one tip in the table — plus the text
-    /// stack and the real `detect_text_needs_rerender`, so what the paint and the dismiss do to
-    /// the node's `ComputedTextBlock` is observable (B383, decision 2212).
+    /// The real node and system with one tip, plus the text stack and `detect_text_needs_rerender`,
+    /// so what the paint and the dismiss do to the `ComputedTextBlock` is observable.
     fn tip_app() -> (App, Entity) {
         let mut app = App::new();
         app.add_plugins((MinimalPlugins, bevy::asset::AssetPlugin::default()));
@@ -605,12 +505,8 @@ mod tests {
             .tip_edge = Some(edge);
     }
 
-    /// **The tip has to reach the node, and only a run of the real system can say that.** Every
-    /// pure-function test here covers the *pick* — and the pick is exactly the half that worked: it
-    /// advanced the cursor, wrote `gameTip`, and logged "tip N of 74" over a screen that drew
-    /// nothing, because the spawned bundle was one component short of what [`drive_game_tip`]'s
-    /// query asks for and the missed `single_mut()` returned in silence. So this drives the
-    /// system over the bundle the loading screen actually spawns and looks at the glass end.
+    /// A pick reaches the node the loading screen spawns, not only the cursor: the bundle must
+    /// match [`drive_game_tip`]'s query.
     #[test]
     fn a_pick_paints_the_node_the_loading_screen_spawns() {
         let (mut app, tip) = tip_app();
@@ -636,8 +532,7 @@ mod tests {
             w.get::<TextSpan>(kids[0]).map(|t| t.0.as_str()),
             Some(" Talk to the innkeeper.")
         );
-        // …and the geometry the paint writes, which is what puts it above the bar rather than at
-        // the box's corner where the bundle leaves it.
+        // The paint's geometry puts the line above the bar, off the bundle's corner.
         let node = w.get::<Node>(tip).expect("Node");
         assert_eq!(node.bottom, Val::Percent(geometry().1));
         assert_eq!(node.width, Val::Percent(geometry().2));
@@ -645,16 +540,12 @@ mod tests {
             w.get::<TextFont>(tip).is_some_and(|f| f.font_size > 0.0),
             "the font height is resolved from the window"
         );
-        // The cursor moved with it: `gameTip` holds the NEXT row.
+        // The cursor moved with it: `gameTip` holds the next row.
         assert_eq!(w.resource::<GameTipSetting>().next, 1);
     }
 
-    /// **A tip outlives every raise and dies with the screen** — [`crate::loading_screen`]'s law
-    /// (decision 2081), seen from the painting end. That module's own test asserts which *edges*
-    /// the state machine emits; this one asserts what the painter does with them, and the case that
-    /// matters is the one with no edge at all: a raise landing on a live screen must leave the line
-    /// exactly where it is, same text and same cursor. Between them the two cover the login snap
-    /// that used to wipe the tip a server round-trip into every world entry.
+    /// A raise with no edge on a live screen keeps the line and the cursor; only the dismiss takes
+    /// it down. [`crate::loading_screen`]'s test covers which edges are emitted.
     #[test]
     fn the_tip_outlives_a_second_raise_and_dies_with_the_screen() {
         let (mut app, tip) = tip_app();
@@ -665,7 +556,7 @@ mod tests {
             Some(&Visibility::Inherited)
         );
 
-        // The destination snap: `drive_loading_screen` raises again and sets NO edge.
+        // The destination snap: `drive_loading_screen` raises again and sets no edge.
         app.update();
         app.update();
         assert_eq!(
@@ -697,21 +588,15 @@ mod tests {
             .is_none_or(|c| c.is_empty()));
     }
 
-    /// **B383 — the dismiss must leave the tip node re-shapeable.** The loading screen's root is
-    /// never despawned, only hidden, so the tip node outlives every load and every later window
-    /// resize re-lays-out its text block. Emptying it by despawning the spans alone left the
-    /// block's shaped buffer pointing at a run that no longer existed, and the first maximize
-    /// after world entry panicked inside `bevy_text`. The observable: after the dismiss the root
-    /// holds no text and the block is marked for a re-shape.
-    ///
-    /// The mechanism's own end — that the re-shape is what stops the panic — is
-    /// [`crate::text_reshape`]'s, which drives the real pipeline over the same shape.
+    /// After the dismiss the root holds no text and the block is marked for a re-shape, so a later
+    /// resize cannot index a despawned run (the loading screen's root is hidden, never despawned).
+    /// [`crate::text_reshape`] shows the re-shape is what stops the panic.
     #[test]
     fn the_dismiss_leaves_the_node_reshapeable() {
         let (mut app, tip) = tip_app();
         set_edge(&mut app, crate::loading_screen::TipEdge::Pick);
         app.update();
-        // The state a painted frame leaves behind: a two-run block, shaped, nothing pending.
+        // A painted frame's state: a two-run block, shaped, nothing pending.
         crate::text_reshape::harness::shape(&mut app, tip);
         assert_eq!(
             app.world()
diff --git a/crates/benilla-app/src/glue/add_material.rs b/crates/benilla-app/src/glue/add_material.rs
index f311d08f..e0c7e83d 100644
--- a/crates/benilla-app/src/glue/add_material.rs
+++ b/crates/benilla-app/src/glue/add_material.rs
@@ -1,8 +1,5 @@
-//! WoW `alphaMode="ADD"` in Bevy UI — a tiny [`UiMaterial`] whose pipeline blends **additively**
-//! (SrcAlpha/One, the FrameXML ADD mode). It replaces the alpha-encode approximation
-//! (`a′ = a·max(r,g,b)`, normal blending), which could only fake the add over *dark* backgrounds:
-//! over the bright arrow/rotate faces its dim glow pixels **darkened** the art instead of
-//! brightening it — the director's "weird/small" and "dark on hover" reports.
+//! FrameXML `alphaMode="ADD"` for Bevy UI: a [`UiMaterial`] blending SrcAlpha/One, so a dim
+//! glow brightens bright art under it instead of darkening it.
 
 use bevy::prelude::*;
 use bevy::render::render_resource::{
@@ -11,8 +8,8 @@ use bevy::render::render_resource::{
 use bevy::shader::ShaderRef;
 use bevy::ui_render::ui_material::{UiMaterial, UiMaterialKey};
 
-/// An additive UI overlay: `texture`'s `rect` sub-region (uv `(u0, v0, u1, v1)`; the whole texture
-/// is `(0,0,1,1)`) drawn `dst + src·srcAlpha`.
+/// An additive UI overlay: `texture`'s uv sub-region `rect` `(u0, v0, u1, v1)`, drawn
+/// `dst + src·srcAlpha`.
 #[derive(Asset, TypePath, AsBindGroup, Clone)]
 pub(crate) struct AddUiMaterial {
     #[texture(0)]
@@ -40,7 +37,7 @@ impl UiMaterial for AddUiMaterial {
                     dst_factor: BlendFactor::One,
                     operation: BlendOperation::Add,
                 },
-                // The destination's coverage stays — the add never erodes what's under it.
+                // The destination's coverage stays: the add never erodes what is under it.
                 alpha: BlendComponent {
                     src_factor: BlendFactor::Zero,
                     dst_factor: BlendFactor::One,
diff --git a/crates/benilla-app/src/glue/art.rs b/crates/benilla-app/src/glue/art.rs
index 68fcbab0..8db69f07 100644
--- a/crates/benilla-app/src/glue/art.rs
+++ b/crates/benilla-app/src/glue/art.rs
@@ -1,10 +1,6 @@
-//! The glue screens' client-data art (decisions 0423 + 0465) — everything the reference
-//! `CharacterCreate.xml` / `CharacterSelect.xml` / `GlueButtons.xml` draw with, loaded off the
-//! player's own patch chain (never embedded): the icon sheets, the tower frame pieces, the rotate
-//! buttons, the select list's row highlight, and the `Backdrop` edge files split into their
-//! eight authored pieces. Plus the frozen texcoord tables from `CharacterCreate.lua` and the authored glue
-//! palette (`GlueFonts.xml` / the Lua color table). Every field is optional — with no client data
-//! the screens degrade to plain text buttons.
+//! The glue screens' art, loaded off the player's own patch chain, plus the texcoord tables of
+//! `CharacterCreate.lua` and the glue palette. Every piece is optional: with no client data the
+//! screens fall back to plain text buttons.
 
 use bevy::prelude::*;
 
@@ -19,21 +15,20 @@ use super::backdrop::BackdropEdges;
 pub(crate) const GOLD: Color = Color::srgb(1.0, 0.78, 0.0);
 /// `GlueFontDisable*`'s gray.
 pub(crate) const DIM: Color = Color::srgb(0.5, 0.5, 0.5);
-/// The info bodies' `GlueFontCharacterCreate` — pure white (inherits `GlueFontHighlightSmall`).
+/// The info bodies' `GlueFontCharacterCreate`: white, from `GlueFontHighlightSmall`.
 pub(crate) const INFO_TEXT: Color = Color::WHITE;
-/// The page tints — ours: the ref swaps a whole 3D scene per race; we lean the flat page instead
-/// (Alliance cool, Horde warm).
+/// The glue screens' root fill, ours (Alliance cool, Horde warm on the create screen), seen only
+/// where no 3D scene draws over it.
 pub(crate) const BACKDROP: Color = Color::srgb(0.05, 0.06, 0.08);
 pub(crate) const BACKDROP_ALLIANCE: Color = Color::srgb(0.05, 0.06, 0.10);
 pub(crate) const BACKDROP_HORDE: Color = Color::srgb(0.09, 0.05, 0.05);
-/// `FACTION_BACKDROP_COLOR_TABLE` (CharacterCreate.lua): border rgb + bg rgb per row. The info
-/// panels apply only the bg tint (the ref *comments out* the border tint); the name box applies
-/// both — always the Alliance row (`CharacterCreate_OnLoad`).
+/// `FACTION_BACKDROP_COLOR_TABLE` (CharacterCreate.lua): the info panels take only the fill (the
+/// border tint is commented out); the name box takes both, always the Alliance row.
 pub(crate) const ALLIANCE_BORDER: Color = Color::srgb(0.5, 0.5, 0.5);
 pub(crate) const ALLIANCE_FILL: Color = Color::srgb(0.09, 0.09, 0.19);
 pub(crate) const HORDE_FILL: Color = Color::srgb(0.19, 0.05, 0.05);
-/// Plain-fill fallbacks (no client art only): a faint button face, its hover, and a translucent
-/// box fill standing in for `UI-Tooltip-Background` (whose ~0.8 alpha is baked into the texture).
+/// Fallbacks with no client art; `FALLBACK_ALPHA` matches the ~0.8 alpha baked into
+/// `UI-Tooltip-Background`.
 pub(crate) const BTN_BG: Color = Color::srgba(1.0, 1.0, 1.0, 0.05);
 pub(crate) const BTN_HOVER: Color = Color::srgba(1.0, 1.0, 1.0, 0.14);
 pub(crate) const FALLBACK_ALPHA: f32 = 0.8;
@@ -45,16 +40,15 @@ pub(crate) const NAME_EDGE: f32 = 16.0;
 
 // ── The art set ──────────────────────────────────────────────────────────────────────────────────
 
-/// One spinner-arrow direction's states (`Glue-{Left,Right}Arrow-Button-{Up,Down,Highlight}` —
-/// the highlight pre-built as its additive overlay material).
+/// One spinner arrow's states, `Glue-{Left,Right}Arrow-Button-{Up,Down,Highlight}`.
 pub(crate) struct ArrowArt {
     pub(crate) up: Handle<Image>,
     pub(crate) down: Option<Handle<Image>>,
     pub(crate) hi: Option<Handle<AddUiMaterial>>,
 }
 
-/// One scrollbar arrow's states (`UI-ScrollBar-Scroll{Up,Down}Button-*`: 32² sheets whose center
-/// quarter is the 16² button — `GlueScrollBarButton`'s texcoords, [`SCROLL_BTN_TC`]).
+/// One scrollbar arrow's states (`UI-ScrollBar-Scroll{Up,Down}Button-*`), the 16² button in the
+/// center quarter of a 32² sheet ([`SCROLL_BTN_TC`]).
 pub(crate) struct ScrollBtnArt {
     pub(crate) up: Handle<Image>,
     pub(crate) down: Handle<Image>,
@@ -63,7 +57,7 @@ pub(crate) struct ScrollBtnArt {
     pub(crate) size: Vec2,
 }
 
-/// The login checkbox's states (`UI-CheckBox-*`, AccountLogin.xml's Save Account Name button).
+/// The login Save Account Name checkbox's states (`UI-CheckBox-*`, AccountLogin.xml).
 pub(crate) struct CheckboxArt {
     pub(crate) up: Handle<Image>,
     pub(crate) down: Handle<Image>,
@@ -76,8 +70,7 @@ pub(crate) struct ScrollArt {
     pub(crate) up_btn: ScrollBtnArt,
     pub(crate) down_btn: ScrollBtnArt,
     pub(crate) knob: (Handle<Image>, Vec2),
-    /// `UI-CharacterCreate-ScrollBar-Top` / `UI-ClassTrainer-ScrollBar` — the decorative track
-    /// behind the slider, shown only when the panel scrolls (the ref's range-changed hook).
+    /// The decorative track behind the slider, shown only when the panel scrolls.
     pub(crate) track_top: Option<(Handle<Image>, Vec2)>,
     pub(crate) track_bottom: Option<(Handle<Image>, Vec2)>,
 }
@@ -105,83 +98,66 @@ pub(crate) struct GlueArt {
     pub(crate) tower_border: Option<(Handle<Image>, Vec2)>,
     /// The 64² shadow behind every race/class/gender icon.
     pub(crate) icon_shadow: Option<Handle<Image>>,
-    /// The dial rows' `CharacterCreate-LabelFrame` (128×64: a 25|stretch|25 horizontal 3-slice).
+    /// The dial rows' `CharacterCreate-LabelFrame`: 128×64, a 25|stretch|25 horizontal 3-slice.
     pub(crate) label_frame: Option<(Handle<Image>, Vec2)>,
-    /// The big rotate buttons (`UI-RotationRight-Big-*`; the left button is this art mirrored).
+    /// `UI-RotationRight-Big-*`; the left rotate button is this art mirrored.
     pub(crate) rotate_up: Option<Handle<Image>>,
     pub(crate) rotate_down: Option<Handle<Image>>,
     /// The rotate buttons' hover ring (`UI-Common-MouseHilight`).
     pub(crate) mouse_hilight: Option<Handle<AddUiMaterial>>,
-    /// The `Backdrop` pieces: the two edge files split into their eight authored pieces
-    /// ([`split_backdrop_edges`]) + the tiled `UI-Tooltip-Background`.
+    /// The two edge files split into their eight pieces, and the tiled `UI-Tooltip-Background`.
     pub(crate) panel_border: Option<BackdropEdges>,
     pub(crate) name_border: Option<BackdropEdges>,
     pub(crate) tooltip_bg: Option<Handle<Image>>,
-    /// The info panels' scrollbar set (all-or-nothing: without the full set the panels stay
-    /// wheel-only, like before).
+    /// All or nothing: without the full set the info panels scroll by wheel only.
     pub(crate) scroll: Option<ScrollArt>,
-    /// The select list's row highlight (`Glue-CharacterSelect-Highlight`, ADD) — hover + the
-    /// locked selected row.
+    /// `Glue-CharacterSelect-Highlight` (ADD), on hover and on the locked selected row.
     pub(crate) select_highlight: Option<Handle<AddUiMaterial>>,
-    /// The delete/rename dialog box (`UI-DialogBox-Background` tile + `-Border` edge 32, split).
+    /// The delete/rename dialog: `UI-DialogBox-Border` (edge 32) over `-Background`.
     pub(crate) dialog_border: Option<BackdropEdges>,
     pub(crate) dialog_bg: Option<Handle<Image>>,
-    /// The dialog's `DialogAlertIcon` (64²).
     pub(crate) dialog_alert: Option<Handle<Image>>,
-    /// The delete dialog's edit-box art (`UI-ChatInputBorder-Left`/`-Right`, CharacterSelect.xml):
-    /// two 75×32 pieces overhanging the 130-wide box by 10 each side.
+    /// The delete dialog's edit box (CharacterSelect.xml): two 75×32 pieces overhanging the
+    /// 130-wide box by 10 each side.
     pub(crate) chat_input_left: Option<(Handle<Image>, Vec2)>,
     pub(crate) chat_input_right: Option<(Handle<Image>, Vec2)>,
-    /// The login screen's set (decision 0539): the Blizzard logo (`Glues-BlizzardLogo`, bottom
-    /// center) and the Save Account Name checkbox states.
+    /// The login screen's logo (bottom center) and checkbox.
     pub(crate) blizzard_logo: Option<Handle<Image>>,
     pub(crate) checkbox: Option<CheckboxArt>,
-    /// The AddOn List screen's set (the reference `GlueXML/AddonList.xml`, read off the patch
-    /// chain): the six `HelpFrame-*` plate pieces that ARE the whole framed panel (top band, dark
-    /// inset, bottom band baked in), the `UI-DialogBox-Header` title plate, the `GlueCloseButton`
-    /// states, the `GlueDropDownMenuTemplate` arrow (`UI-ChatIcon-ScrollDown-*`), the open list's
-    /// row highlight (`UI-QuestTitleHighlight`, ADD), the tri-state's grey check
-    /// (`UI-CheckBox-Check-Disabled`), the tooltip's own border (`UI-Tooltip-Border`, edge 16 —
-    /// the in-game edge file, not `Glue-Tooltip-Border`), and the decorative scrollbar track
-    /// (`UI-Character-ScrollBar`).
+    /// The AddOn List screen's set (`GlueXML/AddonList.xml`). The six `HelpFrame-*` pieces are the
+    /// whole framed panel; its tooltip uses the in-game `UI-Tooltip-Border`, not the glue one.
     pub(crate) help_frame: Option<HelpFrameArt>,
     pub(crate) dialog_header: Option<(Handle<Image>, Vec2)>,
     pub(crate) close_btn: Option<CloseBtnArt>,
     pub(crate) dropdown_arrow_up: Option<Handle<Image>>,
     pub(crate) dropdown_arrow_down: Option<Handle<Image>>,
     pub(crate) quest_hilight: Option<Handle<AddUiMaterial>>,
-    /// The same `UI-QuestLogTitleHighlight` art as a **plain texture**. The realm list tints its
-    /// selection band per row (`RealmListHighlightTexture:SetVertexColor` — green when you have
-    /// characters on that realm, red when it is invalid, gold otherwise), and a shared
-    /// `AddUiMaterial` handle cannot carry a per-row colour. **Stated divergence:** drawn
-    /// alpha-blended rather than the reference's `alphaMode="ADD"`, which is the price of the
-    /// tint until the ADD material grows a colour uniform.
+    /// The realm list's selection band, tinted per row by
+    /// `RealmListHighlightTexture:SetVertexColor`. Drawn alpha-blended where the reference uses
+    /// `alphaMode="ADD"`: `AddUiMaterial` has no tint yet.
     pub(crate) title_highlight: Option<Handle<Image>>,
     pub(crate) check_disabled: Option<Handle<Image>>,
     pub(crate) tooltip_border: Option<BackdropEdges>,
     pub(crate) char_scrollbar: Option<(Handle<Image>, Vec2)>,
 
-    /// The realm list's own additions to that set (`RealmList.xml`): the sort headers'
-    /// `RealmSortButtonTemplate` — a three-slice `WhoFrame-ColumnTabs` plate, the
-    /// `UI-Character-Tab-Highlight` sheen it lights on hover, and the `UI-SortArrow` that sits
-    /// beside each label.
+    /// The realm list's sort headers (`RealmSortButtonTemplate`, RealmList.xml).
     pub(crate) column_tabs: Option<(Handle<Image>, Vec2)>,
     pub(crate) tab_highlight: Option<Handle<AddUiMaterial>>,
     pub(crate) sort_arrow: Option<(Handle<Image>, Vec2)>,
 }
 
-/// `RealmSortButtonTemplate`'s three `WhoFrame-ColumnTabs` slices, `[left, right, top, bottom]`
-/// texcoords each — the left cap (5 wide), the stretched middle, and the right cap (4 wide).
+/// `RealmSortButtonTemplate`'s `WhoFrame-ColumnTabs` slices, `[left, right, top, bottom]` each:
+/// the left cap (5 wide), the stretched middle, the right cap (4 wide).
 pub(crate) const COLUMN_TAB_TC: [[f32; 4]; 3] = [
     [0.0, 0.078_125, 0.0, 0.593_75],
     [0.078_125, 0.906_25, 0.0, 0.593_75],
     [0.906_25, 0.968_75, 0.0, 0.593_75],
 ];
-/// `$parentArrow`'s texcoords into `UI-SortArrow` (the down-pointing half).
+/// `$parentArrow`'s texcoords into `UI-SortArrow`, the down-pointing half.
 pub(crate) const SORT_ARROW_TC: [f32; 4] = [0.0, 0.5625, 0.0, 1.0];
 
-/// The `Interface\HelpFrame\HelpFrame-*` plate: six pieces tiling a 640×512 framed panel
-/// (TopLeft/Top 256², TopRight 128×256 across the top row; BotLeft/Bottom/BotRight below).
+/// The `HelpFrame-*` plate: six pieces tiling a 640×512 panel (TopLeft/Top 256², TopRight
+/// 128×256 on top; BotLeft/Bottom/BotRight below).
 pub(crate) struct HelpFrameArt {
     pub(crate) tl: Handle<Image>,
     pub(crate) top: Handle<Image>,
@@ -201,7 +177,7 @@ pub(crate) struct CloseBtnArt {
 }
 
 impl GlueArt {
-    /// Load the art set once (idempotent; failures stay `None` — the graceful-absence posture).
+    /// Load the art set once; a piece that fails stays `None`.
     pub(crate) fn ensure_loaded(
         &mut self,
         assets: &mut WorldAssets,
@@ -247,8 +223,8 @@ impl GlueArt {
         self.gender = sized(assets, &format!("{CC}Gender"), images);
         self.factions = sized(assets, &format!("{CC}Factions"), images);
         self.banners = assets.sprite_texture(&format!("{CC}Banners"), images);
-        // (`CheckButtonHilight` stays unloaded — the template's `CheckedTexture` is commented out
-        // in the shipped 1.12 GlueXML; the selected visual is the *locked* highlight alone.)
+        // No `CheckButtonHilight`: the template's `CheckedTexture` is commented out in 1.12
+        // GlueXML, so the selected look is the locked highlight alone.
         self.hilight = add_overlay(
             assets,
             "Interface\\Buttons\\ButtonHilight-Square",
@@ -340,7 +316,7 @@ impl GlueArt {
                 ),
             })
         })();
-        // The select screen's set (decision 0465): the row highlight + the delete dialog's box.
+        // The select screen's set.
         self.select_highlight = add_overlay(
             assets,
             "Interface\\Glues\\CharacterSelect\\Glue-CharacterSelect-Highlight",
@@ -367,7 +343,7 @@ impl GlueArt {
             "Interface\\ChatFrame\\UI-ChatInputBorder-Right",
             images,
         );
-        // The login screen's set (decision 0539).
+        // The login screen's set.
         self.blizzard_logo =
             assets.sprite_texture("Interface\\Glues\\Mainmenu\\Glues-BlizzardLogo", images);
         self.checkbox = (|| {
@@ -384,7 +360,7 @@ impl GlueArt {
                 ),
             })
         })();
-        // The AddOn List screen's set (reference `GlueXML/AddonList.xml` off the patch chain).
+        // The AddOn List screen's set.
         const HF: &str = "Interface\\HelpFrame\\HelpFrame-";
         self.help_frame = (|| {
             let tl = sized(assets, &format!("{HF}TopLeft"), images)?;
@@ -515,10 +491,8 @@ impl GlueArt {
 /// The whole-texture uv rect for [`add_overlay`].
 const FULL_TC: [f32; 4] = [0.0, 1.0, 0.0, 1.0];
 
-/// Build one ADD-mode highlight as its [`AddUiMaterial`] — a TRUE additive overlay (every glue
-/// highlight is authored as a glow on opaque black and drawn `alphaMode="ADD"`; see the material's
-/// module docs for why an alpha-encode approximation was retired). `tc` is the authored
-/// `[left, right, top, bottom]` texcoord region (the sheets store the button in a sub-rect).
+/// One `alphaMode="ADD"` highlight (a glow authored on opaque black) as an [`AddUiMaterial`];
+/// `tc` is the `[left, right, top, bottom]` texcoord region.
 fn add_overlay(
     assets: &mut WorldAssets,
     path: &str,
@@ -533,9 +507,9 @@ fn add_overlay(
     }))
 }
 
-// ── The frozen icon-cell tables (CharacterCreate.lua's *_ICON_TCOORDS, verbatim) ─────────────────
+// ── The icon-cell tables (CharacterCreate.lua's *_ICON_TCOORDS, verbatim) ────────────────────────
 
-/// A race's cell in `UI-CharacterCreate-Races` (col, row; female = row + 2) — `RACE_ICON_TCOORDS`.
+/// A race's cell in `UI-CharacterCreate-Races` (col, row; female is row + 2), `RACE_ICON_TCOORDS`.
 fn race_cell(race: u8) -> Option<(f32, f32)> {
     Some(match race {
         1 => (0.0, 0.0), // Human
@@ -550,14 +524,13 @@ fn race_cell(race: u8) -> Option<(f32, f32)> {
     })
 }
 
-/// A race icon's texcoords for a (race, sex).
 pub(crate) fn race_tc(race: u8, sex: u8) -> Option<[f32; 4]> {
     let (c, r) = race_cell(race)?;
     let r = r + if sex == 1 { 2.0 } else { 0.0 };
     Some([c * 0.25, (c + 1.0) * 0.25, r * 0.25, (r + 1.0) * 0.25])
 }
 
-/// A class icon's texcoords in `UI-CharacterCreate-Classes` — `CLASS_ICON_TCOORDS`, verbatim.
+/// A class icon's texcoords in `UI-CharacterCreate-Classes`, `CLASS_ICON_TCOORDS` verbatim.
 pub(crate) fn class_tc(class: u8) -> Option<[f32; 4]> {
     Some(match class {
         1 => [0.0, 0.25, 0.0, 0.25],              // Warrior
@@ -573,14 +546,13 @@ pub(crate) fn class_tc(class: u8) -> Option<[f32; 4]> {
     })
 }
 
-/// The glue-button art regions (`GlueButtons.xml` TexCoords): Up/Down/Disabled share one region,
-/// the Highlight has its own.
+/// `GlueButtons.xml` texcoords: Up/Down/Disabled share one region, the Highlight has its own.
 pub(crate) const BUTTON_TC: [f32; 4] = [0.0, 0.578125, 0.0, 0.75];
 pub(crate) const BUTTON_HI_TC: [f32; 4] = [0.0, 0.625, 0.0, 0.6875];
-/// The scrollbar buttons/knob live in the center quarter of their sheets (`GlueScrollBarButton`).
+/// The scrollbar buttons and knob sit in the center quarter of their sheets.
 pub(crate) const SCROLL_BTN_TC: [f32; 4] = [0.25, 0.75, 0.25, 0.75];
 
-/// Texcoords → an `ImageNode` pixel rect on a texture of `size`.
+/// Texcoords to an `ImageNode` pixel rect on a texture of `size`.
 pub(crate) fn tc_rect(size: Vec2, tc: [f32; 4]) -> Rect {
     Rect::new(
         tc[0] * size.x,
diff --git a/crates/benilla-app/src/glue/backdrop.rs b/crates/benilla-app/src/glue/backdrop.rs
index 659a88f4..6dbb39ac 100644
--- a/crates/benilla-app/src/glue/backdrop.rs
+++ b/crates/benilla-app/src/glue/backdrop.rs
@@ -1,15 +1,12 @@
-//! WoW `Backdrop`s, at the geometry the client itself uses (`0x77e8d0`, `0x77f0c0`;
-//! decision 0543): the `edgeFile` strip split into its eight upright pieces
-//! ([`split_backdrop_edges`] — the un-rotation law), the eight-piece border rig
-//! ([`backdrop_border`]) seated to its frame's laid-out size by [`fit_backdrop_borders`], and the
-//! tiled backdrop bg ([`tiled_bg_node`]). Split out of [`super::art`] (which loads the pieces and
-//! owns every other glue texture): this file is the backdrop *mechanism*, art is the *inventory*.
+//! FrameXML `Backdrop`s at the reference's geometry (`0x77e8d0`, `0x77f0c0`): the `edgeFile`
+//! strip split into eight upright pieces, the border rig fitted to its frame's laid-out size, and
+//! the tiled background.
 
 use bevy::prelude::*;
 
 use benilla_assets::{sprite_image, sprite_image_tiled, WorldAssets};
 
-/// `UI-Tooltip-Background`'s native size (the tile-period → `stretch_value` conversion).
+/// `UI-Tooltip-Background`'s native size, converting a tile period to a `stretch_value`.
 const TOOLTIP_BG_NATIVE: f32 = 64.0;
 
 // ── WoW backdrops ────────────────────────────────────────────────────────────────────────────────
@@ -27,14 +24,11 @@ pub(crate) struct BackdropEdges {
     pub(crate) br: Handle<Image>,
 }
 
-/// Split a WoW `edgeFile` strip into its eight upright `e`×`e` pieces, in the returned order
-/// LEFT, RIGHT, TOP, BOTTOM, TOPLEFT, TOPRIGHT, BOTTOMLEFT, BOTTOMRIGHT — the strip's own order
-/// (read from the client's UV constants in `0x77e8d0`/`0x77f0c0`; independently confirmed here
-/// by reading the shapes out of `Glue-Tooltip-Border`'s pixels).
+/// Split an `edgeFile` strip into its eight upright `e`×`e` pieces, in the strip's order: left,
+/// right, top, bottom, top-left, top-right, bottom-left, bottom-right (`0x77e8d0`, `0x77f0c0`).
 ///
-/// TOP and BOTTOM are stored **rotated 90°** in the strip — the client maps atlas-u to screen-Y
-/// and atlas-v to screen-X reversed — so they are un-rotated here and every piece draws with plain
-/// upright UVs: the TOP cell reads texel `(2e+y, e−1−x)`, the BOTTOM cell `(3e+y, e−1−x)`.
+/// Top and bottom are stored rotated 90° (the reference maps atlas u to screen y and v to screen x
+/// reversed), so they are un-rotated here: top reads texel `(2e+y, e−1−x)`, bottom `(3e+y, e−1−x)`.
 pub(crate) fn split_backdrop_edges(e: usize, strip: &[u8]) -> [Vec<u8>; 8] {
     let src = |x: usize, y: usize| {
         let i = (y * 8 * e + x) * 4;
@@ -60,7 +54,7 @@ pub(crate) fn split_backdrop_edges(e: usize, strip: &[u8]) -> [Vec<u8>; 8] {
     cells
 }
 
-/// Load one edge file and split it ([`split_backdrop_edges`]); the cell size is the strip's height.
+/// Load one edge file and split it; the cell size is the strip's height.
 pub(super) fn backdrop_edges(
     assets: &mut WorldAssets,
     path: &str,
@@ -73,8 +67,8 @@ pub(super) fn backdrop_edges(
         return None;
     }
     let [left, right, top, bottom, tl, tr, bl, br] = split_backdrop_edges(e, &rgba);
-    // The four runs tile, so they must WRAP; the corners map [0,1] exactly once, so they clamp
-    // (a repeat-sampled corner bleeds its opposite edge in under linear filtering).
+    // The runs tile, so they wrap; the corners clamp, since a repeat-sampled corner bleeds its
+    // opposite edge in under linear filtering.
     let mut run = |px: Vec<u8>| images.add(sprite_image_tiled(h, h, px));
     let (left, right, top, bottom) = (run(left), run(right), run(top), run(bottom));
     let mut corner = |px: Vec<u8>| images.add(sprite_image(h, h, px));
@@ -90,20 +84,12 @@ pub(super) fn backdrop_edges(
     })
 }
 
-/// A `Backdrop`'s border, at the geometry the client itself uses (`0x77e8d0`): the border sits
-/// **inside** the frame rect, flush with its edges — corner squares of exactly `e`×`e` at the
-/// four corners, edge strips spanning between them and **tiling** at period `e` (the run math
-/// `side/e − 2` has no upper clamp, so edges never stretch). Eight
-/// pieces on a full-bleed rig child of the frame node, one per authored piece — the client's own
-/// eight `CSimpleTexture`s — seated to the frame's **laid-out** size by [`fit_backdrop_borders`],
-/// so content-sized frames and window rescales stay correct without a spawn-time size.
+/// A `Backdrop`'s border (`0x77e8d0`): inside the frame rect, `e`×`e` corners, and edges between
+/// them that tile at period `e` and never stretch. Eight pieces, as the reference's eight
+/// `CSimpleTexture`s, on a full-bleed rig that [`fit_backdrop_borders`] fits after layout.
 ///
-/// Deliberately **not** Bevy's `TextureSlicer`: its corner scale is
-/// `min(render_size / texture_size, max_corner_scale)`, so feeding it a 3·`e`-tall nine-patch atlas
-/// silently shrank the entire border on any frame shorter than 3·`e`. A 37-tall edit box drew its
-/// 16-unit border at 12.3 — pulling the art clear of the authored `BackgroundInsets`, which are
-/// cut so the fill butts against each edge's bright line, and leaving the scene showing bare
-/// between frame and fill (decision 0543).
+/// Not Bevy's `TextureSlicer`: it shrinks the corners on a frame shorter than 3·`e`, pulling the
+/// border off the authored `BackgroundInsets`.
 pub(crate) fn backdrop_border(
     b: &mut ChildSpawnerCommands,
     edges: &BackdropEdges,
@@ -142,7 +128,7 @@ pub(crate) fn backdrop_border(
                     color,
                     ..default()
                 },
-                // Zero-size until the first fit — nothing shows on the pre-layout frame.
+                // Zero-size until the first fit: nothing shows on the pre-layout frame.
                 Node {
                     position_type: PositionType::Absolute,
                     width: Val::Px(0.0),
@@ -154,17 +140,16 @@ pub(crate) fn backdrop_border(
     });
 }
 
-/// The full-bleed child a [`backdrop_border`] hangs its pieces on: its `ComputedNode` reads the
-/// frame's laid-out size, which is what the pieces are fitted to.
+/// The full-bleed child a [`backdrop_border`] hangs its pieces on; its `ComputedNode` is the
+/// frame's laid-out size.
 #[derive(Component)]
 pub(crate) struct BackdropRig {
     /// The authored `edgeSize`.
     e: f32,
-    /// The (physical size, screen scale) last fitted — skip settled frames.
+    /// The (physical size, screen scale) last fitted, so a settled frame is skipped.
     fitted: (Vec2, f32),
 }
 
-/// Which of the eight authored pieces a rig child draws.
 #[derive(Component, Clone, Copy)]
 pub(crate) enum BackdropPiece {
     Tl,
@@ -177,19 +162,12 @@ pub(crate) enum BackdropPiece {
     Bottom,
 }
 
-/// Seat every [`backdrop_border`]'s eight pieces to its frame's **laid-out** size, re-fitting
-/// whenever the frame or the glue scale changes — so a content-sized frame (the dialogs, which the
-/// ref itself resizes to fit their text) and a window resize both keep a correct border, where a
-/// spawn-time bake could only guess.
+/// Fit every [`backdrop_border`]'s pieces to its frame's laid-out size, again whenever the frame
+/// or the glue scale changes (the dialogs resize to their text).
 ///
-/// Every shared edge is ONE integer of physical pixels, and every piece is placed by
-/// left/top/width/height off that same integer grid — never by a `right`/`bottom` anchor. Bevy
-/// rounds a node's position and its size to physical pixels *independently*, so two pieces meeting
-/// at a fractional coordinate round apart and the seam shows: a 1 px transparent slit at one end
-/// (bare scene through the frame) and a 1 px overlap at the other, where the semi-transparent edge
-/// art composites twice and reads visibly darker. Snapping the shared numbers first makes that
-/// rounding a no-op. Only the frame's OUTER edges keep the fractional remainder, where there is no
-/// neighbour to disagree with.
+/// Every shared edge is one integer of physical pixels and every piece is placed by
+/// left/top/width/height, never a `right`/`bottom` anchor: Bevy rounds position and size
+/// separately, so pieces meeting at a fractional coordinate leave a 1 px slit or a darker overlap.
 pub(crate) fn fit_backdrop_borders(
     window: Query<&Window, With<bevy::window::PrimaryWindow>>,
     mut rigs: Query<(&mut BackdropRig, &ComputedNode, &Children)>,
@@ -205,8 +183,8 @@ pub(crate) fn fit_backdrop_borders(
         let inv = computed.inverse_scale_factor;
         let edge = (rig.e * s / inv).round().max(1.0);
         let (bw, bh) = (size.x.round(), size.y.round());
-        // The client clamps each run to zero when the frame is too small for its two corners
-        // (`side/e − 2`, floored at 0) — the corners then simply overlap, as they do there.
+        // The reference floors each run at zero (`side/e − 2`), so on a small frame the corners
+        // overlap.
         let run_w = (bw - 2.0 * edge).max(0.0);
         let run_h = (bh - 2.0 * edge).max(0.0);
         // A run tiles along its own axis and maps 1:1 across its `e`-thick side; the period
@@ -230,7 +208,7 @@ pub(crate) fn fit_backdrop_borders(
                 BackdropPiece::Top => (edge, 0.0, run_w, edge, run(true)),
                 BackdropPiece::Bottom => (edge, bh - edge, run_w, edge, run(true)),
             };
-            // Physical → logical for `Val::Px`; ×scale-factor at layout restores the integers.
+            // Physical to logical for `Val::Px`; the scale factor at layout restores the integers.
             node.left = Val::Px(x * inv);
             node.top = Val::Px(y * inv);
             node.width = Val::Px(w * inv);
@@ -240,8 +218,7 @@ pub(crate) fn fit_backdrop_borders(
     }
 }
 
-/// The tiled backdrop bg (`UI-Tooltip-Background`) behind a bordered box, at the authored
-/// `tileSize` period, faction-tinted by the caller (the texture's own alpha rides along).
+/// The tiled `UI-Tooltip-Background` behind a bordered box, at the authored `tileSize` period.
 pub(crate) fn tiled_bg_node(sheet: Handle<Image>, period: f32, s: f32, color: Color) -> ImageNode {
     ImageNode {
         image: sheet,
@@ -259,8 +236,7 @@ pub(crate) fn tiled_bg_node(sheet: Handle<Image>, period: f32, s: f32, color: Co
 mod tests {
     use super::*;
 
-    // The split against the backdrop UV law (`0x77f0c0`): an e=2 strip with
-    // pixel (x,y) = (x, y) in the r/g channels, so every copied texel is assertable by coordinates.
+    // An e=2 strip holding each pixel's (x, y) in r/g, so every copied texel names its source.
     #[test]
     fn backdrop_split_follows_the_edgefile_law() {
         let e = 2usize;
@@ -289,14 +265,13 @@ mod tests {
         assert_eq!(at(5, 0, 0), (10, 0)); // TOPRIGHT    ← slice 5
         assert_eq!(at(6, 0, 0), (12, 0)); // BOTTOMLEFT  ← slice 6
         assert_eq!(at(7, 0, 0), (14, 0)); // BOTTOMRIGHT ← slice 7
-                                          // TOP ← slice 2 (x 4..6), UN-ROTATED: dst(x,y) = src(2e+y, e-1-x).
+                                          // TOP ← slice 2, un-rotated: dst(x,y) = src(2e+y, e-1-x).
         assert_eq!(at(2, 0, 0), (4, 1)); // dst(0,0) ← src(4, 1)
         assert_eq!(at(2, 1, 0), (4, 0)); // dst(1,0) ← src(4, 0)
         assert_eq!(at(2, 0, 1), (5, 1)); // dst(0,1) ← src(5, 1)
                                          // BOTTOM ← slice 3 (x 6..8), same un-rotation.
         assert_eq!(at(3, 0, 0), (6, 1));
         assert_eq!(at(3, 1, 1), (7, 0));
-        // Every piece is exactly one e×e cell — nothing is stretched or padded.
         assert!(cells.iter().all(|c| c.len() == e * e * 4));
     }
 }
diff --git a/crates/benilla-app/src/glue/dialog.rs b/crates/benilla-app/src/glue/dialog.rs
index 05cf4202..1099b5d7 100644
--- a/crates/benilla-app/src/glue/dialog.rs
+++ b/crates/benilla-app/src/glue/dialog.rs
@@ -1,31 +1,13 @@
-//! **The glue layer's one dialog** — the reference's shared `GlueDialog`.
+//! The glue layer's one dialog, the reference's shared `GlueDialog`: a `GlueParent` child that
+//! every glue screen raises over itself.
 //!
-//! `GlueDialog.xml` is a `GlueParent` child, not a screen: `GlueDialog_Show` texts it, sizes it to
-//! its content and `Show()`s it over whichever glue screen happens to be up, and every screen
-//! raises the same frame through `OPEN_STATUS_DIALOG`. The realm list is built the same way and
-//! for the same reason (2072).
+//! This module owns the widget: tree, text, which key answers which button, the click sound. What
+//! a press means belongs to the screen that opened it, so a press is published as
+//! [`GlueDialogAnswer`]; only [`DialogKind::Error`] is dismissed here, by its Okay.
 //!
-//! Ours lived inside [`crate::login`] until 2084, because the login screen was the only thing that
-//! had ever needed one. That stopped being true when a refused *character* login had to be said on
-//! the select screen (2071): the choice was a second copy of the widget over there, or this — the
-//! move `crate::glue`'s own charter asks for, so "what the screens share" cannot fork.
-//!
-//! **The split, and where the line is.** This module owns the *widget*: the tree, the text, the
-//! spawn/despawn, which key answers which button, the click sound. It does not own what a press
-//! *means* — a realmlist Okay that refuses a bad address and stays open, a status Cancel that
-//! abandons a login attempt in flight. Those belong to the screen that opened the dialog, so a
-//! press is published as [`GlueDialogAnswer`] and answered by [`crate::login::answer_dialog`].
-//! The one exception is [`DialogKind::Error`], whose entire behaviour is "say a thing, and its
-//! Okay dismisses it" — [`drive_glue_dialog`] ends those itself, which is what lets a screen raise
-//! one without also writing its ending.
-//!
-//! [`drive_glue_dialog`] runs inside **each screen's own chain** rather than being hoisted out
-//! with a `before`/`after` pair. That is not a style choice: the shared painters
-//! ([`crate::glue::art_swaps`] and friends) sit in those chains, and ordering this both after a
-//! screen's input and before those painters from outside makes a painter transitively ordered
-//! against its own `SystemTypeSet`, which Bevy rejects at schedule build. It panics at boot, and
-//! no unit test can see it (2071).
-
+//! [`drive_glue_dialog`] runs inside each screen's own chain, not hoisted out with a
+//! `before`/`after` pair: ordering it from outside against the shared painters in those chains
+//! makes a painter ordered against its own `SystemTypeSet`, which panics at schedule build.
 use bevy::prelude::*;
 
 use benilla_ui::widget::EditBoxState;
@@ -41,25 +23,19 @@ use crate::sound::GlueSound;
 
 use crate::char_select::wow_font;
 
-/// `DEFAULT_TOOLTIP_COLOR` (AccountLogin.lua): the edit box's backdrop tint (border rgb, bg rgb) —
-/// the login screen's own boxes, so the realmlist editor matches the two behind it.
+/// `DEFAULT_TOOLTIP_COLOR` (AccountLogin.lua), the login boxes' border and fill tint.
 const BOX_BORDER: Color = Color::srgb(0.8, 0.8, 0.8);
 const BOX_FILL: Color = Color::srgb(0.09, 0.09, 0.09);
 
-/// The dialog's two buttons — the ref's `GlueDialogButton1`/`GlueDialogButton2`. Its own
-/// component rather than a variant of any screen's action enum: the buttons belong to the widget,
-/// and the widget belongs to no screen.
+/// The dialog's two buttons, `GlueDialogButton1` and `GlueDialogButton2`.
 #[derive(Component, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum GlueDialogAction {
-    /// The affirmative one — Cancel on the status dialog, Okay on the others.
+    /// The affirmative one: Cancel on the status dialog, Okay on the others.
     Button1,
-    /// The second, on the kinds that declare one (Cancel on the realmlist editor).
     Button2,
 }
 
-/// A button was pressed on the dialog, for the screen that opened it to answer. Carries both
-/// flags rather than one enum because the realmlist editor's ESCAPE answers *button 2*, and
-/// nothing but the kind's own table knows that.
+/// A button was pressed on the dialog, for the screen that opened it to answer.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct GlueDialogAnswer {
     pub(crate) kind: DialogKind,
@@ -67,38 +43,29 @@ pub(crate) struct GlueDialogAnswer {
     pub(crate) button2: bool,
 }
 
-/// Which dialog is up: the connecting status (Cancel button, text driven by the stages), an
-/// error (Okay button), or the realmlist editor (Okay + Cancel over an edit box).
+/// Which dialog is up.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum DialogKind {
     Status,
     Error,
-    /// **Queued for a full realm** (decision 1681). The reference has no queue dialog *type*: it
-    /// opens the ordinary `CANCEL` status dialog and re-texts it every frame, relabelling the one
-    /// button to `CHANGE_REALM`. This is that, as a kind — the relabel is the only thing that
-    /// distinguishes it from [`Self::Status`], and a kind is how this screen spells "different
-    /// button caption".
+    /// Queued for a full realm: the reference re-texts the `CANCEL` status dialog every frame
+    /// and relabels its button `CHANGE_REALM`.
     Queued,
-    /// The realmlist editor (decision 1667) — the reference's `GlueDialog` `hasEditBox` shape,
-    /// which is how the shipped dialog asks for a typed value (`GlueDialog.lua`: it shows
-    /// `GlueDialogEditBox` and re-heights the box to
-    /// `16 + text + 8 + editbox + 8 + button + 16`). The reference never opens this particular
-    /// dialog — it has no realmlist UI at all — but the widget is its own.
+    /// The realmlist editor, on the reference's `hasEditBox` dialog shape (`GlueDialog.lua`). The
+    /// 1.12 client has no realmlist dialog.
     Realmlist,
 }
 
 impl DialogKind {
-    /// Whether this dialog carries the ref's `GlueDialogEditBox` (its `hasEditBox` flag).
+    /// Whether this dialog shows `GlueDialogEditBox` (the `hasEditBox` flag).
     pub(crate) fn has_edit_box(self) -> bool {
         matches!(self, DialogKind::Realmlist)
     }
 
-    /// `(button1, button2)` captions — `GlueDialogTypes`' own two fields. A `None` second button
-    /// is the ref's centred single-button layout; `Some` is its BOTTOMRIGHT/LEFT pair.
+    /// `GlueDialogTypes`' `(button1, button2)` captions; no second button centres the first.
     pub(crate) fn buttons(self, strings: &GlueStrings) -> (&str, Option<&str>) {
         match self {
             DialogKind::Status => (strings.text("CANCEL", "Cancel"), None),
-            // The reference's own relabel: leaving a queue is "Change Realm", not "Cancel".
             DialogKind::Queued => (strings.text("CHANGE_REALM", "Change Realm"), None),
             DialogKind::Error => (strings.text("OKAY", "Okay"), None),
             DialogKind::Realmlist => (
@@ -109,32 +76,17 @@ impl DialogKind {
     }
 }
 
-/// Which of the dialog's two buttons a key press answers, as `(button1, button2)` — the keyboard
-/// half of [`drive_glue_dialog`]'s buttons; the mouse half is OR-ed in beside it. Button 1 is the
-/// affirmative one on every kind (Cancel on the status dialog, Okay on the others); button 2
-/// exists only where the kind declares it. ENTER confirms, ESCAPE dismisses; on a one-button
-/// dialog they are the same button.
+/// Which button a key press answers, as `(button1, button2)`: ENTER confirms, ESCAPE dismisses.
 ///
-/// **`on_screen` is the whole of the second bug fixed on 2026-08-29.** Pressing ENTER on an empty
-/// login form played the sound and showed nothing, while *clicking* Login showed the dialog
-/// (director's report). The two systems poll the same [`ButtonInput`]: [`login_input`] opened the
-/// error dialog on the ENTER edge, and [`drive_glue_dialog`] — later in the same chained frame, with
-/// `keys` untouched — read *the same* `just_pressed(Enter)` as that dialog's own Okay and closed
-/// it before it had ever been drawn. Both sounds played, which is exactly what was heard.
-///
-/// The reference cannot have this bug because it is event-driven: the ENTER that fires
-/// `AccountLogin_Login` is *dispatched* to the focused edit box (`OnEnterPressed`), and a dialog
-/// that does not exist yet is not in the dispatch. Polling is our seam, so the gate has to be
-/// ours too, and it says the same thing the dispatch does — **a dialog answers only keys pressed
-/// while it was already on screen**. Not "not this frame": on screen. It is passed the same
-/// `fresh` flag that drives the (re)spawn, so the two cannot drift apart.
+/// A dialog answers only keys pressed while it was already on screen: the reference dispatches
+/// the ENTER that opens a dialog to the focused edit box, but polling would read that same press
+/// as the new dialog's Okay. `on_screen` is the `!fresh` that drives the spawn.
 fn dialog_keys(kind: DialogKind, on_screen: bool, enter: bool, escape: bool) -> (bool, bool) {
     if !on_screen {
         return (false, false);
     }
     let button1 = match kind {
-        // The status dialog's one button IS Cancel, so ESCAPE is it. The queue's button is the
-        // same act under another name, so it answers to ESCAPE the same way.
+        // The status and queue dialogs' one button is Cancel, so ESCAPE is it.
         DialogKind::Status | DialogKind::Queued => escape,
         DialogKind::Error => escape || enter,
         DialogKind::Realmlist => enter,
@@ -142,45 +94,31 @@ fn dialog_keys(kind: DialogKind, on_screen: bool, enter: bool, escape: bool) ->
     (button1, kind == DialogKind::Realmlist && escape)
 }
 
-/// The glue layer's one dialog (the ref's shared `GlueDialog`): kind + text; the driver spawns/
-/// despawns the tree (respawning on a kind change — the button caption differs) and updates the
-/// text in place.
+/// The glue layer's one dialog, the reference's shared `GlueDialog`.
 #[derive(Resource, Default)]
 pub(crate) struct GlueDialog {
     pub(crate) kind: Option<DialogKind>,
     pub(crate) text: String,
     pub(crate) dirty: bool,
     pub(crate) root: Option<Entity>,
-    /// The ref's `GlueDialogEditBox` — a real [`EditBoxState`] like the two on the screen behind
-    /// it, so the realmlist box gets the same caret, selection, Ctrl+A and clipboard law
-    /// (decision 0704). Only meaningful while a [`DialogKind::has_edit_box`] dialog is up; it is
-    /// rebuilt from the current value on every open, so a cancelled edit leaves nothing behind.
+    /// `GlueDialogEditBox`, rebuilt on every open so a cancelled edit leaves nothing behind.
     pub(crate) edit: EditBoxState,
-    /// The queue's sample ring and the realm it is for — live only while [`DialogKind::Queued`]
-    /// is up, and rebuilt from empty on every fresh queue so a second login never inherits the
-    /// first one's estimate.
+    /// The queue's sample ring and realm, live while [`DialogKind::Queued`] is up.
     pub(crate) queue: crate::login::queue::QueueEstimate,
     pub(crate) queue_realm: Option<String>,
-    /// The kind the spawned tree was built for.
     spawned: Option<DialogKind>,
-    /// The glue scale the spawned tree was built at — a resize rebuilds it.
+    /// The glue scale the spawned tree was built at; a resize rebuilds it.
     spawned_s: f32,
 }
 
 impl GlueDialog {
     /// Raise the one-button error dialog over whichever glue screen is up.
-    ///
-    /// `pub(crate)` for the character-select screen: a refused *character* login
-    /// (`SMSG_CHARACTER_LOGIN_FAILED`) is said there, not here, and it is the same dialog — the
-    /// reference has exactly one, under `GlueParent`.
     pub(crate) fn open_error(&mut self, text: &str) {
         self.kind = Some(DialogKind::Error);
         self.set_text(text);
     }
 
-    /// Is a dialog up? The glue screens' modal test — while one is, the screen behind it does not
-    /// answer clicks or keys (the select screen's own delete confirm and AddOns panel are read the
-    /// same way).
+    /// The glue screens' modal test: while a dialog is up, the screen behind it takes no input.
     pub(crate) fn is_open(&self) -> bool {
         self.kind.is_some()
     }
@@ -189,23 +127,21 @@ impl GlueDialog {
         self.kind = Some(DialogKind::Status);
         self.set_text(text);
     }
-    /// Enter the queue: a fresh ring (a second login must not inherit the first one's estimate)
-    /// and the realm's name for the `_NAME` text variants.
+    /// Enter the queue with a fresh ring, so a second login never inherits the first's estimate;
+    /// `realm` feeds the `_NAME` text variants.
     pub(crate) fn open_queued(&mut self, realm: Option<String>) {
         self.kind = Some(DialogKind::Queued);
         self.queue = crate::login::queue::QueueEstimate::default();
         self.queue_realm = realm;
         self.set_text("");
     }
-    /// Open the realmlist editor over `current`, with the caret at the end of it and the whole
-    /// value selected — the reference's `hasEditBox` dialogs open ready to be typed over, and a
-    /// player changing servers is replacing the address far more often than editing it.
+    /// Open the realmlist editor over `current`, the whole value selected to be typed over.
     pub(crate) fn open_realmlist(&mut self, prompt: &str, current: &str) {
         self.kind = Some(DialogKind::Realmlist);
         self.edit = crate::textinput::field(crate::realmlist::MAX_LETTERS, false);
         self.edit.set_text(current);
-        // `HighlightText(0, -1)` — the client's own select-all (`0x77cca0`), which resets the
-        // blink on its way so the box opens on a solid caret.
+        // `HighlightText(0, -1)`, the reference's select-all (`0x77cca0`), also resets the blink
+        // so the box opens on a solid caret.
         self.edit.highlight_text(0, -1);
         self.set_text(prompt);
     }
@@ -215,9 +151,8 @@ impl GlueDialog {
             self.dirty = true;
         }
     }
-    /// Close **and take the tree down in the same frame** — what a button press does. Closing
-    /// alone would leave the spawned root standing until [`drive_glue_dialog`] next runs, and on
-    /// the edges out of the glue layer that is never.
+    /// Close and despawn the tree this frame: on the edges out of the glue layer,
+    /// [`drive_glue_dialog`] never runs again to take it down.
     pub(crate) fn dismiss(&mut self, commands: &mut Commands) {
         self.close();
         if let Some(root) = self.root.take() {
@@ -232,30 +167,20 @@ impl GlueDialog {
     }
 }
 
-/// The dialog's message text (updated in place on stage changes).
+/// The dialog's message text, updated in place.
 #[derive(Component)]
 pub(crate) struct DialogText;
-/// The dialog's edit box row items — the ref's `GlueDialogEditBox`, painted from
-/// [`GlueDialog::edit`] by [`refresh_dialog_box`].
+/// The dialog's `GlueDialogEditBox` parts, painted by [`refresh_dialog_box`].
 #[derive(Component, Clone)]
 pub(crate) struct DialogEditText;
 
-/// Build the dialog tree (the ref's shared `GlueDialog`): the 512-wide `UI-DialogBox` backdrop
-/// centered on the screen, the message (`GlueFontNormalLarge`, wrapping at 440), an optional edit
-/// box, and one or two `GlueDialogButtonTemplate` 200×40 buttons — Cancel for the connecting
-/// status, Okay for an error, Okay + Cancel over the box for the realmlist editor.
-/// Content-sized vertically (the ref's own `GlueDialog_OnShow` resize, by layout).
+/// Build the `GlueDialog` tree: a 512-wide `UI-DialogBox` backdrop, the message wrapping at 440,
+/// an optional edit box and one or two 200×40 buttons, sized to its content as
+/// `GlueDialog_OnShow` does: `16 + text + 8 + editbox + 8 + button + 16`. A button pair is
+/// centred with a 13 gap (Button1 BOTTOMRIGHT at the backdrop's BOTTOM (−6, 16)).
 ///
-/// The edit box and the second button are both the reference's own (`GlueDialog.lua`'s
-/// `hasEditBox` and `button2`); benilla simply had no dialog that used either until 1667. The two
-/// authored geometries they bring with them: the button pair is Button1 BOTTOMRIGHT ← the
-/// backdrop's BOTTOM at (−6, 16) with Button2 LEFT ← Button1's RIGHT at (13, 0) — a centred pair
-/// with a 13 gap — and the box re-heights the backdrop to
-/// `16 + text + 8 + editbox + 8 + button + 16`, which the column below is already shaped as.
-///
-/// **One stated divergence:** the ref's `GlueDialogEditBox` is 130×32, sized for the short values
-/// its own dialogs ask for. A realmlist is a hostname, so ours is 300 wide inside the same 512
-/// backdrop; the height, insets and border treatment are the login screen's boxes unchanged.
+/// Deviation: the edit box is 300 wide, not `GlueDialogEditBox`'s 130, because a realmlist is a
+/// hostname.
 pub(crate) fn spawn_dialog(
     commands: &mut Commands,
     art: &GlueArt,
@@ -310,10 +235,8 @@ pub(crate) fn spawn_dialog(
                         overlay(),
                     ));
                 }
-                // The message (GlueFontNormalLarge 18 at TOP (0,−16), width 440, wrapping) —
-                // **centred**, which `GlueDialogText` gets by omitting `justifyH` (a FontString's
-                // default is CENTER; every other wrapped glue string in the shipped XML asks for
-                // LEFT explicitly). It read left-aligned until the director's eye caught it.
+                // GlueFontNormalLarge 18, centred: `GlueDialogText` omits `justifyH`, and a
+                // FontString defaults to CENTER.
                 outlined_text_centered(
                     b,
                     Node {
@@ -332,7 +255,6 @@ pub(crate) fn spawn_dialog(
                     &font,
                     s,
                 );
-                // The edit box, on the kinds that declare one (`hasEditBox`).
                 if kind.has_edit_box() {
                     glue_edit_box(
                         b,
@@ -346,8 +268,7 @@ pub(crate) fn spawn_dialog(
                         s,
                     );
                 }
-                // The buttons (GlueDialogButtonTemplate 200×40) — one centred, or the authored
-                // pair with its 13 gap.
+                // GlueDialogButtonTemplate 200×40: one centred, or the pair with its 13 gap.
                 b.spawn(Node {
                     flex_direction: FlexDirection::Row,
                     column_gap: px(13.0),
@@ -384,16 +305,7 @@ pub(crate) fn spawn_dialog(
         .id()
 }
 
-/// Spawn/despawn the dialog tree with the resource, keep its text current, and read its buttons
-/// from the mouse and the keyboard.
-///
-/// A press plays the click sound, publishes a [`GlueDialogAnswer`] for the screen that opened the
-/// dialog, and — for [`DialogKind::Error`] alone — dismisses it here, because that kind's whole
-/// behaviour *is* its dismissal. Everything else a press might mean belongs to the opener; see
-/// this module's header for where that line falls and why.
-///
-/// Runs inside each glue screen's own system chain (again: the header says why it cannot be
-/// hoisted out with an ordering pair).
+/// Keep the dialog tree in step with [`GlueDialog`] and read its buttons from mouse and keys.
 pub(crate) fn drive_glue_dialog(
     mut commands: Commands,
     mut dialog: ResMut<GlueDialog>,
@@ -419,12 +331,8 @@ pub(crate) fn drive_glue_dialog(
         return;
     };
 
-    // (Re)spawn on the open edge, a kind change (the button caption differs), or a window resize
-    // (the tree bakes the glue scale); a text-only change updates the message line in place.
-    //
-    // `fresh` is *this dialog appearing*, as opposed to a resize rebuilding a dialog already up —
-    // and it is the same flag [`dialog_keys`] takes as `!on_screen`, so the frame the dialog is
-    // drawn on and the frame it starts answering keys on are one decision, not two.
+    // Respawn on open, a kind change or a resize; a text change updates in place. `fresh` (the
+    // dialog appearing, not a resize) is also `dialog_keys`' `!on_screen`.
     let s = crate::glue::screen_scale(window.single().ok());
     let fresh = dialog.root.is_none() || dialog.spawned != Some(kind);
     if fresh || dialog.spawned_s != s {
@@ -453,8 +361,7 @@ pub(crate) fn drive_glue_dialog(
         dialog.dirty = false;
     }
 
-    // The buttons, from the mouse or the keys. A click needs no `fresh` guard of its own: the
-    // button it would hit did not exist to be clicked on the frame the tree spawned.
+    // A click needs no `fresh` guard: its button did not exist on the frame the tree spawned.
     let hit = |want: GlueDialogAction| buttons.iter().any(|(e, a)| *a == want && clicks.hit(e));
     let (key1, key2) = dialog_keys(
         kind,
@@ -465,39 +372,25 @@ pub(crate) fn drive_glue_dialog(
     let button1 = hit(GlueDialogAction::Button1) || key1;
     let button2 = hit(GlueDialogAction::Button2) || key2;
 
-    // **Every glue dialog button clicks** — `GlueDialog_OnClick` ends with
-    // `PlaySound("gsTitleOptionOK")` for button 1 and button 2 alike, whatever the dialog's type.
-    // Ours played nothing at all. Emitted here, once, before the kinds diverge, so no arm can
-    // forget it (and so the realmlist editor's Okay-that-refuses still clicks: the reference plays
-    // the sound on the press, not on the outcome).
+    // `GlueDialog_OnClick` plays `gsTitleOptionOK` for either button on every dialog type, on
+    // the press whatever its outcome.
     if button1 || button2 {
         sounds.write(GlueSound("gsTitleOptionOK"));
-        // **What a press MEANS belongs to whoever opened the dialog**, not to the widget. A
-        // realmlist Okay may refuse the typed value and stay open; a status Cancel has a login
-        // attempt to abandon. Both are the login screen's business, and neither is reachable from
-        // any other screen — so the press is published and [`crate::login::answer_dialog`]
-        // answers it.
         answers.write(GlueDialogAnswer {
             kind,
             button1,
             button2,
         });
-        // The one kind with no owner: an `Error` states a thing and its Okay dismisses it, which
-        // is the whole of its behaviour. Ending it here is what lets ANY glue screen raise one
-        // without also having to write its ending — the character-select screen's refused login
-        // (2071) raises an error and answers nothing.
+        // An error's Okay only dismisses it, so any glue screen can raise one and answer nothing.
         if kind == DialogKind::Error {
             dialog.dismiss(&mut commands);
         }
     }
 }
 
-/// Paint the dialog's edit box from [`GlueDialog::edit`], through the same
-/// [`paint_glue_field`] the two screen boxes use (decision 0704) — so the realmlist box gets the
-/// identical caret, selection highlight and scrolling.
+/// Paint the dialog's edit box from [`GlueDialog::edit`] through [`paint_glue_field`].
 ///
-/// Runs **after** [`drive_glue_dialog`], which is what spawns the box: on the frame a dialog
-/// opens the entities do not exist until that system has run, and painting before it would show
+/// Runs after [`drive_glue_dialog`], which spawns the box; before it, an opening dialog would show
 /// one frame of empty box.
 #[allow(clippy::type_complexity)]
 pub(crate) fn refresh_dialog_box(
@@ -513,9 +406,6 @@ pub(crate) fn refresh_dialog_box(
 mod tests {
     use super::*;
 
-    /// The dialog kinds' own shape: only the realmlist editor carries the ref's `hasEditBox`, and
-    /// only it declares a second button. The caret clock and the keyboard routing both branch on
-    /// the first of those, and `spawn_dialog` lays out from the second.
     #[test]
     fn only_the_realmlist_dialog_has_a_box_and_two_buttons() {
         let strings = GlueStrings::default();
@@ -530,11 +420,6 @@ mod tests {
         );
     }
 
-    /// **A dialog never answers the key press that opened it.** ENTER on an empty login form
-    /// opened the error dialog in `login_input` and then, later in the *same* frame with the same
-    /// `ButtonInput`, the driver read that identical `just_pressed(Enter)` as the dialog's own
-    /// Okay — so the popup appeared and vanished inside one frame and only the two sounds were
-    /// heard (director's report, 2026-08-29). The gate is being on screen, not a frame count.
     #[test]
     fn a_dialog_does_not_answer_the_key_that_opened_it() {
         // The frame it appears on: the key that opened it is not its answer.
@@ -553,9 +438,6 @@ mod tests {
         );
     }
 
-    /// Which key answers which button, per kind: ENTER and ESCAPE are the same (single) button on
-    /// an error dialog; ESCAPE alone works the Cancel-shaped ones; the two-button editor splits
-    /// them, ENTER to Okay and ESCAPE to Cancel.
     #[test]
     fn each_dialog_kind_maps_its_own_keys() {
         for (kind, enter, escape, want) in [
diff --git a/crates/benilla-app/src/glue/mod.rs b/crates/benilla-app/src/glue/mod.rs
index 1f05c1d2..41ad017c 100644
--- a/crates/benilla-app/src/glue/mod.rs
+++ b/crates/benilla-app/src/glue/mod.rs
@@ -1,9 +1,6 @@
-//! The shared glue-screen vocabulary (decision 0465) — everything the pre-world screens (character
-//! select + character create) draw with, factored out of the create screen when select joined it:
-//! the client-data art set ([`art::GlueArt`]), the widget builders ([`widgets`]), the ADD-mode UI
-//! material ([`add_material`]), and the screen-agnostic interaction systems below. Each screen
-//! keeps its own layout, actions, and selection policy; what lives here is exactly what the two
-//! share — so the vocabulary can never fork.
+//! What the pre-world glue screens share: the art set, the widget builders, the ADD-mode material,
+//! the one dialog and the screen-agnostic interaction systems. Each screen keeps its own layout,
+//! actions and selection.
 
 pub(crate) mod add_material;
 pub(crate) mod art;
@@ -18,25 +15,15 @@ use bevy::ui::FocusPolicy;
 use art::{tc_rect, GlueArt, BTN_BG, BTN_HOVER, BUTTON_TC, GOLD};
 use widgets::{ArtSwap, GlueBtn, GlueCaption, GlueDisabled, OutlineCopy};
 
-/// **The glue widgets' look, run once for every glue screen.**
+/// The glue widgets' look passes, registered once for every glue screen.
 ///
-/// These four passes are screen-agnostic by construction — they find their work by component, not
-/// by state — and every screen registering its own copy was a standing invitation to forget one.
-/// The realm list did exactly that: it shipped with `sync_outlines` and without
-/// [`glue_button_visuals`]/[`art_swaps`], so no button on it lit on hover, none took its pressed
-/// art, and the Okay it carefully marked [`GlueDisabled`] never greyed. Registered here, in
-/// [`GluePlugin`], a new screen gets them by existing.
-///
-/// A screen orders its own refresh **before** this set (`.before(GlueVisuals)`) so the disabled
-/// flags and captions it writes are rendered the same frame it writes them.
+/// A screen orders its own refresh `.before(GlueVisuals)` so the flags and captions it writes
+/// render the same frame.
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub(crate) struct GlueVisuals;
 
-/// The shared glue infrastructure both screens stand on: the ADD-mode UI material pipeline, the
-/// [`GlueArt`] resource (loaded on first screen entry), the GlueStrings table, and the one
-/// [`dialog::GlueDialog`] every glue screen raises. Registered before either screen plugin
-/// (`main.rs`) — which is also why the dialog's resource and message live here rather than in a
-/// screen: they outlive any single screen's plugin.
+/// The shared glue infrastructure: the ADD material pipeline, [`GlueArt`], the GlueStrings table
+/// and the one [`dialog::GlueDialog`]. Registered before any screen plugin.
 pub(crate) struct GluePlugin;
 
 impl Plugin for GluePlugin {
@@ -57,8 +44,8 @@ impl Plugin for GluePlugin {
                 Update,
                 (backdrop::fit_backdrop_borders, seat_outline_copies),
             )
-            // The chrome's canvas is the boxed scene (2091) — fitted before the layout that reads
-            // it, so a screen spawned this frame never lays out against the window first.
+            // Fitted before layout, so a screen spawned this frame never lays out against the
+            // window first.
             .add_systems(
                 PostUpdate,
                 fit_glue_canvas.before(bevy::ui::UiSystems::Layout),
@@ -70,42 +57,25 @@ impl Plugin for GluePlugin {
     }
 }
 
-/// The glue widgets whose click landed **this frame** — the reference's `OnClick`.
-///
-/// Ask this, never `Interaction::Pressed`, to run a button's action: pressing is not clicking (see
-/// [`glue_clicks`]). Rebuilt every frame in `PreUpdate`, so an `Update` reader sees exactly the
-/// current frame's clicks and a screen that did not run misses nothing it should have had.
+/// The glue widgets whose click landed this frame, the reference's `OnClick`. Ask this, never
+/// `Interaction::Pressed`: pressing is not clicking. Rebuilt every frame in `PreUpdate`.
 #[derive(Resource, Default)]
 pub(crate) struct GlueClicks(EntityHashSet);
 
 impl GlueClicks {
-    /// Did this widget's click land this frame?
     pub(crate) fn hit(&self, widget: Entity) -> bool {
         self.0.contains(&widget)
     }
 }
 
-/// The glue layer's click law: a button fires on the **release**, and only when the release lands
-/// back on the button that took the press.
+/// A glue button fires on the release, only when it lands back on the button that took the press.
 ///
-/// In the real 1.12.1 client, `CSimpleButton`'s ctor default click mask `[+0x330] = 0x100`
-/// (`0x7786d0`) is **`LeftButtonUp` alone**, so a stock `<Button>` — every glue button is one — is
-/// dispatched from the mouse-**up** dispatcher `0x7792d0`; the mouse-**down** dispatcher
-/// `0x779210` fires nothing a glue screen registers. Two more predicates ride the release: the
-/// button must be in state `[+0x328] == 2`
-/// (PUSHED — it took the press), and the release must **hit-test inside the frame** (`0x76b020`).
-/// So press-and-slide-off cancels, and press-off-slide-on does nothing — which is what a player
-/// expects of every button they have ever used. Our own in-game FrameXML path already implements
-/// exactly this (`benilla_ui::script::pointer`'s `same_frame` gate); the glue screens were the half
-/// that dispatched on the press edge, and every one of them moved here (1533).
-///
-/// Bevy's [`Interaction`] carries the same three states under other names, so the up edge is a
-/// state transition and needs no cursor maths: `ui_focus_system` sets `Pressed` only on the frame
-/// the press lands on a hovered node, holds it through a drag that leaves the node, and on release
-/// clears every `Pressed` back to `None` — after which the same run re-raises `Hovered` on whatever
-/// still contains the cursor. **`Pressed → Hovered` is therefore exactly "released inside"**, and
-/// `Pressed → None` exactly "released outside, or hidden mid-press". The `pushed` set is the ref's
-/// state byte.
+/// The reference's `CSimpleButton` click mask defaults to `0x100`, `LeftButtonUp` alone
+/// (`0x7786d0`), dispatched from the mouse-up handler `0x7792d0` (the mouse-down one, `0x779210`,
+/// fires nothing a glue screen registers); the button must be pushed
+/// (`[+0x328] == 2`) and the release must hit-test inside the frame (`0x76b020`). In Bevy's
+/// [`Interaction`], `Pressed → Hovered` is released inside and `Pressed → None` released outside
+/// or hidden mid-press; `pushed` is the reference's state byte.
 pub(crate) fn glue_clicks(
     interactions: Query<(Entity, &Interaction)>,
     mut pushed: Local<EntityHashSet>,
@@ -115,11 +85,10 @@ pub(crate) fn glue_clicks(
     pushed.retain(|&e| match interactions.get(e) {
         Ok((_, Interaction::Pressed)) => true, // still held
         Ok((_, Interaction::Hovered)) => {
-            clicks.0.insert(e); // released inside — the click
+            clicks.0.insert(e); // released inside: the click
             false
         }
-        // Released outside, hidden mid-press, or despawned: the press is simply dropped, as the
-        // ref drops one whose release fails the hit test.
+        // Released outside, hidden mid-press, or despawned: the press is dropped.
         _ => false,
     });
     for (e, interaction) in &interactions {
@@ -129,10 +98,8 @@ pub(crate) fn glue_clicks(
     }
 }
 
-/// Seat every outline copy at exactly ONE device pixel from its real string (`dir / scale_factor`
-/// logical) — the reference's baked 1-px dilation ring, reproduced as string geometry (see
-/// [`widgets::OutlineCopy`]). Runs every frame but writes only when the wanted value differs
-/// (fresh spawns, or the window moving to a display with another scale factor).
+/// Seat every outline copy one device pixel from its real string, the reference's baked 1 px
+/// outline ring; writes only on a change (a spawn, or a display with another scale factor).
 pub(crate) fn seat_outline_copies(
     window: Query<&Window, With<bevy::window::PrimaryWindow>>,
     mut copies: Query<(&OutlineCopy, &mut Node)>,
@@ -147,90 +114,49 @@ pub(crate) fn seat_outline_copies(
     }
 }
 
-/// The character-preview **drag rate**: the ref's `CHARACTER_ROTATION_CONSTANT = 0.6` degrees per
-/// **UI unit** (declared once in `CharacterSelect.lua` and read by both screens' `OnUpdate`; the
-/// facing setter takes degrees, deg→rad at the C boundary). Dragging right increases the facing.
-///
-/// It lives here for the reason this module exists: it is one number the two screens share, and it
-/// had already forked — the create screen carried a bare `0.01` rad/px, 4.5 % off its neighbour and
-/// off its own comment (1533). Apply it through [`drag_yaw`], never to a raw pixel delta.
+/// The preview drag rate, `CHARACTER_ROTATION_CONSTANT` (CharacterSelect.lua): 0.6 degrees per UI
+/// unit, dragging right increasing the facing. Apply it through [`drag_yaw`], never per pixel.
 pub(crate) const ROTATION_PER_UI_UNIT: f32 = 0.6 * std::f32::consts::PI / 180.0;
 
-/// The yaw a horizontal cursor move of `delta_px` **logical** pixels turns the preview by.
+/// The yaw a horizontal cursor move of `delta_px` logical pixels turns the preview by.
 ///
-/// `CHARACTER_ROTATION_CONSTANT` is per UI unit, not per pixel: `GetCursorPosition` (`0x46dad0`)
-/// answers on the glue engine's `aspect·768 × 768` virtual canvas, so the same physical drag turns
-/// the character *less* on a taller display — 0.6°/px only at a 768-line window, 0.427°/px at 1080p
-/// (1533). Feeding it the raw pixel delta ran the drag ~40 % fast at 1080p and made it scale with
-/// the window instead of with the canvas.
-///
-/// The divisor is the true `height / 768`, not [`screen_scale`]: that one is clamped at 2.2 so the
-/// *layout* stops growing on a very tall window, and the cursor's canvas has no such clamp.
+/// `GetCursorPosition` (`0x46dad0`) answers on the `aspect·768 × 768` virtual canvas, so a drag
+/// turns less on a taller window. The divisor is the true `height / 768`, not [`screen_scale`],
+/// whose 2.2 cap the cursor's canvas does not have.
 pub(crate) fn drag_yaw(delta_px: f32, window: Option<&Window>) -> f32 {
     let ui_per_px = 768.0 / window.map_or(768.0, |w| w.height().max(1.0));
     delta_px * ui_per_px * ROTATION_PER_UI_UNIT
 }
 
-/// The rotate buttons' **hold rate** — the ref's `CHARACTER_FACING_INCREMENT = 2`, applied per
-/// `OnUpdate` tick by both screens' `RotateLeft/Right_OnUpdate`. Ours is per *second* at the ref's
-/// 60 fps, so the arrow turns at one speed instead of at the frame rate (`docs/METHOD.md` step 3: the
-/// mechanism, not the quirk).
+/// The rotate buttons' hold rate: the reference's `CHARACTER_FACING_INCREMENT = 2` degrees per
+/// `OnUpdate` tick, taken per second at 60 fps, so the turn speed does not follow the frame rate.
 pub(crate) const ROTATE_RATE: f32 = 120.0 * std::f32::consts::PI / 180.0;
 
-/// The glue engine's virtual-screen scale: the ref lays every glue screen out on a 1024×768
-/// virtual screen stretched to the window, so each authored coordinate draws at `value · this`.
-/// The ONE copy of the formula — every glue spawn site and every rescale check reads it here, and
-/// each screen's lifecycle system compares its tree's baked scale against this to know when a
-/// window resize (mac fullscreen, a drag) has invalidated the tree.
+/// The glue virtual-screen scale: the reference lays glue screens out 768 units tall, scaled by
+/// the window height, so an authored coordinate draws at `value · this`. Every spawn site and
+/// rescale check reads it here.
 ///
-/// **There is no lower clamp** (B120). A floor of 1.0 draws the 768-unit-tall authored layout into a
-/// shorter window and the overflow simply falls off the bottom — silently, and always the
-/// *bottom-most* controls: on the create screen that is the last customization row and the
-/// **RANDOMIZE** button (reproduced at `WOW_WIN=1276x677` — both gone, along with the foot of the
-/// right-hand race/class panels). The reference has no such floor: its glue screens are authored in
-/// the 768-tall virtual space and scaled by the window height, so a short window makes everything
-/// smaller and nothing missing. The upper clamp stays — that is the shipped size on a tall screen,
-/// and lifting it would resize the director's UI without being asked.
+/// No lower clamp: a floor would push the bottom controls off a short window. Capped at 2.2 on a
+/// tall window; whether the reference caps its glue scale is untraced.
 pub(crate) fn screen_scale(window: Option<&Window>) -> f32 {
     window.map(|w| (w.height() / 768.0).min(2.2)).unwrap_or(1.0)
 }
 
-/// **The rect a glue screen's chrome lays out into: the boxed scene, never the window** (decision
-/// 2091, B377).
+/// The rect a glue screen's chrome lays out into: the pillarboxed scene's box, not the window, as
+/// a reference client of the box's aspect would lay it out.
 ///
-/// [`screen_scale`] answers *how big* an authored coordinate draws; this answers *what it is
-/// measured from*. The two are not the same question once the scene is pillarboxed (decision
-/// 1619): past the aspect its art can fill, the booth camera renders into a centred box with black
-/// bars either side, and a chrome node anchored `right: 0` against the *window* lands out in the
-/// bar — the logo, the version line, Realmlist/Quit, the character list and Delete/Back all did, at
-/// 21:9 (3440×1440). 1619 wrote that residue down and left it; this is the
-/// answer. Anchor the chrome to the **box** — the window's height, the box's width — and the glue
-/// canvas is exactly what a reference client of the box's own aspect would lay out on, which is
-/// what a 1.12 client on a 21:9 monitor looks like: a 16:9 client, centred by the monitor,
-/// everything inside it.
-///
-/// The screen's root stays full-window: the black bars are the booth camera's own *output* clear
-/// inside a window-sized render target (1619 §3), so the full-bleed scene pane that samples that
-/// target must keep covering the window. Only the chrome moves in.
+/// The screen's root stays full-window: the bars are the booth camera's clear inside a
+/// window-sized target, which the full-bleed scene pane must keep covering.
 #[derive(Component)]
 pub(crate) struct GlueCanvas;
 
-/// The canvas node itself — full height, inset to the pillarbox's bars, sized by its own insets so
-/// it recentres itself. Spawn one under a screen's root and hang the chrome off it; the insets are
-/// kept current by [`fit_glue_canvas`] (which also fills them in on the spawn frame, before the
-/// first layout runs).
-///
-/// Spawn it as a sibling **after** the screen's full-bleed scene pane, so the chrome keeps drawing
-/// over the scene exactly as it did when it hung off the root.
+/// The canvas node: full height, sized by its insets, which [`fit_glue_canvas`] keeps current.
+/// Spawn it after the screen's full-bleed scene pane so the chrome draws over the scene.
 pub(crate) fn glue_canvas() -> (GlueCanvas, FocusPolicy, Node) {
     (
         GlueCanvas,
-        // **`Pass`, and it is load-bearing.** `ui_focus_system` treats a hovered node with no
-        // `FocusPolicy` as `Block` (`focus_policy.unwrap_or(&FocusPolicy::Block)`) and stops the
-        // walk there — so a canvas spanning the whole box would swallow every hover and press
-        // before they reached the full-bleed scene pane beneath it, and the select and create
-        // screens' drag-to-rotate would simply stop working. The canvas is a coordinate frame, not
-        // a surface: it passes everything its own chrome does not take.
+        // `Pass` is load-bearing: `ui_focus_system` treats no `FocusPolicy` as `Block`, and the
+        // canvas would swallow the scene pane's drag-to-rotate.
         FocusPolicy::Pass,
         Node {
             position_type: PositionType::Absolute,
@@ -243,12 +169,10 @@ pub(crate) fn glue_canvas() -> (GlueCanvas, FocusPolicy, Node) {
     )
 }
 
-/// Seat every [`GlueCanvas`] on the boxed scene's rect, every frame the bars change.
+/// Seat every [`GlueCanvas`] on the boxed scene's rect, writing only when the bars change.
 ///
-/// In `PostUpdate` **before** `UiSystems::Layout`, which is what keeps a screen spawned this frame
-/// from laying out once against the window and snapping in the next: the tree's commands have been
-/// applied by then, so a canvas born in `Update` is fitted before it is ever laid out. Writing
-/// only on change keeps it off Bevy's `Changed<Node>` path on the ~every frame nothing moves.
+/// Runs in `PostUpdate` before `UiSystems::Layout`, so a canvas spawned in `Update` is fitted
+/// before its first layout.
 pub(crate) fn fit_glue_canvas(
     window: Query<&Window, With<bevy::window::PrimaryWindow>>,
     mut canvases: Query<&mut Node, With<GlueCanvas>>,
@@ -256,10 +180,8 @@ pub(crate) fn fit_glue_canvas(
     if canvases.is_empty() {
         return;
     }
-    // Off the **window**, not off `CreateScene` (decision 2187): the frame is one aspect for every
-    // scene now, so the canvas has no reason to wait on the booth — which is what used to move it
-    // when a stage swap cleared the box for a frame, and what made a screen spawned before its
-    // scene lay out against the window once and snap in.
+    // Off the window, not `CreateScene`: the box is one aspect for every scene, so the canvas
+    // never waits on the booth.
     let window = window.single().ok();
     let (left, right) = crate::portrait::glue_canvas_bars(
         window,
@@ -274,9 +196,8 @@ pub(crate) fn fit_glue_canvas(
     }
 }
 
-/// Mirror every outlined text's content into its black copies ([`widgets::outlined_text`]) — the
-/// refresh systems write only the real text entity; the copies are its `OutlineCopy` siblings.
-/// Registered by each glue screen under its own state (the trees only exist there).
+/// Mirror every outlined text into its black `OutlineCopy` siblings; refresh systems write only
+/// the real text.
 #[allow(clippy::type_complexity)]
 pub(crate) fn sync_outlines(
     changed: Query<(&Text, &ChildOf), (Changed<Text>, Without<OutlineCopy>)>,
@@ -297,7 +218,7 @@ pub(crate) fn sync_outlines(
     }
 }
 
-/// Two-state button faces (spinner arrows, rotate buttons): pressed swaps to the down art.
+/// Two-state button faces (spinner arrows, rotate buttons): pressed shows the down art.
 pub(crate) fn art_swaps(
     mut swaps: Query<(&ArtSwap, &Interaction, &mut ImageNode), Without<GlueBtn>>,
 ) {
@@ -313,9 +234,8 @@ pub(crate) fn art_swaps(
     }
 }
 
-/// The glue-panel buttons' look: up/down/disabled art states + the caption whitening on hover (the
-/// ref's `HighlightFont`). Disabling is the screen's call — it toggles [`GlueDisabled`]; this pass
-/// only renders it (the ref's `Enable()`/`Disable()` split the same way).
+/// The glue-panel buttons' look: up, down and disabled art, and the caption whitening on hover
+/// (`HighlightFont`). A screen disables with [`GlueDisabled`]; this pass only renders it.
 #[allow(clippy::type_complexity)]
 pub(crate) fn glue_button_visuals(
     art: Res<GlueArt>,
@@ -361,11 +281,8 @@ pub(crate) fn glue_button_visuals(
         } else if fallback {
             bg.0 = if hovered { BTN_HOVER } else { BTN_BG };
         }
-        // DESCENDANTS, not children. The caption is a **grandchild's** child: `outlined_text`
-        // wraps every glue string in a layout wrapper + the −1px trim node before the real string,
-        // so a direct-children scan finds the wrapper and never the `GlueCaption` — which is why a
-        // disabled button's caption never grayed (1533). The walk is over a ~11-entity subtree;
-        // depth is the primitive's business, not this pass's.
+        // Descendants, not children: `outlined_text` nests the `GlueCaption` under a wrapper and
+        // a trim node.
         for child in children.iter_descendants(btn) {
             if let Ok(mut caption) = captions.get_mut(child) {
                 // The disabled caption grays (`GlueFontDisable`), hover whitens, rest is gold.
@@ -381,31 +298,18 @@ pub(crate) fn glue_button_visuals(
     }
 }
 
-/// What [`glue_hilights`] needs off a button to decide whether its sheen is lit: is the cursor on
-/// it, is it disabled, and is the screen holding it.
+/// What [`glue_hilights`] reads off a button: hover, disabled, and held lit.
 type SheenSource = (
     &'static Interaction,
     Option<&'static GlueDisabled>,
     Option<&'static widgets::LockHighlight>,
 );
 
-/// **Every button's highlight sheen, in one pass.** A [`widgets::Hilight`] lights while its owning
-/// [`Button`] is hovered — or while the screen holds it with [`widgets::LockHighlight`], the
-/// reference's own verb for a selected row.
+/// Every button's highlight sheen: a [`widgets::Hilight`] lights while its nearest enclosing
+/// [`Button`] is hovered or held by [`widgets::LockHighlight`], and never while disabled.
 ///
-/// There were **four** of these before, one per screen, and the realm list made five by having
-/// none: no button on it lit at all. Worse, the four had drifted — two folded selection into the
-/// same expression as hover, one folded in a scroll-position disable, and the one that lived
-/// inside [`glue_button_visuals`] was scoped `With<GlueBtn>, Without<ArtSwap>`, so the
-/// `GlueCloseButton` X on every panel in the client had a sheen that could never light. Splitting
-/// "is it lit?" (here) from "is it chosen?" (the screen's, as a `LockHighlight` flag) is what
-/// makes one owner possible.
-///
-/// **Walks UP, from each sheen to its nearest button** — not down from each button, which is the
-/// obvious shape and the wrong one: buttons nest. A modal dialog's own root is a `Button` (that is
-/// how it eats the clicks that miss its controls), so a descendant walk from there would light
-/// every sheen in the dialog at once. The nearest enclosing button is the one whose sheen it is,
-/// and there is exactly one of those.
+/// It walks up from each sheen, not down from each button: a modal dialog's root is itself a
+/// `Button`, so a walk down would light every sheen in the dialog.
 pub(crate) fn glue_hilights(
     mut hilights: Query<(Entity, &mut Visibility), With<widgets::Hilight>>,
     parents: Query<&ChildOf>,
@@ -442,9 +346,7 @@ mod tests {
     use bevy::prelude::*;
     use bevy::window::WindowResolution;
 
-    /// Drive one widget's [`Interaction`] through a press/release and read back whether the click
-    /// landed — the whole of the law in [`glue_clicks`], exercised the way `ui_focus_system` writes
-    /// it (see that function's doc for the three transitions).
+    /// Set one widget's [`Interaction`] as `ui_focus_system` would and read whether a click landed.
     fn click_run(app: &mut App, widget: Entity, interaction: Interaction) -> bool {
         *app.world_mut().get_mut::<Interaction>(widget).unwrap() = interaction;
         app.update();
@@ -459,9 +361,6 @@ mod tests {
         (app, widget)
     }
 
-    /// **A press is not a click.** The reference dispatches a stock `<Button>` from the mouse-UP
-    /// handler alone (ctor click mask `0x100` = `LeftButtonUp`), so the action must not fire while
-    /// the button is held — the whole glue layer used to fire here (1533).
     #[test]
     fn a_held_button_has_not_clicked_yet() {
         let (mut app, widget) = click_app();
@@ -479,7 +378,6 @@ mod tests {
         );
     }
 
-    /// The release **over the button that took the press** is the click, and it fires exactly once.
     #[test]
     fn the_release_over_the_button_is_the_click() {
         let (mut app, widget) = click_app();
@@ -494,10 +392,6 @@ mod tests {
         );
     }
 
-    /// Press, slide off, release: **no click**. The ref hit-tests the release inside the frame
-    /// (`0x76b020`) before firing, which is the escape hatch every player expects of a button they
-    /// pressed by mistake. Bevy leaves the node `Pressed` through the slide and drops it to `None`
-    /// on a release elsewhere, so the law reads it off the transition.
     #[test]
     fn sliding_off_before_the_release_cancels() {
         let (mut app, widget) = click_app();
@@ -513,7 +407,6 @@ mod tests {
         );
     }
 
-    /// A press that begins somewhere else and releases here is not this button's click.
     #[test]
     fn a_release_without_a_press_is_not_a_click() {
         let (mut app, widget) = click_app();
@@ -523,14 +416,6 @@ mod tests {
         );
     }
 
-    /// The caption whitens on hover and grays when disabled — the ref's `<HighlightFont>` /
-    /// `<DisabledFont>` on `GlueButtonTemplate`.
-    ///
-    /// The regression this pins is a *depth* bug, so the test builds the real depth:
-    /// [`super::widgets::outlined_text`] wraps every glue string in a layout wrapper and a −1px
-    /// trim node before the string itself, which put `GlueCaption` three levels under the button
-    /// while `glue_button_visuals` scanned the button's direct children. The sheen (a direct child)
-    /// lit on hover and the caption never moved off gold (1533).
     #[test]
     fn the_caption_whitens_on_hover_however_deep_the_outline_nests_it() {
         let mut app = App::new();
@@ -548,7 +433,7 @@ mod tests {
                 BackgroundColor::DEFAULT,
             ))
             .with_children(|btn| {
-                // wrapper → trim → the real string, exactly as `outlined_text` builds it.
+                // wrapper → trim → the real string, as `outlined_text` builds it.
                 btn.spawn(Node::default()).with_children(|wrapper| {
                     wrapper.spawn(Node::default()).with_children(|trim| {
                         caption = trim.spawn((GlueCaption, TextColor(GOLD))).id();
@@ -579,18 +464,11 @@ mod tests {
         assert_ne!(colour(&app), GOLD, "it grays (the ref's GlueFontDisable)");
     }
 
-    /// **The chrome canvas passes what it does not take** (decision 2091). `ui_focus_system`
-    /// reads a hovered node with no `FocusPolicy` as `Block` and stops the walk there, so a canvas
-    /// spanning the whole boxed scene would eat every hover and press before the full-bleed scene
-    /// pane under it saw one — and drag-to-rotate on the select and create screens would go dead
-    /// with nothing on screen to show for it. Pinned here because the failure is invisible to
-    /// every other check we run.
     #[test]
     fn the_chrome_canvas_never_swallows_the_scenes_drags() {
         let (_, policy, node) = glue_canvas();
         assert_eq!(policy, FocusPolicy::Pass);
-        // …and it is sized by its own four insets, so [`fit_glue_canvas`] can move it by writing
-        // two of them (a width would have to be recomputed, and could disagree with the camera).
+        // Sized by its four insets, so `fit_glue_canvas` moves it by writing two of them.
         assert_eq!(node.position_type, PositionType::Absolute);
         assert_eq!((node.width, node.height), (Val::Auto, Val::Auto));
         for inset in [node.left, node.right, node.top, node.bottom] {
@@ -598,14 +476,9 @@ mod tests {
         }
     }
 
-    /// The authored layout must FIT the window at every height — the B120 regression.
-    /// [`screen_scale`] is the only thing standing between a 768-unit-tall tree and a shorter
-    /// window, so a floor there silently amputates the bottom of every glue screen (the create
-    /// screen's RANDOMIZE button is authored at y 719..749 of 768).
     #[test]
     fn the_authored_layout_fits_any_window_height() {
-        /// Bottom edge of the create screen's lowest control (the RANDOMIZE button) in authored
-        /// units: the configuration tower's TOPLEFT y 74 + its 645 in-tower offset + 30 tall.
+        /// The RANDOMIZE button's bottom edge: the tower's TOPLEFT y 74, its 645 offset, 30 tall.
         const LOWEST_CONTROL: f32 = 74.0 + 645.0 + 30.0;
         for h in [480u32, 600, 677, 720, 768, 900, 1286, 2160] {
             let window = Window {
@@ -623,9 +496,7 @@ mod tests {
 
     // ── The sheen ────────────────────────────────────────────────────────────────────────────
 
-    /// Spawn `button > wrapper > sheen`, so the sheen is a **grand**child — the shape
-    /// `outlined_text` and every art overlay actually produce, and the one a direct-children scan
-    /// would miss.
+    /// Spawn `button > wrapper > sheen`, the grandchild shape the overlays make.
     fn sheen_app(disabled: bool, locked: bool) -> (App, Entity, Entity) {
         let mut app = App::new();
         app.add_systems(Update, glue_hilights);
@@ -648,7 +519,6 @@ mod tests {
         *app.world().get::<Visibility>(sheen).unwrap() == Visibility::Inherited
     }
 
-    /// Hover lights it, leaving darkens it — and it reaches a sheen nested below a wrapper.
     #[test]
     fn a_sheen_follows_its_nearest_button() {
         let (mut app, button, sheen) = sheen_app(false, false);
@@ -667,8 +537,6 @@ mod tests {
         );
     }
 
-    /// **`LockHighlight` holds it lit with the cursor elsewhere** — the reference's own verb, and
-    /// what lets a selected row stay marked without the screen touching `Visibility`.
     #[test]
     fn a_locked_sheen_stays_lit_unhovered() {
         let (mut app, _, sheen) = sheen_app(false, true);
@@ -676,9 +544,7 @@ mod tests {
         assert!(sheen_lit(&app, sheen));
     }
 
-    /// A disabled button lights for neither reason. The reference's `Disable()` takes the
-    /// highlight with it, and an offline realm row (or a scroll arrow at the end of its travel)
-    /// must not glow under the cursor.
+    /// The reference's `Disable()` takes the highlight with it.
     #[test]
     fn a_disabled_button_never_lights() {
         let (mut app, button, sheen) = sheen_app(true, true);
@@ -689,9 +555,6 @@ mod tests {
         assert!(!sheen_lit(&app, sheen), "and hovering does not revive it");
     }
 
-    /// **The walk stops at the nearest button.** A modal dialog's root is itself a `Button` (that
-    /// is how it eats the clicks that miss its controls), so hovering the dim must not light every
-    /// sheen inside it — which is exactly what a descendant walk from each button would do.
     #[test]
     fn an_outer_modal_button_does_not_light_the_sheens_inside_it() {
         let (mut app, button, sheen) = sheen_app(false, false);
diff --git a/crates/benilla-app/src/glue/widgets.rs b/crates/benilla-app/src/glue/widgets.rs
index 444bb9b3..da59b4bb 100644
--- a/crates/benilla-app/src/glue/widgets.rs
+++ b/crates/benilla-app/src/glue/widgets.rs
@@ -1,8 +1,6 @@
-//! The glue screens' reusable widget builders — the art button shapes of `GlueButtons.xml` /
-//! `CharacterCreate.xml` that each screen's layout places at its authored offsets — plus the
-//! widget-vocabulary marker components they spawn. Builders are generic over the screen's action
-//! component (`CreateAction`, `SelectAction`, …); each degrades to a plain-fill + text face
-//! without client art.
+//! The glue screens' widget builders (the button shapes of `GlueButtons.xml` and
+//! `CharacterCreate.xml`) and their marker components. Builders are generic over the screen's
+//! action component; each falls back to a plain face with text without client art.
 
 use benilla_ui::markup::{tokens, TokenKind};
 use benilla_ui::widget::EditBoxState;
@@ -15,64 +13,45 @@ use super::backdrop::{backdrop_border, tiled_bg_node};
 
 // ── The shared widget vocabulary ─────────────────────────────────────────────────────────────────
 
-/// A button's highlight overlay: the reference's `HighlightTexture`, lit while the cursor is on
-/// the button — or held lit by [`LockHighlight`].
-///
-/// **Its visibility belongs to [`super::glue_hilights`] and to nothing else.** It used to be "the
-/// owning screen's to drive", which is how four screens ended up with four hand-rolled hover
-/// loops, two of them subtly different, and how the realm list ended up with none at all — no
-/// sheen on any of its buttons, because nobody remembered to write the fifth.
+/// A button's `HighlightTexture`, lit on hover or by [`LockHighlight`]. Its visibility belongs to
+/// [`super::glue_hilights`] alone.
 #[derive(Component)]
 pub(crate) struct Hilight;
-/// **`Button:LockHighlight()`** — hold this button's [`Hilight`] lit whether or not the cursor is
-/// on it, which is how every glue list marks its selected row.
-///
-/// The reference's own verb, and the reason the sheen can have one owner: "lit" is
-/// `hovered || locked`, and a screen that knows which row is chosen says exactly that much and
-/// nothing about visibility.
+/// `Button:LockHighlight()`: hold this button's [`Hilight`] lit, as every glue list marks its
+/// selected row.
 #[derive(Component, Default)]
 pub(crate) struct LockHighlight(pub(crate) bool);
-/// A button spawned with a plain-fill face because client art is missing — the only buttons whose
-/// `BackgroundColor` a hover pass may shade (every `Node` carries one since Bevy 0.15's required
-/// components, so presence alone can't distinguish the fallback).
+/// A button with a plain-fill face for missing art, the only kind whose `BackgroundColor` a hover
+/// pass may shade (every `Node` carries one).
 #[derive(Component)]
 pub(crate) struct FallbackFace;
-/// An icon button's name label (the ref's `HighlightText`: visible on hover/selected — always,
-/// without icon art).
+/// An icon button's name label, the `HighlightText` shown on hover or selection.
 #[derive(Component)]
 pub(crate) struct HoverLabel;
-/// A glue-panel button (swaps up/down/disabled art; its caption whitens on hover).
+/// A glue-panel button.
 #[derive(Component)]
 pub(crate) struct GlueBtn;
-/// A glue-panel button's enabled state (the ref's `Enable()`/`Disable()`): the screen toggles it,
-/// [`super::glue_button_visuals`] renders it (disabled art, gray caption, no hover).
+/// A glue-panel button's `Enable()`/`Disable()` state: the screen toggles it,
+/// [`super::glue_button_visuals`] renders it.
 #[derive(Component, Default)]
 pub(crate) struct GlueDisabled(pub(crate) bool);
-/// A glue button's own authored `TexCoords` crop, where a template overrides the shared
-/// `GlueButtons.xml` region (`AddonListButtonTemplate` crops `0.025–0.535`). Read by
-/// [`super::glue_button_visuals`] in place of [`BUTTON_TC`].
+/// A template's own `TexCoords` crop, used in place of [`BUTTON_TC`].
 #[derive(Component, Clone, Copy)]
 pub(crate) struct BtnTexCoords(pub(crate) [f32; 4]);
-/// A glue button's caption (gold at rest, white on hover — the ref's `HighlightFont`).
+/// A glue button's caption: gold at rest, white on hover (`HighlightFont`).
 #[derive(Component)]
 pub(crate) struct GlueCaption;
-/// A two-state button face (spinner arrows, rotate): pressed swaps `up` → `down`.
+/// A two-state button face (spinner arrows, rotate): pressed shows `down`.
 #[derive(Component)]
 pub(crate) struct ArtSwap {
     pub(crate) up: Handle<Image>,
     pub(crate) down: Handle<Image>,
 }
-/// One of an outlined text's black copies ([`outlined_text`]) — content mirrored from its real
-/// sibling by [`super::sync_outlines`]; `dir` is its unit offset direction, seated to exactly one
-/// DEVICE pixel by [`super::seat_outline_copies`].
+/// One of an outlined text's eight black copies; `dir` is its offset direction.
 ///
-/// The reference's `outline="NORMAL"` is not string geometry at all: the ring is **baked into the
-/// glyph atlas cell by one 8-neighbour dilation pass at rasterization** (`0x5ce440`/`0x5cea30`) —
-/// and the glyph rasterizes at final
-/// device-pixel size, so the ring is one device pixel hugging the glyph at every resolution
-/// (vanilla's famously thin outlines at high res). Offsetting copies by an authored *unit*
-/// instead put the ring 2–3 device px out at fullscreen scales, where it read as a separate
-/// doubled stroke (director's report, 2026-07-19).
+/// The reference's `outline="NORMAL"` is one 8-neighbour dilation baked into the glyph at its
+/// device-pixel size (`0x5ce440`, `0x5cea30`), so the ring is one device pixel at every resolution,
+/// never one UI unit.
 #[derive(Component)]
 pub(crate) struct OutlineCopy {
     pub(crate) dir: Vec2,
@@ -80,8 +59,7 @@ pub(crate) struct OutlineCopy {
 
 // ── Layout helpers ───────────────────────────────────────────────────────────────────────────────
 
-/// An absolutely-positioned node at the authored `(left, top, w, h)`, scaled by `s` — the shape of
-/// nearly every ref anchor once resolved to 1024×768 coordinates.
+/// An absolutely-positioned node at the authored `(left, top, w, h)`, scaled by `s`.
 pub(crate) fn abs(s: f32, left: f32, top: f32, w: f32, h: f32) -> Node {
     Node {
         position_type: PositionType::Absolute,
@@ -105,12 +83,8 @@ pub(crate) fn overlay() -> Node {
     }
 }
 
-/// A glue string's look, before the outline treatment: content, authored size, color, and whether
-/// it may wrap (the ref FontStrings never break a label; only the info paragraphs wrap).
-///
-/// `text` is **markup**, not a literal: its `|cAARRGGBB…|r` escapes decode to colour and `color`
-/// is the base they override ([`markup_spans`]). Every glue string goes through that decode
-/// because every `CSimpleFontString` in 5875 does.
+/// A glue string's look before the outline. `text` is markup, decoded as every
+/// `CSimpleFontString` decodes it, and `color` is the base its escapes override.
 pub(crate) struct GlueText<'a> {
     pub text: &'a str,
     pub size: f32,
@@ -118,15 +92,9 @@ pub(crate) struct GlueText<'a> {
     pub wrap: bool,
 }
 
-/// A glue text with the fonts' black outline (`outline="NORMAL"`, GlueFonts.xml — every glue font
-/// but the edit box carries it). Bevy text has no stroke, so the string draws nine times: eight
-/// black copies one DEVICE pixel out in the 8-neighbour directions (the ref's baked dilation ring
-/// — see [`OutlineCopy`]), then the real text — with the MasterFont (1,−1) drop shadow — painted
-/// last on top. `node` is the layout shape (position/margins/centering); an auto-sized inner box
-/// keeps the copies registered with the real string wherever `node` puts it. `wrapper_extra` rides
-/// the wrapper (visibility markers hide all nine at once); `text_extra` rides the real text (the
-/// markers the refresh writes — [`super::sync_outlines`] mirrors those writes into the copies).
-/// Returns the real text entity.
+/// A glue text with the glue fonts' `outline="NORMAL"` (GlueFonts.xml): eight black copies one
+/// device pixel out, then the real text with the MasterFont (1,−1) shadow on top.
+/// `wrapper_extra` rides the wrapper of all nine, `text_extra` the real text, which is returned.
 pub(crate) fn outlined_text<W: Bundle, T: Bundle>(
     parent: &mut ChildSpawnerCommands,
     node: Node,
@@ -150,18 +118,8 @@ pub(crate) fn outlined_text<W: Bundle, T: Bundle>(
     )
 }
 
-/// [`outlined_text`], **centred** — for a wrapped paragraph the reference centres.
-///
-/// A separate door rather than a field on [`GlueText`] because centring is the exception here, and
-/// naming it at the one call site that wants it is cheaper and clearer than a fifth field on
-/// thirty-three literals. The justification has to reach all nine strings (the eight outline copies
-/// share the layout), so it cannot be inserted onto the real text afterwards.
-///
-/// **Which way round is faithful is not obvious**, so: a `FontString` with no `justifyH` defaults
-/// to **CENTER**, and `GlueDialogText` (`GlueDialog.xml:56`) omits it — so the dialog is centred.
-/// Every *other* wrapped glue string in the shipped XML sets `justifyH="LEFT"` explicitly
-/// (`CharacterCreate.xml`'s race/class/faction bodies, `AddonList.xml`'s title/notes/deps), which
-/// is why [`outlined_text`] stays left and this is the exception rather than the default.
+/// [`outlined_text`], centred. A `FontString` with no `justifyH` is CENTER, and
+/// `GlueDialogText` omits it (`GlueDialog.xml:56`); every other wrapped glue string sets LEFT.
 pub(crate) fn outlined_text_centered<W: Bundle, T: Bundle>(
     parent: &mut ChildSpawnerCommands,
     node: Node,
@@ -185,29 +143,12 @@ pub(crate) fn outlined_text_centered<W: Bundle, T: Bundle>(
     )
 }
 
-/// Split a glue string into its coloured spans — WoW's `|cAARRGGBB…|r` inline markup, decoded by
-/// the reference's grammar ([`benilla_ui::markup`]) instead of drawn literally.
+/// Split a glue string into coloured spans by the `|c…|r` markup grammar ([`benilla_ui::markup`]).
+/// Every `CSimpleFontString` decodes it unconditionally (`0x5c2810`), so every glue string does.
 ///
-/// **This lives in the primitive on purpose.** It used to be one call site's private helper (the
-/// AddOns row title), which is exactly how the same `|cff0055FF…|r` came out coloured in a list
-/// row and literal in the tooltip an inch to its left (B273): a FontString property implemented
-/// per-caller is a property no caller reliably has. In the real client the decode is
-/// `CSimpleFontString`'s own and takes no opt-in — `0x5c2810` parses `|c`/`|r`/`|H`/`|h`/`||`
-/// unconditionally for every one of them (the flags word that could disable them has no writer
-/// anywhere in the image). So every `GlueText` decodes, and there is no way to spawn one that
-/// doesn't.
-///
-/// `base` is the string's own colour; an escape overrides it until `|r`, and the escape's alpha
-/// byte is discarded exactly as the client discards it (`0x5c2ab2`). Link escapes hide their
-/// payload and keep their visible text — the glue has no clickable links, so a `|H…|h` reads as
-/// its text. `||` draws one `|`.
-///
-/// A line break (`\n`, `|n`) follows the string's own `wrap`: a real break where the ref lets the
-/// string wrap (a tooltip paragraph), a space where it authored one line (a row title, a button
-/// caption) — the flag is our stand-in for the multi-line bit the client tests, and collapsing
-/// beats a label growing a second row inside a 20-unit slot.
-///
-/// Never empty: an empty string yields one empty span, so [`outlined_spans`] always has a root.
+/// An escape overrides `base` until `|r`, its alpha discarded (`0x5c2ab2`); a link keeps only its
+/// text; `||` draws one `|`. A line break is real when `wrap` is set and a space otherwise, `wrap`
+/// standing in for the multi-line flag the reference tests. An empty string yields one empty span.
 pub(crate) fn markup_spans(text: &str, base: Color, wrap: bool) -> Vec<(String, Color)> {
     let mut spans: Vec<(String, Color)> = Vec::new();
     let mut cur = String::new();
@@ -249,13 +190,8 @@ pub(crate) fn markup_spans(text: &str, base: Color, wrap: bool) -> Vec<(String,
     spans
 }
 
-/// [`outlined_text`]'s span-tree body — the decoded spans of [`markup_spans`] drawn as one string
-/// with the colour switching mid-run. The real text is Bevy's `Text` root + `TextSpan` children;
-/// the eight outline copies carry the flattened plain string, which is identical geometry because
-/// the copies only exist to be a black ring.
-///
-/// **Private**: [`outlined_text`] is the one door in, so no caller can hand-build spans and skip
-/// the markup decode (B273's shape — see [`markup_spans`]).
+/// [`outlined_text`]'s body: the real text as a `Text` root with `TextSpan` children, the outline
+/// copies as the flattened string. Private, so no caller skips the markup decode.
 fn outlined_spans<W: Bundle, T: Bundle>(
     parent: &mut ChildSpawnerCommands,
     node: Node,
@@ -268,9 +204,7 @@ fn outlined_spans<W: Bundle, T: Bundle>(
     font: &Handle<Font>,
     s: f32,
 ) -> Entity {
-    // Both fields set, so no `..default()` — `TextLayout` has exactly these two, and clippy's
-    // `needless_update` is right that spelling a rest-pattern here only hides the next field
-    // Bevy adds.
+    // Both fields set, so no `..default()` (clippy's `needless_update`).
     let layout = TextLayout {
         linebreak: if wrap {
             LineBreak::WordBoundary
@@ -289,17 +223,15 @@ fn outlined_spans<W: Bundle, T: Bundle>(
     parent
         .spawn((node, wrapper_extra))
         .with_children(|wrapper| {
-            // The −1px trim: our centered layout box sat the glyphs ~1px lower than the ref's
-            // baseline placement everywhere (director-measured); one optical correction here
-            // covers every glue string.
+            // The −1 px trim: a centred layout box sits the glyphs about 1 px below the
+            // reference's baseline placement.
             let trim = Node {
                 top: Val::Px(-s),
                 ..default()
             };
             wrapper.spawn(trim).with_children(|inner| {
-                // The 8-neighbour ring (see [`OutlineCopy`]) — seated to one device pixel by
-                // `seat_outline_copies`; the 0.5-logical spawn value is the retina guess for the
-                // one frame before that system runs.
+                // The 8-neighbour ring; `seat_outline_copies` sets it to one device pixel, and
+                // 0.5 logical covers the frame before it runs.
                 for dy in [-1.0, 0.0, 1.0] {
                     for dx in [-1.0, 0.0, 1.0] {
                         if dx == 0.0 && dy == 0.0 {
@@ -346,20 +278,12 @@ fn outlined_spans<W: Bundle, T: Bundle>(
     real
 }
 
-/// A 48² icon check-button (race/class/gender): the `IconShadow` behind, the icon face (dynamic —
-/// the owning screen assigns the sheet + rect — or fixed), a `ButtonHilight-Square` overlay lit on
-/// hover *and held while selected* (the ref's `LockHighlight`; the template's `CheckedTexture` is
-/// commented out in the shipped 1.12 GlueXML, so the locked square *is* the whole selected
-/// visual), and the name label along the bottom (the ref's `HighlightText`, `GlueFontNormalSmall`,
-/// anchored BOTTOM +1 — over the icon's bottom edge). `dyn_icon`/`label_dyn` are the screen's
-/// refresh markers, spawned onto the face / real label text.
+/// A 48² race/class/gender check-button: the `IconShadow`, the face, a `ButtonHilight-Square`
+/// lit on hover and locked while selected (the template's `CheckedTexture` is commented out), and
+/// the `HighlightText` name label at BOTTOM +1. `dyn_icon` and `label_dyn` are refresh markers.
 ///
-/// **It carries its own [`LockHighlight`]**, because the reference does: these are the
-/// `CheckButton`s that `SetCharacterRace`/`SetCharacterClass`/`SetCharacterGender` lock and
-/// unlock by hand (`CharacterCreate.lua` l.171/254/326). Leaving the flag to the screen is how
-/// the create screen lost every selected sheen *and* every icon name for ten days — 2072 added a
-/// `&mut LockHighlight` term to the screen's own visuals query and this spawn site had none, so
-/// the query matched nothing at all.
+/// It carries its own [`LockHighlight`]: `SetCharacterRace`/`Class`/`Gender` lock these by hand
+/// (`CharacterCreate.lua` l.171/254/326), and the screen's query needs the component present.
 pub(crate) fn icon_button<A: Component, I: Bundle, L: Bundle>(
     parent: &mut ChildSpawnerCommands,
     font: &Handle<Font>,
@@ -386,15 +310,15 @@ pub(crate) fn icon_button<A: Component, I: Bundle, L: Bundle>(
         b.insert((FallbackFace, BackgroundColor(BTN_BG))); // no art: the label is the button face
     }
     b.with_children(|b| {
-        // The shadow (64² centered, offset (2,−2)) — behind everything.
+        // The shadow: 64² centred, offset (2,−2), behind everything.
         if let Some(shadow) = &art.icon_shadow {
             b.spawn((
                 ImageNode::new(shadow.clone()),
                 abs(s, -6.0, -6.0, 64.0, 64.0),
             ));
         }
-        // The icon face: dynamic (transparent until the refresh assigns the sheet + rect — a
-        // default `ImageNode` is a white square) or fixed at spawn (gender halves).
+        // A dynamic face is transparent until the refresh assigns it, since a default
+        // `ImageNode` is a white square; the gender halves are fixed.
         let mut face = b.spawn((
             match &fixed {
                 Some((sheet, rect)) => ImageNode {
@@ -416,7 +340,6 @@ pub(crate) fn icon_button<A: Component, I: Bundle, L: Bundle>(
         if let Some(icon) = dyn_icon {
             face.insert(icon);
         }
-        // The ADD-mode overlays draw through the true-additive UI material (`add_material`).
         if let Some(hilight) = &art.hilight {
             b.spawn((
                 Hilight,
@@ -425,8 +348,7 @@ pub(crate) fn icon_button<A: Component, I: Bundle, L: Bundle>(
                 overlay(),
             ));
         }
-        // The name label: the wrapper carries the hover visibility (all five strings toggle
-        // together); the dynamic marker rides the real text for the refresh + outline sync.
+        // The wrapper carries the hover visibility, so all nine strings toggle together.
         let real = outlined_text(
             b,
             Node {
@@ -453,8 +375,7 @@ pub(crate) fn icon_button<A: Component, I: Bundle, L: Bundle>(
     });
 }
 
-/// A 32² spinner arrow at its authored x in the dial row — up/down art states + the additive
-/// hover highlight, or a plain `<`/`>` without art.
+/// A 32² spinner arrow at its authored x in the dial row, or a plain `<`/`>` without art.
 pub(crate) fn dial_arrow<A: Component>(
     row: &mut ChildSpawnerCommands,
     arrow: &Option<ArrowArt>,
@@ -510,25 +431,23 @@ pub(crate) fn dial_arrow<A: Component>(
     }
 }
 
-/// A glue button template (`GlueButtons.xml` / `GlueDialog.xml`): the caption font it authors, and
-/// its `<ButtonText>` CENTER-anchor **offset**. The offset is real and per-template — the big
-/// `GlueButtonTemplate` pulls its caption 3 units LEFT and 3 UP of dead centre — and drawing every
-/// caption dead centre instead sat them all low, and the big buttons' right (decision 0543).
+/// A glue button template (`GlueButtons.xml`, `GlueDialog.xml`): its caption font and its
+/// per-template `<ButtonText>` CENTER offset.
 #[derive(Clone, Copy)]
 pub(crate) enum GlueBtnKind {
-    /// `GlueButtonTemplate` (170×45) — GlueFontNormal, ButtonText CENTER (−3, 3).
+    /// `GlueButtonTemplate` (170×45): GlueFontNormal, ButtonText CENTER (−3, 3).
     Normal,
-    /// `GlueButtonSmallTemplate` (150×38) — GlueFontNormalSmall, ButtonText CENTER (0, 3).
+    /// `GlueButtonSmallTemplate` (150×38): GlueFontNormalSmall, ButtonText CENTER (0, 3).
     Small,
-    /// `GlueDialogButtonTemplate` (200×40) — GlueFontNormal, ButtonText CENTER (0, 2).
+    /// `GlueDialogButtonTemplate` (200×40): GlueFontNormal, ButtonText CENTER (0, 2).
     Dialog,
-    /// `AddonListButtonTemplate` (160×35) — GlueFontNormal, ButtonText CENTER (0, 2), and its own
-    /// narrower art crop (TexCoords 0.025–0.535 of the `Glue-Panel-Button` sheets).
+    /// `AddonListButtonTemplate` (160×35): GlueFontNormal, ButtonText CENTER (0, 2), and its own
+    /// art crop, TexCoords 0.025–0.535.
     List,
 }
 
 impl GlueBtnKind {
-    /// `(font size, caption offset)` — the offset in the reference's anchor space, y UP-positive.
+    /// `(font size, caption offset)`, the offset in the reference's anchor space, y up.
     fn caption(self) -> (f32, Vec2) {
         match self {
             Self::Normal => (15.0, Vec2::new(-3.0, 3.0)),
@@ -537,7 +456,6 @@ impl GlueBtnKind {
         }
     }
 
-    /// The template's art crop where it overrides the shared `GlueButtons.xml` region.
     fn tex_coords(self) -> Option<BtnTexCoords> {
         match self {
             Self::List => Some(BtnTexCoords([0.025, 0.535, 0.0, 0.75])),
@@ -546,51 +464,23 @@ impl GlueBtnKind {
     }
 }
 
-/// `GlueEditBoxFont`'s size (GlueFonts.xml: ARIALN 18) — the typed line and the caret beside it.
+/// `GlueEditBoxFont`'s size (GlueFonts.xml: ARIALN 18).
 pub(crate) const EDIT_FONT_SIZE: f32 = 18.0;
-/// The typed line's line-height multiple, pinned here rather than left to Bevy's default so the
-/// caret's height (below) is provably the same number the text lays out with.
+/// The typed line's line-height multiple; the caret's height must use the same number.
 const EDIT_LINE_HEIGHT: f32 = 1.2;
-/// The edit caret's colour: the reference's caret re-applies **`FONTINSTANCE.textColor`** whenever
-/// the font changes (`0x77e2a0`, mask bit 2) — the ctor's `0xFFFFFFFF` is only the pre-font default.
-/// So it is the box's text colour by law, not white by coincidence; both the line and the bar take
-/// it from here.
+/// The typed text and caret colour: the reference's caret takes `FONTINSTANCE.textColor` whenever
+/// the font changes (`0x77e2a0`, mask bit 2).
 const EDIT_TEXT_COLOR: Color = Color::WHITE;
-/// The edit caret is a drawn **bar**, not a character — a `CSimpleTexture` at `E+0x368`, allocated
-/// with a different allocator/tag/ctor than the `CSimpleFontString` beside it (`0x779c86` vs
-/// `0x779bee`; the cursor flush `0x77da80` fires `OnCursorChanged` with
-/// four float caret-*position* args). benilla used to append a `"|"` glyph (login) or a static `"_"`
-/// (create), which put a font's shape on a font's baseline and re-laid the text out every blink.
-///
-/// **Width is 4.0 UI units** — byte-verified, not the 1 px this shipped with first (decision 0542).
-/// `0x77ba2d–0x77ba67` stores `G1·4/(G3·1024)`, which the client's own internal→Lua converter maps
-/// to exactly 4.0 at every aspect and resolution. Same units as every other authored glue number,
-/// so it scales with `s` like the rest. Height is the FontString's line height; the bar is
-/// vertically centred on the line (the ref anchors caret-LEFT to the FontString's own rect, so
-/// TextInsets never enter the caret's own geometry — it inherits them by anchoring).
+/// The edit caret is a drawn bar, a `CSimpleTexture` at `E+0x368` (`0x779c86`), not a glyph. It is
+/// 4.0 UI units wide at every aspect (`0x77ba2d–0x77ba67`) and one line tall, centred on the line.
 const CARET_W: f32 = 4.0;
 
-/// The standard edit caret — the drawn [`CARET_W`]-unit bar, one line tall at the box's font size,
-/// in the box's text colour, spawned hidden (the owning screen blinks its `Visibility` on the ref's
-/// 0.5 s clock, reset solid on every keystroke). Seat it as the flex sibling right after the typed
-/// line so it lands at the cursor without anyone measuring text. The ONE caret; every edit box —
-/// [`glue_edit_box`]'s chrome and the delete dialog's ChatInputBorder box — spawns it here, so the
-/// mechanism can never fork back into per-screen `"|"`/`"_"` glyphs.
+/// The edit caret, spawned hidden for the owner to blink, as the flex sibling after the typed
+/// text so it lands at the cursor with no text measuring. Every glue edit box spawns it here.
 ///
-/// **The caret is an OVERLAY: it takes no width in the row.** The flex item is zero-wide — a bare
-/// *seam* the row's layout collapses to nothing — and the drawn bar is an absolutely-positioned
-/// child hanging off it, left edge on the seam, so the typed line is one continuous run whatever
-/// the cursor or the selection is doing. It used to be the bar itself, [`CARET_W`] units wide and
-/// in flow, which pushed the text apart at the cursor and — because a select-all moves the whole
-/// string from the `Before` slot to the `Selected` slot, across one caret seam — **shifted the
-/// text bodily to the right the moment a box was focused** (the director's report, 2026-08-29).
-///
-/// This is also what the client does, and the two facts are the same fact: the caret is a
-/// `CSimpleTexture` quad at `drawLayer 3`, anchored LEFT-to-LEFT on the FontString with
-/// `x = W(lineStart → cursor)` — the measured advance of the text before the cursor (`0x779c86`,
-/// `0x77da80`). A quad anchored *over* the line cannot
-/// displace it, and its left edge sits exactly on the seam flex puts us on. `drawLayer 3` is above
-/// the FontString's `2`, which is the [`ZIndex`] here.
+/// It takes no width: a zero-wide seam with the bar hung off it, so the text never moves. The
+/// reference's caret is a quad at `drawLayer 3` over the FontString's `2`, anchored at the advance
+/// of the text before the cursor (`0x779c86`, `0x77da80`).
 pub(crate) fn caret_bar<C: Bundle>(
     parent: &mut ChildSpawnerCommands,
     caret: C,
@@ -601,7 +491,7 @@ pub(crate) fn caret_bar<C: Bundle>(
         .spawn((
             caret,
             Visibility::Hidden,
-            // The seam: zero-wide, one line tall (the row centres it), and above its siblings.
+            // The seam: zero-wide, one line tall (the row centres it), above its siblings.
             ZIndex(1),
             Node {
                 width: Val::Px(0.0),
@@ -610,8 +500,7 @@ pub(crate) fn caret_bar<C: Bundle>(
             },
         ))
         .with_children(|c| {
-            // The drawn bar, out of flow so it costs the row nothing. `Visibility::Inherited` by
-            // default, so blinking the seam blinks the bar.
+            // Out of flow; inherits the seam's visibility, so blinking the seam blinks the bar.
             c.spawn((
                 Node {
                     position_type: PositionType::Absolute,
@@ -626,34 +515,23 @@ pub(crate) fn caret_bar<C: Bundle>(
         });
 }
 
-/// Which flex item of a glue edit box's text row an entity is.
-///
-/// The row is `[before][caret][selected][caret][after]` — five items, so the caret lands **at the
-/// cursor** and a selection shows its highlight with **no text measuring anywhere**: flex layout
-/// does the positioning, exactly as the single caret sibling used to. `Selected` carries the
-/// highlight background permanently; with nothing selected its text is empty, so it has zero width
-/// and paints nothing. Which of the two caret slots is visible follows the cursor, which the box
-/// law keeps at one end of the selection or the other.
-///
-/// **Both caret slots are zero-width seams** ([`caret_bar`]), present or not, so the three text
-/// slots concatenate to one unbroken line: which slot a run of text sits in never moves it.
+/// Which item of a glue edit box's row `[before][caret][selected][caret][after]` an entity is.
+/// Flex places the caret and selection with no text measuring; an empty `Selected` has zero
+/// width, and the caret slots are zero-width seams, so the text is one unbroken line.
 #[derive(Component, Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) enum GlueFieldPart {
     /// `display[..sel_start]`
     Before,
-    /// The caret when it sits at the selection's start (and whenever nothing is selected).
+    /// The caret at the selection's start, and whenever nothing is selected.
     CaretAtStart,
-    /// `display[sel_start..sel_end]` — the highlighted run.
+    /// `display[sel_start..sel_end]`, the highlighted run.
     Selected,
-    /// The caret when it sits at the selection's end.
     CaretAtEnd,
     /// `display[sel_end..]`
     After,
 }
 
-/// Paint one glue edit box from its [`EditBoxState`] — the segments, the selection, and the caret.
-/// Shared so the login boxes, the create-name box and the delete dialog can never fork (decision
-/// 0704); everything it draws comes off the same state the shared law edits.
+/// Paint one glue edit box's segments, selection and caret from its [`EditBoxState`].
 pub(crate) fn paint_glue_field<'a>(
     field: &EditBoxState,
     focused: bool,
@@ -665,21 +543,15 @@ pub(crate) fn paint_glue_field<'a>(
         ),
     >,
 ) {
-    // **The highlight is deliberately NOT gated on `focused`** — `focused` drives the caret alone.
-    // That asymmetry looks like an oversight and is the reference's own: the caret's flush
-    // (`0x77da80`) explicitly hides when `E != [0xcf4dc8]`, while the selection flush (`0x77d950`)
-    // and its geometry worker (`0x77de70`) contain no read of the focus global anywhere, and the
-    // per-frame update calls the flush BEFORE its own focus test. The quads show iff
-    // `start < end` — focus never enters it. An unfocused box that still holds a
-    // selection paints it, and that is correct; the login screen simply never leaves one behind
-    // (`LoginForm::focus` collapses the box it leaves).
+    // `focused` gates the caret, not the highlight: the reference's caret flush hides when
+    // `E != [0xcf4dc8]` (`0x77da80`), but the selection flush (`0x77d950`, `0x77de70`) never reads
+    // focus, so an unfocused box paints the selection it holds.
     let display = field.display();
     let lo = field.sel_start.min(field.sel_end);
     let hi = field.sel_start.max(field.sel_end);
     let (d_lo, d_hi) = (field.text_to_display(lo), field.text_to_display(hi));
     let d_cursor = field.text_to_display(field.cursor);
-    // Only a focused box blinks; `caret_shown` is the box's own blink phase, ticked by
-    // `textinput::tick_caret`, so a glue caret and the chat caret share one clock.
+    // `caret_shown` is ticked by `textinput::tick_caret`, the chat caret's clock too.
     let caret_on = focused && field.caret_shown;
     for (part, text, mut vis) in parts {
         let (want_text, want_vis) = match part {
@@ -705,17 +577,9 @@ pub(crate) fn paint_glue_field<'a>(
     }
 }
 
-/// A glue edit box's CHROME — the shape every glue EditBox authors (`AccountLoginAccountEdit`/
-/// `PasswordEdit`, `CharacterCreateNameEdit`): the `UI-Tooltip-Background` fill tiled at 16 inside
-/// the (10,5,4,9) insets, the `Glue-Tooltip-Border` 16-edge over it (both caller-tinted — the
-/// login boxes take `DEFAULT_TOOLTIP_COLOR`, the create name box the Alliance row), and the text
-/// row at the ref's TextInsets (left 15, vertically centered) in `GlueEditBoxFont` (ARIALN 18,
-/// white).
-///
-/// `extras` rides the box node (the screen's click-to-focus action + `Button`); `marker` is cloned
-/// onto all five row items ([`GlueFieldPart`]) so the screen's refresh can query them as a set and
-/// hand them to [`paint_glue_field`]. Plain-fill fallback without art. Focus and typing are the
-/// owning screen's systems — this is chrome only, so the screens' boxes can never fork.
+/// A glue edit box's chrome, as every glue EditBox authors it: `UI-Tooltip-Background` tiled at
+/// 16 inside the (10,5,4,9) insets under the `Glue-Tooltip-Border` 16-edge, both tinted by the
+/// caller, and the text row at `text_insets`. `marker` goes on all five row items.
 pub(crate) fn glue_edit_box<E: Bundle, T: Bundle + Clone>(
     parent: &mut ChildSpawnerCommands,
     art: &GlueArt,
@@ -755,10 +619,8 @@ pub(crate) fn glue_edit_box<E: Bundle, T: Bundle + Clone>(
             ));
             backdrop_border(b, art.name_border.as_ref().unwrap(), NAME_EDGE, border);
         }
-        // The ref's `<TextInsets>` (left, right, top, bottom): the EditBox's FontString rect is
-        // the box inset by them, and the typed line is centred in THAT — not in the whole box. The
-        // login boxes inset the bottom by 5, which lifts the line, and the caret beside it, off the
-        // box's own centre; the create name box insets only the left, so it stays centred.
+        // `<TextInsets>` (left, right, top, bottom): the typed line is centred in the inset rect,
+        // not the whole box.
         let (ti_l, ti_r, ti_t, ti_b) = text_insets;
         b.spawn((Node {
             position_type: PositionType::Absolute,
@@ -789,8 +651,7 @@ pub(crate) fn glue_edit_box<E: Bundle, T: Bundle + Clone>(
                         },
                     ));
                     if part == GlueFieldPart::Selected {
-                        // The box law's own highlight tint (`SetHighlightColor`'s ctor default,
-                        // opaque medium grey) — the same colour the chat box selects with.
+                        // `SetHighlightColor`'s default, opaque medium grey, as the chat box.
                         e.insert(BackgroundColor(Color::srgb(
                             96.0 / 255.0,
                             96.0 / 255.0,
@@ -817,13 +678,8 @@ pub(crate) fn glue_edit_box<E: Bundle, T: Bundle + Clone>(
     });
 }
 
-/// A glue-panel button (Accept/Back/Enter World/…): the real `Glue-Panel-Button` art with its
-/// additive hover sheen and a caption that whitens on hover (the ref's `HighlightFont`);
-/// plain-fill fallback. Art states + caption color are driven by [`super::glue_button_visuals`].
-///
-/// Returns the button's entity, so a screen can reach back into what it just built — the login
-/// screen marks its realmlist button [`GlueDisabled`] when `$WOW_HOST` owns the session (1667).
-/// Ignoring the return is the norm; nothing is `#[must_use]`.
+/// A glue-panel button on `Glue-Panel-Button` art with its hover sheen, or a plain fill. Returns
+/// the button's entity.
 pub(crate) fn glue_button<A: Component>(
     parent: &mut ChildSpawnerCommands,
     art: &GlueArt,
@@ -877,15 +733,12 @@ pub(crate) fn glue_button<A: Component>(
         let (font_size, offset) = kind.caption();
         outlined_text(
             inner,
-            // The template's authored `<ButtonText>` offset off CENTER. The ref's anchor space is
-            // y-UP, so it negates into Bevy's `top`; on a flex item both shift it visually without
-            // disturbing the layout, which is exactly an anchor offset.
+            // The `<ButtonText>` offset off CENTER; the reference's y is up, so it negates into
+            // `top`.
             Node {
                 left: Val::Px(offset.x * s),
-                // +1 cancels `outlined_text`'s shared −1 trim for captions: that trim was fitted
-                // (director-measured) back when captions drew at dead centre, so once the authored
-                // `<ButtonText>` offset above is applied it corrects the same unit twice and the
-                // caption reads a notch high. Director's eye, 2026-07-19.
+                // +1 cancels `outlined_text`'s −1 trim for captions: the `<ButtonText>` offset
+                // already corrects that unit.
                 top: Val::Px((1.0 - offset.y) * s),
                 ..default()
             },
@@ -908,18 +761,6 @@ pub(crate) fn glue_button<A: Component>(
 mod tests {
     use super::*;
 
-    /// `|cAARRGGBB…|r` markup renders as colour, not as text — for **every** glue string, which
-    /// is the whole point of the decode living in the primitive.
-    ///
-    /// Two regressions are pinned here. The MapCoords one (a `## Title` of
-    /// `|cff00ff00MapCoords 0.32`, printed literally in the AddOns list), and B273: the same
-    /// screen's tooltip printed `|cff0055FFDeadly Boss Mod API|r` raw while the row an inch to
-    /// its left drew it blue, because only the row had opted into a decode. Nothing opts in now
-    /// — [`outlined_text`] is the one door and it always decodes — so the case worth testing is
-    /// the function, once, for both.
-    ///
-    /// The grammar is the byte-verified [`benilla_ui::markup`]; the escape's alpha byte is
-    /// discarded there, so only rgb reaches the span colour.
     #[test]
     fn colour_escapes_become_spans_not_text() {
         let base = GOLD;
@@ -963,8 +804,6 @@ mod tests {
         );
     }
 
-    /// A `|H…|h` link keeps its visible text and drops its payload — the glue has no clickable
-    /// links, so the alternative is an addon note printing `|Hitem:1234|h`.
     #[test]
     fn a_link_escape_keeps_its_text_and_hides_its_payload() {
         assert_eq!(
@@ -973,9 +812,6 @@ mod tests {
         );
     }
 
-    /// A line break follows the string's own `wrap`: a real break where the ref lets the string
-    /// wrap, a space where it authored one line. A 20-unit row title growing a second row is the
-    /// failure this avoids; a tooltip paragraph losing its author's break is the other.
     #[test]
     fn a_line_break_follows_the_strings_own_wrap_flag() {
         assert_eq!(
diff --git a/crates/benilla-app/src/glue_strings.rs b/crates/benilla-app/src/glue_strings.rs
index e50e27db..5ef6d3d8 100644
--- a/crates/benilla-app/src/glue_strings.rs
+++ b/crates/benilla-app/src/glue_strings.rs
@@ -1,22 +1,10 @@
-//! The 1.12 glue string table, read off the MPQ chain at startup — the localized text the glue
-//! screens quote: faction/race/class description paragraphs (`FACTION_INFO_*`, `RACE_INFO_*`,
-//! `ABILITY_INFO_*`, `CLASS_*`), the per-race customization dial labels (`HAIR_<tok>_STYLE`,
-//! `FACIAL_HAIR_<tok>`), the login refusals, and the button captions.
+//! The 1.12 glue string table, read off the MPQ chain at startup: the glue screens' localized
+//! text (race and class paragraphs, customization labels, login refusals, button captions).
 //!
-//! **It is two files, in the reference's own order** (decision 2052). `GlueXML.toc` sources
-//! `GlueStrings.lua` at line 1 and `GlueLocalization.xml` at line 3, and that XML exists only to
-//! load its script and call `Localize()` — a function of nothing but assignments, which *overwrite*
-//! the base table. In 1.12 enGB it rewrites 32 keys, among them every long login refusal
-//! (`AUTH_BANNED`, `LOGIN_UNKNOWN_ACCOUNT`, …) and the realm-type suffixes. Reading only the base
-//! file showed the player sentences their own client never shows. The in-game side already loads
-//! its exact twin — `Interface\FrameXML\Localization.xml`, same two-part shape, sourced from
-//! `benilla.toc` — so the glue side was the half that had been left behind.
-//!
-//! Runtime-read, never embedded: the paragraphs are Blizzard content, so they load from the
-//! player's own client data like every other asset (the repo's never-commit rule) — which is also
-//! what makes the locale *theirs* rather than ours to guess. Both files are plain `KEY = "value";`
-//! Lua assignments, one per line — a full Lua VM would be theater here; [`parse_glue_strings`]
-//! handles exactly that shape (and skips everything else).
+//! Two files, in `GlueXML.toc`'s order: `GlueStrings.lua`, then `GlueLocalization.xml`, whose
+//! script's `Localize()` overwrites keys of the base table (32 in enGB, among them the long login
+//! refusals and the realm-type suffixes). Both are plain `KEY = "value";` lines, parsed without a
+//! Lua VM; the text is read from the player's install, never embedded.
 
 use std::collections::HashMap;
 
@@ -27,14 +15,12 @@ use benilla_assets::{LockRecover, WorldAssets};
 const GLUE_STRINGS: &str = "Interface\\GlueXML\\GlueStrings.lua";
 const GLUE_LOCALIZATION: &str = "Interface\\GlueXML\\GlueLocalization.lua";
 
-/// The glue string table. Present but possibly empty (missing client data — the graceful-absence
-/// posture; callers fall back to their built-in captions).
+/// The glue string table; empty without client data, and callers fall back to built-in captions.
 #[derive(Resource, Default)]
 pub(crate) struct GlueStrings(HashMap<String, String>);
 
 impl GlueStrings {
-    /// Build a table straight from parsed pairs — the test seam for code that has to resolve
-    /// against the *real* shipped file rather than a stub.
+    /// A table from parsed pairs, for tests that resolve against the real file.
     #[cfg(test)]
     pub(crate) fn from_map(map: HashMap<String, String>) -> Self {
         Self(map)
@@ -46,7 +32,6 @@ impl GlueStrings {
         self.0
     }
 
-    /// The string for a key, or `None` (unknown key / no data).
     pub(crate) fn get(&self, key: &str) -> Option<&str> {
         self.0.get(key).map(String::as_str)
     }
@@ -57,11 +42,8 @@ impl GlueStrings {
     }
 }
 
-/// Startup: read + parse the glue string table off the chain (after the chain exists).
-///
-/// Two reads, and the **order is the whole point**: the base file, then the locale patch over it,
-/// exactly as `GlueXML.toc` sources them. A chain missing either one degrades on its own — no
-/// base means built-in captions, no patch means the base text.
+/// Startup: reads the base file, then lays the locale patch over it, in `GlueXML.toc`'s order.
+/// Either may be missing on its own.
 pub(crate) fn load_glue_strings(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
     let mut table = GlueStrings::default();
     if let Some(assets) = assets {
@@ -85,8 +67,8 @@ pub(crate) fn load_glue_strings(mut commands: Commands, assets: Option<Res<World
     commands.insert_resource(table);
 }
 
-/// Parse the `KEY = "value";` assignments (one per line; `\n`/`\t`/`\"`/`\\` escapes unfolded).
-/// Anything else — comments, code, multi-line constructs — is skipped.
+/// Parses the `KEY = "value";` lines, unfolding `\n`/`\t`/`\"`/`\\` escapes; anything else is
+/// skipped.
 fn parse_glue_strings(src: &str) -> HashMap<String, String> {
     let mut out = HashMap::new();
     for line in src.lines() {
@@ -128,24 +110,12 @@ fn parse_glue_strings(src: &str) -> HashMap<String, String> {
     out
 }
 
-/// The assignments inside `GlueLocalization.lua`'s **`Localize()`** — the locale patch the
-/// reference lays over `GlueStrings.lua`.
+/// The assignments inside `GlueLocalization.lua`'s `Localize()`, which `GlueLocalization.xml` runs
+/// as it loads. The file's other function, `LocalizeFrames()`, moves the `WorldOfWarcraftRating`
+/// logo (called on `FRAMES_LOADED`), a frame benilla's glue does not have, so it is not read.
 ///
-/// Scoped to that one function deliberately, because the file defines two and only one of them is
-/// a string table:
-///
-/// - **`Localize()`** is run by `GlueLocalization.xml`'s own inline `<Script>` (l.6) the moment the
-///   file loads, which in `GlueXML.toc` is line 3 — after `GlueStrings.lua` at line 1. Its body is
-///   nothing but `KEY = "value";`, and it is what this reads.
-/// - **`LocalizeFrames()`** is called much later, from `GlueParent_OnEvent`'s `FRAMES_LOADED` arm
-///   (`GlueParent.lua` l.95), and is frame surgery rather than text: in 1.12 enGB, a texture swap
-///   and reposition of the login screen's `WorldOfWarcraftRating` logo — a frame benilla's native
-///   glue does not have at all. Nothing there to apply, so nothing here reads it.
-///
-/// The body runs from `function Localize()` to the first **unindented** `end`, which is Blizzard's
-/// own formatting: nested blocks are indented, a function's own terminator is not. A file whose
-/// shape doesn't match yields no overrides rather than the wrong ones — the loader logs the count,
-/// so a zero is visible rather than silent.
+/// The body ends at the first unindented `end`, as the stock file is formatted; a file of another
+/// shape yields no overrides.
 fn parse_localize_overrides(src: &str) -> HashMap<String, String> {
     let mut body = String::new();
     let mut inside = false;
@@ -160,13 +130,10 @@ fn parse_localize_overrides(src: &str) -> HashMap<String, String> {
         body.push_str(line);
         body.push('\n');
     }
-    // No terminator (or no `Localize()` at all): an unrecognised file patches nothing.
     HashMap::new()
 }
 
-/// Build the table the way [`load_glue_strings`] does — base file, then the locale patch over it.
-/// Every test that resolves against the *real* chain goes through here, so no test can assert a
-/// sentence the running client would not show.
+/// Builds the table as [`load_glue_strings`] does, for tests against the real chain.
 #[cfg(test)]
 pub(crate) fn table_from_chain(chain: &mut benilla_formats::Chain) -> GlueStrings {
     let base = chain.read_file(GLUE_STRINGS).expect("GlueStrings.lua");
@@ -204,9 +171,6 @@ BROKEN = "no close
         assert_eq!(t.len(), 3);
     }
 
-    /// `Localize()`'s body, and **only** its body: the second function in the file is frame
-    /// surgery that the reference calls from somewhere else entirely, so an assignment there must
-    /// not leak into the string table.
     #[test]
     fn the_locale_patch_reads_localize_and_stops_at_its_end() {
         let src = r#"function Localize()
@@ -235,19 +199,13 @@ end
         assert_eq!(t.len(), 2);
     }
 
-    /// A file that is not the shape we understand patches **nothing** — never a partial or a
-    /// guessed table. The two ways it can fail: no `Localize()` at all, and a body with no
-    /// terminator to stop at.
     #[test]
     fn an_unrecognised_file_patches_nothing() {
         assert!(parse_localize_overrides("KEY = \"value\";\n").is_empty());
         assert!(parse_localize_overrides("function Localize()\n\tK = \"v\";\n").is_empty());
     }
 
-    /// **The real chain's patch, applied in the reference's own order.** Reading only the base
-    /// file is what decision 2052 fixed, and this is the regression: three keys whose base text
-    /// and patched text differ, asserted from both ends so neither a lost patch nor a lost base
-    /// can pass. Skips without client data.
+    /// Three keys whose base and patched text differ. Skips without client data.
     #[test]
     fn the_real_chain_patches_the_login_refusals_and_the_realm_suffixes() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -263,16 +221,14 @@ end
             assert_ne!(before, after, "{key} was not patched by Localize()");
         }
 
-        // The suffix is the one a player can read at a glance: the base file parenthesises it,
-        // the enGB patch does not — `CharSelectRealmName` says "Realm PVP", not "Realm (PVP)".
+        // The enGB patch drops the parentheses: `CharSelectRealmName` reads "Realm PVP".
         assert_eq!(
             base.get("PVP_PARENTHESES").map(String::as_str),
             Some("(PVP)")
         );
         assert_eq!(table.get("PVP_PARENTHESES"), Some("PVP"));
 
-        // Every key the base file never had still resolves, and every key it had is still there:
-        // the patch overwrites, it does not replace the table.
+        // The patch overwrites keys; it does not replace the table.
         assert!(table.get("FACTION_INFO_HORDE").is_some(), "base lost");
         assert!(base.len() > 100 && table.0.len() >= base.len());
     }
diff --git a/crates/benilla-app/src/go_templates.rs b/crates/benilla-app/src/go_templates.rs
index 798920c7..c162da03 100644
--- a/crates/benilla-app/src/go_templates.rs
+++ b/crates/benilla-app/src/go_templates.rs
@@ -1,11 +1,6 @@
-//! The ask-once GameObject template cache (decision 0239) — benilla's `GAMEOBJECT_QUERY` store.
-//!
-//! A GameObject's **lockId** (a type-specific slot of its template `data[]`) decides its right-click
-//! action: a locked object (chest / mining vein / herb node / locked door) casts an `OPEN_LOCK` spell
-//! at it, an unlocked one sends `CMSG_GAMEOBJ_USE`. The lockId isn't in the create packet, so it's
-//! fetched ask-once by entry when a GameObject streams in ([`GameObjectTemplates::request`], warmed
-//! from [`crate::net::apply`]'s `ObjectCreate`, the same discipline as the name cache), the answer
-//! resolved in [`GameObjectTemplates::insert`], and read by the interact routing ([`crate::target`]).
+//! The ask-once GameObject template cache, filled by `CMSG_GAMEOBJECT_QUERY` when an object
+//! streams in. The template's lockId decides a right-click: a locked object is opened by an
+//! `OPEN_LOCK` cast, an unlocked one by `CMSG_GAMEOBJ_USE`.
 
 use benilla_formats::{LockCatalog, LockTypeCatalog};
 use benilla_protocol::guid;
@@ -14,88 +9,55 @@ use bevy::prelude::*;
 use crate::net::{ClientCommand, NetCommands};
 use crate::query_cache::QueryCache;
 
-/// `Lock.dbc` as a resource (decision 0239) — `lockId → requirement slots`, read by the interact
-/// routing to decide use-vs-cast and, for a lockable object, which `LockType` the opener spell must
-/// match. Loaded once at startup ([`crate::entities`]); absent when the client data is.
+/// `Lock.dbc`: decides use against cast, and which `LockType` the opener spell must match.
 #[derive(Resource)]
 pub(crate) struct Locks(pub(crate) LockCatalog);
 
-/// `LockType.dbc` as a resource (decision 0236) — `LockType.Id → cursor stem`, read by the world
-/// cursor's GameObject branch ([`crate::target`]) to name a lockable object's cursor by data
-/// (`PickLock`/`GatherHerbs`/`Mine`), the client's own lock → LockType → CursorName chain. Loaded
-/// once at startup; absent when the client data is, in which case a lock-bearing GO shows the
-/// generic Interact gear like any other base type.
+/// `LockType.dbc`: names a lockable object's cursor (`PickLock`, `GatherHerbs`, `Mine`) through
+/// the client's lock, LockType, CursorName chain.
 #[derive(Resource)]
 pub(crate) struct LockTypes(pub(crate) LockTypeCatalog);
 
-/// A cached GameObject template — what the interact routing and the hover tooltip need. The
-/// `type_id` is consumed transiently to pick the lock's `data[]` slot (the entity already
-/// carries it).
+/// A cached GameObject template, as the interact routing and the hover tooltip need it.
 #[derive(Clone)]
 pub(crate) struct GoTemplate {
-    /// The `Lock.dbc` id from the type's data slot — `0` means no lock (opens by `CMSG_GAMEOBJ_USE`).
+    /// The `Lock.dbc` id; `0` is no lock.
     pub(crate) lock_id: u32,
-    /// The display name — the hover tooltip's gold first line (decision 0276's GO law).
+    /// The hover tooltip's first line.
     pub(crate) name: String,
-    /// The vanilla **highlight** column, for the two types whose mouseover-eligibility slot reads
-    /// it instead of running a predicate (decision 1110): GENERIC(5)'s `data[1]` (`0x5f4830`,
-    /// decision 0762 — nonzero on 1387 of the 1870 shipped type-5 templates, which is why a road
-    /// signpost hovers and the scenery beside it never does) and CAPTURE_POINT(29)'s `data[19]`
-    /// (`0x5f6d80` — byte-for-byte the same shape, a different slot). `false` for every other type,
-    /// which never consults it.
+    /// Mouseover eligibility for the two types that read a column: GENERIC(5) `data[1]`
+    /// (`0x5f4830`) and CAPTURE_POINT(29) `data[19]` (`0x5f6d80`).
     pub(crate) highlight_column: bool,
-    /// GENERIC(5) only: the template's **`data[0]`**, the sole input of that type's `[vtbl+0x5c]`
-    /// (`0x5f8630`) — the fork in the mouseover publisher that decides whether this object's
-    /// tooltip FOLLOWS THE CURSOR (`0x492a01` → `0x52ffe0(owner, 6, 0, 0)`, the SetOwner core at
-    /// anchor state 6) or takes the default corner seat like a creature's (`0x492a42`, which
-    /// writes no owner and fires `OnTooltipSetDefaultAnchor` instead).
-    ///
-    /// The slot is named by `0x621b00(type, semantic 0x13)`, a key that resolves for exactly one
-    /// of the 31 GO types — so no other type can take the cursor arm, and 0766's INTERIM "GENERIC
-    /// vs not" proxy is replaced by the real key (decision 2259). **Distinct from
-    /// [`Self::highlight_column`]**, which is `data[1]` via semantic `0x12` and gates *eligibility*
-    /// rather than *placement*: an object can be hoverable and still be corner-seated.
-    ///
-    /// `false` for every other type. (The *name* is inferred from vmangos's field order; the index
-    /// and the fork are byte-verified, and the data is cross-checked against the reference client's
-    /// own `gameobjectcache.wdb` — 1890 entries, zero disagreements with the server's.)
+    /// GENERIC(5) `data[0]` (`0x5f8630`, semantic `0x13`, which no other type has): the tooltip
+    /// follows the cursor (`0x492a01`, SetOwner `0x52ffe0` at anchor state 6) or takes the default
+    /// corner (`0x492a42`).
+    /// Placement, not eligibility: a hoverable object can still be corner-seated.
     pub(crate) floating_tooltip: bool,
-    /// MEETINGSTONE (type 23) only: the three template slots the stone's own strategy reads —
-    /// `data[0]`/`data[1]` = minLevel/maxLevel and `data[2]` = areaID (decisions 1110, 2283).
-    /// `None` for every other type.
+    /// MEETINGSTONE (type 23) only.
     pub(crate) meeting_stone: Option<MeetingStoneTemplate>,
-    /// MO_TRANSPORT (type 15) path parameters — `Some` only for boats/zeppelins (decision 0438):
-    /// the template's `data0..2` = (taxiPathId, moveSpeed, accelRate), the inputs the transport
-    /// timetable is built from.
+    /// MO_TRANSPORT (type 15) only: the transport timetable's inputs.
     pub(crate) mo_transport: Option<MoTransport>,
-    /// TEXT (type 9) only: the book/plaque's page chain head + frame material (decision 1105).
-    /// `Some` with a nonzero `page_id` is what makes a right-click *read* it; a type-9 template
-    /// with no page (vanilla ships a handful) opens nothing at all, exactly like the reference.
+    /// TEXT (type 9) only; a right-click reads it only when `page_id` is nonzero.
     pub(crate) text_page: Option<TextPage>,
-    /// The `PageTextMaterial.dbc` id `GetQuestBackgroundMaterial` answers for a quest sourced from
-    /// this object — by `GAMEOBJECT_TYPE_ID`: QUESTGIVER (2) and GOOBER (9) read `data[2]`, CHEST
-    /// (10) reads `data[9]`, every other type answers none (`0x5f5950`).
+    /// The `PageTextMaterial.dbc` id `GetQuestBackgroundMaterial` answers for a quest from this
+    /// object (`0x5f5950`): QUESTGIVER (2) and TEXT (9) read `data[2]`, GOOBER (10) `data[9]`.
     pub(crate) quest_material: Option<u32>,
 }
 
-/// A MEETINGSTONE (type 23) template's three slots, all of them read by the stone's own strategy
-/// through the per-type attribute table `0x621b00`: keys `0x33`/`0x34`/`0x35` → indices 0/1/2
-/// (vmangos `GameObjectInfo::meetingstone` = `minLevel, maxLevel, areaID`; decision 2283).
-///
-/// The **areaID** is the input of the type's own `highlightable` slot `0x5f6990`
-/// ([`crate::target::cursor_mode::meeting_stone_queued`]); the **level pair** is the input of the
-/// use-slot validator's level refusal (`ERR_MEETING_STONE_INVALID_LEVEL`).
+/// A MEETINGSTONE template's slots, read through `0x621b00` keys `0x33` to `0x35` (vmangos
+/// `GameObjectInfo::meetingstone`). The area feeds the type's highlightable slot `0x5f6990`, the
+/// levels the use refusal `ERR_MEETING_STONE_INVALID_LEVEL`.
 #[derive(Clone, Copy)]
 pub(crate) struct MeetingStoneTemplate {
-    /// `data[0]` — the lowest level the stone accepts.
+    /// `data[0]`.
     pub(crate) min_level: u32,
-    /// `data[1]` — the highest level the stone accepts.
+    /// `data[1]`.
     pub(crate) max_level: u32,
-    /// `data[2]` — the `AreaTable` id the stone queues for.
+    /// `data[2]`, the `AreaTable` id the stone queues for.
     pub(crate) area: u32,
 }
 
-/// A MO_TRANSPORT template's path tuple (`gameobject_template.data0..2`, decision 0438).
+/// A MO_TRANSPORT template's path tuple (`gameobject_template.data0..2`).
 #[derive(Clone, Copy)]
 pub(crate) struct MoTransport {
     pub(crate) taxi_path_id: u32,
@@ -103,19 +65,17 @@ pub(crate) struct MoTransport {
     pub(crate) accel_rate: f32,
 }
 
-/// A TEXT (type 9) template's readable head — `data[0]`/`data[2]` (vmangos `GameObjectInfo::text`
-/// = `pageID, language, pageMaterial, allowMounted`; decision 1105). The client reads both through
-/// the same per-type attribute→slot table (`0x621b00`, attribute `0x11` = pageMaterial), so the
-/// two layouts are the one layout.
+/// A TEXT template's readable head (vmangos `GameObjectInfo::text`; the client's `0x621b00` key
+/// `0x11` is the same material slot).
 #[derive(Clone, Copy)]
 pub(crate) struct TextPage {
-    /// `data[0]` — the first page's `PageText` id; `0` = nothing to read.
+    /// `data[0]`, the first `PageText` id; `0` is nothing to read.
     pub(crate) page_id: u32,
-    /// `data[2]` — the `PageTextMaterial.dbc` id the reader's frame paints with.
+    /// `data[2]`, a `PageTextMaterial.dbc` id.
     pub(crate) material: u32,
 }
 
-/// `entry → template`, ask-once per connection (mirrors [`crate::names::NameCache`]'s discipline).
+/// Entry to template, asked once per connection.
 #[derive(Resource, Default)]
 pub(crate) struct GameObjectTemplates {
     templates: QueryCache<u32, GoTemplate>,
@@ -128,9 +88,7 @@ impl crate::query_cache::AskOnce for GameObjectTemplates {
 }
 
 impl GameObjectTemplates {
-    /// Ask the server for a GameObject's template if not already known or in flight (once per entry).
-    /// `guid` names the asking object; the server answers by entry, so all spawns of a template share
-    /// the one query.
+    /// Asks for a template once per entry; every spawn of a template shares the one query.
     pub(crate) fn request(&self, guid: u64, commands: &NetCommands) {
         let Some(entry) = guid::entry(guid) else {
             return;
@@ -143,42 +101,31 @@ impl GameObjectTemplates {
         });
     }
 
-    /// Record a `SMSG_GAMEOBJECT_QUERY_RESPONSE`, resolving the lockId from the type-specific
-    /// `data[]` slot. A miss (server didn't know the entry) arrives zeroed → `lock_id = 0` (no lock).
+    /// Records a `SMSG_GAMEOBJECT_QUERY_RESPONSE`; a miss arrives zeroed, so no lock.
     pub(crate) fn insert(&mut self, entry: u32, type_id: u32, name: String, data: &[i32; 24]) {
         let lock_id = go_lock_slot(type_id)
             .and_then(|slot| data.get(slot))
             .map(|&v| v.max(0) as u32)
             .unwrap_or(0);
-        // The highlight column, at the slot its type reads it from (decision 1110): GENERIC(5)
-        // `data[1]`, CAPTURE_POINT(29) `data[19]`. Both slots are resolved by the same
-        // `0x621b00(type, semantic 0x12)` lookup in the reference; the two shipped answers are
-        // inlined here for the same reason [`go_lock_slot`] inlines the lock's.
+        // The reference resolves both slots by `0x621b00(type, semantic 0x12)`.
         let highlight_column = match type_id {
             5 => data[1] != 0,
             29 => data[19] != 0,
             _ => false,
         };
-        // GENERIC(5): data[0] = the tooltip-placement fork's input (decision 2259). Same shape as
-        // the highlight column above and deliberately beside it — they are adjacent slots that
-        // answer different questions, and reading them as one is the mistake 0766 made.
+        // Adjacent to the highlight column but a different question: placement.
         let floating_tooltip = type_id == 5 && data[0] != 0;
-        // MEETINGSTONE (23): data[0..2] = minLevel, maxLevel, areaID (vmangos
-        // `gameobject_template`) — the area feeds that type's own highlightable slot, the level
-        // pair the use-slot validator's level refusal (decision 2283).
         let meeting_stone = (type_id == 23).then(|| MeetingStoneTemplate {
             min_level: data[0].max(0) as u32,
             max_level: data[1].max(0) as u32,
             area: data[2].max(0) as u32,
         });
-        // MO_TRANSPORT (15): data0..2 = taxiPathId / moveSpeed / accelRate (vmangos
-        // `GameObjectInfo::moTransport`; decision 0438).
+        // vmangos `GameObjectInfo::moTransport`.
         let mo_transport = (type_id == 15).then(|| MoTransport {
             taxi_path_id: data[0].max(0) as u32,
             move_speed: data[1].max(0) as f32,
             accel_rate: data[2].max(0) as f32,
         });
-        // TEXT (9): data[0] = pageID, data[2] = pageMaterial (decision 1105).
         let text_page = (type_id == 9).then(|| TextPage {
             page_id: data[0].max(0) as u32,
             material: data[2].max(0) as u32,
@@ -203,23 +150,21 @@ impl GameObjectTemplates {
         );
     }
 
-    /// The cached template for a GameObject guid, or `None` if its query hasn't answered yet.
+    /// The cached template for a GameObject guid.
     pub(crate) fn get(&self, guid: u64) -> Option<&GoTemplate> {
         guid::entry(guid).and_then(|e| self.templates.get(e))
     }
 }
 
-/// Which `data[]` slot holds a GameObject type's lockId (mangos `GameObjectInfo::GetLockId`), or
-/// `None` for a type that never carries one. DOOR/BUTTON keep it at slot 1 (slot 0 is `startOpen`),
-/// FISHINGHOLE at slot 4, and the rest that have a lock at slot 0.
+/// The `data[]` slot of a type's lockId (vmangos `GameObjectInfo::GetLockId`).
 fn go_lock_slot(type_id: u32) -> Option<usize> {
     match type_id {
         // DOOR(0), BUTTON(1): data[0] = startOpen, data[1] = lockId.
         0 | 1 => Some(1),
-        // QUESTGIVER(2), CHEST(3), TRAP(6), GOOBER(10), AREADAMAGE(12), CAMERA(13), FLAGSTAND(24),
-        // FLAGDROP(26): data[0] = lockId. (Gathering nodes are CHEST(3).)
+        // QUESTGIVER(2), CHEST(3, also gathering nodes), TRAP(6), GOOBER(10), AREADAMAGE(12),
+        // CAMERA(13), FLAGSTAND(24), FLAGDROP(26).
         2 | 3 | 6 | 10 | 12 | 13 | 24 | 26 => Some(0),
-        // FISHINGHOLE(25): data[4] = lockId.
+        // FISHINGHOLE(25).
         25 => Some(4),
         _ => None,
     }
@@ -235,12 +180,11 @@ mod tests {
         assert_eq!(go_lock_slot(0), Some(1)); // DOOR (slot 0 is startOpen)
         assert_eq!(go_lock_slot(1), Some(1)); // BUTTON
         assert_eq!(go_lock_slot(25), Some(4)); // FISHINGHOLE
-        assert_eq!(go_lock_slot(5), None); // GENERIC — never a lock
-        assert_eq!(go_lock_slot(19), None); // MAILBOX — no lock (opens by USE)
+        assert_eq!(go_lock_slot(5), None); // GENERIC
+        assert_eq!(go_lock_slot(19), None); // MAILBOX opens by USE
     }
 
-    /// The quest-giver material arm — by type: QUESTGIVER (2) and GOOBER (9) read `data[2]`,
-    /// CHEST (10) reads `data[9]`, anything else none (`0x5f5950`).
+    /// `0x5f5950`: QUESTGIVER (2) and TEXT (9) read `data[2]`, GOOBER (10) `data[9]`.
     #[test]
     fn insert_captures_the_quest_material_by_type() {
         let mut t = GameObjectTemplates::default();
@@ -265,8 +209,7 @@ mod tests {
     fn insert_captures_mo_transport_tuple() {
         let mut t = GameObjectTemplates::default();
         let mut data = [0i32; 24];
-        // The Menethil–Theramore boat (entry 176231): taxiPathId 292, moveSpeed 30, accelRate 1
-        // (vmangos gameobject_template, decision 0438).
+        // The Menethil to Theramore boat's vmangos template row.
         data[0] = 292;
         data[1] = 30;
         data[2] = 1;
@@ -285,8 +228,6 @@ mod tests {
         assert!(t.templates.get(2).unwrap().mo_transport.is_none());
     }
 
-    /// TEXT (9) captures the readable head — `data[0]` page id, `data[2]` material (decision
-    /// 1105); no other type does.
     #[test]
     fn insert_captures_the_text_page_head() {
         let mut t = GameObjectTemplates::default();
@@ -303,7 +244,7 @@ mod tests {
             .expect("type 9 captures");
         assert_eq!(page.page_id, 1416);
         assert_eq!(page.material, 2);
-        // A goober with the same bytes does not — its data[0] is a lockId.
+        // A goober's data[0] is a lockId.
         t.insert(2037, 10, "Lever".into(), &data);
         assert!(t.templates.get(2037).unwrap().text_page.is_none());
     }
@@ -313,7 +254,7 @@ mod tests {
         let mut t = GameObjectTemplates::default();
         let mut data = [0i32; 24];
         data[0] = 38; // a Copper Vein's lockId lives in chest slot 0
-                      // guid 0xF110_0000_026C_3xxx — HIGHGUID_GAMEOBJECT with entry 1731 (0x6C3) in bits 24..47.
+                      // HIGHGUID_GAMEOBJECT with entry 1731 in bits 24..47.
         let guid = 0xF110_0000_0000_0000 | (1731u64 << 24) | 0x40;
         t.insert(
             guid::entry(guid).unwrap(),
@@ -324,18 +265,8 @@ mod tests {
         assert_eq!(t.get(guid).map(|g| g.lock_id), Some(38));
     }
 
-    /// **`data[0]` and `data[1]` are different questions, and a GENERIC object can answer them
-    /// differently** — the pin that replaces 0766's INTERIM proxy (decision 2259).
-    ///
-    /// `data[1]` (semantic `0x12`, `0x5f4830`) is mouseover ELIGIBILITY: is this hoverable at all.
-    /// `data[0]` (semantic `0x13`, `0x5f8630`) is PLACEMENT: does its plate follow the cursor or
-    /// take the corner seat. Reading one as the other is exactly the mistake 0766 named as a proxy.
-    ///
-    /// The two rows are real, taken from the reference client's own `gameobjectcache.wdb`
-    /// (build 5875): `Brill` (entry 1630) is hoverable *and* cursor-seated, while
-    /// `Doodad_WoodSignPointerNice10` (175656) — the same family of wooden pointer sign — is
-    /// hoverable and CORNER-seated. Same model family, opposite answers, which is why the type
-    /// alone could never have been the key.
+    /// Real rows from the 1.12 client's `gameobjectcache.wdb`: two pointer signs, both hoverable,
+    /// one cursor-seated and one corner-seated.
     #[test]
     fn a_generic_can_be_hoverable_and_still_corner_seated() {
         let mut t = GameObjectTemplates::default();
@@ -361,9 +292,7 @@ mod tests {
         );
     }
 
-    /// The fork's key exists for GENERIC(5) and for no other type: `0x621b00` answers semantic
-    /// `0x13` for exactly one of the 31 types, so `data[0]` is never read as a placement flag
-    /// anywhere else — a CHEST's `data[0]` is its lockId, and must not move its tooltip.
+    /// `0x621b00` answers semantic `0x13` for GENERIC(5) alone.
     #[test]
     fn no_other_type_reads_data0_as_the_placement_fork() {
         let mut t = GameObjectTemplates::default();
diff --git a/crates/benilla-app/src/hover_log.rs b/crates/benilla-app/src/hover_log.rs
index 75113601..66133912 100644
--- a/crates/benilla-app/src/hover_log.rs
+++ b/crates/benilla-app/src/hover_log.rs
@@ -1,21 +1,10 @@
-//! `hover_log.rs` — the **hover-cost recorder** (`WOW_HOVER_LOG`).
+//! The hover-cost recorder (`WOW_HOVER_LOG`): every frame to a CSV, tagged with what the tooltip
+//! showed, and a report at exit ranking cost by tooltip state.
 //!
-//! The director reports dropped frames while hovering bag items and spells. Reproducing that needs
-//! a live session and a *hand* on the mouse, which the headless capture harness cannot supply and
-//! reading `[ui-cost]` lines off a terminal cannot survive: the interesting frames are a handful of
-//! spikes inside thousands of quiet ones. So this records **every frame** to a file, tagged with
-//! what the tooltip was showing at the time, and prints a report at exit that ranks the cost
-//! *against the tooltip state* — hovering vs not, and which hover.
-//!
-//! Run: `WOW_HOVER_LOG=1 cargo run --release -p benilla` (writes `target/hover-log.csv`; a path
-//! value writes there instead). Hover whatever feels bad, for as long as you like, then quit — the
-//! report prints to the terminal and the raw rows stay in the file.
-//!
-//! Columns are one frame each: the wall frame time and the process-CPU delta (the meter vsync
-//! cannot rail — `perf.rs`), the UI pass's own phase split (tick/resolve/measure/extract/diff,
-//! μs — the same marks `WOW_UI_COST=1` prints), and the tooltip context (shown, line count, owner
-//! frame, first line). A spike with flat UI phases is NOT a UI-pass cost, and that negative is the
-//! most valuable thing this can say.
+//! `WOW_HOVER_LOG=1` writes `benilla-config/Diagnostics/hover-log.csv`; any other value is a path.
+//! Columns per frame: wall time, process-CPU delta, the UI pass's phase split in microseconds
+//! (the `WOW_UI_COST=1` marks), the mesh rebuild's split, and the tooltip (owner, line count,
+//! first line). A spike with flat UI phases is not a UI-pass cost.
 
 use std::io::Write;
 
@@ -24,15 +13,10 @@ use bevy::time::Real;
 
 use benilla_ui::script::UiScript;
 
-/// The per-frame phase split this recorder writes to the CSV. Produced and owned by the UI pass
-/// itself (decision 1174) — an instrument reads the fact, it does not define it.
 use crate::ui_script::{UiCostWanted, UiFrameCost};
 
-/// Where to write, from `$WOW_HOVER_LOG`: unset ⇒ off, `1` ⇒
-/// `benilla-config/Diagnostics/hover-log.csv` (the one folder, 0954/1486 — never the cwd-relative
-/// `target/…` this once named, which is the install folder when the binary is launched from
-/// inside it), anything else ⇒ that path. A hermetic run has no folder: `1` is then off, and
-/// says so, the sound probe's rule.
+/// Where to write, from `$WOW_HOVER_LOG`: unset or `0` is off, `1` is
+/// `benilla-config/Diagnostics/hover-log.csv` (off in a hermetic run), anything else a path.
 fn log_path() -> Option<String> {
     match std::env::var("WOW_HOVER_LOG") {
         Err(_) => None,
@@ -51,23 +35,21 @@ fn log_path() -> Option<String> {
     }
 }
 
-/// Is the recorder on? Read once — the phase marks in the UI pass (`extract::tick_script`/`paint_script`) consult this every frame.
+/// Whether the recorder is on, read once; the UI pass's phase marks consult it every frame.
 pub fn enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| log_path().is_some())
 }
 
-/// One recorded frame, kept in memory for the exit report (the file gets it either way).
+/// One recorded frame, kept for the exit report.
 #[derive(Clone)]
 struct Row {
     frame_ms: f32,
     cpu_ms: f32,
     cost: UiFrameCost,
-    /// The RENDER-side half of the same frame (`ui_pass::UiMeshCost`). Added after the 1625 fix
-    /// left the symptom standing: the UI-script phases read flat on a hovered frame while the mesh
-    /// rebuild below them was doing whole-interface work, and this recorder could not see it.
+    /// The same frame's mesh rebuild cost.
     mesh: crate::ui_pass::UiMeshCost,
-    /// The tooltip context: `None` = no tooltip up. `(owner frame, line count, first line)`.
+    /// `(owner frame, line count, first line)`, or `None` with no tooltip up.
     tip: Option<(String, i64, String)>,
 }
 
@@ -87,8 +69,7 @@ impl Plugin for HoverLogPlugin {
             return;
         }
         let path = log_path().expect("enabled() checked");
-        // Ask the UI pass for its phase split. `init_resource` first so this holds whichever
-        // plugin builds first — `UiScriptPlugin`'s own init is then a no-op (decision 1174).
+        // `init_resource` first so this holds whichever plugin builds first.
         app.init_resource::<UiCostWanted>();
         app.world_mut().resource_mut::<UiCostWanted>().0 = true;
         if let Some(dir) = std::path::Path::new(&path).parent() {
@@ -118,8 +99,7 @@ impl Plugin for HoverLogPlugin {
     }
 }
 
-/// The tooltip context, asked of the VM itself so it reads the same names the director sees. One
-/// tiny chunk per frame, only while recording.
+/// The tooltip context, asked of the Lua VM, once per frame while recording.
 fn tooltip_context(script: &UiScript) -> Option<(String, i64, String)> {
     let chunk = r#"
         if not GameTooltip or not GameTooltip:IsShown() then return "" end
@@ -234,34 +214,24 @@ fn summarize(label: &str, rows: &[&Row]) -> String {
     let ui_us = |f: fn(&UiFrameCost) -> u128| {
         rows.iter().map(|r| f(&r.cost) as f64).sum::<f64>() / f64::from(n)
     };
-    // The churn number: mean FontStrings re-shaped per frame. A settled UI sits at 0.00; anything
-    // above it in a steady hover population is a string whose measure key moves every frame.
+    // Mean FontStrings re-shaped per frame; a settled UI sits at 0.
     let measured = rows.iter().map(|r| r.cost.measured as f64).sum::<f64>() / f64::from(n);
-    // What the frame actually DID, as opposed to what it cost: how often the layout fixpoint ran
-    // (a solve walks the whole anchor graph, not the tooltip's corner of it) and how often the
-    // extract gate skipped the conversion+rasterize loop outright.
+    // How often the layout fixpoint ran, and how often the extract gate skipped conversion.
     #[allow(clippy::cast_precision_loss)]
     let solves = rows.iter().map(|r| r.cost.solves as f64).sum::<f64>() / f64::from(n);
-    // The term `solves` hides (decision 1625): a solve that had to DERIVE the layout graph first
-    // costs an order of magnitude more than one that used the ledger, and both count as one solve.
-    // The law is zero — anything else is a write site that gave up naming its node, which
-    // `WOW_LAYOUT_DERIVE_TRACE=<secs>:<n>` will backtrace on a live run.
+    // Solves that had to derive the layout graph first; should be zero, and
+    // `WOW_LAYOUT_DERIVE_TRACE=<secs>:<n>` backtraces one on a live run.
     let derives = rows.iter().map(|r| r.cost.derives as f64).sum::<f64>() / f64::from(n);
-    // The RENDER half of the same frame. `rebuilt%` is the one to read first: a population that
-    // rebuilds the mesh on every frame is paying whole-interface work per frame, whatever the
-    // script-pass phases say.
+    // The mesh half: a population that rebuilds every frame pays whole-interface work.
     let mesh_us = |f: fn(&crate::ui_pass::UiMeshCost) -> u128| {
         rows.iter().map(|r| f(&r.mesh) as f64).sum::<f64>() / f64::from(n)
     };
     let rebuilt = 100.0 * rows.iter().filter(|r| r.mesh.rebuilt).count() as f32 / n;
     let mesh_runs = rows.iter().map(|r| r.mesh.runs as f64).sum::<f64>() / f64::from(n);
-    // The number that reaches Bevy: a rewritten batch re-extracts, and `rewrites` tracking `runs`
-    // means the skip gate is being defeated for every batch at once (decision 1632).
+    // A rewritten batch re-extracts; `rewrites` tracking `runs` means the skip gate never holds.
     let mesh_rw = rows.iter().map(|r| r.mesh.rewrites as f64).sum::<f64>() / f64::from(n);
     let skips = 100.0 * rows.iter().filter(|r| r.cost.skipped).count() as f32 / n;
-    // Counted against the DROPPED threshold, not the raw budget: synced wall time rails at the
-    // display's present grant and jitters around it, so counting frames over 16.7 ms mostly counts
-    // jitter (`perf.rs`'s `DROPPED_FACTOR` — a missed interval is what a player feels).
+    // Over 1.5 budgets, not the raw budget: vsynced wall time jitters around the interval.
     let dropped = rows
         .iter()
         .filter(|r| r.frame_ms > crate::perf::FRAME_BUDGET_MS * 1.5)
@@ -299,10 +269,7 @@ fn summarize(label: &str, rows: &[&Row]) -> String {
     )
 }
 
-/// At quit: the ranked read. Splits the run by tooltip state — that split IS the question, and a
-/// per-owner breakdown says whether one hover channel (bag slot vs spell button) is the expensive
-/// one. The worst frames print with their tooltip context so a spike is attributable to what was
-/// under the cursor at the time.
+/// At quit: the report, split by tooltip state and owner, with the worst frames' tooltips.
 fn report_on_exit(mut exits: MessageReader<AppExit>, mut rec: ResMut<Recorder>) {
     if exits.read().next().is_none() {
         return;
@@ -316,10 +283,8 @@ fn report_on_exit(mut exits: MessageReader<AppExit>, mut rec: ResMut<Recorder>)
     println!("{}", report(&rows, &rec.path));
 }
 
-/// Re-read a recorded CSV and print the report — `WOW_HOVER_LOG_REPORT=<path>`, handled before the
-/// app starts (see `main`). The analysis moves faster than the sessions that feed it: a question
-/// this report cannot yet answer is one column away, and re-deriving it from rows already on disk
-/// costs nobody a second play session.
+/// Re-reads a recorded CSV and prints the report (`WOW_HOVER_LOG_REPORT=<path>`, before the app
+/// starts).
 pub fn report_recorded_file(path: &str) {
     let text = match std::fs::read_to_string(path) {
         Ok(t) => t,
@@ -341,8 +306,7 @@ pub fn report_recorded_file(path: &str) {
     println!("{}", report(&rows, path));
 }
 
-/// One CSV line back into a [`Row`]. Splits on commas OUTSIDE quotes (the text columns carry
-/// commas and doubled quotes — `cell`'s escaping, read back).
+/// One CSV line back into a [`Row`], splitting on commas outside quotes.
 fn parse_row(line: &str) -> Option<Row> {
     let mut fields: Vec<String> = Vec::new();
     let mut cur = String::new();
@@ -363,8 +327,7 @@ fn parse_row(line: &str) -> Option<Row> {
     if fields.len() < 17 {
         return None;
     }
-    // The render-side columns are APPENDED (a pre-1625 recording has none) — absent reads as zero,
-    // the same posture `spliced` took when it was added.
+    // Later columns are appended at the end, and an older recording without them reads zero.
     let n = |i: usize| fields.get(i).and_then(|f| f.parse().ok()).unwrap_or(0);
     let mesh = crate::ui_pass::UiMeshCost {
         rebuilt: n(18) > 0,
@@ -398,11 +361,7 @@ fn parse_row(line: &str) -> Option<Row> {
             solves: num(9)? as u64,
             derives: num(10)? as u64,
             skipped: num(11)? != 0.0,
-            // Appended column (absent in pre-splice recordings — those read back as 0).
             spliced: fields.get(17).and_then(|f| f.parse().ok()).unwrap_or(0),
-            // Appended after the mesh block for the same reason `spliced` was appended after
-            // the tip block: a new column goes on the END so every recording made before it
-            // still reads (decision 1638).
             dropped: fields.get(25).and_then(|f| f.parse().ok()).unwrap_or(0),
         },
         mesh,
@@ -427,7 +386,7 @@ fn report(rows: &[Row], path: &str) -> String {
     out.push('\n');
     out.push_str(&summarize("tooltip up", &hover));
     out.push('\n');
-    // Per hover target, busiest first — one line per owner frame the tooltip was anchored to.
+    // Per owner frame, busiest first.
     let mut by_owner: std::collections::BTreeMap<String, Vec<&Row>> = Default::default();
     for r in &hover {
         if let Some((owner, _, _)) = &r.tip {
@@ -440,11 +399,7 @@ fn report(rows: &[Row], path: &str) -> String {
         out.push_str(&summarize(&format!("  ↳ {owner}"), rs));
         out.push('\n');
     }
-    // The split that separates a STEADY tax from a per-CHANGE one: frames that ran the layout
-    // fixpoint against frames that did not. A hover whose quiet frames are as expensive as its
-    // solving ones has a per-frame problem; one where the cost lives entirely in the solving
-    // frames is paying per content CHANGE — and moving the mouse across a bag grid changes content
-    // constantly, which is the same felt hitch by a different mechanism and a different fix.
+    // Frames that solved layout against those that did not: a steady tax or a per-change one.
     let solved: Vec<&Row> = hover
         .iter()
         .copied()
@@ -460,11 +415,8 @@ fn report(rows: &[Row], path: &str) -> String {
     out.push_str(&summarize("tooltip up · frames that did NOT", &quiet));
     out.push('\n');
 
-    // The churn roll-up: which strings the font engine was asked to re-shape, and on how many
-    // frames. A string appearing on hundreds of frames is a measure key that never settles — the
-    // per-frame re-shape and the forced second resolve both hang off it, and it is the fix's
-    // target. Counted per frame it appears on, not per request, so one loud string reads as one
-    // row.
+    // Re-shaped strings by frames seen; one on hundreds of frames has a measure key that never
+    // settles.
     let mut churn: std::collections::HashMap<String, (usize, usize)> = Default::default();
     for r in rows {
         for t in &r.cost.measured_texts {
@@ -482,9 +434,7 @@ fn report(rows: &[Row], path: &str) -> String {
         }
     }
 
-    // The worst frames, with what was under the cursor.
-    // Ranked by CPU, not wall: under vsync every wall reading rails at the present interval and
-    // says nothing (`perf.rs`) — CPU is the cost meter the rail cannot fool.
+    // The worst frames by CPU, since vsynced wall time rails at the present interval.
     let mut worst = rows.to_vec();
     worst.sort_by(|a, b| b.cpu_ms.total_cmp(&a.cpu_ms));
     out.push_str(
diff --git a/crates/benilla-app/src/items.rs b/crates/benilla-app/src/items.rs
index e30d9ba5..6006005b 100644
--- a/crates/benilla-app/src/items.rs
+++ b/crates/benilla-app/src/items.rs
@@ -1,24 +1,7 @@
-//! The item layer — decision 0068's T2 (containers) groundwork.
+//! The item layer: item objects in the guid index and the item template cache.
 //!
-//! The wire splits item knowledge in two:
-//!
-//! - **Objects** — the item/container *instances* the server streamed at us (`ItemCreate`: our own
-//!   inventory at login, loot, trades; they are private, so only ours ever arrive). **An item is
-//!   an object** (decision 2334): it is an entity in the one guid index with the same
-//!   [`ObjectStore`] every unit has — `Guid` + `ObjectStore` + [`ItemObject`] — created, merged
-//!   and destroyed by the object layer's handlers like any other kind, its field edges on the
-//!   same watch (`FieldChanged`, kind `Item`/`Container`), gone with the session's sweep. Which
-//!   *slot* holds a guid lives one level up, in the player descriptor's `INV_SLOT`/`PACK_SLOT`
-//!   arrays and a bag's `CONTAINER_FIELD_SLOT` array; [`crate::net::Objects`] resolves those guids
-//!   to the item's fields. Its countdowns (temporary enchants, its own lifetime) are its own
-//!   [`Countdowns`] component — the reference's per-object deadline cells (decision 2340).
-//!
-//! - **Templates** — the static item *definitions* (`SMSG_ITEM_QUERY_SINGLE_RESPONSE`: name,
-//!   quality, class, display id), keyed by entry and shared by every copy. The exact twin of
-//!   [`crate::names::NameCache`], with the same **ask-once** discipline: [`Items::template`]
-//!   returns the answer when known, otherwise sends the query (deduped while in flight) and
-//!   reports "not yet". Negative answers are cached — a bad entry never becomes a query loop.
-//!   Templates survive disconnect: item definitions are stable across sessions.
+//! An item is `Guid` + [`ObjectStore`] + [`ItemObject`] in the guid index; item fields are private,
+//! so only our own arrive. Templates are keyed by entry, asked once, and survive disconnect.
 
 use std::time::{Duration, Instant};
 
@@ -31,20 +14,17 @@ use bevy::ecs::system::SystemParam;
 use crate::net::{ClientCommand, Guid, GuidIndex, NetCommands, ObjectStore, Objects};
 use crate::query_cache::QueryCache;
 
-/// **An item or container entity's kind** — the reference's `TYPEMASK_ITEM` / `TYPEMASK_CONTAINER`
-/// on the one object index (decision 2334). An item is `Guid` + [`ObjectStore`] + this; it has no
-/// `NetEntity` and no `Transform` because it has no model and no pose. Every system that iterates
-/// stores as *units* filters this out (`Without<ItemObject>`): an item block's dwords overlap the
-/// unit block's indices, so an unfiltered unit read of an item's store answers with item fields.
+/// An item or container entity's kind (`TYPEMASK_ITEM` / `TYPEMASK_CONTAINER`), with no model or
+/// pose. Unit readers filter it out (`Without<ItemObject>`): an item block's dwords overlap the
+/// unit block's indices.
 #[derive(Component, Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) struct ItemObject {
-    /// `TYPEMASK_CONTAINER` — the create said so; a bag's slot array lives past the item block.
+    /// `TYPEMASK_CONTAINER`: a bag's slot array lives past the item block.
     pub(crate) container: bool,
 }
 
-/// Spawn an item object into the index — the item half of the object layer's create, and what a
-/// fixture seeds with. The seed is never merged (the create-time notify-suppress, 2297); a
-/// re-create of a live guid takes the values path in the handler, not this.
+/// Spawn an item object into the index. The seed is never merged, so the create raises no field
+/// notify; a re-create of a live guid takes the handler's values path instead.
 pub(crate) fn spawn_item(
     commands: &mut Commands,
     index: &mut GuidIndex,
@@ -64,31 +44,22 @@ pub(crate) fn spawn_item(
     e
 }
 
-/// The item's enchantment slots — `ITEM_FIELD_ENCHANTMENT`'s 21 dwords, three per slot, and the
-/// reference's seven enchant deadline cells `[obj + 0x324 + slot*4]` (`0x5d9d00`), which end where
-/// the next member begins at `+0x340`.
+/// `ITEM_FIELD_ENCHANTMENT`'s 21 dwords, three per slot; the reference's seven deadline cells at
+/// `obj + 0x324 + slot*4` (`0x5d9d00`) end where the next member begins, at `+0x340`.
 pub(crate) const ENCHANT_SLOTS: usize = 7;
 
-/// **An item's countdowns** — the reference's per-object deadline cells on `CGItem_C` (decision
-/// 2340): its own lifetime at `+0x320` (fed only by `SMSG_ITEM_TIME_UPDATE`, decision 1933) and
-/// one temporary-enchant deadline per enchant slot at `+0x324` (fed only by
-/// `SMSG_ITEM_ENCHANT_TIME_UPDATE`, decision 0920; the item's `ITEM_FIELD_ENCHANTMENT` duration
-/// field is never read for it). Every item object carries one from its spawn, so the cells die
-/// with the object as the reference's do, and a write through `Mut` is the landing the inventory
-/// feeds' [`ItemChanges`] sees.
-///
-/// Absolute deadlines, recomputed on read and never ticked — `0x5d9c60` / `0x5d9d00` subtract
-/// `now` from the cell on every call.
+/// An item's countdowns, the reference's deadline cells on `CGItem_C`: its lifetime at `+0x320`
+/// (fed only by `SMSG_ITEM_TIME_UPDATE`) and one temporary-enchant deadline per slot at `+0x324`
+/// (fed only by `SMSG_ITEM_ENCHANT_TIME_UPDATE`; the enchantment field's duration is never read).
+/// Absolute deadlines, recomputed on every read and never ticked (`0x5d9c60`, `0x5d9d00`).
 #[derive(Component, Clone, Debug, Default, PartialEq, Eq)]
 pub(crate) struct Countdowns {
     lifetime: Option<Instant>,
     enchants: [Option<Instant>; ENCHANT_SLOTS],
 }
 
-/// The two setters' shared store rule (`0x5d9c00`, `0x5d9cc0`): a **signed** `<= 0` clears the
-/// cell — `jle` on the wire value, so `0` and anything with the top bit set both store absence
-/// rather than a 68-year deadline — and anything else parks `now + seconds`, the wire's seconds
-/// times the one `imul 0x3e8`.
+/// The setters' store rule (`0x5d9c00`, `0x5d9cc0`): a signed `<= 0` (`jle`) clears the cell, so a
+/// top-bit value is absence, not a 68-year deadline; anything else parks `now + seconds`.
 fn deadline(seconds: u32) -> Option<Instant> {
     ((seconds as i32) > 0).then(|| Instant::now() + Duration::from_secs(u64::from(seconds)))
 }
@@ -98,8 +69,7 @@ fn left(cell: Option<Instant>) -> Option<Duration> {
     cell.map(|at| at.saturating_duration_since(Instant::now()))
 }
 
-/// The tooltip's read: an elapsed cell is no timer at all (the `!= 0` gate prints the plain
-/// line).
+/// The tooltip's read: an elapsed cell is no timer (its `!= 0` gate prints the plain line).
 fn remaining_ms(cell: Option<Instant>) -> Option<u64> {
     left(cell)
         .filter(|l| !l.is_zero())
@@ -107,9 +77,8 @@ fn remaining_ms(cell: Option<Instant>) -> Option<u64> {
 }
 
 impl Countdowns {
-    /// `SMSG_ITEM_ENCHANT_TIME_UPDATE`'s setter `0x5d9cc0`. The reference indexes the cell array
-    /// with the wire's slot unchecked — a slot past the seventh overruns into the next member;
-    /// this refuses it instead (`false`), as the spell-modifier tables refuse theirs.
+    /// `SMSG_ITEM_ENCHANT_TIME_UPDATE`'s setter `0x5d9cc0`. A slot past the seventh is refused
+    /// (`false`), where the reference indexes unchecked and overruns into the next member.
     pub(crate) fn set_enchant(&mut self, slot: u32, seconds: u32) -> bool {
         let Some(cell) = self.enchants.get_mut(slot as usize) else {
             return false;
@@ -127,55 +96,36 @@ impl Countdowns {
         self.enchants.get(slot as usize).copied().flatten()
     }
 
-    /// Milliseconds left on the temporary enchant in `slot`, or `None` when that slot carries no
-    /// timer — including an expired one (`0x5d9d00` returns 0 past the deadline, and the tooltip's
-    /// `!= 0` gate then prints the plain name).
+    /// Milliseconds left on the temporary enchant in `slot`; `None` also once expired.
     pub(crate) fn enchant_remaining_ms(&self, slot: u32) -> Option<u64> {
         remaining_ms(self.enchant(slot))
     }
 
-    /// [`Self::enchant_remaining_ms`] at **display granularity**: floored to the whole second.
-    ///
-    /// The snapshot feeds read this one. The tooltip's bucket ladder is ceil at day/hour/min and
-    /// truncate at seconds, so every value inside one second renders the same line — but a raw
-    /// per-ms read makes the *snapshot* differ every frame, which held the 1439 gates open and
-    /// fired `UNIT_INVENTORY_CHANGED` at frame rate for as long as a poison ticked (director
-    /// report, 2026-08-19: the char window's cost, and its refusal to settle after closing).
-    /// Floored, the snapshot moves once a second — exactly as often as its rendering can.
-    /// The live per-ms reader stays for `GetWeaponEnchantInfo` ([`Self::enchant_deadline_ms`]),
-    /// whose per-frame push is the reference's own recompute-per-call (`0x5d9d00`).
+    /// [`Self::enchant_remaining_ms`] floored to the second, for the snapshot feeds: a per-ms read
+    /// would fire `UNIT_INVENTORY_CHANGED` every frame while a timer runs.
     pub(crate) fn enchant_remaining_display_ms(&self, slot: u32) -> Option<u64> {
         self.enchant_remaining_ms(slot).map(|ms| ms - ms % 1000)
     }
 
-    /// The same deadline read **without** the tooltip's expired-is-absent collapse: `Some(0)` for a
-    /// timer that has run out, `None` only when the slot never had one.
-    ///
-    /// `GetWeaponEnchantInfo` needs the two apart where the tooltip does not. Its expiration return
-    /// is `max(0, deadline − now)` from the client-local deadline array (`0x5d9d00`, subtract on
-    /// read), so an enchant whose timer has elapsed answers the NUMBER 0, and
-    /// `BuffFrame_Enchant_OnUpdate` then draws "0 s" and pulses the icon. Collapsing that to nil
-    /// would silently hide a expiring enchant's last state.
+    /// The deadline read without the expired-is-absent collapse: `Some(0)` once run out, `None`
+    /// only when never set. `GetWeaponEnchantInfo` returns `max(0, deadline - now)` (`0x5d9d00`),
+    /// so an elapsed enchant answers 0 and `BuffFrame_Enchant_OnUpdate` draws "0 s".
     pub(crate) fn enchant_deadline_ms(&self, slot: u32) -> Option<u64> {
         left(self.enchant(slot)).map(|l| l.as_millis() as u64)
     }
 
-    /// Milliseconds left on the item's own lifetime, or `None` when it carries no timer —
-    /// including an elapsed one.
+    /// Milliseconds left on the item's own lifetime; `None` also once elapsed.
     pub(crate) fn lifetime_remaining_ms(&self) -> Option<u64> {
         remaining_ms(self.lifetime)
     }
 
-    /// [`Self::lifetime_remaining_ms`] at **display granularity** — floored to the whole second,
-    /// for the same reason [`Self::enchant_remaining_display_ms`] is.
+    /// [`Self::lifetime_remaining_ms`] floored to the whole second, as the enchant read is.
     pub(crate) fn lifetime_remaining_display_ms(&self) -> Option<u64> {
         self.lifetime_remaining_ms().map(|ms| ms - ms % 1000)
     }
 
-    /// This item's share of [`ItemChanges::countdown_steps`]: each live cell contributes
-    /// `floor(seconds left) + 1`, an unset or elapsed one 0 — so the final `Some(0) → None`
-    /// collapse (the tooltip reverting to the plain enchant name, the lifetime line vanishing) is
-    /// its own step, one frame after the deadline elapses.
+    /// This item's share of [`ItemChanges::countdown_steps`]: `floor(seconds left) + 1` per live
+    /// cell, 0 when unset or elapsed, so the final `Some(0)` to `None` collapse is its own step.
     fn steps(&self, now: Instant) -> u64 {
         std::iter::once(self.lifetime)
             .chain(self.enchants)
@@ -198,11 +148,7 @@ type ItemMoved = (
     Or<(Changed<ObjectStore>, Changed<Countdowns>)>,
 );
 
-/// **Did any item object move this frame** — the gate input the inventory feeds watch in place of
-/// the item map's old epoch (decision 2334): a create, a values delta, a countdown landing or a
-/// destroy on any item entity. `Changed` covers the first three (a spawn is a change, and so is a
-/// write to either component), the removal reader the fourth — a bag's slot going empty is the
-/// player's own field, but the *item* vanishing is only this.
+/// Whether any item object was created, written or destroyed this frame; the inventory feeds' gate.
 #[derive(SystemParam)]
 pub(crate) struct ItemChanges<'w, 's> {
     changed: Query<'w, 's, (), ItemMoved>,
@@ -217,21 +163,15 @@ impl ItemChanges<'_, '_> {
         !self.changed.is_empty() || removed
     }
 
-    /// The value a gated feed watches instead of holding its gate open per-frame while a
-    /// countdown runs: it moves exactly when some **displayable** countdown can — the two
-    /// second-floored reads a bag/equipment snapshot renders. The sum of every item's
-    /// [`Countdowns`] steps; between landings (which [`Self::moved`] reports) each term only
-    /// falls, so a displayable change can never be masked by another. No live cell — the
-    /// overwhelmingly common case — sums to 0.
+    /// The sum of every item's [`Countdowns`] steps: it moves exactly when a second-floored read
+    /// can, and each term only falls between landings, so no change masks another.
     pub(crate) fn countdown_steps(&self) -> u64 {
         let now = Instant::now();
         self.countdowns.iter().map(|c| c.steps(now)).sum()
     }
 }
 
-/// **The player's inventory, as one read** — what a bag, paper-doll or spellbook feed resolves
-/// its slots from (decision 2334): the self descriptor's slot arrays and their change tick, the
-/// object lookup those guids resolve through, and the item entities' own change watch.
+/// The player's inventory as one read: the self descriptor, the object lookup and the item watch.
 #[derive(SystemParam)]
 pub(crate) struct Inventory<'w, 's> {
     pub(crate) self_store: Query<'w, 's, &'static ObjectStore, With<crate::net::SelfPlayer>>,
@@ -241,9 +181,7 @@ pub(crate) struct Inventory<'w, 's> {
     pub(crate) changes: ItemChanges<'w, 's>,
 }
 
-/// The slice of an item template that equipment rendering + combat animation consume (decisions
-/// 0072/0073): the ItemDisplayInfo key, the two placement inputs, and the weapon class pair the
-/// swing/ready selectors key on. A Copy **view** of the cached [`ItemInfo`] ([`Items::held`]).
+/// The Copy slice of an [`ItemInfo`] that equipment rendering and combat animation read.
 #[derive(Clone, Copy)]
 pub(crate) struct HeldTemplate {
     pub(crate) display_info_id: u32,
@@ -251,103 +189,61 @@ pub(crate) struct HeldTemplate {
     pub(crate) sheath: u32,
     pub(crate) class: u32,
     pub(crate) subclass: u32,
-    /// `Material` — the item's `Material.dbc` id (1 metal · 2 wood · 5 chain · 6 plate · 7 cloth ·
-    /// 8 leather · 0 undefined). On the wire in `SMSG_ITEM_QUERY_SINGLE_RESPONSE`, and the **only**
-    /// input to the draw/stow sound pick: `SheatheSoundLookups` carries one row per weapon subclass
-    /// per material, and every row of a material agrees — the subclass is inert (decision 0882).
+    /// `Material.dbc` id (1 metal, 2 wood, 5 chain, 6 plate, 7 cloth, 8 leather, 0 undefined), the
+    /// only input to the draw/stow sound: every `SheatheSoundLookups` row of a material agrees.
     pub(crate) material: u32,
 }
 
-/// `SpellItemEnchantment.dbc`'s two consumer columns, loaded once and read by both lanes that
-/// need them: the **visual** by the weapon-glow chain (decision 0805,
-/// [`crate::entities::item_glow`]) and the **name** by the item tooltip's enchant line (decision
-/// 0915, [`crate::ui_items`]). It lives here rather than inside either consumer because it is
-/// item *data*, and because a second loader over one DBC is how a schema quietly drifts.
-///
-/// Optional, like every DBC-backed resource: absent, weapons draw unadorned and no tooltip prints
-/// an enchant line — each lane's own pre-existing behaviour.
+/// `SpellItemEnchantment.dbc`, for the weapon glow ([`crate::entities::item_glow`]) and the
+/// tooltip enchant line ([`crate::ui_items`]). Optional: absent, neither draws.
 #[derive(Resource)]
 pub(crate) struct Enchants(pub(crate) benilla_formats::EnchantCatalog);
 
-/// One enchant SLOT's contribution, as the app resolved it — `(slot index, id, charges,
-/// remaining ms)`. The id is **signed**, because its sign is load-bearing downstream: it picks the
-/// line's colour and nothing else (`0x52c9f9` — `abs(id)` names the DBC row either way).
+/// One enchant slot: `(slot index, id, charges, remaining ms)`. The id is signed: the sign picks
+/// the line's colour only, and `abs(id)` names the DBC row (`0x52c9f9`).
 pub(crate) type EnchantSlot = (u8, i32, u32, Option<u64>);
 
-/// The tooltip lines an item instance's enchant slots contribute — the one place the app turns
-/// enchant *ids* into text (decisions 0915/0920). Every tooltip surface feeds through here, so a
-/// bag hover, a paper-doll hover and an inspect hover can never disagree.
-///
-/// The per-slot gate is the reference's (`0x52c9f9`–`0x52ca23`): `id != 0`, then `abs(id)` must
-/// name a real `SpellItemEnchantment` row — **the sign never changes which row**, only the colour
-/// the engine paints. An id that names no row contributes nothing rather than a placeholder.
-///
-/// `slots` is the caller's source, and it differs by surface for a reason the wire fixes: our own
-/// items stream as OBJECTS, so all 7 `ITEM_FIELD_ENCHANTMENT` slots (plus charges, plus the
-/// `SMSG_ITEM_ENCHANT_TIME_UPDATE` timer) are readable; anybody else's are visible only through
-/// the slots their descriptor broadcasts, which in 1.12 vmangos fills for PERM and TEMP only.
+/// The tooltip lines an item's enchant slots contribute; every tooltip surface feeds through here.
+/// The reference's per-slot gate (`0x52c9f9` to `0x52ca23`): `id != 0` and `abs(id)` names a
+/// `SpellItemEnchantment` row, else nothing. Our own items carry all seven slots; another
+/// player's descriptor carries only the permanent and temporary ones (vmangos).
 pub(crate) fn enchant_lines(
     slots: impl IntoIterator<Item = EnchantSlot>,
     enchants: Option<&Enchants>,
 ) -> Vec<benilla_ui::script::EnchantView> {
     let lines = enchant_lines_quiet(slots, enchants);
-    // One breadcrumb per session the first time any surface resolves an enchant — the
-    // machine-readable "this lane is live" signal for a feature whose whole symptom is ABSENCE
-    // (`entities::item_glow`'s idiom, and the reason this one exists: the enchant ids reaching the
-    // tooltip travel a DIFFERENT wire field from the ones the weapon glow reads, so a silent miss
-    // here would look exactly like an unenchanted item).
+    // Logged once per session: a missing enchant looks exactly like an unenchanted item.
     if !lines.is_empty() {
         static FIRST: std::sync::Once = std::sync::Once::new();
-        // The whole view, not just the name: the countdown and the charges each ride a different
-        // wire lane from the id, so "which of the three arrived" is exactly what this must answer.
+        // The whole view: the id, charges and countdown each ride a different wire lane.
         FIRST.call_once(|| info!("item enchant: {lines:?} (the first resolved this session)"));
     }
     lines
 }
 
-/// `0x5da2c0` — **"has this item already been through the bind question?"**: the instance's
-/// `ITEM_FIELD_FLAGS & 1` (already soulbound), **or** any of its seven live
-/// `ITEM_FIELD_ENCHANTMENT` slots naming a `SpellItemEnchantment` row that binds the item
-/// ([`benilla_formats::EnchantCatalog::binds_the_item`], the ref's `5da300`–`5da320` walk).
-///
-/// One predicate, two consumers — the enchant cursor's bind question
-/// ([`crate::ui_action`]'s `ClickedItem::already_bound`, the `0x495d60` gate) and the item
-/// tooltip's **Soulbound** override (B310). They must agree: an item the cursor considers
-/// already bound is exactly an item whose tooltip says *Soulbound*.
-///
-/// Read off the RAW descriptor, never off the rendered [`enchant_lines`] list. That list is a
-/// *display* view: it drops rows the catalog cannot name, and it drops every
-/// `Flags & 0x2` row outright (the line the reference refuses to print — decision 0928). The two
-/// flag sets **overlap**, so this is not a hypothetical: **Firestone 1-4 and Orb of Fire carry
-/// both bits** — they bind the item AND print no line — so an imbued weapon would read back as
-/// "not bound" from the lines while the reference calls it bound.
+/// `0x5da2c0`: already bound when `ITEM_FIELD_FLAGS & 1` is set or a live enchant slot names a
+/// binding `SpellItemEnchantment` row (`0x5da300` to `0x5da320`). The enchant cursor's bind
+/// question (gate `0x495d60`) and the tooltip's Soulbound line both read it. It reads the raw
+/// descriptor, not [`enchant_lines`]: Firestone and Orb of Fire both bind and print no line.
 pub(crate) fn already_bound(fields: &ObjectFields, cat: Option<&Enchants>) -> bool {
     fields.item_flags().is_some_and(|f| f & 0x1 != 0)
         || (0..7).any(|slot| live_enchant(fields, slot, cat).is_some_and(|id| binds(id, cat)))
 }
 
-/// One `ITEM_FIELD_ENCHANTMENT` slot as the bind checks read it (`495eec:
-/// movl 0x40(%ecx,%eax,4)` with `eax = 3*slot`): the raw id must be **positive** (the ref's `jl`
-/// skip at `495ef4`/`5da306`) and must name a real `SpellItemEnchantment` row (its
-/// `testl %eax,%eax` after the table load). Anything else is "no enchant here".
-///
-/// NB this is the *bind-question* reading, not the *line* reading — the line law names its row
-/// off `abs(id)` and keeps the sign only for the colour ([`enchant_lines`], `0x52c9f9`).
+/// One enchant slot as the bind checks read it (`0x495eec`): the raw id must be positive (`jl` at
+/// `0x495ef4`, `0x5da306`) and name a row, where the tooltip line uses `abs(id)`.
 pub(crate) fn live_enchant(fields: &ObjectFields, slot: u8, cat: Option<&Enchants>) -> Option<u32> {
     let id = u32::try_from(fields.item_enchant(slot)?).ok()?;
     cat.is_some_and(|c| c.0.has_row(id)).then_some(id)
 }
 
-/// `SpellItemEnchantment.Flags & 1` — this enchant soulbinds the item it lands on.
+/// `SpellItemEnchantment.Flags & 1`: this enchant soulbinds the item it lands on.
 pub(crate) fn binds(id: u32, cat: Option<&Enchants>) -> bool {
     cat.is_some_and(|c| c.0.binds_the_item(id))
 }
 
-/// [`enchant_lines`] without the breadcrumb — the same gate and the same naming, for the one
-/// caller that is not a live item: the startup resolve of the whole `ItemRandomProperties` table
-/// ([`random_property_views`]). Routing that through the loud one would fire "the first enchant
-/// resolved this session" at load, every session, which is exactly the signal the breadcrumb
-/// exists to distinguish from silence.
+/// [`enchant_lines`] without the log line, for the load-time resolve of the whole
+/// `ItemRandomProperties` table ([`random_property_views`]).
 fn enchant_lines_quiet(
     slots: impl IntoIterator<Item = EnchantSlot>,
     enchants: Option<&Enchants>,
@@ -358,13 +254,9 @@ fn enchant_lines_quiet(
     let lines: Vec<benilla_ui::script::EnchantView> = slots
         .into_iter()
         .filter(|&(_, id, _, _)| id != 0)
-        // `SpellItemEnchantment.Flags & 0x2` — the row prints NO line at all. Both of the
-        // reference's enchant-line printers open with it and return before they ever read the
-        // name (`6290e4` / `62923e`, each `testb $0x2, 0x5c(...)` → `jne <retl>`). Twelve shipped
-        // rows, one family: the totem-granted weapon imbues, Firestone, Orb of Fire — buffs whose
-        // source already shows elsewhere on screen, so the weapon does not repeat them. Found and
-        // closed while transcribing the *other* bit of that column (decision 0928); 0915 read the
-        // name column alone and printed all twelve.
+        // `SpellItemEnchantment.Flags & 0x2`: no line; both reference printers return before
+        // reading the name (`0x6290e4`, `0x62923e`). Twelve rows: the totem weapon imbues,
+        // Firestone, Orb of Fire.
         .filter(|&(_, id, _, _)| !enchants.0.tooltip_hides_name(id.unsigned_abs()))
         .filter_map(|(slot, id, charges, remaining_ms)| {
             let name = enchants.0.name(id.unsigned_abs())?.to_string();
@@ -380,26 +272,14 @@ fn enchant_lines_quiet(
     lines
 }
 
-/// `ItemRandomProperties.dbc` — the **random-suffix roll**: the "of the Monkey" a drop rolled, and
-/// the enchants that roll grants (decision 1547). One table, two consumers, exactly as in the
-/// reference: the display NAME ([`item_display_name`], its `0x5d8b00`) and the tooltip's enchant
-/// slots 2..6 ([`random_property_lines`], its `0x52b7e0` suffix-row copy).
-///
-/// Optional like every DBC-backed resource: absent, names stay unsuffixed and a rolled item shows
-/// no suffix lines — the behaviour benilla had before this arc.
+/// `ItemRandomProperties.dbc`, the random-suffix roll: a name suffix and tooltip enchant slots
+/// 2..6 (`0x52b7e0`). Optional: absent, names stay unsuffixed.
 #[derive(Resource)]
 pub(crate) struct RandomProperties(pub(crate) benilla_formats::RandomPropertyCatalog);
 
-/// The item's display NAME — the reference's one name formatter `0x5d8b00(entry, randomPropertyId)`,
-/// whose whole law is its two exits: `ITEM_SUFFIX_TEMPLATE` (`"%s %s"`) joined with the roll's
-/// suffix, or the plain template name when the id is 0, negative, past the table, or names a row
-/// with no suffix string.
-///
-/// **Every** display of an item's name goes through here, because in the reference every one of
-/// them goes through that function: the tooltip plate, the `|Hitem:…|h[Name]|h` link (the link is
-/// built FROM this string), the loot row, the chat "You receive loot" line, the auction and mail
-/// rows. A surface that composed the name itself would print "Chipped Claw" where the client prints
-/// "Chipped Claw of the Bear" — which is exactly the drift decision 0888 recorded and this closes.
+/// The item's display name, the reference's one formatter `0x5d8b00(entry, randomPropertyId)`:
+/// `ITEM_SUFFIX_TEMPLATE` (`"%s %s"`) with the roll's suffix, or the plain name when the id names
+/// no suffixed row. Every surface that shows an item name goes through here.
 pub(crate) fn item_display_name(
     base: &str,
     random_property_id: i32,
@@ -411,17 +291,8 @@ pub(crate) fn item_display_name(
     }
 }
 
-/// The tooltip lines a random-property **roll** contributes, for a source that has no item object
-/// to read `ITEM_FIELD_ENCHANTMENT` from — a loot slot, a chat link, an auction or mail row.
-///
-/// This is the reference's mechanism (`0x52b7bf`–`0x52b7fb`), one for one: the tooltip resolves
-/// its `+0x424` randomPropertyId against `ItemRandomProperties.dbc` and copies the row's five
-/// enchant ids into session slots **2..6**, which the enchant family then prints exactly like an
-/// object's own slots (white, since only slots 0/1 ever colour). So the same [`enchant_lines`] gate
-/// runs over them — one law for both id sources, which is the point of routing them through it.
-///
-/// An item OBJECT needs none of this: the server writes the rolled ids into its own enchant slots,
-/// and the object path already reads them.
+/// The tooltip lines of a roll, for a source with no item object: the reference (`0x52b7bf` to
+/// `0x52b7fb`) copies the row's five enchant ids into slots 2..6 and prints them as its own.
 pub(crate) fn random_property_lines(
     row: &benilla_formats::RandomProperty,
     enchants: Option<&Enchants>,
@@ -437,14 +308,8 @@ pub(crate) fn random_property_lines(
     enchant_lines_quiet(slots, enchants)
 }
 
-/// The whole roll table, resolved for the engine — every `ItemRandomProperties` row as the
-/// suffix plus its named enchant lines, ready to push once ([`benilla_ui::script::UiScript::
-/// set_random_properties`]).
-///
-/// Pushed whole rather than asked for per id, because it is a static table the app already holds
-/// and its consumers are click-driven: a chat-link tooltip has no hover re-enter loop, so a late
-/// answer would leave the first click showing an item with no lines. The reference reads its own
-/// loaded DBC store the same way, at draw time, from the id the source supplied.
+/// Every `ItemRandomProperties` row as its suffix and named enchant lines, pushed to the engine
+/// whole: a chat-link tooltip has no hover re-enter, so a per-id ask would miss the first click.
 pub(crate) fn random_property_views(
     props: &RandomProperties,
     enchants: Option<&Enchants>,
@@ -464,11 +329,7 @@ pub(crate) fn random_property_views(
         .collect()
 }
 
-/// The two catalogs a random-suffix **roll** resolves through, as one value: the roll's own table
-/// and the enchant names its five ids land on. They are never useful apart — a roll is a name plus
-/// a set of enchant ids, and both halves come from a DBC the app owns — and every surface that
-/// shows a rolled item needs the pair, so it travels as a pair rather than as two `Option` params
-/// threaded through every loot/link/auction/mail feed.
+/// The two catalogs a random-suffix roll resolves through: the roll table and the enchant names.
 #[derive(Clone, Copy)]
 pub(crate) struct RollCatalogs<'a> {
     pub(crate) props: Option<&'a RandomProperties>,
@@ -476,22 +337,19 @@ pub(crate) struct RollCatalogs<'a> {
 }
 
 impl RollCatalogs<'_> {
-    /// No DBC catalogs — what the unit tests run with (no install), and what a shipping session
-    /// falls back to when the tables are missing: the plain name, and no suffix lines.
+    /// No DBC catalogs: the plain name and no suffix lines.
     #[cfg(test)]
     pub(crate) const NONE: RollCatalogs<'static> = RollCatalogs {
         props: None,
         enchants: None,
     };
 
-    /// [`item_display_name`] — the item's name with this roll's suffix joined on.
+    /// [`item_display_name`] with this roll's suffix.
     pub(crate) fn name(&self, base: &str, random_property_id: u32) -> String {
         item_display_name(base, random_property_id as i32, self.props)
     }
 
-    /// [`random_property_lines`] for one id — the roll's enchant slots 2..6, resolved and named.
-    /// The live surfaces do NOT call this (the engine resolves the lines itself, off the pushed
-    /// table); it is the app-side check that the id → row → slot mapping is what the law says.
+    /// [`random_property_lines`] for one id; the live surfaces read the engine's pushed table.
     #[cfg(test)]
     pub(crate) fn lines(&self, random_property_id: u32) -> Vec<benilla_ui::script::EnchantView> {
         match self.props.and_then(|p| p.0.get(random_property_id as i32)) {
@@ -501,39 +359,29 @@ impl RollCatalogs<'_> {
     }
 }
 
-/// The item stores: instances by guid, templates by entry (+ the in-flight ask-once set).
-/// Filled by the net bridge; read by the container APIs (`GetContainerItemInfo` and kin).
+/// Item templates by entry, asked once, and the enchant times queued for items not yet held.
 #[derive(Resource, Default)]
 pub(crate) struct Items {
-    /// The template cache — ask-once through [`QueryCache`] (decision 2288); a `None` answer is
-    /// the server's "unknown entry" (the top-bit miss branch), cached so it is never re-asked.
+    /// A `None` answer is the server's unknown entry, cached so it is never re-asked.
     templates: QueryCache<u32, ItemInfo>,
-    /// Entries whose template landed since the last [`Self::take_fresh`] drain — the push half of
-    /// the tooltip store (every landed template goes to the UI unprompted, so the first hover of
-    /// an item whose name is already on screen never misses).
+    /// Landed since the last [`Self::take_fresh`]; pushed to the UI unprompted.
     fresh: Vec<u32>,
-    /// **`PlayerPendingItemExpiration`** — the temporary-enchant updates that named an item not
-    /// yet held, kept for the item's arrival (decision 2340). The reference's `0x1EB` arm, on an
-    /// item-lookup miss, links a `{item guid, slot, seconds}` record onto the active player's list
-    /// (`0x5ebd40`, the list at `CGPlayer_C + 0x1cc8`); `0x5ebde0` walks it when an item of ours is
-    /// set up (`0x5d8440`), applies each match through the setter — `seconds` counted from then,
-    /// not from the packet — and unlinks it. Records for an item that never arrives live as long
-    /// as the player object: here, the session. The item-lifetime arm `0x1EA` has no such list.
+    /// The reference's `PlayerPendingItemExpiration` list (`0x5ebd40`, at `CGPlayer_C + 0x1cc8`):
+    /// `(guid, slot, seconds)` enchant updates for an item not yet held. `0x5ebde0` applies them
+    /// when the item is set up (`0x5d8440`), counting seconds from then; they live as long as the
+    /// player, here the session. `SMSG_ITEM_TIME_UPDATE` has no such list.
     pending_enchant_times: Vec<(u64, u32, u32)>,
 }
 
 impl Items {
-    /// `SMSG_ITEM_ENCHANT_TIME_UPDATE` named an item we do not hold: keep it for the item's
-    /// arrival ([`Self::pending_enchant_times`]'s `0x5ebd40`). The caller has checked the active
-    /// player resolves — the reference queues onto a player object, and drops the update when
-    /// none resolves.
+    /// Queue an `SMSG_ITEM_ENCHANT_TIME_UPDATE` for an item not held. The caller has checked the
+    /// active player resolves: the reference drops the update when none does.
     pub(crate) fn queue_enchant_time(&mut self, guid: u64, slot: u32, seconds: u32) {
         debug!("enchant timer: item {guid:#x} not held — queued for its arrival");
         self.pending_enchant_times.push((guid, slot, seconds));
     }
 
-    /// The item `guid` arrived: its queued enchant updates, in arrival order, unlinked — what
-    /// `0x5ebde0` replays through the setter.
+    /// The item `guid` arrived: its queued enchant updates in arrival order, unlinked (`0x5ebde0`).
     pub(crate) fn take_enchant_times(&mut self, guid: u64) -> Vec<(u32, u32)> {
         let mut taken = Vec::new();
         self.pending_enchant_times.retain(|&(g, slot, seconds)| {
@@ -546,10 +394,8 @@ impl Items {
         taken
     }
 
-    /// The template for `entry`, if known. On a miss, asks the server (once per entry per
-    /// connection; `guid` rides along when the ask is about a concrete item, `0` for
-    /// template-only) and returns `None` — call again after the answer lands. A cached negative
-    /// (server doesn't know the entry) is also `None`, without a re-ask.
+    /// The template for `entry` if known; a miss asks once per entry per connection (`guid` rides
+    /// along, `0` for template-only). A cached negative is also `None`, without a re-ask.
     pub(crate) fn template(
         &self,
         entry: u32,
@@ -562,18 +408,13 @@ impl Items {
         })
     }
 
-    /// Whether the server has ANSWERED the `entry` query with "unknown item" — the cached
-    /// negative, distinct from a still-pending ask (both read `None` from [`Self::template`]).
-    /// The cast-fail redisplay queue (decision 0552) keys on it: pending → keep waiting for the
-    /// answer (the ref's `DBCACHECALLBACK` redisplay), negative → give up and show the ref's
-    /// `"UNKNOWN"` fallback instead of waiting forever.
+    /// Whether the server answered `entry` as unknown, not still pending; the cast-fail redisplay
+    /// then shows the reference's `"UNKNOWN"` instead of waiting.
     pub(crate) fn template_answered_unknown(&self, entry: u32) -> bool {
         self.templates.answered_unknown(entry)
     }
 
-    /// The held/worn display head for `entry` — the [`HeldTemplate`] view of [`Self::template`]
-    /// (same ask-once discipline, template-only ask). Equipment rendering + the swing selector
-    /// consume this Copy slice instead of borrowing the full info.
+    /// The [`HeldTemplate`] view of [`Self::template`], asked template-only.
     pub(crate) fn held(&self, entry: u32, commands: &NetCommands) -> Option<HeldTemplate> {
         self.template(entry, 0, commands).map(|i| HeldTemplate {
             display_info_id: i.display_info_id,
@@ -585,10 +426,7 @@ impl Items {
         })
     }
 
-    /// [`Self::template`]'s **read-only** twin: the record for `entry` only if it is already
-    /// cached, and never an ask. For callers holding `&Items` — the cast ladder's equipped-item
-    /// rung runs inside a `&Items` borrow, and by the time a button is pressed the greying feed
-    /// that shares its search has had the template for many frames.
+    /// [`Self::template`] without the ask: the cached record only.
     pub(crate) fn template_cached(&self, entry: u32) -> Option<&ItemInfo> {
         self.templates.get(entry)
     }
@@ -598,26 +436,18 @@ impl Items {
         if info.is_some() {
             self.fresh.push(entry);
         }
-        // A NEGATIVE answer moves the generation too: it flips the entry from "still asking" to
-        // "answered unknown", which is a real display transition for anything that waits on the
-        // ask (the cast-fail redisplay's `"UNKNOWN"` literal, [`Self::template_answered_unknown`]).
+        // A negative answer moves the generation too: "still asking" to "answered unknown" is a
+        // display transition for the cast-fail redisplay.
         self.templates.insert(entry, info);
     }
 
-    /// The landed-template broadcast counter — the cache's own generation, bumped by every
-    /// landed answer, positive or negative. The **broadcast** twin of [`Self::fresh`]: `fresh`
-    /// is a DRAIN (exactly one consumer can take it — the tooltip feed does), so a second
-    /// consumer that caches a template-derived view needs its own signal; it keeps the epoch it
-    /// last resolved at and re-resolves when it advances — the modern stand-in for the ref's
-    /// `DBCACHECALLBACK` redisplay (`0x6e29b0`), which is how the real client repaints a view
-    /// drawn while the item cache was still answering (decision 0660).
+    /// Bumped by every landed answer, for consumers besides the drain; the stand-in for the
+    /// reference's `DBCACHECALLBACK` redisplay (`0x6e29b0`).
     pub(crate) fn template_epoch(&self) -> u64 {
         self.templates.generation()
     }
 
-    /// Drain the entries whose template landed since the last drain (see the `fresh` field).
-    /// Every entry with a CACHED template — the re-push sweep's domain (a `$z`-style
-    /// player-state input changing means every already-pushed view may be stale).
+    /// Every entry with a cached template.
     pub(crate) fn cached_template_ids(&self) -> Vec<u32> {
         self.templates
             .iter()
@@ -625,31 +455,19 @@ impl Items {
             .collect()
     }
 
+    /// Drain the entries whose template landed since the last drain.
     pub(crate) fn take_fresh(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.fresh)
     }
 
-    /// Disconnect: drop the instances (the server re-streams inventory at login) and the in-flight
-    /// asks (a query dropped by a dead writer must be re-askable); keep the templates (static).
-    /// Release the ask-once latch without dropping what the cache LEARNED — the world-enter
-    /// counterpart to [`Self::clear_session`]'s disconnect teardown.
-    ///
-    /// `template` marks an entry pending *before* the send, and a send made while the io thread
-    /// holds no writer evaporates. Nothing told the cache, so the entry stayed pending for the
-    /// life of the process and was never re-asked. That is not hypothetical: `feed_mail` carries
-    /// no run condition, so on 2026-09-06 it asked all five `Stationery.dbc` templates at the
-    /// login screen, every one was dropped "not connected", and the send tab's stationery list
-    /// was empty for the whole session — which the stock `SendMailFrame_Reset` turns into every
-    /// send silently unsent. The ask site is fixed; this makes the CLASS harmless, because the
-    /// cost of a wrong latch (a feature dead all session, in silence) is nothing like the cost of
-    /// a redundant re-ask.
+    /// World enter: release the ask-once latch and keep what the cache learned. An ask is marked
+    /// pending before the send, and a send made while no writer is held is dropped silently.
     pub(crate) fn clear_pending(&mut self) {
         self.templates.clear_pending();
     }
 
-    /// The objects themselves — and their countdowns — are the index's, swept with every other
-    /// entity (decisions 2334, 2340); the pending enchant times die with the player they were
-    /// queued on.
+    /// Disconnect: drop the in-flight asks and the queued enchant times, keep the templates. The
+    /// item objects and their countdowns go with the index's sweep.
     pub(crate) fn clear_session(&mut self) {
         self.pending_enchant_times.clear();
         self.templates.clear_pending();
@@ -662,21 +480,12 @@ impl crate::query_cache::AskOnce for Items {
     }
 }
 
-/// The ask-once trio every UI resolver needs to be tested: the template cache, the command
-/// channel, and — crucially — the channel's live **receiver**, without which every `ItemQuery`
-/// send fails and the "asked the server" half of the law goes unobservable. `items` starts empty,
-/// so a fresh `TestDeps` reads as "template in flight"; seed one with [`Items::insert_template`]
-/// to test the landed arm.
-///
-/// Shared because the three icon laws (`ui_trainer::service_icon`, `ui_tradeskill::recipe_icon`,
-/// `ui_craft::craft_icon`) all terminate in this same cache — the fixture is the one thing they
-/// legitimately have in common, unlike the laws themselves.
+/// The ask-once test fixture; it holds the live receiver, without which every send fails.
 #[cfg(test)]
 pub(crate) struct TestDeps {
     pub(crate) items: Items,
     pub(crate) commands: NetCommands,
-    /// The object index the item objects live in (decision 2334) — seed it with
-    /// [`Self::spawn_item`], read it through [`Self::with_objects`].
+    /// The object index: seed with [`Self::spawn_item`], read through [`Self::with_objects`].
     pub(crate) world: World,
     rx: crossbeam_channel::Receiver<ClientCommand>,
 }
@@ -695,13 +504,12 @@ impl TestDeps {
         }
     }
 
-    /// An item object in the index — what the wire's `ItemCreate` spawns.
+    /// An item object in the index, as the wire's `ItemCreate` spawns it.
     pub(crate) fn spawn_item(&mut self, guid: u64, fields: ObjectFields) -> Entity {
         test_spawn_item(&mut self.world, guid, fields, false)
     }
 
-    /// Run `f` with the lookup the helpers under test take, beside the template cache and the
-    /// command channel — the three borrows split so a test can hold all of them at once.
+    /// Run `f` with the object lookup, the template cache and the command channel borrowed apart.
     pub(crate) fn with_objects<R>(
         &mut self,
         f: impl FnOnce(&Objects, &Items, &NetCommands) -> R,
@@ -712,8 +520,7 @@ impl TestDeps {
         f(&objects, items, commands)
     }
 
-    /// The entries the resolver asked the server for — an ask-once gate firing is observable here
-    /// even when the icon it feeds is still `None`.
+    /// The entries asked of the server, observable while the icon they feed is still `None`.
     pub(crate) fn queried_entries(&self) -> Vec<u32> {
         self.rx
             .try_iter()
@@ -725,8 +532,7 @@ impl TestDeps {
     }
 }
 
-/// Spawn an item object straight into a test world's index — [`spawn_item`] without the command
-/// queue, for a test that holds the `World`.
+/// [`spawn_item`] straight into a test world, without the command queue.
 #[cfg(test)]
 pub(crate) fn test_spawn_item(
     world: &mut World,
@@ -741,12 +547,11 @@ pub(crate) fn test_spawn_item(
     e
 }
 
-/// Equipment slots 15/16 — `EQUIPMENT_SLOT_MAINHAND` / `_OFFHAND` (vmangos `EquipmentSlots`).
+/// `EQUIPMENT_SLOT_MAINHAND` / `_OFFHAND` (vmangos `EquipmentSlots`).
 pub(crate) const EQUIPMENT_SLOT_MAINHAND: u8 = 15;
 pub(crate) const EQUIPMENT_SLOT_OFFHAND: u8 = 16;
 
-/// One equipment slot's item class, through the guid → entry → template walk. `None` for an empty
-/// slot or a template still in flight.
+/// One equipment slot's item class; `None` while empty or its template is in flight.
 fn equipped_class(
     store: &ObjectStore,
     objects: &Objects,
@@ -759,16 +564,10 @@ fn equipped_class(
     Some(items.template(entry, guid, commands)?.class as u8)
 }
 
-/// **Which equipment slot this character's disarm hides** — the ladder
-/// ([`crate::creature_anim::disarmed_hand`]) asked of the raw inventory rather than of the
-/// resolved hands, which is the form the two *item*-side consumers need: the action bar's
-/// equipped-item requirement (`0x5f0c50`, which strips the bit out of its slot mask) and the
-/// item-use refusal (`CGItem::Use`'s rung 15, which compares it against the clicked item's own
-/// worn position). `None` while the flag is down or neither hand holds a weapon.
-///
-/// It lives here, next to the cache it reads, so the ladder is stated once and asked twice rather
-/// than re-derived per consumer — the failure decision 0664 names, and the reason the quest fork
-/// was once missing from all three of its call sites.
+/// The equipment slot this character's disarm hides ([`crate::creature_anim::disarmed_hand`] over
+/// the raw inventory), for the action bar's equipped-item requirement (`0x5f0c50`) and the
+/// item-use refusal (`CGItem::Use` rung 15). `None` while the flag is down or neither hand holds
+/// a weapon.
 pub(crate) fn disarmed_equipment_slot(
     store: &ObjectStore,
     objects: &Objects,
@@ -783,7 +582,7 @@ pub(crate) fn disarmed_equipment_slot(
     crate::creature_anim::disarmed_hand(main, off).map(|hand| EQUIPMENT_SLOT_MAINHAND + hand as u8)
 }
 
-/// [`disarmed_equipment_slot`]'s read-only twin — same ladder, no ask (decision 1925).
+/// [`disarmed_equipment_slot`] without the ask.
 pub(crate) fn disarmed_equipment_slot_cached(
     store: &ObjectStore,
     objects: &Objects,
@@ -804,8 +603,8 @@ pub(crate) fn disarmed_equipment_slot_cached(
     .map(|hand| EQUIPMENT_SLOT_MAINHAND + hand as u8)
 }
 
-/// A minimal, VALID item template named `name` — the shared test seam for every module that
-/// needs a landed template (the sentinels that matter are `allowable_*` = −1 and `stackable` = 1).
+/// A minimal valid item template named `name`; the sentinels that matter are `allowable_*` = -1
+/// and `stackable` = 1.
 #[cfg(test)]
 pub(crate) fn test_template(name: &str) -> ItemInfo {
     ItemInfo {
@@ -904,10 +703,6 @@ mod tests {
         );
     }
 
-    /// The gated feeds' template-side counter (1439): a template landing moves it, and a lazy
-    /// `template()` miss — the per-frame read that poisons `is_changed` — moves nothing. The
-    /// instance side is the item entities' own change ticks since 2334
-    /// ([`an_item_is_an_object_in_the_index_and_its_changes_are_watched`]).
     #[test]
     fn the_template_epoch_counts_landings_and_asks_count_nothing() {
         let (cmds, _rx) = commands();
@@ -924,10 +719,7 @@ mod tests {
         assert_ne!(items.template_epoch(), t0, "a landing is");
     }
 
-    /// The display step/quantize pair on one item's cells (decision 2340): a parked deadline
-    /// contributes `floor(secs)+1` (bounded here, not exact — the test can't pin the sub-second
-    /// phase), the display read is floored to the whole second, and clearing the cell takes its
-    /// term away (the `Some(0) → None` collapse is the term's own last step).
+    /// The step count is bounded, not exact: the test cannot pin the sub-second phase.
     #[test]
     fn countdown_steps_move_by_displayable_seconds() {
         let now = Instant::now();
@@ -944,7 +736,6 @@ mod tests {
         assert_eq!(shown % 1000, 0, "the display read is second-floored");
         assert!(shown <= 90_000);
 
-        // The lifetime cell joins the same step sum.
         c.set_lifetime(1800);
         let shown = c.lifetime_remaining_display_ms().expect("parked");
         assert_eq!(shown % 1000, 0);
@@ -962,16 +753,6 @@ mod tests {
         assert_eq!(c.lifetime_remaining_ms(), None);
     }
 
-    /// The two setters' store rules, each the reference's (`0x5d9c00` / `0x5d9cc0`):
-    ///
-    /// - **A non-POSITIVE value clears, in both cells.** The test is SIGNED (`jle`), so `0` and
-    ///   a wire value with the top bit set both store absence instead of a 68-year deadline.
-    ///   Before decision 2340 only the lifetime path knew this; the enchant path parked the far
-    ///   future.
-    /// - **A slot past the seventh is refused**, where the reference would index past the cell
-    ///   array into the next member.
-    /// - The deadline read answers `Some(_)` for a live cell and `None` for a slot that never had
-    ///   one, where the tooltip read collapses both an unset and an elapsed cell to `None`.
     #[test]
     fn the_setters_clear_on_signed_non_positive_and_refuse_a_slot_past_the_array() {
         let mut c = Countdowns::default();
@@ -1003,8 +784,6 @@ mod tests {
         assert!(c.enchant_deadline_ms(6).is_some_and(|ms| ms <= 30_000));
     }
 
-    /// The push half of the tooltip store: a landed template is marked fresh exactly once (the
-    /// drain empties), and a cached negative never is (there's nothing to push).
     #[test]
     fn landed_templates_drain_as_fresh_once() {
         let mut items = Items::default();
@@ -1014,11 +793,8 @@ mod tests {
         assert!(items.take_fresh().is_empty(), "a drain empties the queue");
     }
 
-    /// The right-click-to-open predicates — and the fact that the **line and the click are not the
-    /// same test** (decision 0896). The tooltip's `shows_open_line` carries the lock sub-gate (a
-    /// `LockID` template earns the line only once the INSTANCE says UNLOCKED); the click's
-    /// `opens_loot` is the BARE template bit, so a still-locked junkbox sends anyway and the
-    /// server supplies the refusal. Getting that backwards eats the click in silence.
+    /// The tooltip's open line waits for an unlocked instance; the click is the bare template bit,
+    /// so a locked junkbox still sends and the server refuses.
     #[test]
     fn open_line_carries_the_lock_gate_the_open_send_does_not() {
         let plain = |flags: u32, lock_id: u32| {
@@ -1028,22 +804,20 @@ mod tests {
             t
         };
 
-        // The clam: LOOTABLE, no lock — line and send agree, instance flags irrelevant.
+        // The clam: lootable, no lock; line and send agree.
         assert!(plain(ITEM_FLAG_LOOTABLE, 0).shows_open_line(0));
         assert!(plain(ITEM_FLAG_LOOTABLE, 0).opens_loot());
         // An ordinary item does neither, however its instance is flagged.
         assert!(!plain(0, 0).shows_open_line(ITEM_DYNFLAG_UNLOCKED | ITEM_DYNFLAG_WRAPPED));
         assert!(!plain(0, 0).opens_loot());
-        // A junkbox: LOOTABLE but locked. **The two predicates part company here** — no line
-        // until the instance says UNLOCKED, but the click goes out either way.
+        // A junkbox, lootable but locked: no line until unlocked, but the click goes out.
         assert!(!plain(ITEM_FLAG_LOOTABLE, 7).shows_open_line(0));
         assert!(plain(ITEM_FLAG_LOOTABLE, 7).shows_open_line(ITEM_DYNFLAG_UNLOCKED));
         assert!(
             plain(ITEM_FLAG_LOOTABLE, 7).opens_loot(),
             "the send ignores LockID entirely — the server owns the refusal"
         );
-        // Gift wrap: the WRAPPER template unwraps only while the instance is still WRAPPED, and
-        // that arm is its own dispatcher position, not a nested case of the loot arm.
+        // Gift wrap unwraps only while the instance is still wrapped, its own dispatcher arm.
         assert!(!plain(ITEM_FLAG_WRAPPER, 0).unwraps_gift(0));
         assert!(plain(ITEM_FLAG_WRAPPER, 0).unwraps_gift(ITEM_DYNFLAG_WRAPPED));
         assert!(
@@ -1072,9 +846,6 @@ mod tests {
         );
     }
 
-    /// **An item is an object** (decision 2334): spawned into the one index with its store,
-    /// resolved through [`Objects`] like a unit, and its create, its delta, a countdown landing
-    /// and its despawn each move [`ItemChanges`] exactly once — the gate the inventory feeds watch.
     #[test]
     fn an_item_is_an_object_in_the_index_and_its_changes_are_watched() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1123,8 +894,7 @@ mod tests {
             .merge(ObjectFields::from_pairs(&[(14, 4)]));
         assert_eq!(world.run_system(read).unwrap(), (Some(117), Some(4), true));
         assert!(!world.run_system(read).unwrap().2);
-        // A countdown landing is the item's own change too (decision 2340), and its cell joins
-        // the step sum the feeds watch between landings.
+        // A countdown landing is the item's own change, and its cell joins the step sum.
         world
             .get_mut::<Countdowns>(e)
             .expect("every item carries its cells")
@@ -1144,9 +914,6 @@ mod tests {
         assert!(!world.run_system(read).unwrap().2);
     }
 
-    /// **`PlayerPendingItemExpiration`** (decision 2340): an enchant time for an item not yet held
-    /// waits for it, is handed over in arrival order once, and a disconnect drops what never
-    /// arrived — while the templates the session learned survive it.
     #[test]
     fn a_queued_enchant_time_waits_for_its_item_and_the_session_keeps_templates() {
         let mut items = Items::default();
@@ -1163,15 +930,14 @@ mod tests {
             "unlinked once replayed"
         );
 
-        // A disconnect drops the records for items that never arrived and the in-flight asks,
-        // and keeps the templates.
+        // A disconnect drops unarrived records and in-flight asks, and keeps the templates.
         let (cmds, rx) = commands();
         items.insert_template(117, Some(info("Tough Jerky")));
         assert!(items.template(118, 0, &cmds).is_none()); // leaves 118 in flight
         items.clear_session();
         assert!(items.take_enchant_times(0x43).is_empty());
         assert!(items.template(117, 0, &cmds).is_some(), "templates survive");
-        // 118's ask was dropped with the writer — it must re-ask now.
+        // 118's ask was dropped with the writer, so it re-asks now.
         let _ = rx.try_recv();
         assert!(items.template(118, 0, &cmds).is_none());
         assert!(matches!(
@@ -1180,10 +946,7 @@ mod tests {
         ));
     }
 
-    /// The id → row join (decisions 0915/0920): slot order is preserved, a `0` slot and an id with
-    /// no `SpellItemEnchantment` name are both silently absent (never a placeholder line), and with
-    /// no catalog at all nothing renders. Plus the reference's sign rule — **`abs(id)` names the
-    /// row, the sign only travels** (`0x52c9f9`), which is why a negative id resolves at all.
+    /// `abs(id)` names the row and the sign only travels (`0x52c9f9`).
     #[test]
     fn enchant_lines_join_named_ids_in_slot_order() {
         let cat = Enchants(benilla_formats::EnchantCatalog::from_rows(
@@ -1206,7 +969,7 @@ mod tests {
             )),
             vec!["Agility +15".to_string(), "Crusader".to_string()]
         );
-        // A NEGATIVE id resolves off `abs(id)` — the same row — and only carries its sign onward.
+        // A negative id resolves off `abs(id)` and carries its sign onward.
         let neg = enchant_lines([(0, -2564, 0, None)], Some(&cat));
         assert_eq!(neg.len(), 1);
         assert_eq!(neg[0].name, "Agility +15");
@@ -1214,9 +977,9 @@ mod tests {
         // Charges and a countdown ride the slot through untouched (the engine formats them).
         let temp = enchant_lines([(1, 1900, 5, Some(90_000))], Some(&cat));
         assert_eq!((temp[0].charges, temp[0].remaining_ms), (5, Some(90_000)));
-        // An id the table doesn't name contributes nothing at all.
+        // An id the table does not name contributes nothing.
         assert!(enchant_lines([(0, 999_999, 0, None)], Some(&cat)).is_empty());
-        // No DBC → no lines, the pre-0915 tooltip.
+        // No DBC, no lines.
         assert!(enchant_lines([(0, 2564, 0, None)], None).is_empty());
     }
 
@@ -1235,12 +998,8 @@ mod tests {
         ObjectFields::from_pairs(&[(21, flags), (22, slot0)])
     }
 
-    /// **`0x5da2c0` — the bind question's predicate**, and the reason it reads the raw descriptor.
-    ///
-    /// Two halves, `||`: the instance's soulbound bit, or any live enchant slot naming a row with
-    /// `Flags & 1`. The last case is the one that decides the shape: the Firestone family carries
-    /// BOTH the binding bit and the tooltip-suppression bit, so the same item is bound *and*
-    /// prints no enchant line — a predicate read off [`enchant_lines`] would call it unbound.
+    /// `0x5da2c0`: the Firestone shape binds and prints no line, so a predicate read off
+    /// [`enchant_lines`] would call it unbound.
     #[test]
     fn the_bind_predicate_reads_the_descriptor_not_the_rendered_lines() {
         let cat = catalog();
@@ -1273,7 +1032,7 @@ mod tests {
             !already_bound(&item(0x0, 11), None),
             "no catalog loaded — the enchant half cannot answer, and does not guess"
         );
-        // The one that pins the design: bound, and invisible to the line law.
+        // The case that pins the design: bound, and no line.
         assert!(
             already_bound(&item(0x0, 12), cat),
             "the Firestone shape — binds AND hides its line"
diff --git a/crates/benilla-app/src/lib.rs b/crates/benilla-app/src/lib.rs
index 54e66c5e..ad11480e 100644
--- a/crates/benilla-app/src/lib.rs
+++ b/crates/benilla-app/src/lib.rs
@@ -1,40 +1,20 @@
-//! `benilla` — a from-scratch World of Warcraft 1.12.1 client on Bevy, talking to a local vmangos server.
+//! `benilla`: a from-scratch World of Warcraft 1.12.1 client on Bevy. It opens the patch chain from
+//! the install (`$WOW_DATA`, the project folder on a dev build, else beside the binary), streams
+//! the world around the player through the `benilla-assets` `mpq://` pipeline, and runs the network
+//! session on a background thread ([`net`]).
 //!
-//! Opens the vanilla patch chain from wherever the install is (`$WOW_DATA`, the project folder on a
-//! dev build, else beside the binary — decision 1175) and streams the world around the
-//! player through Bevy's `AssetServer` (the `benilla-assets` `mpq://` pipeline): ADT terrain tiles within
-//! the live Terrain Distance window (decision 1513) — their splat-blended ground, doodads/WMOs, water,
-//! and ground clutter — plus the avian colliders the character controller walks on. Lit by a time-of-day WoW
-//! lighting model (`Light.dbc` sampled against the server clock) with a sky dome, sun/moon discs, and
-//! distance fog; a faithful `EffectGlow` bloom on top.
-//!
-//! In parallel a background thread ([`net`]) logs in (`$WOW_USER`/`$WOW_PASS`/`$WOW_HOST`, host
-//! default `localhost`), enters the world, and streams object updates. NPCs and GameObjects
-//! render as their real models (resolved from the display id via the creature/GameObject catalogs); other
-//! players stay cyan cubes, and our own avatar is blue until we take third-person control of it.
-//! **The world is loaded when a character enters it, and released when they leave** — the glue
-//! screens have no world behind them (decision 0777). With no server there is no world: the client
-//! sits at the login screen, which is what the real one does. The scene harness (`$WOW_CAPTURE`)
-//! boots straight in-world and is unaffected.
-//!
-//! Controls: WASD walks the avatar; right-drag turns it, left-drag orbits the camera (both
-//! hide/freeze the cursor while held), scroll wheel zooms. Those are all **bindings** now (0997) —
-//! rebindable, and nothing in the client squats on a bare key beside them (1043). The dev chord
-//! (`Ctrl`+`Shift`) + `F` toggles free-fly, then WASD flies the camera with Space up / C down and
-//! `Ctrl` boosts — a boost that exists only inside free-fly, itself behind the chord.
+//! The world is loaded when a character enters it and released when they leave; the glue screens
+//! have no world behind them, so with no server the client sits at the login screen, as the
+//! reference does. The capture harness (`$WOW_CAPTURE`) boots straight in-world.
 
-// **A player build's dead code is the seam working, not a defect.** With `--no-default-features`
-// every symbol whose only caller is an instrument goes unused — the camera-park seam, the aim
-// seam, the pool-slot identity, a dozen accessors the panel and the probes read. Warning about
-// each one would bury a REAL warning in the one build nobody looks at daily, and the alternative
-// (a `cfg` attribute per item) would spread seam knowledge back across the gameplay modules 1174
-// spent its whole diff clearing it out of. Dev builds still warn normally.
+// A player build's dead code is the seam working: with `--no-default-features` every symbol only an
+// instrument calls goes unused, and a `cfg` per item would spread seam knowledge into gameplay
+// modules. Dev builds warn normally.
 #![cfg_attr(not(feature = "dev"), allow(dead_code))]
 
-/// The realtime-audio allocation tripwire (decision 1857). In debug builds an allocation inside
-/// the output IO callback or the render pass (`sound::output`'s `no_alloc` scopes) aborts the
-/// process, so a realtime-safety regression fails a test or a smoke instead of reaching an ear;
-/// release builds carry no wrapper at all.
+/// The realtime-audio allocation tripwire: in debug builds an allocation inside `sound::output`'s
+/// `no_alloc` scopes (the output IO callback, the render pass) aborts the process; release builds
+/// carry no wrapper.
 #[cfg(debug_assertions)]
 #[global_allocator]
 static ALLOC: assert_no_alloc::AllocDisabler = assert_no_alloc::AllocDisabler;
@@ -67,8 +47,8 @@ mod cvars;
 mod death;
 #[cfg(feature = "dev")]
 mod debug_panel;
-/// **The dev/player seam** (decisions 0026/1173, built in 1174) — the group, and the boundary
-/// rule, in one file. Always compiled; what it *holds* is not.
+/// The dev/player seam: the instrument groups and the boundary rule. Always compiled; what it holds
+/// is not.
 mod dev;
 mod doodad_events;
 mod entities;
@@ -91,7 +71,7 @@ mod names;
 mod net;
 mod npc_text;
 mod pending_item_ops;
-/// Ships in part: the FPS journal and the clocks it reads (2008); the rest is `dev` (1173).
+/// Ships in part (the FPS journal and the clocks it reads); the rest is `dev`.
 mod perf;
 mod pipe_warm;
 mod player;
@@ -115,8 +95,8 @@ mod shaders;
 mod game_tip;
 mod name_persist;
 mod opaque2d;
-/// Where "the client is going down" may be observed, and why that is `Last` and not `Update`
-/// (decision 1528). Every system that persists state on the way out registers through it.
+/// Where "the client is going down" is observed, in `Last`; every system that persists state on the
+/// way out registers through it.
 mod shutdown;
 mod smart_rect;
 mod sound;
@@ -209,23 +189,18 @@ mod world_state_ui;
 
 use bevy::prelude::*;
 
-// The `benilla` launcher shim (the bin package) is this library's only caller: it stamps the
-// build id at compile time and hands it into [`run`]. Re-exported so the shim needs no bevy
-// dep of its own.
+// The `benilla` launcher shim stamps the build id at compile time and hands it to [`run`];
+// re-exported so the shim needs no bevy dependency of its own.
 pub use benilla_world::build_id::BuildId;
-/// The world viewer's entry point — the engine with no game attached (decision 1160).
-/// Its shim (`benilla-worldview`) is this library's second caller; see [`worldview`].
+/// The world viewer's entry point, the engine with no game attached, called by the
+/// `benilla-worldview` shim.
 pub use benilla_world::worldview::run as run_worldview;
 pub use bevy::app::AppExit;
 
-/// Build and run the client app. `build` is the launcher shim's compile-time git stamp
-/// ([`build_id`]) — passed in as plain data so the sha lives in the shim's fingerprint, not
-/// this crate's, and a commit stops recompiling the app (decision 0993).
+/// Builds and runs the client app. `build` is the launcher's compile-time git stamp, passed in as
+/// data so the sha lives in the shim's fingerprint and a commit does not recompile this crate.
 pub fn run(build: BuildId) -> AppExit {
-    // `WOW_CAPTURE=list` just prints the harness scenario names (the source of truth `scripts/visual.sh`
-    // reads) and exits before any window/asset setup.
-    // `WOW_HOVER_LOG_REPORT=<csv>` re-reads a recorded run and prints its report, then exits —
-    // no window, no game. New analysis lands on runs already captured (see `hover_log`).
+    // `WOW_HOVER_LOG_REPORT=<csv>` and `WOW_CAPTURE=list` print and exit before any setup.
     if let Ok(path) = std::env::var("WOW_HOVER_LOG_REPORT") {
         dev::report_recorded_hover_log(&path);
         return AppExit::Success;
@@ -234,50 +209,34 @@ pub fn run(build: BuildId) -> AppExit {
         dev::print_scenario_names();
         return AppExit::Success;
     }
-    // `WOW_PROBE=list` prints the probe fleet's environment registry (`capture::probe_env`) the
-    // same way — before any window, so a session can ask the binary what the fleet takes.
+    // `WOW_PROBE=list` likewise prints the probe environment registry.
     if std::env::var("WOW_PROBE").as_deref() == Ok("list") {
         dev::print_probe_vars();
         return AppExit::Success;
     }
 
-    // From here on a panic leaves `benilla-config/Diagnostics/crash-<unix>.txt` behind (decision
-    // 2266 §B2) — armed before the `App` exists, so a panic while plugins build is a report too.
+    // From here a panic leaves `benilla-config/Diagnostics/crash-<unix>.txt`; armed before the
+    // `App` exists, so a panic while plugins build is reported too.
     crash::install(build);
 
     let mut app = App::new();
-    // The stamp is plain data from here on — the panel footer and preflight banner read it back.
+    // The panel footer and the preflight banner read the stamp back.
     app.insert_resource(build);
-    // Pin Bevy's static-scene transform tracking ON (decision 1356). At the default threshold
-    // `mark_dirty_trees` re-decides per frame by counting every changed-Transform row and every
-    // tree row — two full scans of the very population the tracking exists to skip. This scene
-    // is provably static-heavy (terrain/WMO batches and parked units barely move), so the
-    // auto-tuner can only ever confirm what this line states. The guard it removes bites only
-    // when MOST rows move in one frame (a load burst into a near-empty world), where
-    // dirty-marking briefly costs more than it saves — a loading-band term, accepted knowingly.
+    // Static-scene transform tracking pinned on: the default threshold re-decides every frame with
+    // two full scans of the rows the tracking exists to skip, and this scene is static-heavy. It
+    // costs more only when most rows move in one frame (a load burst into a near-empty world).
     app.insert_resource(bevy::transform::systems::StaticTransformOptimizations::enabled());
-    // The Update schedule runs on the SINGLE-THREADED executor (decision 1366). Not a tuning
-    // whim: ~60% of our per-frame Update systems are non-Send (mlua's UiScript, kira's audio
-    // handles) and serialize through the multi-threaded executor's one `local_thread_running`
-    // flag anyway, so the cross-thread dispatch machinery was pure overhead — measured
-    // −1.30 cpu_ms at the LBRS pin under 5-round grading with the wall tail (p95/p99/max)
-    // flat-to-better (the 1364 "fatter tail" reading did not reproduce; 1366 has the tables,
-    // both pins). `WOW_MT_UPDATE=1` is the A/B lever back to the multi-threaded executor.
+    // Update runs single-threaded: most per-frame Update systems are non-Send (mlua's `UiScript`,
+    // kira's audio handles) and serialize through the multi-threaded executor anyway, so its
+    // dispatch is pure overhead (measured faster, tails flat). `WOW_MT_UPDATE=1` restores it.
     if std::env::var_os("WOW_MT_UPDATE").is_none() {
         app.edit_schedule(Update, |s| {
             s.set_executor_kind(bevy::ecs::schedule::ExecutorKind::SingleThreaded);
         });
     }
-    // PostUpdate too (decision 1437, closing 1366's named open probe — which expected a
-    // REGRESSION here and was refuted by measurement). The census: 208 systems paying
-    // ~10 µs/system of MT dispatch parked (schedule self 2.09 ms/f in the 1435 band map) while
-    // the wide bands the 1366 expectation leaned on are exactly the ones later work gated or
-    // pinned (1429 idle-gates the animation par sweep, 1356 pins static-transform tracking).
-    // Graded −0.49 cpu_ms parked (all 5 rounds negative) and winning IN MOTION as part of the
-    // combo (−0.76/−0.80 across two 4-round LBRS walk sittings), parked tails flat, motion
-    // p99/max flipping sign wholesale between sittings on both executors — 1366's own
-    // noise-dominated shape. `WOW_MT_POSTUPDATE=1` is the lever back; the engagement line makes
-    // every leg log name the config it measured.
+    // PostUpdate too: 208 systems paid about 10 µs each of multi-threaded dispatch, and
+    // single-threaded measured faster parked and in motion. `WOW_MT_POSTUPDATE=1` restores it; the
+    // log line names the config a run measured.
     if std::env::var_os("WOW_MT_POSTUPDATE").is_none() {
         app.edit_schedule(PostUpdate, |s| {
             s.set_executor_kind(bevy::ecs::schedule::ExecutorKind::SingleThreaded);
@@ -286,49 +245,32 @@ pub fn run(build: BuildId) -> AppExit {
             "executor: PostUpdate -> single-threaded (1437 default; WOW_MT_POSTUPDATE=1 for MT)"
         );
     }
-    // …and one startup line says which build produced this log. Registered HERE, beside the stamp
-    // it prints, rather than in `preflight` where it sat until decision 1179: **which build is
-    // this** is the first thing a bug report from someone else's machine has to establish, and a
-    // player build is the one whose logs always come from someone else's machine. Gating it out
-    // with the instruments got the argument exactly backwards (`preflight`'s own module doc makes
-    // the case; 1174 moved the file without re-reading it).
+    // The build banner ships in every build: which build produced a log is the first thing a report
+    // from another machine must establish.
     app.add_systems(Startup, benilla_world::build_id::banner);
 
-    // Visual A/B harness (decision 0008): with `$WOW_CAPTURE` set, the app runs a deterministic,
-    // server-less capture (net off so no NPCs stream in nondeterministically) and exits. See `capture`.
+    // With `$WOW_CAPTURE` set the app runs a deterministic, server-less capture (net off, so no
+    // NPCs stream in) and exits.
     let capturing = run_mode::scenario_active();
-    // Any instrumented run — captures AND the live-probe fleet — opens in the background so it
-    // never fights the director's screen (decision 0703; `WOW_BG` overrides). See `bgwin`.
+    // Every instrumented run, captures and live probes, opens in the background so it never takes
+    // over a person's screen; `WOW_BG` overrides.
     let background = benilla_world::bgwin::background_run();
     if capturing {
-        // Ground clutter scatters with per-run randomness, so disable it for byte-stable baselines
-        // — clutter isn't what the lighting rework validates, and the regression diff must not be
-        // masked by grass wobble. Set before plugins build so `ClutterConfig::from_env` reads it.
-        // It is not the only source of per-run drift, though it was long documented as such: the
-        // other is the frame clock itself, frozen in `capture` (decision 0723).
+        // Ground clutter scatters with per-run randomness, so captures turn it off for byte-stable
+        // baselines; set before plugins build so `ClutterConfig::from_env` reads it. The frame
+        // clock, frozen in `capture`, is the other source of drift.
         std::env::set_var("WOW_CLUTTER_DENSITY", "0");
-        // Third source of per-run drift, and the one the lighting matrix (decision 0746) hit: the
-        // anim-LOD park/wake gate (`creature_anim::lod::gate_rig_animation`). Whether a rig is
-        // parked, and which pose it wakes into, depends on when its model finished loading relative
-        // to the frustum/room evaluation — asset-load timing, which the frozen clock does not
-        // control. MEASURED: the seeded wolf lands in one of exactly two poses, the pair always
-        // MAE 4.123 apart, and three runs with the gate off are bit-identical.
-        //
-        // Off for captures, unless explicitly overridden. A still frame is meant to contain only
-        // rigs that are IN view, and a rig in view is one the gate should never park — so what a
-        // capture loses is the gate's own correctness, not the shot's subject. That loss is named,
-        // not free: a rig wrongly parked in frame stays invisible to the sweep, and the deeper
-        // question the measurement raises — why a woken rig does not converge on the absolute-clock
-        // pose the gate promises — is open in 0746 and worth its own hunt.
+        // Anim-LOD park/wake (`creature_anim::lod::gate_rig_animation`) hangs on asset-load timing,
+        // which the frozen clock does not control, so captures turn it off unless overridden. A rig
+        // in frame should never be parked, so the shot keeps its subject.
         if std::env::var("WOW_NO_ANIM_LOD").is_err() {
             std::env::set_var("WOW_NO_ANIM_LOD", "1");
         }
     }
 
-    // The `mpq://` asset source must be registered BEFORE `AssetPlugin` (inside `DefaultPlugins`)
-    // builds. Finds the install the one way anything does (`benilla_formats::wow_data`, decision
-    // 1175) — the same answer the `WorldAssets` foundation gets. On failure the source is simply
-    // absent and the AdtTile-pipeline loads fail gracefully (the terrain just doesn't appear).
+    // The `mpq://` source must be registered before `AssetPlugin` (in `DefaultPlugins`) builds. The
+    // install is found by `benilla_formats::wow_data`, as everywhere; without one the source is
+    // absent and terrain loads fail gracefully.
     match benilla_formats::wow_data() {
         Some(data_dir) => {
             if let Err(e) = benilla_assets::register_mpq_source(&mut app, &data_dir) {
@@ -341,53 +283,36 @@ pub fn run(build: BuildId) -> AppExit {
         ),
     }
 
-    // NOTE: there is deliberately no `game://` asset source here (decision 1175). 1171 gave the
-    // game's five UI shaders their own source pointed at this crate's `assets/` — with the path
-    // baked from `CARGO_MANIFEST_DIR`, so it named the build machine's source tree and resolved
-    // to nothing anywhere else. The line 1171 drew survives: those five are still this crate's,
-    // now compiled in by `crate::shaders` and addressed `embedded://benilla_app/shaders/…`,
-    // because `embedded_asset!` is per-crate by construction. Only the directory is gone.
+    // No `game://` source: the five UI shaders are compiled in by `crate::shaders`
+    // (`embedded://benilla_app/shaders/…`), so no build-machine path reaches the binary.
 
     app.add_plugins(benilla_world::boot::tuned_default_plugins(Window {
         title: "benilla".into(),
-        // **Born in the player's display mode, not flipped into it** (decision 1627). `gxWindow`
-        // is read straight off `config.toml` here rather than waiting for `Startup`'s
-        // `load_config`, because a launch that opens windowed and goes fullscreen one frame later
-        // is a visible flash on every start — and, under a compositor that only maps a fullscreen
-        // surface 1:1 (gamescope), a first second spent in the exact input state this is meant to
-        // end. Every instrumented run stays windowed regardless (`video::windowed_env`), so the
-        // capture harness, the probe fleet and `$WOW_WIN` are untouched by any of this.
+        // Born in the player's display mode (`gxWindow` read straight off `config.toml`) rather
+        // than flipped into it at `Startup`, which would flash on every launch and, under
+        // gamescope, spend the first second in the input state fullscreen is meant to end.
+        // Instrumented runs stay windowed (`video::windowed_env`).
         mode: video::boot_window_mode(),
-        // UI-fixture captures shrink the window so the docked panel fills the frame — the capture
-        // is the look-pass instrument and the window is its subject. The action bar is the
-        // exception: it spans 1024px + 128px end caps along the screen bottom, so it gets a wide,
-        // short window instead of the tall default (else the caps crop). The vplates scenario pins
-        // the 1:1 gx window: at 1024×768 one gx unit = 1280 px, so the plate must land at the
-        // border texture's native 128×32 — directly diffable against the decoded BLP. Sized
-        // per-capture off WOW_CAPTURE.
+        // UI-fixture captures size the window to what they photograph: the action bar's 1024 px
+        // plus 128 px end caps get a wide, short window, and vplates pins 1024×768, where one gx
+        // unit is 1280 px and the plate lands at the border texture's native 128×32, diffable
+        // against the BLP.
         resolution: video::at_requested_dpi(
-            // Same opt-in as the UI load itself (`ui_script::lifecycle::ui_wanted`): a scenario
-            // that declares a `ui:` fixture sizes its window for the window it photographs, with
-            // or without the env var. The two must agree — a UI loaded into a world-sized window
-            // is a capture of the right content at the wrong size.
+            // Same opt-in as the UI load (`ui_script::lifecycle::ui_wanted`); the two must agree,
+            // or the right content is captured at the wrong size.
             if capturing && crate::run_mode::capture_ui_opted_in() {
-                // `$WOW_WIN` overrides here too — the resolution-A/B instrument for UI scenarios (a
-                // scale-dependent text bug looks fine at the scenario's default size and truncates at
-                // fullscreen heights).
+                // `$WOW_WIN` overrides here too, for scale-dependent UI bugs.
                 if let Some(win) = video::requested_window_size() {
                     win
                 } else {
                     match std::env::var("WOW_CAPTURE").as_deref() {
                         Ok("ui-actionbar") => UVec2::new(1300, 260),
                         Ok("vplates") => UVec2::new(1024, 768),
-                        // The director's small-window shape: short enough that the action bar strip
-                        // overlaps the chat edit box rows — the overlap is the subject.
+                        // Short enough for the action bar to overlap the chat edit box.
                         Ok("ui-chatedit") => UVec2::new(566, 377),
-                        // The fullscreen map's chrome is a centered 1024×768 block; a hair of margin
-                        // shows the blackout doing its job.
+                        // The map's chrome is a centered 1024×768 block, with margin.
                         Ok("ui-worldmap") => UVec2::new(1100, 800),
-                        // The 920×724 era options window wants air on every side so the straddling
-                        // right-edge tile and the hung close X stay in frame.
+                        // Margin keeps the 920×724 window's edge tile and close X in frame.
                         Ok("ui-options") | Ok("ui-options-audio") | Ok("ui-options-graphics") => {
                             UVec2::new(1200, 900)
                         }
@@ -396,54 +321,31 @@ pub fn run(build: BuildId) -> AppExit {
                 }
                 .into()
             } else {
-                // `$WOW_WIN=WxH` (logical px): override the world capture/window size — the
-                // resolution-A/B instrument. The FFXGlow blur geometry is byte-pinned in TEXELS, so its
-                // angular footprint shrinks as resolution grows and thin bright features (fence rails)
-                // self-amplify at 4K where the 1024-era reference diluted them; matching the era's
-                // pixel density (e.g. `WOW_WIN=512x288` on a 2× display → 1024×576 physical) isolates
-                // that term. Also the knob for any future era-resolution comparison.
+                // `$WOW_WIN=WxH` (logical px) overrides the size. FFXGlow's blur is pinned in
+                // texels, so thin bright features self-amplify at high resolution; matching the
+                // reference's pixel density (`WOW_WIN=512x288` on a 2× display is 1024×576)
+                // isolates that term.
                 video::requested_window_size()
-                    // A run that reads no pixels gets a SMALL window. It is held `AlwaysOnTop` for its
-                    // whole life so it can never be occluded into the ~1 fps throttle
-                    // (`capture::ProbeFocusPlugin`, decision 0906) — at the full default that meant
-                    // every agent probe planted a screen-filling window over the director's work. Small
-                    // + cornered (`ProbeFocusPlugin` parks it) is un-occludable AND out of the way;
-                    // anything photographing pixels keeps the full size, and `WOW_WIN` overrides either
-                    // way (decision 1148).
+                    // A run that reads no pixels gets a small window: it is held `AlwaysOnTop`
+                    // against the occlusion throttle (`capture::ProbeFocusPlugin`), and small and
+                    // cornered keeps it out of the way. Pixel runs keep the full size.
                     .unwrap_or(if benilla_world::bgwin::no_pixel_run() {
                         UVec2::new(640, 360)
                     } else {
-                        // The player's `gxResolution` — what "windowed" means for them, and what
-                        // leaving fullscreen restores (1627). Its default is the 1600×900 that was
-                        // hard-coded here before, and while `mode` above is fullscreen `bevy_winit`
-                        // ignores this entirely (it applies an inner size only on the `Windowed` arm).
+                        // The player's `gxResolution`; `bevy_winit` ignores it while fullscreen.
                         video::boot_windowed_size()
                     })
                     .into()
             },
         ),
-        // The boot present mode. `$WOW_NOVSYNC=1` uncaps presentation so a headless FPS-journal
-        // run measures true frame cost, not the vsync ceiling — the same uncap the capture probe
-        // flips mid-run, available from boot for non-capture probes (perf triage at the glue
-        // screens, where no capture scenario runs). Absent it, we boot synced and the player's
-        // `gxVSync` setting takes over from `Startup` on ([`crate::video`]).
+        // `$WOW_NOVSYNC=1` uncaps presentation from boot so a headless FPS-journal run measures
+        // frame cost, not the vsync ceiling; otherwise the player's `gxVSync` takes over from
+        // `Startup` ([`crate::video`]).
         present_mode: video::present_mode(!video::novsync_env()),
-        // An instrumented run must never fight the director's screen (decision 0703).
-        // Focused, it steals the keyboard — on 2026-07-19 a login-shot run swallowed
-        // their keystrokes out of another app and typed them into the account box,
-        // which is also how that capture lost the bare caret it was taken to measure.
-        // So every probe/capture/regression run (`bgwin`) opens unfocused; an ordinary
-        // `cargo run` is unaffected and focuses normally.
-        //
-        // A background run is BORN at `AlwaysOnBottom` (`kCGNormalWindowLevel - 1`)
-        // so it can never flash over their work on the way up — winit raises a new
-        // window twice before our first frame runs, and at the normal level that
-        // showed as ~half a second of probe window on top (measured). But it does not
-        // STAY there: that level is a cage, and 0703 leaving it on for the whole run
-        // is why an instrumented window could never be raised again however hard you
-        // clicked it. `BgWinPlugin` promotes it back to Normal the moment the launch
-        // settles (decision 0709), and owns the app-level half — winit's forced macOS
-        // app activation — as well.
+        // A background run opens unfocused, so it cannot take keystrokes meant for another app, and
+        // is born `AlwaysOnBottom` (`kCGNormalWindowLevel - 1`), so winit's two raises before the
+        // first frame cannot flash it on top. `BgWinPlugin` promotes it to Normal once the launch
+        // settles, so it can still be raised.
         focused: !background,
         window_level: if background {
             bevy::window::WindowLevel::AlwaysOnBottom
@@ -453,60 +355,40 @@ pub fn run(build: BuildId) -> AppExit {
         ..default()
     }))
     .add_plugins(benilla_world::thread_qos::ThreadQosPlugin)
-    // The app-side half of background instrumented runs: undo winit's forced macOS app
-    // activation so a probe/capture launch never yanks focus off the director's screen. The
-    // window-side half (unfocused + always-on-bottom) is in the `Window` above. Decision 0703.
+    // Undoes winit's forced macOS app activation for background runs; the window-side half is the
+    // `Window` above.
     .add_plugins(benilla_world::bgwin::BgWinPlugin)
-    // The other winit-default the client has to undo (decision 1528): macOS's `Cmd+Q` is wired
-    // straight to `terminate:`, which never runs another frame — so the gesture a Mac player
-    // reaches for first exited without writing one line of their session. Re-pointed at the
-    // window close, which the shutdown tail in [`shutdown`] already sees.
+    // macOS `Cmd+Q` goes straight to `terminate:`, which never runs another frame, so the session
+    // was never written; re-pointed at the window close, which [`shutdown`] sees.
     .add_plugins(benilla_world::mac_quit::MacQuitPlugin)
-    // **The engine, as one name** (decision 1164). Everything `benilla-world` will own,
-    // in the order both binaries used before this group existed — see `world_plugins.rs`
-    // for the two ordering edges inside it that are load-bearing, and for what is
-    // deliberately left out (`pipe_warm`).
+    // The engine as one group; `world_plugins.rs` has its load-bearing ordering edges and what it
+    // leaves out (`pipe_warm`).
     .add_plugins(benilla_world::world_plugins::WorldPlugins)
-    // The instruments, which the engine group deliberately does not carry (1160: instruments at
-    // the top of the stack). The panel first — `PerfPlugin` needs the egui plugin/context it sets
-    // up. Toggles: the dev chord + D, and P.
-    // **The instruments** (decisions 1173/1174): the debug panel, the perf HUD, the object
-    // inspector, the hover-cost recorder, the asset-churn meter, the session preflight and the
-    // probe shield — one group, in the slot the panel has always held (it sets up the egui
-    // context the perf pill needs). `--no-default-features` compiles every one of them out; see
-    // `dev.rs` for what is in the group and the one rule that governs the boundary.
+    // The instruments, which the engine group does not carry; `--no-default-features` compiles them
+    // all out (see `dev.rs`).
     .add_plugins(dev::DevToolsPlugin)
-    // The FPS journal — the one instrument that ships (2008): `/console fpsJournal 1` in any
-    // build appends a per-second row of position, frame cost and the GPU's per-pass split to
-    // `benilla-config/Diagnostics/fps-journal.csv`; `WOW_FPS_JOURNAL=<csv>` is the harness lever.
+    // The FPS journal ships: `/console fpsJournal 1` appends a per-second row of position, frame
+    // cost and the GPU's per-pass split to `benilla-config/Diagnostics/fps-journal.csv`;
+    // `WOW_FPS_JOURNAL=<csv>` is the harness lever.
     .add_plugins(perf::FpsJournalPlugin)
-    // **The game, as one name** (decision 2279): everything the client adds on top of the
-    // engine, in the order it always had. See `game_plugins.rs` for the members, the ordering
-    // edges inside it that are load-bearing, and the test that builds it headless.
+    // The game as one group on top of the engine; `game_plugins.rs` has its members, its
+    // load-bearing ordering edges and the test that builds it headless.
     .add_plugins(game_plugins::GamePlugins {
         connect: !capturing,
         start: run_mode::start_state(),
     });
 
-    // Register benilla-assets' loaders AFTER `AssetPlugin` (they go into the live `AssetServer`).
+    // benilla-assets' loaders go into the live `AssetServer`, so they register after `AssetPlugin`.
     benilla_assets::register_asset_loaders(&mut app);
 
-    // The render app's `ExtractSchedule` runs SINGLE-THREADED too (decision 1437, same grading
-    // as the PostUpdate flip above): bevy_render never sets an executor kind, so it ran the
-    // multi-threaded one by default — 0.34 ms/f of schedule self in the 1435 parked band map
-    // over 165 systems (census) with zero true non-Send members. Graded −0.26 parked alone,
-    // −0.90 parked as the combo. `WOW_MT_EXTRACT=1` is the lever back.
+    // `ExtractSchedule` runs single-threaded too: bevy_render leaves it multi-threaded, with no
+    // non-Send member, and single-threaded measured faster. `WOW_MT_EXTRACT=1` restores it.
     //
-    // The `Render` schedule stays MULTI-threaded, and not as a tuning judgment (1437, measured
-    // the hard way): under pipelined rendering the MT executor is ALSO bevy's non-Send→main-
-    // thread routing, and `bevy_render::view::window::create_surfaces` is non-Send precisely to
-    // ride it — on macOS a Metal layer can only be made on the UI thread, and the ST executor
-    // runs everything on the render thread (`get_metal_layer cannot be called in non-ui thread`,
-    // a startup panic). One system pins the schedule; its 1.06 ms/f self stays on the table
-    // until that coupling changes upstream.
+    // `Render` stays multi-threaded: under pipelined rendering that executor is also bevy's route
+    // for non-Send systems to the main thread, and `create_surfaces` needs it because macOS makes a
+    // Metal layer only on the UI thread (the single-threaded executor panics at startup).
     //
-    // Lives HERE, not beside its siblings: the render sub-app only exists once the plugin chain
-    // has built (pipelining detaches it at cleanup, later still).
+    // Set here because the render sub-app exists only once the plugin chain has built.
     if std::env::var_os("WOW_MT_EXTRACT").is_none() {
         if let Some(render_app) = app.get_sub_app_mut(bevy::render::RenderApp) {
             render_app.edit_schedule(bevy::render::ExtractSchedule, |s| {
@@ -516,19 +398,16 @@ pub fn run(build: BuildId) -> AppExit {
                 "executor: ExtractSchedule -> single-threaded (1437 default; WOW_MT_EXTRACT=1 for MT)"
             );
         } else {
-            // A silently missing sub-app would flip nothing — say so instead of measuring a ghost.
+            // A missing sub-app would silently flip nothing.
             eprintln!("executor: no render app — ExtractSchedule flip NOT applied");
         }
     }
 
-    // **The probe fleet** — the capture harness and every scripted live probe, each armed by its
-    // own environment variable and inert without it. Added last so they observe the fully-built
-    // app; compiled out entirely by `--no-default-features` (decisions 1173/1174), which is why
-    // this is one line and the twenty env checks behind it live in `dev.rs`.
+    // The probe fleet, last so it observes the fully-built app; compiled out by
+    // `--no-default-features`.
     app.add_plugins(dev::DevProbesPlugin);
 
-    // Return the app's own exit status instead of dropping it: a failed capture writes
-    // `AppExit::error()` (see `capture::drive_capture`), and discarding it made the process exit 0
-    // with no PNG on disk — which is how a sweep carried on around a missing shot (decision 0743).
+    // Returns the app's exit status: a failed capture sets `AppExit::error()`
+    // (`capture::drive_capture`), which must not exit 0 with no PNG on disk.
     app.run()
 }
diff --git a/crates/benilla-app/src/loading_screen.rs b/crates/benilla-app/src/loading_screen.rs
index 048191f5..bebdbdbe 100644
--- a/crates/benilla-app/src/loading_screen.rs
+++ b/crates/benilla-app/src/loading_screen.rs
@@ -1,42 +1,17 @@
-//! Loading screen — the faithful full-screen world-load splash + progress bar shown on initial
-//! world entry and on cross-map teleport (the load latency async streaming can't hide). Built on the
-//! VERIFIED reference mechanism: per-map art via the
-//! `Map.dbc` → `LoadingScreens.dbc` → BLP FK chain (resolved by `benilla-formats`), under the engine's
-//! bar — which in 1.12 is exactly two layers, `Loading-BarBorder` + `Loading-BarFill`, at the
-//! screen-fraction rects byte-verified from `LoadingScreen.cpp` (NOT the 5-texture stack the asset
-//! names suggest; Background/Glow/Glass are never composited in vanilla).
+//! The loading screen: the full-screen splash and progress bar over world entry and cross-map
+//! teleports. The art resolves `Map.dbc` → `LoadingScreens.dbc` → BLP for every map kind; the bar
+//! is two layers, `Loading-BarBorder` and `Loading-BarFill` (Background, Glow and Glass are never
+//! drawn in 1.12).
 //!
-//! **Foundation, not a one-off.** The art lookup is the *same* mechanism for every map kind (open
-//! world / instance / battleground) — only the BLP row differs — so this hosts all of them for free.
-//! The two cases out of current scope (taxi/boat/zeppelin's moving flight-path icon; a richer
-//! progress model) slot in as an extra overlay layer / a different progress source without restructure.
+//! Event-raised and readiness-cleared, as in the reference: it rises at the character pick's
+//! `Connected` edge and at `SMSG_TRANSFER_PENDING` (the reference's two entries into `0x406640`'s
+//! tail) and clears on a per-frame readiness poll. The reference's one blocking stretch
+//! (`SMSG_NEW_WORLD`'s `0x401b00` defers `0x401bc0` onto the deadline heap, drained at `0x420d0c`)
+//! also suppresses input, which this client builds explicitly ([`input`]).
 //!
-//! **The lifecycle is event-raised, readiness-cleared (decision 0737)** — and the reference's is
-//! too, which 0737 assumed it was not. This header claimed for months that the reference *blocks*
-//! on its world load and so covers "by construction"; decision 1990 says
-//! half of that is wrong. The reference runs ordinary frames with **one** blocking stretch inside
-//! them (`SMSG_NEW_WORLD`'s `0x401b00` defers `0x401bc0` onto the deadline heap, which drains at
-//! `0x420d0c` and runs to completion in that one iteration, `Sleep(1)` residency spins and all) —
-//! but the screen is raised *frames earlier*, at `TRANSFER_PENDING`, and dismissed *frames later*
-//! by a per-frame readiness poll. Which is this file's shape. What an async-streaming client has to
-//! build explicitly is not the lifecycle after all: it is the **input suppression** the blocking
-//! stretch does not provide either (see [`input`], decision 1990). The screen
-//! rises at the **transition edges and only those** — the character pick's `Connected` edge (before
-//! the glue tears down) and `SMSG_TRANSFER_PENDING` (the portal walk-in), which are precisely the
-//! reference's two entries into `0x406640`'s tail — all observed *here*, from the
-//! messages/resources the net bridge already publishes. The destination **snap** is not one of
-//! them: `SMSG_NEW_WORLD` and `SMSG_LOGIN_VERIFY_WORLD` are two handlers there (`0x401b00` /
-//! `0x401de0`) and neither can reach the raise `0x406800` or the screen's map global `[0x82f00c]`,
-//! so a snap only ends the wait its raise armed and can never re-point a live screen
-//! ([`LoadingScreen::far_snap`]). And what a live screen *shows* is latched harder still: the
-//! resolved texture, not the map id ([`LoadingScreen::art_resolved`], decision 2087). A residency backstop catches any
-//! path with no edge, **in world only** — it used to fire at boot too, and that is what warmed the
-//! world's pipelines behind the glue (0540), which only worked while a world was being streamed
-//! there at all. Since 0777 none is, and the warm-up rides the entry cover instead. It clears when
-//! the destination is **scene-presentable** ([`WorldLoadProgress`],
-//! published by `terrain_stream` + the collider queue): every wanted tile spawned, the focus
-//! neighbourhood's placements up, colliders quiet, the snap no longer awaited. Never anything
-//! about the *body* — feet-on-ground is not a load condition (the flying-teleport hang, 0737).
+//! A destination snap only ends a raise's wait ([`LoadingScreen::snap_landed`]). The screen clears
+//! when the destination is scene-presentable ([`WorldLoadProgress`]), never on the body reaching
+//! the ground.
 
 use bevy::prelude::*;
 use std::collections::HashMap;
@@ -50,22 +25,14 @@ use benilla_world::schedule::WorldStage;
 use benilla_world::terrain_stream::WorldLoadProgress;
 use benilla_world::world_map::CurrentMap;
 
-/// **The cover takes the input plane** — the loading screen's input half, in its own file because
-/// it is a different mechanism (a source cut in `PreUpdate`) from the state machine below, and one
-/// file should not have to explain both.
+/// The cover's input half: while it is up the client takes no input (a source cut in `PreUpdate`).
 mod input;
 pub(crate) use input::CoverInput;
 
-// Bar layout — VERIFIED THREE ways (build 5875): the `WoW.exe` `LoadingScreen.cpp` bar descriptor
-// table (@0x7ffd34, `FUN_00407150`) gives entry = {cx, cy, halfW, halfH} with rect = [cx ± halfW·0.5]
-// × [cy ± halfH·0.5] and fill right edge = left + progress·halfW; Border {0.5,0.075,0.600,0.050}, Fill
-// {0.5,0.075,0.525,0.025}. An apitrace of the live reference (WoW.12/WoW.17) confirmed these rects, and
-// a reference screenshot measured the fill at left=0.245 (≈0.2375), ~9% from the BOTTOM. The bar sits
-// at the BOTTOM — `cy=0.075` is measured from the bottom (the engine's GL ortho origin); the trace's
-// "top" reading was the wined3d D3D→GL y-flip (a host representation, see memory
-// `apitrace-is-crossover-translated`), refuted by the screenshot + the binary. ONLY Border + Fill are
-// drawn in 1.12 (Background/Glow/Glass are never composited). Rects are viewport fractions; y is the
-// distance from the BOTTOM edge (Bevy UI `bottom:`).
+// The bar, from the `LoadingScreen.cpp` descriptor table at `0x7ffd34` (read by `0x407150`):
+// entry {cx, cy, halfW, halfH}, rect [cx ± halfW·0.5] × [cy ± halfH·0.5], fill right edge
+// left + progress·halfW; Border {0.5, 0.075, 0.600, 0.050}, Fill {0.5, 0.075, 0.525, 0.025}.
+// Viewport fractions, `cy` measured up from the bottom edge (Bevy UI `bottom:`).
 const BORDER_LEFT: f32 = 0.200; // 0.5 − 0.600·0.5
 const BORDER_WIDTH: f32 = 0.600;
 const BORDER_BOTTOM: f32 = 0.050; // 0.075 − 0.050·0.5
@@ -75,54 +42,28 @@ const FILL_BOTTOM: f32 = 0.0625; // 0.075 − 0.025·0.5
 const FILL_HEIGHT: f32 = 0.025;
 const FILL_MAX_WIDTH: f32 = 0.525; // halfW; fill width = progress · FILL_MAX_WIDTH
 
-/// The glue/loading screen is authored 4:3; on a wider window the reference fits it to height and
-/// letterboxes (black bars L/R). Measured from a reference screenshot (content ≈ 1878×1385 ≈ 4:3 in a
-/// 1999-wide window). The square BLP is stretched to this aspect (a mild widen).
+/// The glue and loading screens are authored 4:3; on a wider window the reference fits them to
+/// height and pillarboxes. The square BLP is stretched to this aspect.
 const BACKDROP_ASPECT: f32 = 4.0 / 3.0;
-/// Frames the world must read fully-resident before we clear the screen — debounces the post-teleport
-/// frame where `loaded` is drained (`total > 0`, `ready` momentarily 0) so we don't flicker off/on.
+/// Consecutive fully resident frames before the clear: debounces the post-teleport frame where
+/// `ready` reads 0 against a nonzero `total`.
 const CLEAR_AFTER_READY_FRAMES: u32 = 3;
-/// The wait instrument (decision 0737): once the screen has been up this long, say *which term*
-/// still blocks the clear, every [`WAIT_LOG_EVERY`] seconds — so a "loading screen stuck" report is
-/// a one-line diagnosis instead of a session. Ordinary loads finish under the threshold and log
-/// nothing extra.
+/// Once the screen has been up this long, log which term still blocks the clear, every
+/// [`WAIT_LOG_EVERY`] seconds.
 const WAIT_LOG_AFTER: f32 = 3.0;
 const WAIT_LOG_EVERY: f32 = 2.0;
-/// How far a same-map snap must move the body before its destination is treated as a **load** at
-/// all (yards). Under this, a teleport cannot outrun the streamer — the ground and buildings you
-/// land on are the ones you left — and the raise below would only be able to flash a cover over
-/// content that happened to be arriving anyway. Sized to clear every *combat* relocation with
-/// room to spare (charge/intercept 25 yd, blink 20 yd, the knockbacks under 30), because those
-/// end in a server teleport too and a black screen mid-fight is the one thing this must never
-/// do; the reported case — `.tele` across a city — is 458 yd.
+/// How far (yd) a same-map snap must move the body to count as a load. It clears every combat
+/// relocation (charge and intercept 25 yd, blink 20, knockbacks under 30), which also ends in a
+/// server teleport and must never black out the screen.
 const SNAP_LOAD_MIN_YD: f32 = 100.0;
 
-/// Consecutive covered+in-world frames before the cover counts as **on the glass**.
-///
-/// Renders are serial, so at 3 the two intermediate frames' renders have committed their
-/// presents. This was 0962's argument and its constant; it now lives beside the fact it defines
-/// rather than being restated in each consumer (it had already been copied twice, and the third
-/// consumer — the world camera — never got it at all).
+/// Consecutive covered, in-world frames before the cover is on the glass: renders are serial, so
+/// at 3 the two frames before have presented.
 const COVER_PRESENT_FRAMES: u32 = 3;
 
-/// **Is the entry cover ON THE GLASS?** — the one fact 0962's rule is written in terms of, held
-/// in one place because restating it is exactly how it gets forgotten.
-///
-/// The world-entry raise happens in `Update`; the state flips a frame later, so the FIRST
-/// covered+in-world frame is also the first frame whose render can draw the cover. Anything
-/// synchronous on that frame holds the *previous* present — the character-select screen, frozen
-/// — for its whole duration. That is the director's report, three times now (0962, 1345, and the
-/// world camera below), and each time it was one consumer nobody had counted:
-///
-/// - the **pipeline-warm menagerie** (0962) — its own `covered_frames`, now this;
-/// - the **world-entry FrameXML load** (1345) — its own `covered_frames`, now this;
-/// - the **world camera and the booth wake** — never deferred at all, and measured (this record's
-///   round) as **57 of the flip frame's 60 ms**: the first render of a 3 000-entity world with
-///   cold pipelines, plus fifteen booth cameras woken by the warm pass, all on the one frame that
-///   owes the glass a loading screen.
-///
-/// Counted in `First` so a `PreUpdate` reader (the entry load, an exclusive system) and an
-/// `Update` reader (the warm pass, the camera gate) see the same frame's answer.
+/// Whether the entry cover has reached the glass. The first covered frame is the first whose
+/// render can draw the cover, so synchronous work on it freezes character select on screen.
+/// Counted in `First` so `PreUpdate` and `Update` readers see the same frame's answer.
 #[derive(Resource, Default)]
 pub(crate) struct EntryCover {
     /// Consecutive covered+in-world frames; reset the moment either goes false.
@@ -130,26 +71,23 @@ pub(crate) struct EntryCover {
 }
 
 impl EntryCover {
-    /// Has the cover had enough frames to reach the glass? **True whenever no cover is up** —
-    /// there is then no glass to protect, and a consumer that waited would wait forever (the
-    /// capture that boots straight in-world is exactly this case).
+    /// Whether the cover has had enough frames to reach the glass; true when no cover is up, since
+    /// a consumer would otherwise wait forever (a capture that boots straight in world).
     pub(crate) fn presented(&self) -> bool {
         self.frames == 0 || self.frames >= COVER_PRESENT_FRAMES
     }
 
-    /// Is a cover up and still owed its first present? The inverse of the arm above that a
-    /// *renderer* wants: "do not draw anything but the cover this frame".
+    /// A cover is up and not yet presented: a renderer draws nothing but the cover this frame.
     pub(crate) fn owes_a_present(&self) -> bool {
         self.frames > 0 && self.frames < COVER_PRESENT_FRAMES
     }
 
-    /// **Is a world cover up right now?** — `LoadingScreen::covering()` ∧ in world, which is
-    /// the pair every cover consumer actually means, counted once here.
+    /// A cover is up and the client is in world.
     pub(crate) fn covering(&self) -> bool {
         self.frames > 0
     }
 
-    /// Covered frames so far — what the tests assert on.
+    /// Covered frames so far.
     #[cfg(test)]
     pub(crate) fn frames(&self) -> u32 {
         self.frames
@@ -157,8 +95,7 @@ impl EntryCover {
 }
 
 impl EntryCover {
-    /// One frame's worth of counting — the whole rule, so the test seam and the system cannot
-    /// drift apart.
+    /// One frame's count; the system and the tests both go through this.
     pub(crate) fn tick(&mut self, covered: bool) {
         self.frames = if covered {
             self.frames.saturating_add(1)
@@ -168,7 +105,7 @@ impl EntryCover {
     }
 }
 
-/// `First`: advance (or reset) the covered-frame count. One writer, read by every consumer.
+/// `First`: advance or reset the covered-frame count.
 fn count_entry_cover(
     screen: Res<LoadingScreen>,
     state: Res<State<crate::char_select::ClientState>>,
@@ -178,12 +115,11 @@ fn count_entry_cover(
     cover.tick(screen.covering() && in_world);
 }
 
-/// Bevy resource wrapper around the format-crate [`LoadingScreenCatalog`] (the `LoadingScreenID` → BLP
-/// path table). Paired with [`MapCatalogRes`] (the `mapId` → `LoadingScreenID` FK) to resolve art.
+/// The `LoadingScreenID` → BLP path table; [`MapCatalogRes`] maps a map to its `LoadingScreenID`.
 #[derive(Resource)]
 struct LoadingScreenCatalogRes(LoadingScreenCatalog);
 
-/// What a raise means for the tip of the day (decision 2077).
+/// What a raise means for the tip of the day.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) enum TipEdge {
     /// The glue→world entry: pick the next row and advance the cursor.
@@ -192,90 +128,51 @@ pub(crate) enum TipEdge {
     Clear,
 }
 
-/// Loading-screen state machine (decision 0737: event-raised, readiness-cleared).
+/// Loading-screen state machine (event-raised, readiness-cleared).
 #[derive(Resource, Default)]
 pub(crate) struct LoadingScreen {
     active: bool,
-    /// A raise from an entry edge (the pick's `Connected`, `SMSG_TRANSFER_PENDING`) holds until the
-    /// destination snap (worldport/teleport) actually lands — so the OLD location's readiness can
-    /// never clear a screen raised for the NEW one. This is what closes the world-entry flash: the
-    /// login-vista tiles are fully resident the moment the glue tears down, and without this hold
-    /// that residency would clear the screen seconds before `SMSG_LOGIN_VERIFY_WORLD` arrives.
+    /// A raise from an entry edge holds until the destination snap lands, so the old location's
+    /// residency cannot clear a screen raised for the new one (at world entry the login vista is
+    /// resident well before `SMSG_LOGIN_VERIFY_WORLD`).
     awaiting_snap: bool,
-    /// **The map to resolve this screen's art from** — the reference's `[0x82f00c]`, set by every
-    /// raise: the roster's `Character.map` at the pick edge, the transfer's map at
-    /// `SMSG_TRANSFER_PENDING`, the map we are on for a backstop raise. `None` is the reference's
-    /// `-1`: *this screen draws no backdrop* — the boot default, and what a failed resolve leaves
-    /// behind ([`Self::art_resolved`]).
-    ///
-    /// It is deliberately not `CurrentMap`, which moves under a live screen. Log out inside a
-    /// dungeon whose instance is gone by the time you come back and vmangos relocates you *during*
-    /// `Player::LoadFromDB` (`Player.cpp`, the `GetGoBackTrigger` arm) — no
-    /// `SMSG_TRANSFER_PENDING`, no `SMSG_NEW_WORLD`, just a `SMSG_LOGIN_VERIFY_WORLD` naming a
-    /// different map than the roster row the screen was raised from. Reading the art per frame
-    /// from `CurrentMap` made the dungeon backdrop switch to the continent one mid-load; nothing
-    /// on the wire can do that in the reference ([`Self::snap_landed`]).
-    ///
-    /// **This field is not the latch, though — [`Self::art_resolved`] is** (decision 2087). Five
-    /// writers touch `[0x82f00c]` image-wide, all inside the `LoadingScreen.cpp` TU: `0x4067e6`
-    /// and `0x4072d3` store a map id (the two transition entries), and `0x406d0e`/`0x4073d4`/
-    /// `0x407e59` store `-1`. A raise landing on a screen that is already up re-points it
-    /// *unconditionally* — and repaints nothing, because the texture is already resolved.
+    /// The map this screen's art resolves from, the reference's `[0x82f00c]`, set by every raise;
+    /// `None` is its `-1`, no backdrop. Not `CurrentMap`: vmangos can relocate a character inside
+    /// `Player::LoadFromDB` (`Player.cpp:15020`), under a live screen. Its writers: `0x4067e6` and
+    /// `0x4072d3` store a map id, `0x406d0e`, `0x4073d4` and `0x407e59` store `-1`.
     map: Option<u32>,
-    /// **Has this screen resolved its backdrop yet?** — the reference's `[0x882e04]`, the loaded
-    /// texture handle, and the thing the art is actually latched by (decision 2087). `0x406cf0`
-    /// reads the map id only to reject `-1`, then `0x406cfc`/`0x406d01`/`0x406d03` skip the
-    /// resolver `0x406e20` outright whenever the handle is non-null; the handle's three writers
-    /// image-wide are the resolver's two stores and `0x407ed7 = 0` inside the dismiss `0x407e80`.
-    ///
-    /// So the map id decides the picture on **exactly one frame per screen**, and nothing that
-    /// happens afterwards can change it. Cleared by [`Self::dismiss`], never by a raise.
+    /// The reference's `[0x882e04]` texture handle, which latches the art: `0x406cf0` reads the map
+    /// id only to reject `-1`, and `0x406cfc`/`0x406d01`/`0x406d03` skip the resolver `0x406e20`
+    /// while it is set. Cleared by [`Self::dismiss`], never by a raise.
     art_resolved: bool,
-    /// **Plain black cover, no art, no bar** — the logout transition (decision 0738). The logout
-    /// teardown despawns the avatar and the streamed world in the same frame's Net stage, but
-    /// `CharSelect` (and the glue screen with it) only applies at the NEXT frame's state
-    /// transition — without this the dead world renders uncovered for that frame, and it is
-    /// exactly the teardown-burst frame, so it lingers. The ref's world→glue swap shows black
-    /// there too. Dropped the moment the state leaves `InWorld` (the glue owns the screen from
-    /// then, at a higher z); any real raise replaces it with the full screen.
+    /// Plain black cover with no art or bar, for the world→glue cut; dropped once the state leaves
+    /// `InWorld`.
     blackout: bool,
-    /// Consecutive presentable frames while active (see [`CLEAR_AFTER_READY_FRAMES`]).
+    /// Consecutive presentable frames while active ([`CLEAR_AFTER_READY_FRAMES`]).
     ready_frames: u32,
-    /// Monotonic bar fill, 0..1 — only ever advances within a load (reset to 0 on each activation), so
-    /// the bar reads as one continuous stream even though the raw residency ratio dips as `desired`
-    /// shifts while the view moves. A real loading bar never goes backwards.
+    /// Bar fill, 0..1, monotonic within a load: the raw residency ratio dips as the view moves.
     displayed: f32,
-    /// Decoded backdrop art by BLP path, so repeated teleports to a continent don't re-decode.
+    /// Decoded backdrop art by BLP path.
     art_cache: HashMap<String, Handle<Image>>,
-    /// **Which tip the next raise should carry** — `Pick` on the glue→world entry, `Clear` on every
-    /// other raise, taken by [`crate::game_tip::drive_game_tip`] on the same frame. A field rather
-    /// than a message because it is a property OF the raise, and the raise is this struct's.
+    /// Which tip the next raise carries, taken by [`crate::game_tip::drive_game_tip`].
     pub(crate) tip_edge: Option<TipEdge>,
-    /// **Capture only** — the clear below is skipped while this is set. A loading screen is a
-    /// picture that is up for a second and then gone: nothing in the tree could photograph one,
-    /// which is how the tip of the day shipped dead and stayed dead through a live smoke run
-    /// (decision 2083). Written by [`Self::hold_for_capture`] and by nothing a player can reach.
+    /// Capture only: the clear is skipped while set ([`Self::hold_for_capture`]).
     held: bool,
 
-    /// `Time::elapsed_secs` at the last raise + at the last wait-instrument line (see
-    /// [`WAIT_LOG_AFTER`]).
+    /// `Time::elapsed_secs` at the last raise and at the last wait log line.
     active_since: f32,
     last_wait_log: f32,
-    /// The avatar's position as of LAST frame — so a snap's own displacement is knowable here
-    /// (the snap is applied in `Input`, a stage before this one). Read only by the snap raise
-    /// below, which uses it to tell a relocation from a spell's little hop.
+    /// The avatar's position last frame, to measure a snap (applied in `Input`, a stage earlier).
     last_pos: Option<Vec3>,
 }
 
 impl LoadingScreen {
-    /// Whether the opaque loading backdrop currently covers the frame — the world camera renders
-    /// under it (pipeline warm-up), never behind the glue screens (decision 0540).
+    /// Whether the opaque cover is up; the world camera renders under it, never behind the glue.
     pub(crate) fn covering(&self) -> bool {
         self.active
     }
 
-    /// An active cover, for tests that drive covered-frame accounting (the entry-load deferral)
-    /// and the cursor's covered arm.
+    /// An active cover, for tests.
     #[cfg(test)]
     pub(crate) fn test_covering() -> Self {
         Self {
@@ -284,19 +181,13 @@ impl LoadingScreen {
         }
     }
 
-    /// Take the raise's tip edge, if one is pending — read once, by
-    /// [`crate::game_tip::drive_game_tip`].
+    /// Take the pending raise's tip edge; read once, by [`crate::game_tip::drive_game_tip`].
     pub(crate) fn take_tip_edge(&mut self) -> Option<TipEdge> {
         self.tip_edge.take()
     }
 
-    /// **The capture instrument** (`WOW_CAPTURE=loading-tip`): raise the screen the way the
-    /// glue→world entry does — art, bar and a `Pick` edge for the tip — and then never let go, so
-    /// the harness's settle window has something to hold still on. The one screen in the client
-    /// whose whole existence is measured in the seconds before it disappears, made photographable.
-    /// `map` is the destination the art latches to, exactly as a real raise's is ([`Self::map`]):
-    /// the harness knows it from the scenario, and with `None` the shot would be a black box with a
-    /// tip on it rather than the real `Map.dbc` → `LoadingScreens.dbc` → BLP chain.
+    /// The capture instrument (`WOW_CAPTURE=loading-tip`): raise as the glue→world entry does,
+    /// with art, bar and a `Pick` tip, and never clear. `map` latches the art as a raise's does.
     pub(crate) fn hold_for_capture(&mut self, map: Option<u32>) {
         self.active = true;
         self.blackout = false;
@@ -306,13 +197,9 @@ impl LoadingScreen {
         self.tip_edge = Some(TipEdge::Pick);
     }
 
-    /// Raise the screen for a fresh load. `awaiting_snap` marks a raise whose destination snap is
-    /// still in flight; `map` is the destination this screen's art is LATCHED to for its whole life
-    /// ([`Self::map`]) — every caller states what it knows, and a caller with no announced
-    /// destination passes the map we are on rather than leaving the art to follow `CurrentMap`.
-    ///
-    /// **Only an edge that would reach the reference's own transition entries calls this.** The
-    /// destination *snap* is not one of them ([`Self::snap_landed`]).
+    /// Raise the screen for a fresh load, its art latched to `map` for its life (a caller with no
+    /// announced destination passes the current map). Only an edge that reaches the reference's
+    /// transition entries calls this, never a snap ([`Self::snap_landed`]).
     fn raise(&mut self, reason: &str, awaiting_snap: bool, map: Option<u32>, now: f32) {
         self.active = true;
         self.blackout = false;
@@ -325,22 +212,11 @@ impl LoadingScreen {
         info!("loading screen: up ({reason}, map {map:?})");
     }
 
-    /// **The destination snap landed** — `SMSG_NEW_WORLD` or `SMSG_LOGIN_VERIFY_WORLD`. It ends the
-    /// wait a raise armed, and it does **nothing else**: not the art, not the tip, not the bar.
-    ///
-    /// The two are one [`crate::net::WorldportMessage`] here and two handlers in the reference
-    /// (`0x401b00` and `0x401de0`), and *neither touches the screen*:
-    /// the raise `0x406800` has three call sites and all three are inside the `LoadingScreen.cpp`
-    /// TU, so nothing on the wire can re-raise or re-point a screen that is already up. Treating
-    /// the snap as a fresh load is what swapped the backdrop mid-load ([`Self::map`]), restarted
-    /// the bar, and — a round-trip into *every* world entry — wiped the tip of the day that
-    /// decision 2077 had just picked.
-    ///
-    /// `map` is the destination the snap names — `None` for a same-map teleport ack, which cannot
-    /// disagree with the screen by construction.
+    /// The destination snap (`SMSG_NEW_WORLD` or `SMSG_LOGIN_VERIFY_WORLD`) landed: it ends the
+    /// raise's wait and nothing else, not the art, the tip or the bar. The reference's handlers
+    /// (`0x401b00`, `0x401de0`) never touch the screen: the raise `0x406800` has three call sites,
+    /// all inside `LoadingScreen.cpp`. `map` is `None` for a same-map teleport ack.
     fn snap_landed(&mut self, map: Option<u32>) {
-        // Worth a line on its own: the destination the server actually seated us on is not the one
-        // this screen was raised for, i.e. we were relocated between the roster and the login.
         if let (Some(raised), Some(dest)) = (self.map, map) {
             if raised != dest {
                 info!("loading screen: snap landed on map {dest} — raised for map {raised}, art holds");
@@ -349,14 +225,9 @@ impl LoadingScreen {
         self.awaiting_snap = false;
     }
 
-    /// **The far snap's whole rule** — the one place it lives, so the test seam and the system
-    /// cannot drift apart (the [`EntryCover::tick`] pattern, two structs up).
-    ///
-    /// A screen that is already up **is this snap's screen** — the entry raise waiting for
-    /// `SMSG_LOGIN_VERIFY_WORLD`, the portal's waiting for `SMSG_NEW_WORLD` — so the snap ends its
-    /// wait and nothing more. Returns `true` only when no screen is up at all, which is the
-    /// caller's cue to raise one: our backstop for a server-initiated port that arrived with no
-    /// announcing edge (the reference needs no such backstop — its own world load blocks).
+    /// A far snap: a screen already up is this snap's own, so the snap only ends its wait. Returns
+    /// `true` when no screen is up and the caller should raise one, our backstop for a port with no
+    /// announcing edge (the reference's blocking world load needs none).
     #[must_use]
     fn far_snap(&mut self, map: u32) -> bool {
         if !self.active {
@@ -366,15 +237,13 @@ impl LoadingScreen {
         false
     }
 
-    /// **The dismiss** (the reference's `0x407e80`) — the one place the screen comes down, so the
-    /// things a screen owns for its lifetime come down with it exactly once. The tip is one of
-    /// those: `[0x882e10]`'s only writers image-wide are the `EnterWorld` setter `0x406630` and
-    /// `0x407f2b` inside this dismiss, so a *raise* never clears a tip — only this does.
+    /// The dismiss (the reference's `0x407e80`), the only place a tip clears: `[0x882e10]`'s
+    /// writers are the `EnterWorld` setter `0x406630` and `0x407f2b` here.
     fn dismiss(&mut self) {
         self.active = false;
         self.blackout = false;
         self.tip_edge = Some(TipEdge::Clear);
-        // `0x407ed7 mov ds:0x882e04,edi` — the next screen resolves its own art, and only here.
+        // `0x407ed7` clears `[0x882e04]`: the next screen resolves its own art.
         self.art_resolved = false;
     }
 }
@@ -388,8 +257,7 @@ struct LoadingBackdrop;
 struct LoadingBarFill;
 #[derive(Component)]
 struct LoadingBarBorder;
-/// The tip-of-the-day text block (decision 2077) — its `Text` root; the coloured runs are its
-/// children, rebuilt when the shown tip changes.
+/// The tip-of-the-day `Text` root; its coloured runs are children, rebuilt when the tip changes.
 #[derive(Component)]
 pub(crate) struct LoadingTip;
 
@@ -399,34 +267,25 @@ impl Plugin for LoadingScreenPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<LoadingScreen>()
             .init_resource::<EntryCover>()
-            // `First`, ahead of every consumer in `PreUpdate` and `Update` — see [`EntryCover`].
+            // In `First`, ahead of every consumer in `PreUpdate` and `Update`.
             .add_systems(First, count_entry_cover)
             .add_systems(Startup, setup_loading_screen.after(AssetSet::Open))
-            // In `WorldStage::Present` (after Input + Stream): we read residency for the SAME frame's
-            // player position — a teleport snaps in Input → the streamer recomputes focus in Stream →
-            // we cover it here. Visibility set now propagates in PostUpdate and renders this frame, so
-            // the swap never flashes.
+            // In `WorldStage::Present`, after Input and Stream: a teleport snaps in Input and the
+            // streamer refocuses in Stream, so the cover lands on the same frame, never a flash.
             .add_systems(Update, drive_loading_screen.in_set(WorldStage::Present));
-        // …and the other half of what a cover *is*: while it is up, the client takes no input
-        // (`input`). Wired here rather than as a plugin of its own so the cover and its input rule
-        // can never be registered apart.
+        // The cover's input rule, registered here so the two cannot be registered apart.
         input::build(app);
     }
 }
 
-/// Startup: load the LoadingScreens catalog + the bar texture stack off the shared chain, and spawn
-/// the (initially hidden, then activated on the first `drive` frame) UI tree.
+/// Startup: load the LoadingScreens catalog and the bar textures, and spawn the hidden UI tree.
 fn setup_loading_screen(
     mut commands: Commands,
     world_assets: Option<ResMut<WorldAssets>>,
     mut images: ResMut<Assets<Image>>,
 ) {
-    // Root: fullscreen black — this IS the pillarbox letterbox, and it spawns UNCONDITIONALLY.
-    // Every `covering()` consumer (the world camera stays active to warm pipelines, the warm
-    // pass, the settle hold, and now the audio hold) behaves as if covered whenever
-    // `LoadingScreen::active` is true — so a missing catalog or bar texture must degrade to a
-    // plain black cover, never to "no cover node at all" while the whole client pretends one is
-    // up (the naked-world failure this used to be). Flex-centres the 4:3 content area.
+    // The black pillarbox root spawns unconditionally: `covering()` consumers act as covered while
+    // the screen is active, so missing art must still leave a black cover.
     let root = commands
         .spawn((
             LoadingRoot,
@@ -439,7 +298,7 @@ fn setup_loading_screen(
                 ..default()
             },
             BackgroundColor(Color::BLACK),
-            // Above the 3D scene; UI already paints after the main pass, this orders within UI.
+            // UI already paints after the 3D scene; this orders within UI.
             GlobalZIndex(1000),
             Visibility::Hidden,
         ))
@@ -461,22 +320,17 @@ fn setup_loading_screen(
         }
     }
 
-    // The two layers 1.12 actually draws (sRGB clamp sprites — UI art, not tiling world art).
+    // The two layers 1.12 draws, as sRGB clamp sprites.
     let mut tex = |path: &str| assets.sprite_texture(path, &mut images);
     let Some(border) = tex("Interface\\Glues\\LoadingBar\\Loading-BarBorder.blp") else {
         error!("loading bar textures missing — plain black cover, no art");
         return;
     };
     let fill = tex("Interface\\Glues\\LoadingBar\\Loading-BarFill.blp").unwrap_or_default();
-    // The spawned ImageNodes below own these handles (the root is never despawned, only hidden), so
-    // the textures stay resident without a separate holder resource.
 
     commands.entity(root).with_children(|root| {
-        // The whole loading screen renders in one 4:3 area fit to viewport height, centred, with
-        // the root's black showing as pillarbox bars L/R (the reference's behaviour — the glue/load
-        // screen is authored 4:3; on a wider window it letterboxes). Width = height·4/3 in vh.
-        // The backdrop + bar are children, so their verified fractions are relative to THIS area.
-        // Sibling paint order = spawn order: backdrop → fill → border (border on top).
+        // One 4:3 area fit to the viewport height and centred; the bar's fractions are relative
+        // to it. Paint order is spawn order: backdrop, tip, fill, border.
         root.spawn(Node {
             width: Val::Vh(100.0 * BACKDROP_ASPECT),
             height: Val::Vh(100.0),
@@ -484,8 +338,7 @@ fn setup_loading_screen(
             ..default()
         })
         .with_children(|area| {
-            // Backdrop art: the square BLP stretched to fill the 4:3 area (mild widen — what the
-            // reference does). Starts black (default-white texture tinted) until the art resolves.
+            // Tinted black until the art resolves.
             area.spawn((
                 LoadingBackdrop,
                 ImageNode {
@@ -500,16 +353,10 @@ fn setup_loading_screen(
                     ..default()
                 },
             ));
-            // The tip of the day (decision 2077), drawn between the background quad and the
-            // progress bar — the reference's own order (`0x406e12`/`0x406e18`). The block is
-            // positioned in PERCENT of this 4:3 area, which is exactly the space
-            // `crate::game_tip`'s constants are in; only the font size and the shadow need pixels,
-            // and those follow the window each frame. Empty and hidden until a glue->world raise
-            // fills it.
+            // The tip, between the backdrop and the bar as in the reference (`0x406e12`,
+            // `0x406e18`), placed in percent of this area, the space of `crate::game_tip`.
             area.spawn((LoadingTip, crate::game_tip::tip_bundle()));
-            // Fill — left-anchored; width = progress·FILL_MAX_WIDTH (set each frame). y from the
-            // BOTTOM (verified by screenshot + binary). The fill art is a horizontally-uniform
-            // gradient, so width-scaling reads as a left→right reveal.
+            // The fill art is a horizontally uniform gradient, so scaling its width is a reveal.
             area.spawn((
                 LoadingBarFill,
                 Node {
@@ -547,14 +394,12 @@ fn setup_loading_screen(
     });
 }
 
-/// Per-frame: observe the lifecycle edges, run the trigger/clear state machine, resolve backdrop
-/// art, and push the progress fraction into the bar.
+/// Per frame: observe the lifecycle edges, run the raise and clear rules, resolve the backdrop and
+/// set the bar.
 #[allow(clippy::type_complexity)]
 fn drive_loading_screen(
     mut screen: ResMut<LoadingScreen>,
-    // The streamer's two published facts, bundled into one param (Bevy's 16-element system-param
-    // ceiling, the same squeeze `player::control` and `feed_ui_input` already pay): what is
-    // resident, and whether that residency is even ABOUT the player's own ground this frame.
+    // Bundled to stay under Bevy's 16-parameter ceiling.
     stream: (
         Res<WorldLoadProgress>,
         Res<benilla_world::terrain_stream::ViewFocus>,
@@ -576,23 +421,12 @@ fn drive_loading_screen(
         ),
     >,
     player: Option<Res<crate::player::Player>>,
-    // **Real, not virtual** — this clock measures a LOAD, and `Time<Virtual>` clamps any frame
-    // longer than 250 ms (`transport.rs` names the same constant for the same reason). A loading
-    // screen is made of exactly those frames, so the default clock under-reports it: measured on
-    // one smoke re-entry, a cover that was up for 2.24 s wall reported 1.2 s. An instrument whose
-    // whole job is "how long was this up, and what was blocking it" cannot run on a clock that
-    // discards the stalls.
+    // Real time: `Time<Virtual>` clamps frames over 250 ms, and a load is made of those.
     time: Res<Time<Real>>,
-    // The 0837 warm pass: the cover holds until the menagerie's pipelines have compiled — the
-    // point of the cover is that NOTHING first-sight-compiles after it lifts.
+    // The cover holds until the warm pass has compiled its pipelines.
     warm: Res<crate::pipe_warm::WarmPass>,
-    // The deferred world-entry UI load (0962's frame accounting, applied to 1051's burst):
-    // armed at the entry edge, run behind this cover a few frames in. While it is still
-    // pending the reveal would show a world with no interface — the reference's reveal always
-    // has the UI up, because its UI load happens inside its blocking world load.
+    // The world-entry UI load runs behind this cover; the reference's reveal always has the UI up.
     entry_ui_pending: Option<Res<crate::ui_script::PendingEntryUiLoad>>,
-    // The lifecycle edges (decisions 0737/0738), all observed from what the net bridge already
-    // publishes — this module owns the whole state machine, nothing else is instrumented for it.
     edges: (
         Res<State<crate::char_select::ClientState>>,
         MessageReader<crate::net::EnteredWorldMessage>,
@@ -619,70 +453,46 @@ fn drive_loading_screen(
     let (progress, focus) = (&stream.0, &stream.1);
     let now = time.elapsed_secs();
     let map_id = current_map.as_ref().map(|m| m.0);
-    // The physics hold releases on the same residency signal that clears this screen (decision
-    // 0737 — never on ground contact), so waiting for it costs nothing and guarantees the safe
-    // order: the body's world is live before the reveal, never a reveal of a body about to drop.
+    // The physics hold releases on the same residency signal, so the body's world is live first.
     let player_settling = player.as_ref().is_some_and(|p| p.settling);
 
     // --- The edges. ---
-    // A real glue entry (not 0065's seamless in-world reconnect, which must stay seamless): the
-    // same frame `enter_on_connected` flips the state that tears the glue down, this raise puts
-    // the cover up — raise and teardown are atomic by construction. The destination snap
-    // (`SMSG_LOGIN_VERIFY_WORLD`) is still a server character-load away; `awaiting_snap` holds the
-    // screen across that gap. Art resolves at once from the roster's own `Character.map`.
+    // A glue entry (not the seamless in-world reconnect), raised on the frame the glue tears down
+    // and held across the server's character load; the art comes from the roster's map.
     if entered.read().next().is_some() && *state.get() != crate::char_select::ClientState::InWorld {
         let map = roster.as_ref().and_then(|r| r.pending_map());
         screen.raise("world entry", true, map, now);
-        // **The tip of the day rides THIS edge and no other** (decision 2077): the reference's
-        // setter `0x406630` has exactly one caller, inside `CGlueMgr::EnterWorld`, and neither
-        // `SMSG_TRANSFER_PENDING` arm reaches it — so a portal or worldport screen carries no tip.
-        // The pick itself is `crate::game_tip`'s, one system over; this list is at Bevy's
-        // sixteen-parameter ceiling and the tip needs three resources of its own.
+        // The tip rides this edge alone: the reference's setter `0x406630` has one caller, in
+        // `CGlueMgr::EnterWorld`, which neither `SMSG_TRANSFER_PENDING` arm reaches.
         screen.tip_edge = Some(TipEdge::Pick);
     }
-    // A portal walk-in (`SMSG_TRANSFER_PENDING`, no transport): the server is about to unload us
-    // and the `SMSG_NEW_WORLD` snap follows after its own load — cover now, like the reference.
-    // Transport crossings (0455) keep riding visibly until their worldport lands below.
+    // A portal (`SMSG_TRANSFER_PENDING`, no transport): cover now, before the server unloads us, as
+    // the reference does. A transport crossing rides visibly until its worldport lands.
     if let Some(t) = transfer.as_ref().filter(|t| t.is_changed()) {
         match &t.0 {
             Some(info) if info.transport_entry.is_none() => {
                 screen.raise("transfer pending", true, Some(info.map_id), now);
             }
-            // The latch cleared with no snap in flight = `SMSG_TRANSFER_ABORTED` (a worldport
-            // clears it too, but that path also lands below this frame): stop awaiting, and the
-            // still-resident old world clears the screen through the ordinary debounce.
+            // Cleared with no snap in flight is `SMSG_TRANSFER_ABORTED` (a worldport lands below
+            // this frame): stop waiting, and the resident old world clears the screen.
             None => screen.awaiting_snap = false,
             Some(_) => {}
         }
     }
-    // The snap ([`LoadingScreen::far_snap`]): it never re-raises a live screen, so the art that
-    // screen was raised with holds even when the server seats us on a different map than the one
-    // it announced. That is the reference exactly — `0x406800` is reachable from nothing outside
-    // the loading-screen TU, so no packet can re-point a screen that is up.
+    // A snap never re-raises a live screen ([`LoadingScreen::far_snap`]).
     for w in worldports.read() {
         if screen.far_snap(w.map_id) {
             screen.raise("worldport", false, Some(w.map_id), now);
         }
     }
-    // A same-map teleport just ends any awaited snap — whether it needs a screen at all is the
-    // backstop's call below (a summon across the room shouldn't flash one).
+    // A same-map teleport ends any awaited snap; whether it needs a screen is decided below.
     let teleported = teleports.read().next().is_some();
     if teleported {
         screen.snap_landed(None);
     }
-    // Logout (decision 0738): the same frame's Net stage despawned the avatar and tore the world
-    // down, but `CharSelect` only applies at the NEXT frame's state transition — cover the dead
-    // world with plain black until the glue owns the screen. No art, no bar: the ref's
-    // world→glue swap is a black cut, not a loading screen.
-    // A dead session is the same world→glue cut (decision 1262), and it needs this arm more than
-    // logout does: the entry race raises the cover on `EnteredWorldMessage` a few lines up and
-    // arms `awaiting_snap` for a snap the dead socket will never send, so without the disarm here
-    // the cover is what the player would have been left staring at.
+    // Logout, a lost session or a refused login: `CharSelect` applies next frame, so cover the torn
+    // down world with black (the reference's world→glue cut), and disarm a snap that will not come.
     let session_over = lost.read().any(|m| m.session_over);
-    // A **refused character login** is the same cut, and it needs the disarm as badly as a dead
-    // session does: the entry edge above raised the cover with `awaiting_snap` armed for a snap
-    // the server has just told us will never come, and nothing else in this function can end that
-    // wait. Left alone it is a loading screen with no world behind it and no way off.
     let refused = refusals.read().next().is_some();
     if logouts.read().next().is_some() || session_over || refused {
         screen.active = true;
@@ -705,53 +515,24 @@ fn drive_loading_screen(
         screen.dismiss();
     }
 
-    // --- Backstop trigger: the ground under the view focus isn't resident and nothing raised us
-    // (a far same-map `.tele`, or any path with no edge). Normal streaming keeps the focus tile
-    // resident, so this never fires while walking.
-    //
-    // **In world only** (decision 0777). It used to fire at boot as well, and that was load-bearing
-    // by accident: a raised screen keeps the world camera active (0540), which is what compiled the
-    // world's pipelines behind the glue. But it only worked because the world was being streamed
-    // behind the glue in the first place — with no world to load there, the same trigger would put
-    // an invisible screen up forever against residency that never arrives. The warm-up is not lost,
-    // it MOVED: the world now loads under the cover this same function raises on world entry, which
-    // is where a warm-up belongs. ---
-    //
-    // **And only while the focus IS the body** ([`ViewFocus::follows_body`]). The trigger's whole
-    // premise is "residency says the ground under the player is missing and no edge announced it,
-    // so a load must be happening". While the eye is deliberately elsewhere — a cinematic fly-by,
-    // a free-fly — residency describes the *camera's* tile, and reading it as a fact about the
-    // player is reading someone else's ground (decision 1336's lesson, one consumer over).
-    // Measured: every cinematic raised this cover the instant it started (`.debug play cinematic
-    // 41` → "loading screen: up (focus not resident, map None)" in the same millisecond as the
-    // shot), covering the opening seconds of the fly-by the deferred-start latch exists to protect
-    // — and, once the body took the settle hold for the same detachment, covering ALL of it,
-    // because this cover's clear waits on that hold and that hold waits on the focus coming home.
+    // --- Backstop: the ground under the focus is not resident and nothing raised us. In world
+    // only, since behind the glue nothing loads; and only while the focus is the body, since in a
+    // cinematic or free-fly residency describes the camera's tile. ---
     if !screen.active
         && !progress.focus_resident
         && focus.follows_body()
         && *state.get() == crate::char_select::ClientState::InWorld
     {
-        // Same map by construction — the destination this covers is the ground under the body.
+        // Same map by construction: the ground under the body.
         screen.raise("focus not resident", false, map_id, now);
     }
 
-    // --- …and the same test at the SNAP, on everything the reveal actually needs. The backstop
-    // above watches one term — the focus TERRAIN tile — and a teleport inside the streamer's keep
-    // band (up to ~1600 yd, three tiles) lands on ground that is already resident, so it never
-    // fires. The destination's *buildings* are a different question: their placements may still be
-    // spawning, and since the retained pass (1429) a spawned building still has a bake between it
-    // and the screen. That is how `.tele` across a city put the player down in a Stormwind with no
-    // Stormwind in it, uncovered, for the frames it took to arrive.
-    //
-    // Only at a snap, and only against the same predicate that CLEARS the screen: a summon across
-    // a room whose world is already there raises nothing (no flash), and ordinary walking — which
-    // crosses tile lines with placements pending all day — is not a snap and cannot reach this. ---
+    // --- At a snap, the same test against the clear's own predicate: a teleport inside the keep
+    // band lands on resident terrain while the destination's buildings may still be arriving. ---
     let body = player.as_ref().map(|p| p.pos);
     let relocated = match (teleported, screen.last_pos, body) {
         (true, Some(was), Some(now_pos)) => was.distance(now_pos) >= SNAP_LOAD_MIN_YD,
-        // No previous position to compare (the entry frame): treat the snap as a relocation, the
-        // conservative arm — a covered load is recoverable, a naked one is what this closes.
+        // No previous position (the entry frame): treat it as a relocation.
         (true, _, _) => true,
         _ => false,
     };
@@ -764,9 +545,7 @@ fn drive_loading_screen(
         screen.raise("teleport, destination not presentable", false, map_id, now);
     }
 
-    // --- Clear: the destination snap has landed, the scene is presentable (tiles + focus
-    // placements + colliders — [`WorldLoadProgress::presentable`]), and the physics hold is done,
-    // sustained a few frames. ---
+    // --- Clear, sustained a few frames. ---
     if screen.active && !screen.held {
         if progress.is_ready()
             && progress.presentable()
@@ -787,7 +566,6 @@ fn drive_loading_screen(
             }
         } else {
             screen.ready_frames = 0;
-            // The wait instrument (0737): a screen up past the threshold names the blocking term.
             if now - screen.active_since > WAIT_LOG_AFTER
                 && now - screen.last_wait_log >= WAIT_LOG_EVERY
             {
@@ -811,8 +589,7 @@ fn drive_loading_screen(
         }
     }
 
-    // --- Visibility. The root is the cover; the backdrop art + bar hide under blackout (0738's
-    // plain black cut — the root's black background IS the frame then). ---
+    // --- Visibility: under blackout only the root's black shows. ---
     if let Ok(mut vis) = root.single_mut() {
         *vis = if screen.active {
             Visibility::Visible
@@ -839,15 +616,10 @@ fn drive_loading_screen(
         return;
     }
 
-    // --- Backdrop art — `0x406cf0`'s gate in shape (decision 2087): the map id is read ONCE per
-    // screen, to resolve the texture; from then on the resolved texture is what draws, and only
-    // the dismiss clears it. A raise landing on a live screen re-points [`LoadingScreen::map`] and
-    // repaints nothing, which is why "the screen you were given is the screen you keep" survives
-    // even a transfer arriving mid-load. Resolution walks the FK chain and caches by path. ---
+    // --- Backdrop art, `0x406cf0`'s gate: the map id is read once per screen to resolve the
+    // texture, so a raise onto a live screen repaints nothing. ---
     if !screen.art_resolved {
-        // Until this screen's own art lands, the backdrop is the root's black — never the LAST
-        // screen's texture, which is what a stale tint would leave on the glass (the reference
-        // holds a null handle here and does not draw the quad at all).
+        // Black, never the last screen's texture (the reference holds a null handle, no quad).
         if let Ok((mut img, _)) = backdrop.single_mut() {
             if img.color != Color::BLACK {
                 img.color = Color::BLACK;
@@ -870,15 +642,11 @@ fn drive_loading_screen(
             match (handle, backdrop.single_mut()) {
                 (Some(handle), Ok((mut img, _))) => {
                     img.image = handle;
-                    img.color = Color::WHITE; // reveal the art (was tinted black)
+                    img.color = Color::WHITE; // untint to reveal the art
                     screen.art_resolved = true;
-                    // Once per screen, and the only place the picture is decided — so "which
-                    // backdrop did that load actually show" is a log line rather than a capture.
                     info!("loading screen: backdrop for map {map_id} resolved");
                 }
-                // The resolve failed — no `LoadingScreens` row, or the BLP is missing. This screen
-                // shows no backdrop for the rest of its life and does not retry: `0x406d0e` writes
-                // `-1` into the map id for exactly this, and `0x406cf0` early-returns on it after.
+                // No retry: `0x406d0e` writes `-1` into the map id and `0x406cf0` returns on it.
                 _ => {
                     warn!("loading screen: no backdrop for map {map_id} — plain black this load");
                     screen.map = None;
@@ -887,9 +655,7 @@ fn drive_loading_screen(
         }
     }
 
-    // --- Progress bar: monotonic fill, reveals left→right, width = progress·FILL_MAX_WIDTH.
-    // While the snap is still in flight the residency being published is the OLD location's
-    // (fully resident) — hold the bar at zero until the destination's own numbers exist. ---
+    // --- Progress bar: zero until the snap lands (residency is still the old place's). ---
     if !screen.awaiting_snap {
         screen.displayed = screen.displayed.max(progress.fraction());
     }
@@ -903,11 +669,6 @@ fn drive_loading_screen(
 mod tests {
     use super::*;
 
-    /// **The one fact three consumers now share** ([`EntryCover`]). Two of them each kept their
-    /// own copy of this count (0962's menagerie, 1345's FrameXML load) and the third — the world
-    /// camera, which renders the whole arriving world on the same frame — never had one at all,
-    /// which is the freeze this round measured. The arithmetic is trivial; that it has exactly one
-    /// home is the point.
     #[test]
     fn the_cover_counts_frames_to_the_glass_and_resets_the_moment_it_drops() {
         let mut cover = EntryCover::default();
@@ -935,22 +696,15 @@ mod tests {
         );
         assert!(!cover.owes_a_present());
 
-        // A reveal (or leaving the world) drops it back to the uncovered arm in one frame — the
-        // next raise must not inherit the last one's credit.
+        // A reveal drops the count to zero in one frame; the next raise earns its own.
         cover.tick(false);
         assert_eq!(cover.frames(), 0);
         assert!(cover.presented());
         cover.tick(true);
         assert!(!cover.presented(), "the next raise starts its own count");
     }
-    /// **The director's report, as an assertion.** Log out inside a dungeon, come back hours
-    /// later, and the instance is gone: vmangos relocates the character to the dungeon's go-back
-    /// trigger *inside* `Player::LoadFromDB`, before the world is entered — so no
-    /// `SMSG_TRANSFER_PENDING` and no `SMSG_NEW_WORLD` ever announce it, and the first the client
-    /// hears is `SMSG_LOGIN_VERIFY_WORLD` naming a map the roster row did not. The screen keeps
-    /// the art it was raised with, for its whole life. The reference could not do otherwise:
-    /// `[0x82f00c]` has no writer on either world-load handler's path (`0x401b00`/`0x401de0`), and
-    /// the raise `0x406800` is reachable from nothing outside the `LoadingScreen.cpp` TU.
+    /// vmangos can relocate a character out of an expired instance inside `Player::LoadFromDB`, so
+    /// `SMSG_LOGIN_VERIFY_WORLD` names another map than the roster did.
     #[test]
     fn a_relocating_snap_cannot_move_the_art_the_screen_was_raised_with() {
         let mut screen = LoadingScreen::default();
@@ -986,9 +740,8 @@ mod tests {
         assert!(screen.active, "the screen stays up across its own snap");
     }
 
-    /// The other half of the same rule: a cross-map port that arrived with **no** announcing edge
-    /// still gets a cover. This is ours, not the reference's — its own world load blocks, so it
-    /// needs no backstop.
+    /// A cross-map port with no announcing edge still gets a cover: our backstop, which the
+    /// reference's blocking world load does not need.
     #[test]
     fn a_snap_with_nothing_covering_it_asks_for_a_raise() {
         let mut screen = LoadingScreen::default();
@@ -999,10 +752,6 @@ mod tests {
         );
     }
 
-    /// **The tip comes down with the screen, never with a raise** — `[0x882e10]`'s only writers
-    /// image-wide are `EnterWorld`'s setter `0x406630` and `0x407f2b`, inside the dismiss
-    /// `0x407e80`. Ours used to clear it on every non-entry raise, which meant the login snap wiped
-    /// the tip a server round-trip into *every* world entry.
     #[test]
     fn only_the_dismiss_clears_the_tip() {
         let mut screen = LoadingScreen::default();
@@ -1021,11 +770,7 @@ mod tests {
         assert!(!screen.active);
     }
 
-    /// **What a live screen SHOWS is latched by the resolved texture, not by the map id**
-    /// (decision 2087, correcting 2081's reading). A raise onto a screen that is already up
-    /// re-points `[0x82f00c]` unconditionally — the reference's `0x406640`/`0x4072c0` have no
-    /// guard on that store — and repaints nothing, because `0x406cf0` skips the resolver whenever
-    /// `[0x882e04]` is non-null. Only the dismiss `0x407ed7` clears it.
+    /// The reference's raises (`0x406640`/`0x4072c0`) store the map id with no guard.
     #[test]
     fn a_raise_onto_a_live_screen_repoints_the_map_but_never_the_picture() {
         let mut screen = LoadingScreen::default();
diff --git a/crates/benilla-app/src/loading_screen/input.rs b/crates/benilla-app/src/loading_screen/input.rs
index 3863cf22..060871ca 100644
--- a/crates/benilla-app/src/loading_screen/input.rs
+++ b/crates/benilla-app/src/loading_screen/input.rs
@@ -1,100 +1,25 @@
-//! **The cover takes the input plane.** While the loading screen covers the frame, benilla accepts
-//! no mouse and no keyboard: no hover, no cursor classification, no click, no keybinding, no
-//! camera, no movement. One system, at the source, so *nothing under the cover has to know the
-//! cover exists*.
+//! While the loading screen covers the frame, no mouse or keyboard input reaches anything: one
+//! cut at the source, in `PreUpdate` after `InputSystems`, so no consumer needs to know the cover.
+//! The reference does the same: the raise (`0x406800`, `0x4068e0 call 0x4069e0`) registers the
+//! stub `0x406a50` (`xor eax,eax; ret`) at priority 8.0 on event categories 1, 8 (key down), 0xa
+//! (repeat), 0xb (button down) and 0xc (mouse move), above every `CSimpleTop` handler at 1.0; the
+//! dispatcher `0x4245b0` stops on a zero return (`0x4246ad`), and the dismiss `0x407e80`
+//! unregisters them.
+//! Category 0xc feeds `UpdateMouseFocus` (`0x7660d0`), so the cursor freezes.
 //!
-//! ## The reference does this too, and it does it at the source
+//! - Up edges are swallowed too, which matches by outcome: the reference's held key comes back
+//!   released on world enter (`0x4908c0 → 0x49093c → 0x5144c0`).
+//! - Deviation: the wheel is swallowed, where the reference still zooms the hidden camera, because
+//!   nothing should act through the screen.
+//! - Deviation: the world pick is cleared, where the reference's `0x481790` keeps picking at the
+//!   frozen point, because ours is quieter and looks the same: the reference's pointer cannot
+//!   move, so its pick changes nothing visible.
 //!
-//! This file was written on the assumption that the reference simply blocks inside its world load,
-//! so the question never arises there. The disassembly behind decision 1990 says otherwise, and
-//! the answer is better than the assumption: **the reference has an explicit input veto, registered
-//! by the screen's own raise.**
-//!
-//! `0x406800` (the raise) ends `0x4068e0 call 0x4069e0`, which registers the three-byte stub
-//! `0x406a50` — `xor eax,eax; ret` — on event-bus categories **1, 8 (key down), 0xa (auto-repeat),
-//! 0xb (button down) and 0xc (mouse move)** at priority **8.0f**; `0x407e80` (the dismiss)
-//! unregisters all five. The dispatcher `0x4245b0` stops its walk on a zero return (`0x4246ad`),
-//! and every `CSimpleTop` input handler sits at 1.0f — so those five categories never reach the
-//! interface at all while the screen is up. Category 0xc's registrant is `UpdateMouseFocus`
-//! (`0x7660d0`) itself, so the veto stops the pointer resolver outright: **the cursor freezes.**
-//! Key-up, button-up, the wheel, category 0x10 and `WM_ACTIVATE` are deliberately let through.
-//!
-//! So the shape below is the reference's shape — one veto at the source, not a condition on each
-//! consumer — arrived at independently and then confirmed. Two deliberate differences, named
-//! rather than drifted into:
-//!
-//! - **We swallow the wheel and the up edges too.** The up edges are equivalent by outcome: the
-//!   reference's held key comes back **released** anyway (`0x4908c0 → 0x49093c → 0x5144c0` zeroes
-//!   the movement mask on world-enter, and a still-held key cannot re-arm it — it reclassifies to
-//!   the vetoed auto-repeat category), which is exactly what the release edge below produces. The
-//!   wheel is a real deviation: in the reference a notch under the loading screen still zooms the
-//!   camera you cannot see. Swallowing it is the director's "nothing through the screen", and it
-//!   costs a zoom nobody asked for.
-//! - **We clear the world pick; the reference leaves it running at the frozen point.** `0x481790`
-//!   hangs off the layer walk rather than the bus, so it keeps picking — and in the two windows
-//!   where a world is populated (before `SMSG_NEW_WORLD`, and again once the new player object
-//!   exists) it *can* set a context cursor under the screen. It is invisible there only because the
-//!   pointer cannot move. Ours is strictly quieter and observably identical.
-//!
-//! ## Why this is a source cut and not a run condition
-//!
-//! The obvious way to build it is a run condition per input system. That is the way it regresses:
-//! the census behind this module counted **fifty-one** places raw input enters the app, more than
-//! half of them with no state gate of any kind — the whole `target::TargetUpdate` pick chain
-//! included, which is the one the director caught. Every one of them would have had to remember,
-//! and every future one would have to remember too. The director's report was exactly a thing
-//! nobody remembered: the world pick ran under the cover, found a unit, and the *hardware cursor
-//! changed to the sword* over art the player was only waiting on.
-//!
-//! So the cut is at the source, in `PreUpdate`, after `bevy::input::InputSystems` has built this
-//! frame's input and before anything reads it. A consumer written a year from now is covered
-//! without knowing this file exists — which is the only property that survives a multi-year
-//! codebase.
-//!
-//! ## The four things it takes, and what makes the pointer half work
-//!
-//! 1. **The button planes** — `ButtonInput<KeyCode>`/`<Key>`/`<MouseButton>`. See [`swallow`] for
-//!    the exact rule: a press that arrives under the cover never happened, and anything held from
-//!    *before* the cover is released once, with a real release edge, so a gesture already in
-//!    flight (a mouselook session, a held `MOVEFORWARD` binding, an armed UI drag) unwinds through
-//!    the path it already has for a released button instead of being stranded down forever.
-//! 2. **The raw message queues** — `KeyboardInput`, `MouseButtonInput`, `MouseMotion`,
-//!    `MouseWheel`, `CursorMoved` — drained, because a `MessageReader` reads the queue, not the
-//!    button state (`feed_ui_input`'s character/EditBox feed and the glue screens all read raw).
-//! 3. **The accumulators** — `AccumulatedMouseMotion`/`AccumulatedMouseScroll`, which
-//!    `InputSystems` builds from those same messages and which the camera and the wheel bindings
-//!    poll rather than read.
-//! 4. **The pointer position itself**, which is the half a message drain cannot reach: a hit-test
-//!    does not read an event, it reads `Window::cursor_position()`, a *field*. So the cover blanks
-//!    it and restores it on the way out ([`CoveredPointer`]).
-//!
-//! That fourth one is the load-bearing trick, and it is not a hack: **"the pointer is not in the
-//! window" is a state every pointer consumer in the client already implements correctly**, because
-//! it is the ordinary alt-tabbed-away case. `update_hover`/`update_hovered_object` clear
-//! [`crate::target::Hovered`] and return; `update_pick_occlusion` leaves the ray at infinity;
-//! `classify_cursor` then reads an empty pick and settles on Point; `feed_ui_input` takes its
-//! `pointer_left_window()` arm, which leaves the hovered frame (one `OnLeave`) and disarms any
-//! press/drag; bevy's own `ui_focus_system` clears every `Interaction`, so `glue_clicks` goes
-//! quiet with it. Not one of those had to be told about loading screens.
-//!
-//! ## What it deliberately does not take
-//!
-//! **Synthetic input.** The capture probes press into the same `ButtonInput` resources — but they
-//! do it in `Update`, after this system, and the pointer probes drive
-//! `ui_script::SyntheticPointer` rather than the window. An instrument driving the client is the
-//! operator, not the player. The two probe writers that *do* run in `PreUpdate` order themselves
-//! [`after`](CoverInput) this set so the relationship is written down rather than left ambiguous.
-//!
-//! **The cursor's own art.** Parking it at the plain arrow and dropping any item/spell overlay is
-//! the reference's `0x6e4940` (cursor index 1, set *before* the screen goes up), and it lives with
-//! the cursor in [`crate::cursor`] rather than here — it is an output, not a channel.
-//!
-//! **Nothing else.** There is no dev exemption: the debug panel, the perf pill, the inspector and
-//! their chords go quiet under the cover along with everything else. That is a real cost — a stuck
-//! load is exactly when you want the instruments — and it is deliberate, because the alternative
-//! is a keycode allowlist, and a keycode handed to the dev plane is also a keycode handed to the
-//! keybinding table. The diagnosis path for a stuck load is the wait instrument
-//! ([`super::WAIT_LOG_AFTER`]), which names the blocking term without anyone touching a key.
+//! Taken: the button planes ([`swallow`]), the raw message queues, the mouse accumulators, and the
+//! window's cursor position, blanked so every hit-test takes its pointer-outside-the-window path
+//! ([`CoveredPointer`]). Not taken: synthetic probe input, written in `Update` or ordered after
+//! [`CoverInput`]. The cursor art (`0x6e4940`, the plain arrow) lives in [`crate::cursor`]. There
+//! is no dev exemption; a stuck load is diagnosed by [`super::WAIT_LOG_AFTER`].
 
 use bevy::input::keyboard::{Key, KeyboardInput};
 use bevy::input::mouse::{
@@ -106,80 +31,32 @@ use bevy::window::{CursorLeft, CursorMoved, PrimaryWindow};
 
 use super::LoadingScreen;
 
-/// The set [`swallow_input_under_the_cover`] runs in — `PreUpdate`, after
-/// `bevy::input::InputSystems` and before `bevy::ui::UiSystems::Focus`.
-///
-/// Exported so the handful of `PreUpdate` systems that legitimately write input — the capture
-/// probes — can order themselves after it instead of racing it.
+/// The set [`swallow_input_under_the_cover`] runs in, between `InputSystems` and
+/// `UiSystems::Focus`; the capture probes that write input in `PreUpdate` order after it.
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub(crate) struct CoverInput;
 
-/// Where the OS pointer really is while the cover has the window's cursor position blanked.
+/// Where the OS pointer is while the cover has the window's cursor position blanked, re-read every
+/// covered frame and handed back when the cover drops, so hover works without a mouse move.
 ///
-/// Re-read every covered frame, not stashed once: `bevy_winit` keeps writing the window's position
-/// on every physical move regardless of whether anyone reads the `CursorMoved` message we drain,
-/// so this tracks the pointer through the whole load and hands it back on the way out. Without the
-/// hand-back the position would stay `None` until the player's next mouse move — hover would come
-/// back dead after a teleport, and the first click would land nowhere, which is the same defect in
-/// the other direction.
-///
-/// # `set_physical_cursor_position` MOVES THE MOUSE (decision 2090)
-///
-/// The load-bearing fact, because the name does not say it and getting it wrong shipped a bug for
-/// months: **`Window::set_physical_cursor_position` is not "tell bevy where the pointer is", it is
-/// "put the pointer there".** It writes `Window.internal.physical_cursor_position`, and
-/// `bevy_winit::system::changed_windows` turns *any* change of that field to a `Some` into
-/// `winit_window.set_cursor_position(…)` — `CGWarpMouseCursorPosition` on macOS, a real hardware
-/// warp. There is no bookkeeping-only setter; this field is bevy's cursor-warp API, and winit is
-/// its only other writer.
-///
-/// So the hand-back cannot simply write what it stashed. It used to, and the pointer was yanked
-/// across the screen on every cover drop: measured on 2026-09-08 across a live `/logout`, the
-/// restore wrote `(811.9, 1242.6)` physical and the hardware cursor teleported from `(308, 588)`
-/// to `(406, 621)` points in the same millisecond. The stash goes stale over exactly the frames a
-/// cover is up for — a world teardown is one ~283 ms frame during which no events are pumped at
-/// all — so the pointer landed wherever it had been when the world went away, which after a click
-/// on the centred game menu's Logout is the middle of the window.
-///
-/// **The law, therefore: never write a position we do not know to be true right now.** Which is
-/// [`swallow_input_under_the_cover`]'s three-way hand-back:
-///
-/// - Winit already has a position (the field reads `Some`) → it is fresher than anything stashed,
-///   so leave it alone. This is the case a moving mouse always takes: the events queued during a
-///   hitch are delivered *before* the frame that drops the cover.
-/// - The pointer has left the window ([`left`](Self::left)), or the window does not have the
-///   keyboard → write nothing. We have no business moving a pointer that is over somebody else's
-///   window.
-/// - Otherwise nothing has moved since we stashed it, so the stash *is* where the pointer is and
-///   writing it back moves nothing.
+/// `Window::set_physical_cursor_position` with `Some` is a hardware warp (`changed_windows` calls
+/// winit's `set_cursor_position`), so the hand-back writes only a position still true: none when
+/// winit already has a fresher one, none when the pointer left or the window lacks focus, and
+/// otherwise the stash, where the pointer still is.
 #[derive(Resource, Default)]
 pub(crate) struct CoveredPointer {
     /// The last position seen while covered, in physical pixels.
     stashed: Option<DVec2>,
-    /// Is the window's cursor position currently ours (blanked) rather than winit's?
+    /// Whether the window's cursor position is currently our blank rather than winit's.
     blanked: bool,
-    /// Has winit said the pointer left the window since [`stashed`](Self::stashed) was taken?
-    ///
-    /// The one thing the window's own field cannot tell us: a `None` there is either winit's
-    /// `CursorLeft` or our blank, and the two must not be confused — restoring the stash over the
-    /// first would warp the pointer back *into* the window from wherever the player took it.
+    /// Whether winit reported `CursorLeft` since the stash; the window's `None` cannot tell that
+    /// from our blank, and restoring over it would warp the pointer back into the window.
     left: bool,
 }
 
-/// One frame's swallow of one button plane.
-///
-/// The whole rule, and it needs no memory of its own:
-///
-/// - **A press that arrives under the cover never happened** — `just_pressed` is exactly this
-///   frame's arrivals, and [`ButtonInput::reset`] takes each out of all three sets.
-/// - **Whatever is still held came from before the cover, and is released once, with an edge** —
-///   after the step above, `pressed` can only contain buttons held on an earlier frame, so
-///   [`ButtonInput::release_all`] moves precisely those into `just_released`. On every *later*
-///   covered frame `pressed` is already empty and this is a no-op, so the release edge is
-///   delivered exactly once per cover, with no flag to keep.
-///
-/// A real OS release arriving mid-cover is likewise silent: bevy's own release only records an
-/// edge for a button it still has pressed, and we took it out on the first covered frame.
+/// One frame's swallow of one button plane: a press arriving under the cover is erased, and a
+/// button held from before it is released once with a real edge, so a gesture in flight unwinds.
+/// Later covered frames find nothing pressed, so the edge comes once per cover.
 fn swallow<T>(input: &mut ButtonInput<T>)
 where
     T: Copy + Eq + std::hash::Hash + Send + Sync + 'static,
@@ -191,8 +68,7 @@ where
     input.release_all();
 }
 
-/// `swallow` for a plane whose button type is not `Copy` (`ButtonInput<Key>`'s logical keys carry
-/// a `SmolStr`).
+/// `swallow` for a non-`Copy` button type (`ButtonInput<Key>`).
 fn swallow_cloned<T>(input: &mut ButtonInput<T>)
 where
     T: Clone + Eq + std::hash::Hash + Send + Sync + 'static,
@@ -204,8 +80,8 @@ where
     input.release_all();
 }
 
-/// The raw input-message queues, as one [`bevy::ecs::system::SystemParam`] — bevy's 16-element
-/// system-param ceiling, the same squeeze `drive_loading_screen` next door already pays.
+/// The raw input-message queues, as one [`bevy::ecs::system::SystemParam`] to stay under Bevy's
+/// 16-parameter ceiling.
 #[derive(bevy::ecs::system::SystemParam)]
 struct RawInput<'w> {
     keyboard: ResMut<'w, Messages<KeyboardInput>>,
@@ -225,7 +101,7 @@ impl RawInput<'_> {
     }
 }
 
-/// The button planes + the accumulators, as one param (see [`RawInput`] on the ceiling).
+/// The button planes and the accumulators, as one param.
 #[derive(bevy::ecs::system::SystemParam)]
 struct Buttons<'w> {
     keys: ResMut<'w, ButtonInput<KeyCode>>,
@@ -245,14 +121,9 @@ impl Buttons<'_> {
     }
 }
 
-/// `PreUpdate`, in [`CoverInput`]: take the whole input plane for as long as the cover is up.
-///
-/// **The one-frame edge, stated so nobody has to rediscover it.** The cover is raised in `Update`
-/// (`drive_loading_screen`, in `WorldStage::Present`), and this runs in `PreUpdate`, so the raise
-/// frame itself still takes input — its `Input` stage ran before the raise did. That is the
-/// correct boundary rather than a miss: the raise frame's *render* is the first one that draws the
-/// cover, so input dies on exactly the frames whose previous present showed it, and the player
-/// never sees the cover on a frame that also acted on their mouse.
+/// `PreUpdate`, in [`CoverInput`]: take the whole input plane while the cover is up. The cover
+/// rises in `Update`, so its raise frame still takes input; that frame is also the first to draw
+/// it, so input stops exactly on the frames after the cover was shown.
 fn swallow_input_under_the_cover(
     screen: Res<LoadingScreen>,
     mut pointer: ResMut<CoveredPointer>,
@@ -261,12 +132,8 @@ fn swallow_input_under_the_cover(
     mut buttons: Buttons,
     mut raw: RawInput,
 ) {
-    // **Winit's last word on the pointer, read before anything below can overwrite it.** The
-    // window's position field already reflects the LAST cursor event of this frame (bevy_winit
-    // writes it as it dispatches, in order, before the update runs), so `Some` here is the live
-    // truth and outranks the stash. A `None` is ambiguous — winit's `CursorLeft` or our own blank —
-    // which is the whole reason [`CoveredPointer::left`] exists. Drained every frame, covered or
-    // not, so the reader never hands a covered frame a departure from two frames ago.
+    // Read before anything below writes it: bevy_winit has already applied this frame's cursor
+    // events, so `Some` is the live pointer. Departures drain every frame, so none goes stale.
     let departed = departures.read().count() > 0;
     let here = window
         .single()
@@ -279,10 +146,7 @@ fn swallow_input_under_the_cover(
     }
 
     if !screen.covering() {
-        // The way out: hand the window its pointer back, once, on the frame the cover drops — and
-        // only when that hand-back is TRUE, because the write is a hardware warp (see
-        // [`CoveredPointer`]). Winit's own fresher answer wins; a pointer that has left the window,
-        // or a window that does not have the keyboard, gets nothing.
+        // Hand the pointer back once, only when the stash is still true (see [`CoveredPointer`]).
         if pointer.blanked {
             pointer.blanked = false;
             let stashed = pointer.stashed.take();
@@ -299,33 +163,27 @@ fn swallow_input_under_the_cover(
     buttons.swallow_all();
     raw.drain();
 
-    // The pointer half. Re-stash before blanking so the position tracks the real cursor through
-    // the load (see [`CoveredPointer`]); `physical_cursor_position()` already answers `None` for a
-    // pointer outside the window, which is the same nothing we are about to write.
+    // Re-stash before blanking so the stash tracks the real cursor through the load.
     if let Ok(mut window) = window.single_mut() {
         if let Some(seen) = here {
             pointer.stashed = Some(seen.as_dvec2());
-            // Blanking is safe where restoring is not: `changed_windows` guards its warp on the
-            // *clamped* getter answering `Some`, so writing `None` re-caches without touching the
-            // hardware pointer. Only when there is something to blank — an unconditional write
-            // would deref-mut `Window` every covered frame, and a spurious `Changed<Window>` is a
-            // surface reconfigure (`video::apply_present_mode`'s note).
+            // Writing `None` does not warp. Only when there is something to blank: a spurious
+            // `Changed<Window>` reconfigures the surface.
             window.set_physical_cursor_position(None);
         }
         pointer.blanked = true;
     }
 }
 
-/// Wire the gate. Called by [`super::LoadingScreenPlugin`] — this is not a plugin of its own,
-/// because the cover and its input rule are one system and must never be registerable apart.
+/// Wire the gate; called by [`super::LoadingScreenPlugin`] so the cover and its input rule are
+/// never registered apart.
 pub(super) fn build(app: &mut App) {
     app.init_resource::<CoveredPointer>().add_systems(
         PreUpdate,
         swallow_input_under_the_cover
             .in_set(CoverInput)
-            // After the input is built, before anything reads it. `UiSystems::Focus` is bevy's own
-            // `PreUpdate` reader (it hit-tests the cursor into `Interaction`, which is what
-            // `glue::glue_clicks` rides), so it has to land on the other side of us.
+            // Before `UiSystems::Focus`, Bevy's own `PreUpdate` reader, which hit-tests the cursor
+            // into `Interaction`.
             .after(bevy::input::InputSystems)
             .before(bevy::ui::UiSystems::Focus),
     );
@@ -336,17 +194,13 @@ mod tests {
     use super::*;
     use bevy::input::ButtonState;
 
-    /// The [`swallow`] rule, both halves, in the order they matter: a press that arrives under the
-    /// cover is erased, and a button held from before it is released **once**, with a real edge.
     #[test]
     fn a_press_under_the_cover_never_happened_and_a_held_one_is_released_once() {
         let mut keys = ButtonInput::<KeyCode>::default();
 
-        // Held from before the cover: pressed on an earlier frame, so its `just_pressed` edge is
-        // gone by now (bevy clears the edge sets at the head of every frame).
+        // Held from before the cover: `clear` drops its `just_pressed` edge, as a new frame does.
         keys.press(KeyCode::KeyW);
         keys.clear();
-        // …and this frame, under the cover, the player also presses SPACE.
         keys.press(KeyCode::Space);
 
         swallow(&mut keys);
@@ -363,7 +217,6 @@ mod tests {
             "…with a real release edge, so a held MOVEFORWARD binding unwinds"
         );
 
-        // The next covered frame: bevy clears the edge sets, and there is nothing left to release.
         keys.clear();
         swallow(&mut keys);
         assert_eq!(
@@ -374,8 +227,6 @@ mod tests {
         assert_eq!(keys.get_pressed().count(), 0);
     }
 
-    /// A real OS release arriving mid-cover produces no second edge — bevy's own `release` only
-    /// records one for a button it still holds pressed, and the first covered frame took it out.
     #[test]
     fn an_os_release_under_the_cover_is_silent() {
         let mut keys = ButtonInput::<KeyCode>::default();
@@ -392,16 +243,13 @@ mod tests {
         );
     }
 
-    /// The gate against a real `App` and bevy's own `InputSystems`: with the cover up, a frame of
-    /// input reaches nobody — button planes, raw queues and the window's cursor position all read
-    /// empty — and the pointer comes back on the frame the cover drops, with no mouse move needed.
+    /// Against a real `App` and Bevy's `InputSystems`.
     #[test]
     fn a_covered_frame_hands_no_input_to_anyone_and_gives_the_pointer_back() {
         let mut app = App::new();
         app.add_plugins((
             bevy::input::InputPlugin,
-            // For `Messages<CursorMoved>` — a window message, not an input one — and for the
-            // window types themselves. `primary_window: None`: the test spawns its own.
+            // For `Messages<CursorMoved>` and the window types; the test spawns its own window.
             bevy::window::WindowPlugin {
                 primary_window: None,
                 exit_condition: bevy::window::ExitCondition::DontExit,
@@ -410,8 +258,6 @@ mod tests {
         ))
         .init_resource::<LoadingScreen>()
         .init_resource::<CoveredPointer>()
-        // `UiSystems::Focus` is bevy's, and pulling `UiPlugin` into a unit test to state an
-        // ordering the real wiring already states would test bevy, not us.
         .add_systems(
             PreUpdate,
             swallow_input_under_the_cover
@@ -444,13 +290,11 @@ mod tests {
                 .set_physical_cursor_position(at);
         };
 
-        // A pointer in the middle of the window, and a key held from before the cover.
         put_cursor(&mut app, Some(DVec2::new(400.0, 300.0)));
         app.world_mut()
             .resource_mut::<ButtonInput<KeyCode>>()
             .press(KeyCode::KeyW);
 
-        // --- Uncovered: an ordinary frame. Nothing is touched.
         app.update();
         assert!(seen(&app).is_some(), "no cover, no blanking");
         assert!(
@@ -460,7 +304,6 @@ mod tests {
             "no cover, no swallow"
         );
 
-        // --- The cover goes up, and the player presses SPACE under it.
         app.world_mut().resource_mut::<LoadingScreen>().active = true;
         app.world_mut().write_message(KeyboardInput {
             key_code: KeyCode::Space,
@@ -492,7 +335,6 @@ mod tests {
             "the raw queue is drained too, so a MessageReader sees nothing either"
         );
 
-        // --- The cover clears: the pointer comes straight back.
         app.world_mut().resource_mut::<LoadingScreen>().active = false;
         app.update();
         assert_eq!(
@@ -502,15 +344,10 @@ mod tests {
         );
     }
 
-    /// **The hand-back never invents a position** (decision 2090). Writing the window's cursor
-    /// position is a hardware warp, so the cover may only write one it knows is still true — which
-    /// is the difference between handing the pointer back and dragging it across the player's
-    /// screen. Three cases, one harness: winit's fresher answer wins; a departed pointer and an
-    /// unfocused window get nothing; a still pointer gets its stash.
+    /// Writing the cursor position is a hardware warp, so the hand-back writes only a true one.
     #[test]
     fn the_hand_back_never_writes_a_position_it_does_not_know_to_be_true() {
-        /// Cover, blank, then drop the cover under `arrange` — answering: what does the cover write
-        /// into the window on the way out?
+        /// Cover, blank, then drop the cover under `arrange`; returns what the cover wrote back.
         fn round_trip(arrange: impl FnOnce(&mut App, Entity)) -> Option<Vec2> {
             let mut app = App::new();
             app.add_plugins((
@@ -547,7 +384,6 @@ mod tests {
                     .set_physical_cursor_position(at);
             };
 
-            // A pointer in the window, then the cover: one covered frame stashes and blanks it.
             put(&mut app, Some(DVec2::new(400.0, 300.0)));
             app.world_mut().resource_mut::<LoadingScreen>().active = true;
             app.update();
@@ -578,10 +414,7 @@ mod tests {
              that is where the pointer already is"
         );
 
-        // Winit spoke first: bevy_winit writes the window's field as it dispatches the frame's
-        // events, so a `Some` on the drop frame is the live pointer. Overwriting it with the stash
-        // is exactly the warp — this is the case a moving mouse always takes, and the one that
-        // dragged the cursor to the middle of the window on every `/logout` before 2090.
+        // A `Some` on the drop frame is winit's live pointer, the case a moving mouse takes.
         assert_eq!(
             round_trip(|app, window| {
                 app.world_mut()
diff --git a/crates/benilla-app/src/local_state.rs b/crates/benilla-app/src/local_state.rs
index 9b833cc5..96aef80d 100644
--- a/crates/benilla-app/src/local_state.rs
+++ b/crates/benilla-app/src/local_state.rs
@@ -1,59 +1,26 @@
-//! Where benilla keeps **local state** — THE LAW (decision 0954, placement amended by 1175). Every
-//! file benilla persists on a player's machine — config today; realmlist, caches, per-character
-//! state as they arrive — lives in **one visible folder, `benilla-config/`, beside the benilla binary**.
-//! Never scattered into the install, never hidden in a platform config dir: the 1.12 client is
-//! itself fully portable (`WTF/`, `realmlist.wtf`, `Cache/` all in-folder — verified on the live
-//! install), its community expects the drop-in-a-folder shape, and one folder answers "what here
-//! is benilla's?" at a glance (the director's call, 2026-08-04; prior art: Dolphin's
-//! `portable.txt`, DREAMM's config-next-to-exe).
+//! Where benilla keeps local state: one folder, `benilla-config/`, never inside the install, and
+//! this module is the only place that computes a path into it; each path fn's doc says what it
+//! holds. The 1.12 client is portable the same way, its `WTF/` and `Cache/` in its own folder.
 //!
-//! **0954 put this folder inside the WoW install and 1175 moved it out**, on the director's word:
-//! *the benilla folder should be outside the wow folder … in root of the project or same folder as
-//! the benilla binary.* 0954's reasoning was sound for what it knew — `$WOW_DATA` was the only
-//! root the client reliably had — but it made benilla's own state a *guest* of the install, so
-//! pointing at a second install silently swapped your keybinds and a data path that failed to
-//! resolve took your config with it. benilla reads a WoW install; it does not live in one. One
-//! behaviour improves as a result: the state folder no longer depends on finding the install at
-//! all. Everything else about 0954 stands, including this module being the only place in the tree
-//! that may compute a persistence path (grep `local_state::` for every resident) — a new file gets
-//! a path fn here with a doc comment saying what it holds and why it is scoped the way it is.
-//! **Those doc comments are the layout table** (decision 1689): 0954's own table is a
-//! point-in-time snapshot of the law it set and, like every decision record, immutable — it lists
-//! none of the residents added since, and it should not.
+//! Resolution, in order, the same shape as [`benilla_formats::wow_data`]:
+//! 1. `$BENILLA_HOME`.
+//! 2. `<project folder>/benilla-config/`, dev builds only: a shipped binary must not carry the
+//!    build machine's source tree.
+//! 3. `<exe dir>/benilla-config/`.
 //!
-//! Resolution, in order — deliberately the **same three-step shape** as
-//! [`benilla_formats::wow_data`], because it is one law over two folders:
-//! 1. **`$BENILLA_HOME`** — explicit override (tests point it at a tempdir; a shared-config setup
-//!    points it wherever it likes).
-//! 2. **`<project folder>/benilla-config/`** — `#[cfg(feature = "dev")]` only, so dev runs across the
-//!    worktrees of the repo keep one predictable place. Gated for the same reason the install resolver's
-//!    project-folder probe is: a shipped binary must not carry the build machine's source tree.
-//!    (`.gitignore` carries `/benilla-config` for it.)
-//! 3. **`<exe dir>/benilla-config/`** — the release answer: your settings sit next to the program that
-//!    wrote them.
-//!
-//! **Capture/probe runs are hermetic**: with `$WOW_CAPTURE` set every path resolves to `None` —
-//! a deterministic capture must not read one machine's saved settings or write anything back
-//! (the harness owns its inputs; decision 0008's reproducibility posture).
+//! With `$WOW_CAPTURE` set every path resolves to `None`: a capture neither reads nor writes
+//! player state.
 
 use std::io::Write;
 use std::path::{Path, PathBuf};
 
-/// The folder's name, everywhere. **Not** `benilla/`, which is what 0954 called it and what 1175
-/// §4 assumed it would keep: beside the binary that name collides with the binary itself, which is
-/// also `benilla`. The bare-directory falsifier caught it immediately — `<exe dir>/benilla/`
-/// resolved onto the executable and every read failed with `Not a directory (os error 20)`, so a
-/// player's settings had nowhere to live. 0954 could name it for the program because it sat inside
-/// somebody else's folder and had to announce whose it was; beside our own binary that reason is
-/// gone and only the collision is left. The reference client has the same shape and the same
-/// answer — `WoW.exe` keeps its state in `WTF/`, named for what it is (and `WTF/` is exactly why we
-/// cannot borrow that name: drop benilla into a real install and it is already taken).
-/// The director's call, 2026-08-10.
+/// The folder's name: not `benilla`, which beside the binary is the executable itself, and not
+/// `WTF`, which a real install already uses.
 const STATE_DIR: &str = "benilla-config";
 
-/// The one benilla-state folder, or `None` when persistence is off (a hermetic capture run, or a
-/// platform with no discoverable executable path). Existence is NOT guaranteed — [`write_atomic`]
-/// creates it on first write; readers just try their file and treat absent as defaults.
+/// The state folder, or `None` when persistence is off (a capture run, or no executable path).
+/// It may not exist yet: [`write_atomic`] creates it, and a reader treats a missing file as
+/// defaults.
 pub(crate) fn home() -> Option<PathBuf> {
     if std::env::var_os("WOW_CAPTURE").is_some() {
         return None; // hermetic: captures neither read nor write player state
@@ -61,37 +28,20 @@ pub(crate) fn home() -> Option<PathBuf> {
     if let Some(over) = std::env::var_os("BENILLA_HOME") {
         return Some(PathBuf::from(over));
     }
-    // 2 · the project folder, dev builds only — see [`dev_project_root`] for why that is the
-    // PRIMARY checkout and not the worktree this binary was built in. `None` in a player build,
-    // where there is no source tree to name (`run_mode::dev_source_dir`).
+    // 2 · the project folder, dev builds only.
     if let Some(root) = dev_project_root() {
         return Some(root.join(STATE_DIR));
     }
-    // 3 · beside the binary. A dev build never reaches here — that is what step 2 means by "one
-    // predictable place", and it is why the release path is proven with a player build, not a
-    // dev one.
+    // 3 · beside the binary; a dev build never reaches here.
     std::env::current_exe()
         .ok()
         .and_then(|e| e.parent().map(Path::to_path_buf))
         .map(|dir| dir.join(STATE_DIR))
 }
 
-/// The project folder a dev build keeps its state in: **the primary checkout**, whichever worktree
-/// this binary was actually built in.
-///
-/// This is the one place 1175's §4 needed a correction on contact with how we work. `benilla/` used
-/// to hang off `$WOW_DATA`, and every worktree of the repo points `WoW` at the same install — so
-/// there has always been exactly ONE settings folder no matter which worktree built the binary.
-/// Resolving to `CARGO_MANIFEST_DIR` instead would give one per worktree, and the player's
-/// keybinds, macros and camera pose would appear to reset whenever a session happened to build
-/// in a different one. That is a silent, recurring surprise, and it is not what "one predictable
-/// place" meant.
-///
-/// A linked worktree's `.git` is a **file** reading `gitdir: <primary>/.git/worktrees/<slot>`, so
-/// the primary is derivable with no git binary and no build script: walk up to the common dir and
-/// take its parent. In the primary checkout `.git` is an ordinary directory and the answer is the
-/// crate root's grandparent, unchanged. Anything unexpected falls back to that same answer rather
-/// than to `None` — a wrong-but-present settings folder beats losing persistence entirely.
+/// The project folder a dev build keeps its state in: the primary checkout, whichever worktree
+/// built the binary, so every worktree shares one settings folder. Anything unexpected falls back
+/// to the crate root's grandparent rather than `None`.
 fn dev_project_root() -> Option<PathBuf> {
     let here = crate::run_mode::dev_source_dir()?.ancestors().nth(2)?;
     let dot_git = here.join(".git");
@@ -117,111 +67,78 @@ fn dev_project_root() -> Option<PathBuf> {
     Some(here.to_path_buf())
 }
 
-/// `benilla-config/config.toml` — the CVar overrides (the `Config.wtf` analog; see `crate::cvars`).
+/// `benilla-config/config.toml`: the CVar overrides, the `Config.wtf` analog.
 pub(crate) fn config_path() -> Option<PathBuf> {
     home().map(|h| h.join("config.toml"))
 }
 
-/// `benilla-config/macros/account.txt` — the account-wide macro tab (indices 1..=18; decision 0983). One
-/// file per scope rather than one file with two sections, because the two have different lifetimes:
-/// the account tab follows the install, a character tab dies with its character.
+/// `benilla-config/macros/account.txt`: the account-wide macro tab (indices 1..=18).
 pub(crate) fn macros_account_path() -> Option<PathBuf> {
     home().map(|h| h.join("macros/account.txt"))
 }
 
-/// `benilla-config/macros/<realm>-<character>.txt` — the per-character macro tab (indices 19..=36). The
-/// reference nests these (`WTF/Account/<ACC>/<REALM>/<CHAR>/macros-cache.txt`); benilla flattens to
-/// one `macros/` folder because [`home`] is already account-scoped by the install it sits beside.
+/// `benilla-config/macros/<realm>-<character>.txt`: the per-character macro tab (19..=36), the
+/// reference's `WTF/Account/<ACC>/<REALM>/<CHAR>/macros-cache.txt` flattened into one folder.
 pub(crate) fn macros_character_path(realm: &str, character: &str) -> Option<PathBuf> {
     let key = format!("{}-{}", file_token(realm), file_token(character));
     home().map(|h| h.join("macros").join(format!("{key}.txt")))
 }
 
-/// `benilla-config/bindings/account.txt` — the account-wide key bindings (decision 0997; the
-/// `bindings-cache.wtf` analog, command-centric diff-vs-defaults so a growing command set keeps
-/// its new defaults).
+/// `benilla-config/bindings/account.txt`: the account-wide key bindings (the `bindings-cache.wtf`
+/// analog), a diff against the defaults.
 pub(crate) fn bindings_account_path() -> Option<PathBuf> {
     home().map(|h| h.join("bindings/account.txt"))
 }
 
-/// `benilla-config/bindings/<realm>-<character>.txt` — the character-specific binding set (decision
-/// 0997). Its existence IS the "character specific key bindings" state: the window's checkbox
-/// writes it, Okay-back-to-general deletes it (the reference's confirmed permanent delete).
+/// `benilla-config/bindings/<realm>-<character>.txt`: the character-specific binding set. Its
+/// existence is the "character specific key bindings" state; going back to general deletes it.
 pub(crate) fn bindings_character_path(realm: &str, character: &str) -> Option<PathBuf> {
     let key = format!("{}-{}", file_token(realm), file_token(character));
     home().map(|h| h.join("bindings").join(format!("{key}.txt")))
 }
 
-/// `benilla-config/saved-variables.lua` — the Lua saved-variables file (decision 1128; the
-/// `WTF/Account/<ACC>/SavedVariables.lua` analog). Install-scoped, like the reference's account
-/// scope: written whole at logout/exit, executed as a chunk at UI load. One file, because our
-/// ported UI is one FrameXML tree rather than a set of addons — when third-party addons land they
-/// get `benilla-config/saved/<Addon>.lua`, the reference's per-addon shape.
+/// `benilla-config/saved-variables.lua`: the flat channel our FrameXML saves through
+/// `RegisterForSave` (the `SavedVariables.lua` analog), written whole at logout, run at UI load.
 pub(crate) fn saved_variables_path() -> Option<PathBuf> {
     home().map(|h| h.join("saved-variables.lua"))
 }
 
-/// `benilla-config/addons/<Realm>-<Character>.txt` — the AddOn **enable state** (1188 phase 2).
-///
-/// Per character, like the reference: it writes `WTF/Account/<ACC>/<Realm>/<Char>/AddOns.txt` as
-/// the last step of its UI shutdown (`0x490bd0`'s tail, after the saved-variables files). The
-/// file's own format is the reference's too — one `<AddOnName>: enabled|disabled` per line,
-/// confirmed against a real 1.12 install rather than remembered. An addon absent from the file is
-/// enabled, which is what makes a freshly-dropped-in folder just work.
+/// `benilla-config/addons/<Realm>-<Character>.txt`: the AddOn enable state, per character in the
+/// reference's `AddOns.txt` format (`<AddOnName>: enabled|disabled`), which it writes at the tail
+/// of its UI shutdown (`0x490bd0`). An addon absent from the file is enabled.
 pub(crate) fn addons_state_path(realm: &str, character: &str) -> Option<PathBuf> {
     let key = format!("{}-{}", file_token(realm), file_token(character));
     home().map(|h| h.join("addons").join(format!("{key}.txt")))
 }
 
-/// `benilla-config/saved/` — **per-addon** saved variables, account scope (1188 phase 3): one
-/// `<Addon>.lua` per addon that declares `## SavedVariables`.
-///
-/// The reference's shape, one level flatter: it writes
-/// `WTF/Account/<ACC>/SavedVariables/<Addon>.lua`, and our whole state folder is already
-/// per-install, so the folder IS the account scope (0954, and 1128 reserved this exact path —
-/// spelled `benilla/saved/` before 1180 renamed the folder).
-///
-/// Distinct from [`saved_variables_path`], which is the *flat* channel our own FrameXML uses
-/// through `RegisterForSave`. The reference has both too, and they are not the same mechanism.
+/// `benilla-config/saved/`: per-addon saved variables, account scope, one `<Addon>.lua` per addon
+/// declaring `## SavedVariables` (the reference's `WTF/Account/<ACC>/SavedVariables/<Addon>.lua`).
 pub(crate) fn addon_saved_account_dir() -> Option<PathBuf> {
     home().map(|h| h.join("saved"))
 }
 
-/// `benilla-config/saved/<Realm>-<Character>/` — per-addon saved variables, character scope
-/// (`## SavedVariablesPerCharacter`). Loaded **after** the account file, so it wins.
+/// `benilla-config/saved/<Realm>-<Character>/`: per-addon saved variables, character scope
+/// (`## SavedVariablesPerCharacter`), loaded after the account file so it wins.
 pub(crate) fn addon_saved_character_dir(realm: &str, character: &str) -> Option<PathBuf> {
     let key = format!("{}-{}", file_token(realm), file_token(character));
     home().map(|h| h.join("saved").join(key))
 }
 
-/// `benilla-config/camera/<realm>-<character>.txt` — the third-person camera pose (decision 1131; the
-/// `<Char>/camera-settings.txt` analog, and character-scoped for the same reason it is there: a
-/// gnome rogue and a tauren warrior want different zooms). Two lines, the reference's own keys and
-/// order, so the file stays readable beside its ancestor.
+/// `benilla-config/camera/<realm>-<character>.txt`: the third-person camera pose (the
+/// `<Char>/camera-settings.txt` analog), two lines in the reference's keys and order.
 pub(crate) fn camera_character_path(realm: &str, character: &str) -> Option<PathBuf> {
     let key = format!("{}-{}", file_token(realm), file_token(character));
     home().map(|h| h.join("camera").join(format!("{key}.txt")))
 }
 
-/// `benilla-config/account` — the account name the login screen remembers (decision 0539 §4; the
-/// reference's `GetSavedAccountName`/`SetSavedAccountName`, whose own store is `WTF/Config.wtf`'s
-/// `accountName`). Install-scoped like every other resident here.
-///
-/// It resolved to `$HOME/.benilla/account` until decision 1181, through a second path function
-/// that `login` had grown before this module's law existed (0539 predates 0954, whose layout table
-/// never mentioned it). That split a player's state across two folders and — the part that
-/// actually bit — skipped [`home`]'s hermetic guard, so a **capture read the account name off
-/// whatever machine it ran on** and rendered it into the login screen it was photographing.
+/// `benilla-config/account`: the account name the login screen remembers
+/// (`GetSavedAccountName`/`SetSavedAccountName`; the reference's is `Config.wtf`'s `accountName`).
 pub(crate) fn saved_account_path() -> Option<PathBuf> {
     home().map(|h| h.join("account"))
 }
 
-/// `benilla-config/chat/<realm>-<character>.txt` — the chat windows' saved state (decision 1589):
-/// the background tint, the background alpha, the font size a chat tab's right-click menu sets,
-/// and the window's lock. **Character-scoped**, where the reference keeps the same four inside its
-/// per-character `chat-cache.txt` — a raid alt and a questing alt want different chat boxes. See
-/// [`crate::ui_chat`]'s `settings` module for the file's shape and why it is a subset of its
-/// ancestor.
+/// `benilla-config/chat/<realm>-<character>.txt`: the chat windows' tint, alpha, font size and
+/// lock, the four the reference keeps in its per-character `chat-cache.txt`.
 pub(crate) fn chat_character_path(realm: &str, character: &str) -> Option<PathBuf> {
     Some(home()?.join("chat").join(format!(
         "{}-{}.txt",
@@ -230,16 +147,9 @@ pub(crate) fn chat_character_path(realm: &str, character: &str) -> Option<PathBu
     )))
 }
 
-/// `benilla-config/layout/<realm>-<character>.txt` — the **layout cache**: where every frame the
-/// player has moved or resized sits, so a dragged chat window is still there after a relog.
-///
-/// The reference's own resident is `WTF/Account/<ACC>/<REALM>/<CHAR>/layout-cache.txt`, written by
-/// the engine for exactly the frames carrying the userPlaced bit — so the scope is its scope and
-/// the name is its name, one folder flatter like every other resident here ([`home`] is already
-/// account-scoped by the binary it sits beside). Character-scoped because the state IS per
-/// character: a raid alt wants the combat log wide where a questing alt wants it out of the way.
-///
-/// The file's shape, and the seam that fills it, are [`crate::ui_layout`]'s.
+/// `benilla-config/layout/<realm>-<character>.txt`: the layout cache, the geometry of every
+/// user-placed frame, as the reference's per-character `layout-cache.txt`; [`crate::ui_layout`]
+/// owns the shape.
 pub(crate) fn layout_character_path(realm: &str, character: &str) -> Option<PathBuf> {
     Some(home()?.join("layout").join(format!(
         "{}-{}.txt",
@@ -248,20 +158,11 @@ pub(crate) fn layout_character_path(realm: &str, character: &str) -> Option<Path
     )))
 }
 
-/// `benilla-config/cache/<realm>.tsv` — the **name cache**: the player, creature and pet names the
-/// server has already answered for, kept across sessions (decision 1689).
+/// `benilla-config/cache/<realm>.tsv`: the player, creature and pet names the server has answered,
+/// one file for the reference's `WDB/namecache.wdb`, `creaturecache.wdb` and `petnamecache.wdb`.
 ///
-/// The reference's residents are `WDB/namecache.wdb`, `creaturecache.wdb` and `petnamecache.wdb`
-/// — three files **inside the install**, which is exactly where benilla may not write (the install
-/// is read-only, `docs/METHOD.md`'s hard rule), so ours lives here like every other thing we persist.
-/// One file rather than three because our three stores share a lifetime and a realm; the
-/// reference's split follows its `DBCache<T>` template instantiation, not a property of the data.
-///
-/// **Realm-scoped, where the reference's is not** — and that is a correctness fix, not a
-/// preference. Every key here is realm-local: a player guid, a creature template entry and a pet
-/// number all mean something different on another realm, so one shared file would serve a second
-/// realm another realm's names. The reference gets away with it because a 1.12 install typically
-/// saw one realm.
+/// Realm-scoped, where the reference's is not: guids, creature entries and pet numbers are
+/// realm-local, so one shared file would serve a realm another realm's names.
 pub(crate) fn name_cache_path(realm: &str) -> Option<PathBuf> {
     Some(
         home()?
@@ -270,76 +171,40 @@ pub(crate) fn name_cache_path(realm: &str) -> Option<PathBuf> {
     )
 }
 
-/// `benilla-config/shots.txt` — the framing instrument's appended camera poses (decision 0600). A dev
-/// affordance (`/shot`, compiled out by `--no-default-features` since 1179), but it persists on a
-/// real machine, so it resolves here like everything else rather than through a private path.
-/// `Logs/` — `WoWChatLog.txt` and `WoWCombatLog.txt`, the reference's two names beside its
-/// `WTF`, kept here beside ours ([`crate::ui_chat`]'s logging).
+/// `benilla-config/Logs/`: `WoWChatLog.txt` and `WoWCombatLog.txt`, the reference's names.
 pub(crate) fn logs_dir() -> Option<PathBuf> {
     home().map(|h| h.join("Logs"))
 }
 
+/// `benilla-config/shots.txt`: the framing instrument's camera poses (`/shot`, dev builds).
 pub(crate) fn shots_path() -> Option<PathBuf> {
     home().map(|h| h.join("shots.txt"))
 }
 
-/// `benilla-config/Screenshots/` — where the print-screen key writes (decisions 1486, 1487).
+/// `benilla-config/Screenshots/`: where the print-screen key writes, each image once, not through
+/// [`write_atomic`].
 ///
-/// **The reference writes `Screenshots\\` inside the install and we deliberately do not.** benilla
-/// reads a WoW install; it never writes to one (decision 1486, the director's rule) — the folder is
-/// somebody else's, it is shared with other tools on this machine, and a client that
-/// scatters its output through it makes "what here is benilla's?" unanswerable. So the reference's
-/// own folder NAME is kept, capital S and all, and only its parent moves: a player who knows where
-/// WoW put screenshots finds the same folder one level over.
-///
-/// Unlike every other resident here this is a DIRECTORY, not a file, and it is not written through
-/// [`write_atomic`] — an image is bytes, not a settings diff, and it is written once and never
-/// rewritten, so the tmp-then-rename dance buys nothing. It resolves through [`home`] like
-/// everything else, which is what makes a capture run hermetic ([`home`] answers `None`).
+/// Deviation: the reference writes `Screenshots\\` inside the install, which benilla never writes
+/// to; the folder keeps the reference's name.
 pub(crate) fn screenshots_dir() -> Option<PathBuf> {
     home().map(|h| h.join("Screenshots"))
 }
 
-/// `benilla-config/Diagnostics/` — where the stuck-thread self-sampler drops its profiles
-/// ([`crate::perf::stall`]) and the FPS journal its rows ([`fps_journal_path`]).
-///
-/// **This was `~/Library/Logs/benilla/` until 2026-08-27, hand-built from `$HOME`** — a platform
-/// log directory, which is the exact shape the one-folder rule names as forbidden ("never a
-/// hand-built path, never a platform config dir"). It had been that way since decision 0713, and it
-/// went unnoticed because the sampler only writes when something is already wrong, so the stray
-/// folder appeared on the bad days and nobody was looking at paths on a bad day. It surfaced while
-/// proving out the MSAA clamp (1631): three probe runs stalled, and the stall lines named a
-/// directory that had no business existing.
-///
-/// It resolves through [`home`] like every other resident, which costs the sampler its capture
-/// runs (`home` answers `None` there, deliberately) and is the right trade: a `WOW_CAPTURE` run is
-/// bounded by the harness timeout and already has the probe backstop's `_exit(0)`, while the runs
-/// this instrument was built for — the director's, and the long probe rounds — keep it. The
-/// alternative, an ungated second accessor, would put "which paths are exempt from hermetic?" back
-/// into someone's head, which is what the single rule exists to prevent.
+/// `benilla-config/Diagnostics/`: the stuck-thread sampler's profiles ([`crate::perf::stall`]) and
+/// the FPS journal; `None` on a capture run like every path here, so a capture has no sampler.
 pub(crate) fn diagnostics_dir() -> Option<PathBuf> {
     home().map(|h| h.join("Diagnostics"))
 }
 
-/// `benilla-config/Diagnostics/fps-journal.csv` — the FPS journal's rows while the `fpsJournal`
-/// CVar is on (decision 2008): the file a reporter attaches. `None` on a hermetic run like
-/// everything here; the harness names its own path through `WOW_FPS_JOURNAL` instead.
+/// `benilla-config/Diagnostics/fps-journal.csv`: the FPS journal's rows while the `fpsJournal`
+/// CVar is on; a capture names its own path through `WOW_FPS_JOURNAL`.
 pub(crate) fn fps_journal_path() -> Option<PathBuf> {
     diagnostics_dir().map(|d| d.join("fps-journal.csv"))
 }
 
-/// Make an arbitrary realm/character name safe as one path component: anything that is not a
-/// letter or digit becomes `_`, so a realm called `Hydraxian Waterlords` or one with a slash cannot
-/// escape the folder or collide with the path separator.
-///
-/// **Letters are any script's, kept as they are** — the reference names its per-character folder
-/// with the raw name (`WTF/Account/<ACC>/<REALM>/<CHAR>/`). This was ASCII-only, which folded every
-/// other letter to `_`: vmangos accepts extended-Latin, Cyrillic and East-Asian names by default
-/// (`StrictPlayerNames = 0`), so `Zoë` and `Zoé` — or any two Cyrillic names of one length — shared
-/// one set of macros, bindings, addon state and SavedVariables, and each login saved over the
-/// other's. A character name is letters only (vmangos `isValidString`), so keeping every letter
-/// makes the token one-to-one for them; an ASCII name maps exactly as before, so no existing file
-/// moves.
+/// A realm or character name as one path component: anything not a letter or digit becomes `_`.
+/// Letters of any script stay, as in the reference's raw-name folders: vmangos accepts non-Latin
+/// names (`StrictPlayerNames = 0`) and a character name is letters only, so no two share a file.
 fn file_token(s: &str) -> String {
     let t: String = s
         .chars()
@@ -352,15 +217,13 @@ fn file_token(s: &str) -> String {
     }
 }
 
-/// Write a state file atomically: parent dirs created, contents to `<path>.tmp`, then rename —
-/// a crash mid-write leaves the old file intact, never a truncated one. The one write path for
-/// every resident of the folder.
+/// Write a state file atomically, through `<path>.tmp` and a rename, so a crash leaves the old
+/// file intact.
 pub(crate) fn write_atomic(path: &Path, contents: &str) -> std::io::Result<()> {
     write_atomic_bytes(path, contents.as_bytes())
 }
 
-/// [`write_atomic`] for a resident that is bytes, not text — the saved-variables files, which
-/// carry a Lua byte string's bytes as they are.
+/// [`write_atomic`] for bytes: the saved-variables files carry Lua byte strings as they are.
 pub(crate) fn write_atomic_bytes(path: &Path, contents: &[u8]) -> std::io::Result<()> {
     if let Some(dir) = path.parent() {
         std::fs::create_dir_all(dir)?;
@@ -374,10 +237,8 @@ pub(crate) fn write_atomic_bytes(path: &Path, contents: &[u8]) -> std::io::Resul
     std::fs::rename(&tmp, path)
 }
 
-/// Shared test plumbing for anything that toggles the persistence env vars: `std::env::set_var`
-/// is process-global and cargo runs tests in threads, so every such test takes [`ENV_LOCK`] and
-/// scopes its overrides in [`EnvGuard`]s (restore-on-drop). Used here and by `crate::cvars`'s
-/// end-to-end test.
+/// Test plumbing for the persistence env vars: `set_var` is process-global, so every such test
+/// takes [`ENV_LOCK`] and scopes its overrides in [`EnvGuard`]s.
 #[cfg(test)]
 pub(crate) mod test_env {
     pub(crate) static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
@@ -410,9 +271,7 @@ mod tests {
     use super::test_env::{EnvGuard, ENV_LOCK};
     use super::*;
 
-    /// **Two characters never share a file.** Every per-character resident keys on this token, so
-    /// a collision is one character's macros, bindings and SavedVariables loaded and then saved
-    /// over by another. ASCII names — every file already on disk — keep their exact paths.
+    /// Every per-character file keys on this token; ASCII names map unchanged.
     #[test]
     fn distinct_names_never_share_a_token() {
         assert_ne!(file_token("Вася"), file_token("Петя"));
@@ -432,10 +291,7 @@ mod tests {
         );
     }
 
-    /// The residents' layout, exercised through the override — which is the *only* step of
-    /// [`home`] whose answer a test can state, since the other two are the machine's project
-    /// folder and the test runner's own exe directory. Those two get their own tests below; what
-    /// this one owns is 0954's layout table, unchanged by 1175's move.
+    /// The layout under the override, the one step of [`home`] whose answer a test can state.
     #[test]
     fn the_home_law_override_then_the_residents_and_hermetic_captures() {
         let _l = ENV_LOCK
@@ -444,18 +300,15 @@ mod tests {
         let tmp = std::env::temp_dir().join(format!("benilla-ls-{}", std::process::id()));
         std::fs::create_dir_all(&tmp).unwrap();
 
-        // 1 · the explicit override, and every resident hanging off it.
+        // 1 · the explicit override.
         let _c = EnvGuard::unset("WOW_CAPTURE");
         let _h = EnvGuard::set("BENILLA_HOME", tmp.join(STATE_DIR).to_str().unwrap());
         assert_eq!(home(), Some(tmp.join(STATE_DIR)));
         assert_eq!(config_path(), Some(tmp.join("benilla-config/config.toml")));
-        // The macro residents (decision 0983): one account file, one per character, and every
-        // realm/character name reduced to a safe single path component.
         assert_eq!(
             macros_account_path(),
             Some(tmp.join("benilla-config/macros/account.txt"))
         );
-        // The saved-variables resident (decision 1128) — one install-scoped file.
         assert_eq!(
             saved_variables_path(),
             Some(tmp.join("benilla-config/saved-variables.lua"))
@@ -469,42 +322,30 @@ mod tests {
             Some(tmp.join("benilla-config/macros/___evil-a_b.txt")),
             "no name can escape the folder"
         );
-        // The camera-pose resident (decision 1131) — character-scoped, same key shape.
         assert_eq!(
             camera_character_path("Hydraxian Waterlords", "Probeone"),
             Some(tmp.join("benilla-config/camera/Hydraxian_Waterlords-Probeone.txt"))
         );
-        // The chat windows' saved look (decision 1589) — character-scoped, same key shape again.
         assert_eq!(
             chat_character_path("Hydraxian Waterlords", "Probeone"),
             Some(tmp.join("benilla-config/chat/Hydraxian_Waterlords-Probeone.txt"))
         );
-        // The layout cache — the userPlaced frames' geometry, character-scoped like its neighbours
-        // and like the reference's own `layout-cache.txt`.
         assert_eq!(
             layout_character_path("Hydraxian Waterlords", "Probeone"),
             Some(tmp.join("benilla-config/layout/Hydraxian_Waterlords-Probeone.txt"))
         );
 
-        // The login screen's remembered account name (decision 0539 §4) and the framing
-        // instrument's pose log (0600) — the two residents that computed their own path in
-        // `login::config_base` (`$HOME/.benilla`) until decision 1181 folded them in here.
         assert_eq!(
             saved_account_path(),
             Some(tmp.join("benilla-config/account"))
         );
         assert_eq!(shots_path(), Some(tmp.join("benilla-config/shots.txt")));
-        // The print-screen folder (decisions 1486/1487) — the one resident that is a DIRECTORY,
-        // and the one whose reference lives inside the install we refuse to write to.
         assert_eq!(
             screenshots_dir(),
             Some(tmp.join("benilla-config/Screenshots"))
         );
 
-        // 0 · hermetic: a capture run resolves nothing, even with an override set. The account
-        // name is the reason this line now matters more than it did: `config_base` had no such
-        // guard, so a login-screen capture read whatever account the host machine had saved and
-        // photographed it into the frame (decision 1181).
+        // 0 · a capture run resolves nothing, even with an override set.
         let _c2 = EnvGuard::set("WOW_CAPTURE", "ui-options");
         assert_eq!(home(), None);
         assert_eq!(
@@ -531,10 +372,7 @@ mod tests {
         std::fs::remove_dir_all(&tmp).ok();
     }
 
-    /// **The move itself** (1175 §4): the state folder no longer hangs off the WoW install, so a
-    /// missing or wrong `$WOW_DATA` cannot take a player's settings with it. This is the exact
-    /// case that used to return `None` — the one behaviour 1175 changes, and the reason it
-    /// changed.
+    /// A missing or wrong `$WOW_DATA` does not move or lose the state folder.
     #[test]
     fn the_state_folder_no_longer_depends_on_finding_the_install() {
         let _l = ENV_LOCK
@@ -552,15 +390,8 @@ mod tests {
         assert!(h.ends_with(STATE_DIR), "{}", h.display());
     }
 
-    /// **Where the folder lands, in both builds** — 1175's falsifier, as far as a test can take it.
-    ///
-    /// One test rather than a `#[cfg]`-ed pair, because the seam is `run_mode::dev_source_dir()`'s
-    /// to know and nothing else's (1179): a player build has no source dir, so the state folder
-    /// must sit beside the binary; a dev build has one, and must resolve to the PRIMARY checkout
-    /// so every worktree keeps sharing a single settings folder — exactly as they did when it
-    /// hung off the shared install. The dev half is asserted structurally (a `.git` *file* means a
-    /// linked worktree, and then the answer must be somewhere else), so it says the same thing
-    /// whether it runs in the primary or in a slot.
+    /// A player build resolves beside the binary; a dev build to the primary checkout, even from a
+    /// linked worktree (whose `.git` is a file).
     #[test]
     fn the_state_folder_lands_where_the_build_says() {
         let _l = ENV_LOCK
@@ -573,7 +404,7 @@ mod tests {
 
         let Some(here) = crate::run_mode::dev_source_dir().and_then(|d| d.ancestors().nth(2))
         else {
-            // Player build: beside the binary, and nowhere near a source tree.
+            // Player build: beside the binary.
             let exe_dir = std::env::current_exe()
                 .unwrap()
                 .parent()
diff --git a/crates/benilla-app/src/login/mod.rs b/crates/benilla-app/src/login/mod.rs
index d2a3d5b9..1170f17f 100644
--- a/crates/benilla-app/src/login/mod.rs
+++ b/crates/benilla-app/src/login/mod.rs
@@ -1,24 +1,16 @@
-//! The login screen (decision 0539) — the faithful `AccountLogin` glue, functional core only:
-//! the `UI_MainMenu` scene with its authored fog/fires, the account/password boxes, Remember
-//! Account Name, Login/Quit, the version block, and the connecting/error dialogs. The Credits/
-//! Cinematics/TOS side of the reference screen is deliberately cut (the director's call).
+//! The login screen, the reference's `AccountLogin` glue: state, the credential policy, input,
+//! dialogs and the saved account; the layout is [`screen`]. Deviation: the Credits, Cinematics
+//! and TOS side of the reference screen is absent, because the screen keeps only what logging in
+//! needs.
 //!
-//! This module owns the **credential policy** — the 0193 §3 mirror for the IO thread's pre-logon
-//! park: the env fast path (`WOW_USER` and `WOW_PASS` both set auto-submits
-//! with the old default account, so every probe/smoke invocation keeps working), the
-//! pending-credentials resubmit (paced at the flat 3 s, app-side — the IO thread never sleeps),
-//! and the director's typed submit. A *refused* code (bad password) clears the intent and shows
-//! the authored `AUTH_*` dialog — never an auto-retry against a refusal.
+//! The credential policy drives the IO thread's pre-logon park: `WOW_USER` plus `WOW_PASS`
+//! auto-submit, pending credentials resubmit every 3 s (app-side; the IO thread never sleeps),
+//! and a typed submit. A refusal clears the credentials and shows its dialog, never a retry.
 //!
-//! **A session that is lost is over** (decision 1262): the reference's `GlueParent.lua` answers
-//! `DISCONNECTED_FROM_SERVER` with `SetGlueScreen("login")` + `GlueDialog_Show("DISCONNECTED")`,
-//! and so does this. 0065's seamless reconnect survives only where the run has *declared* that
-//! nobody is here ([`crate::run_mode::unattended`], decision 1769) — because a client that
-//! re-authenticates on its own takes the account back off whoever just displaced it.
-//!
-//! Module split: this file (state, policy, input, dialogs, the saved-account persistence),
-//! [`screen`] (the authored layout, transcribed from `AccountLogin.xml`), [`smoke`] (the
-//! `WOW_LOGIN_SMOKE` headless prover).
+//! A lost session is over, as in `GlueParent.lua`: `DISCONNECTED_FROM_SERVER` returns to login
+//! with the `DISCONNECTED` dialog. Only an unattended run ([`crate::run_mode::unattended`])
+//! reconnects, because a client that re-authenticates takes the account back from whoever
+//! displaced it.
 
 pub(crate) mod queue;
 mod screen;
@@ -48,12 +40,11 @@ use crate::sound::GlueSound;
 pub(crate) use screen::LoginAction;
 pub(crate) use smoke::smoke_character;
 
-/// The flat resubmit pacing after a transport failure with pending credentials (decision 0065's
-/// reconnect cadence, moved app-side by 0539 — the IO thread never sleeps).
+/// The resubmit delay after a transport failure with pending credentials.
 const RETRY_DELAY_SECS: f32 = 3.0;
-/// The quit grace: `gsTitleQuit` gets this long to be audible before `AppExit` drops the mixer.
+/// How long `gsTitleQuit` plays before `AppExit` drops the mixer.
 const QUIT_GRACE_SECS: f32 = 0.4;
-/// The ref's `letters="16"` on both edit boxes.
+/// `letters="16"` on both edit boxes (`AccountLogin.xml`).
 const MAX_LETTERS: usize = 16;
 
 pub(crate) struct LoginPlugin;
@@ -67,8 +58,8 @@ impl Plugin for LoginPlugin {
             .add_systems(
                 Update,
                 (
-                    // Policy + transitions run in EVERY state: the reconnect resubmit fires while
-                    // `InWorld`, and the roster edge lands wherever it lands.
+                    // Every state: the reconnect resubmit fires while `InWorld`, and the roster
+                    // edge lands wherever it lands.
                     (drive_policy, to_select_on_roster, drive_quit).chain(),
                     (
                         screen::materialize_screen,
@@ -76,18 +67,13 @@ impl Plugin for LoginPlugin {
                         tick_login_caret,
                         screen::refresh_boxes,
                         screen::refresh_checkbox,
-                        // The shared glue dialog (2084) — the widget is `crate::glue::dialog`'s
-                        // and the select screen runs the same system over the same resource; what
-                        // a press *means* here is [`answer_dialog`]'s, right behind it. It sits
-                        // inside this chain rather than being hoisted out with a `before`/`after`
-                        // pair, because the shared painters below are in this chain too and
-                        // ordering across it makes a painter transitively ordered against its own
-                        // `SystemTypeSet` — rejected at schedule build, so it panics at boot and
-                        // no unit test sees it (2071).
+                        // The shared glue dialog stays inside this chain: ordering it from outside
+                        // would order a shared painter against its own `SystemTypeSet`, which
+                        // panics at schedule build, at boot, where no unit test sees it.
                         crate::glue::dialog::drive_glue_dialog,
                         answer_dialog,
-                        // Both after the driver: it is what spawns the dialog's edit box, and a
-                        // realmlist Okay is what changes the address this repaints.
+                        // After the driver: it spawns the dialog's edit box, and a realmlist Okay
+                        // changes the address repainted here.
                         (
                             crate::glue::dialog::refresh_dialog_box,
                             screen::refresh_realmlist,
@@ -95,10 +81,8 @@ impl Plugin for LoginPlugin {
                     )
                         .chain()
                         .before(crate::glue::GlueVisuals)
-                        // After the UI tick: one member holds the VM (`answer_dialog` writes
-                        // into it), and every VM holder in `Update` declares its side of the
-                        // tick (decision 2304). A glue screen has no push the tick must see,
-                        // so the whole chain takes the drain side.
+                        // `answer_dialog` holds the VM, and every VM holder in `Update` declares
+                        // its side of the UI tick; a glue screen has nothing the tick must see.
                         .after(crate::ui_script::UiInput)
                         .run_if(in_state(ClientState::Login)),
                     (smoke::debug_login_smoke, screen::debug_login_shot),
@@ -111,61 +95,52 @@ impl Plugin for LoginPlugin {
 
 // ── The credential policy ────────────────────────────────────────────────────────────────────────
 
-/// Where the IO thread's read loop currently is, as far as the app can tell — the policy submits
-/// credentials only while it's parked pre-logon.
+/// Where the IO thread's read loop is, as far as the app can tell; credentials are submitted
+/// only while it is parked pre-logon.
 #[derive(Default, PartialEq, Eq, Clone, Copy)]
 enum IoPark {
-    /// Parked at the pre-logon park (boot, a failure, a disconnect, a Back).
+    /// Parked pre-logon (boot, a failure, a disconnect, a Back).
     #[default]
     AtLogin,
-    /// Past logon — parked at select or streaming the world.
+    /// Past logon: at select or in the world.
     Active,
 }
 
-/// The credential policy's memory (the 0193 §3 mirror): the last credentials this session
-/// authenticated (or asked) with, the in-flight/park bookkeeping, and the resubmit timer.
+/// The credential policy's memory: the session's credentials, the in-flight and park state, and
+/// the resubmit timer.
 #[derive(Resource, Default)]
 pub(crate) struct LoginIntent {
-    /// The session's credentials — kept while in-world so the logout relist and an unattended
-    /// run's reconnect re-authenticate silently (0065); cleared by select's Back, a refusal code,
-    /// a Cancel, and by a lost session (1262 — they are the session's, and the session is over).
+    /// Kept in-world so the logout relist and an unattended reconnect re-authenticate silently;
+    /// cleared by select's Back, a refusal, a Cancel and a lost session.
     creds: Option<(String, String)>,
-    /// A submit is in flight (between our send and its LoginFailed/CharacterList answer).
+    /// Between our send and its LoginFailed or CharacterList answer.
     in_flight: bool,
-    /// Whether the in-flight submit came from the screen (it announced a connecting dialog and
-    /// wants its failure surfaced) or from the silent auto path.
+    /// The in-flight submit came from the screen, which shows its connecting dialog and failure.
     announced: bool,
     park: IoPark,
-    /// `Time::elapsed_secs` deadline for the next silent resubmit (`None` = no retry scheduled).
+    /// `Time::elapsed_secs` deadline for the next silent resubmit.
     retry_at: Option<f32>,
-    /// Env fast path read latch (checked once, on the first policy run).
+    /// The env fast path is read once, on the first policy run.
     env_read: bool,
 }
 
 impl LoginIntent {
-    /// Forget the session's credentials and any scheduled retry (select's Back, a refusal).
+    /// Forget the session's credentials and any scheduled retry.
     pub(crate) fn clear(&mut self) {
         self.creds = None;
         self.retry_at = None;
     }
 
-    /// The account this session authenticated as, however it got there — the env fast path or the
-    /// login screen. The one honest answer to "whose body is this?", which is what decides whether
-    /// the probe shield has any business touching it (decision 0677).
+    /// The account this session authenticated as, from the env fast path or the screen; it
+    /// decides whether the probe shield applies.
     pub(crate) fn account(&self) -> Option<&str> {
         self.creds.as_ref().map(|(user, _)| user.as_str())
     }
 }
 
-/// **Everything one login attempt is made of**, as a single [`SystemParam`]: the policy's memory,
-/// the channel to the parked IO thread, the abandon generation a Cancel bumps, and — since
-/// decision 1667 — the realmlist it dials.
-///
-/// A bundle rather than four parameters, for the reason the CVar host's old knob bundle had
-/// (retired by 2303): adding the realmlist put
-/// [`login_input`] at **seventeen** parameters, one past Bevy's ceiling, and the three systems
-/// that submit were already re-typing the same four names. Now a submit is one call on one param,
-/// and the next thing an attempt needs is one field here instead of a fourth signature to widen.
+/// One login attempt's inputs as a single [`SystemParam`]: the policy's memory, the channel to
+/// the parked IO thread, the abandon generation a Cancel bumps, and the realmlist it dials. A
+/// bundle keeps [`login_input`] under Bevy's sixteen-parameter ceiling.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(super) struct Attempt<'w> {
     pub(super) intent: ResMut<'w, LoginIntent>,
@@ -175,12 +150,8 @@ pub(super) struct Attempt<'w> {
 }
 
 impl Attempt<'_> {
-    /// Send one login attempt to the parked IO thread, stamped with the current abandon
-    /// generation.
-    ///
-    /// The realmlist is read **at submit time** (decision 1667) rather than by the IO thread, so a
-    /// resubmit fired after the player repointed the client dials the new server while an attempt
-    /// already on the wire keeps the one it started with.
+    /// Send one login attempt to the parked IO thread, stamped with the abandon generation. The
+    /// realmlist is read at submit time, so an attempt keeps the server it started with.
     fn send(&mut self, user: &str, pass: &str, announced: bool) {
         self.intent.creds = Some((user.to_string(), pass.to_string()));
         self.intent.in_flight = true;
@@ -195,17 +166,13 @@ impl Attempt<'_> {
     }
 }
 
-/// The millisecond clock the queue ring is stamped with — the app's own elapsed time, which is
-/// what the reference's `GetTickCount` is here. Only differences matter to the estimate, so an
-/// arbitrary epoch is fine; `u32` keeps the wrapping arithmetic the same width the reference used.
+/// The queue ring's clock, standing in for the reference's `GetTickCount`: only differences
+/// matter, and `u32` keeps the reference's wrapping width.
 fn queue_now_ms(time: &Time) -> u32 {
     time.elapsed().as_millis() as u32
 }
 
-/// What a Login press should do — the reference's two guards, as a verdict.
-///
-/// Extracted from [`login_input`] so the validation can be tested without standing a screen up,
-/// and so the click sound has somewhere to live that is not inside one of its branches.
+/// What a Login press should do: the reference's two empty-field guards, as a verdict.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum LoginPress {
     NeedAccount,
@@ -213,8 +180,7 @@ enum LoginPress {
     Submit,
 }
 
-/// The account box is checked first, so a wholly empty form asks for the account name — which is
-/// the order the reference's dialogs come in.
+/// The account is checked first, so an empty form asks for it, the reference's order.
 fn login_press(form: &LoginForm) -> LoginPress {
     if form.account.text.is_empty() {
         LoginPress::NeedAccount
@@ -225,7 +191,7 @@ fn login_press(form: &LoginForm) -> LoginPress {
     }
 }
 
-/// The `LOGIN_STATE_*` glue string for a stage (the connecting dialog's text).
+/// The connecting dialog's `LOGIN_STATE_*` text for a stage.
 fn stage_text(strings: &GlueStrings, stage: LoginStage) -> &str {
     match stage {
         LoginStage::Connecting => strings.text("LOGIN_STATE_CONNECTING", "Connecting"),
@@ -234,17 +200,11 @@ fn stage_text(strings: &GlueStrings, stage: LoginStage) -> &str {
     }
 }
 
-/// The authored failure string for an auth result byte (the vmangos-verified map, decision 0539
-/// §6): each row is the client's own `GlueStrings` text; a transport failure (`None`) reads
-/// `LOGIN_FAILED` ("Unable to connect").
+/// The failure text for a login result; a transport failure (`None`) reads `LOGIN_FAILED`.
 ///
-/// **A dial that never opened a socket answers ahead of all of them**, because it is the only
-/// failure the player can act on and — since 1667 made the address editable — the only one they can
-/// misread. "Unable to connect" cannot distinguish *that name does not exist* from *the address is
-/// fine and nothing is listening*, so a player whose server is simply down edits a correct address
-/// until they give up. That is what the editor's first live use produced. Both replacement strings
-/// are the reference's own (`AUTH_LOGIN_SERVER_NOT_FOUND` / `LOGIN_SERVER_DOWN`, so they localize);
-/// the address line under them is ours, because the reference never had an address to get wrong.
+/// Deviation: a dial that never opened a socket reads `AUTH_LOGIN_SERVER_NOT_FOUND` or
+/// `LOGIN_SERVER_DOWN` plus the address, because with an editable realmlist "Unable to connect"
+/// cannot tell a bad name from a server that is down.
 fn fail_text(
     strings: &GlueStrings,
     refusal: Option<LoginRefusal>,
@@ -266,15 +226,8 @@ fn fail_text(
     without_dead_url(authored).into_owned()
 }
 
-/// **The world server's** `SMSG_AUTH_RESPONSE` refusal, in the client's own words.
-///
-/// A straight transcription of the client's own dispatch over this enum (`0x5aa960`, through the
-/// key table `0x85cae8`) — each case loads exactly the `GlueStrings` key named below,
-/// and the numbering is `AuthResponseCodes` in cmangos `SharedDefines.h:1721+`. Nothing here is a
-/// judgement call; where the client picks a string, so do we.
-///
-/// Every one of these used to arrive as a generic "Unable to connect", because the world result
-/// was formatted into an error string in `WorldSession::connect` and the byte thrown away.
+/// The world server's `SMSG_AUTH_RESPONSE` refusal text: the client's dispatch (`0x5aa960`,
+/// key table `0x85cae8`), numbered as `AuthResponseCodes` in cmangos `SharedDefines.h:1721+`.
 fn world_refusal_text(strings: &GlueStrings, code: u8) -> &str {
     use benilla_protocol::messages as m;
     let (key, fallback): (&str, &str) = match code {
@@ -295,12 +248,10 @@ fn world_refusal_text(strings: &GlueStrings, code: u8) -> &str {
         m::AUTH_SERVER_SHUTTING_DOWN => ("AUTH_SERVER_SHUTTING_DOWN", "Server Shutting Down"),
         m::AUTH_ALREADY_LOGGING_IN => ("AUTH_ALREADY_LOGGING_IN", "Already Logging In"),
         m::AUTH_LOGIN_SERVER_NOT_FOUND => ("AUTH_LOGIN_SERVER_NOT_FOUND", "Invalid Login Server"),
-        // The tail past the queue. These five are exactly the rows of the client's `OKAY_WITH_URL`
-        // table (`0x803740`), which is why the URL dialog is reachable only from THIS enum: the
-        // lookup is a linear search over a ClientServices code and realmd's results never enter it.
-        // benilla shows the text without the URL button — `LaunchURL` is a shell-out we do not do,
-        // and its whitelist (`0x85cc34`) is ten worldofwarcraft.com/blizzard.com domains that have
-        // not served these pages in fifteen years.
+        // All but `AUTH_ALREADY_ONLINE` below are the rows of the client's `OKAY_WITH_URL` table
+        // (`0x803740`). Deviation: no URL button, because `LaunchURL` is a shell-out benilla does
+        // not make and its whitelist (`0x85cc34`) names only Blizzard domains that no longer
+        // serve these pages.
         m::AUTH_BANNED => (
             "AUTH_BANNED",
             "This account has been banned for violating the Terms of Use Agreement",
@@ -319,30 +270,16 @@ fn world_refusal_text(strings: &GlueStrings, code: u8) -> &str {
             "AUTH_PARENTAL_CONTROL",
             "Access to this account has been blocked by parental controls.",
         ),
-        // `AUTH_OK` never reaches here (it is the success path) and `AUTH_WAIT_QUEUE` is not a
-        // refusal at all; anything else is a code this client does not know.
+        // `AUTH_OK` and `AUTH_WAIT_QUEUE` never reach here; anything else is unknown.
         _ => ("AUTH_FAILED", "Authentication failed"),
     };
     strings.text(key, fallback)
 }
 
-/// Cut the **dead web address** off the tail of an authored failure string (director's call,
-/// 2026-08-28).
-///
-/// Every long `LOGIN_*`/`AUTH_*` string ends by pointing the player at a Blizzard page —
-/// `www.worldofwarcraft.com`, `worldofwarcraft.com/misc/banned.html`. None has served anything in
-/// fifteen years, and none was ever about *this* server: benilla's player is on somebody's private
-/// realm, where "see www.worldofwarcraft.com for more information" is not merely stale but
-/// misdirection. The rest of the sentence is still worth reading, so the address is cut at its
-/// **clause**, not its sentence — `"…a lost or stolen password and account, see
-/// www.worldofwarcraft.com for more information."` becomes `"…a lost or stolen password and
-/// account."`
-///
-/// Find the first web address, walk back to the clause boundary before it (a comma or a full
-/// stop), end there. **With no boundary to walk back to the string is left exactly as it is** —
-/// that guard is what stops `AUTH_BANNED` ("…violating the Terms of Use Agreement -
-/// www.worldofwarcraft.com/termsofuse.shtml…"), whose address sits behind a dash with no clause
-/// break before it, from being trimmed away to nothing.
+/// Cut a failure string at the clause (comma or full stop) before its first web address.
+/// Deviation: the reference prints the address, but those Blizzard pages no longer serve and a
+/// private realm's player is not served by them. With no boundary before the address (as in
+/// `AUTH_BANNED`) the string is left whole.
 fn without_dead_url(text: &str) -> std::borrow::Cow<'_, str> {
     let Some(url) = ["www.", "http://", "https://"]
         .iter()
@@ -362,40 +299,16 @@ fn without_dead_url(text: &str) -> std::borrow::Cow<'_, str> {
     std::borrow::Cow::Owned(format!("{kept}."))
 }
 
-/// The **realmd** logon-proof refusal, in the client's own words — the LONG `LOGIN_*` family.
+/// The realmd logon-proof refusal text, the long `LOGIN_*` family: realmd results resolve
+/// through key table `0x836b78` (`Logon::OnAuthResult` `0x5b2c90`, byte-index table `0x5b2ea4`,
+/// jump table `0x5b2e78`), the world server's through `0x85cae8` ([`world_refusal_text`]).
 ///
-/// **This table was wrong in every row until decision 1679**, and wrong in an instructive way: the
-/// codes were right and the *string family* was not. Decision 0539 §6 built it by reading vmangos'
-/// `AuthCodes.h`, which names the wire bytes but says nothing about what the client displays, and
-/// `GlueStrings.lua` happens to define two plausible families whose keys read alike. So a bad
-/// password showed the terse `AUTH_UNKNOWN_ACCOUNT` ("Unknown account") — a real reference string,
-/// in the wrong slot.
-///
-/// The client keeps **two** login-status enums with **two** key tables, and they are conflated
-/// precisely because both raise the dialog through `OPEN_STATUS_DIALOG`. realmd's results resolve
-/// against table `0x836b78` — the long `LOGIN_*` family; the world server's resolve against
-/// `0x85cae8` — the short `AUTH_*` family ([`world_refusal_text`]). The chain is grunt opcode table
-/// `0x85e278` → `Logon::OnAuthResult 0x5b2c90` (byte-index table `0x5b2ea4` + jump table
-/// `0x5b2e78`) → `CGlueMgr::OnLoginState 0x46b0f0` → `CGlueMgr::UpdateGlueDialog 0x46b140`.
-///
-/// Two consequences worth stating outright:
-///
-/// **0x04 and 0x05 share one jump-table arm** — byte-identical, both `LOGIN_UNKNOWN_ACCOUNT`. The
-/// reference client structurally *cannot* say "wrong password" on a logon refusal, and
-/// `LOGIN_INCORRECT_PASSWORD` is dead surface it never reaches. That also retires the emulator lore
-/// that the client locks out after 0x05 (vmangos sends 0x04 for both to avoid it): there is no
-/// lockout — no disabled button, no delay, nothing persisted. Its one counter is gated on a
-/// `securityFlags` byte that is zero on vmangos and cmangos, and only escalates the same string
-/// toward its `_PIN`/`_CALL` variants.
-///
-/// **Anything past 0x0F is clamped**, not passed through: the byte-index table saturates at 0xFF,
-/// which lands on the arm that shows `DISCONNECTED`. So 0x10/0x11/0x12 and every unknown future
-/// code read as a disconnect rather than as an authentication message.
+/// 0x04 and 0x05 share one arm, `LOGIN_UNKNOWN_ACCOUNT`: the reference never shows
+/// `LOGIN_INCORRECT_PASSWORD` and has no lockout. Codes past 0x0F saturate to the arm that shows
+/// `DISCONNECTED`.
 fn logon_refusal_text(strings: &GlueStrings, code: Option<u8>) -> &str {
     let (key, fallback): (&str, &str) = match code {
-        // A transport failure never had a code; the client's own answer for the codes that mean
-        // "no usable connection" is the same string, so they share this row.
-        // 0x01/0x02 (unknown0/1), 0x0B (invalid server), 0x0D (no access).
+        // No code, unknown0/1, invalid server and no access all read `LOGIN_FAILED`.
         None | Some(0x01) | Some(0x02) | Some(0x0B) | Some(0x0D) => {
             ("LOGIN_FAILED", "Unable to connect")
         }
@@ -404,7 +317,7 @@ fn logon_refusal_text(strings: &GlueStrings, code: Option<u8>) -> &str {
             "This World of Warcraft account has been closed and is no longer available for use.  \
              Please go to http://www.worldofwarcraft.com/misc/banned.html for further information. ",
         ),
-        // BOTH the unknown account and the wrong password — see the doc above.
+        // The unknown account and the wrong password alike.
         Some(0x04) | Some(0x05) => (
             "LOGIN_UNKNOWN_ACCOUNT",
             "The information you have entered is not valid.  Please check the spelling of the \
@@ -441,17 +354,14 @@ fn logon_refusal_text(strings: &GlueStrings, code: Option<u8>) -> &str {
             "Access to this account has been blocked by parental controls.  Your settings may be \
              changed in your account preferences at http://www.worldofwarcraft.com.",
         ),
-        // 0x0A (version update) is IGNORED on the proof (`0x5bada2`) and never reaches a dialog;
-        // it only means anything on the challenge, where it is the patch-download state. Every
-        // remaining code clamps to the disconnect arm.
+        // 0x0A (version update) is ignored on the proof (`0x5bada2`); every remaining code takes
+        // the disconnect arm.
         Some(_) => ("DISCONNECTED", "Disconnected from server"),
     };
     strings.text(key, fallback)
 }
 
-/// The policy tick + the net-message reactions. Runs in every state (the reconnect path fires
-/// while `InWorld`); the screen's own submit comes through [`login_input`], which calls
-/// [`send_login`] with `announced = true`.
+/// The policy tick and the net-message reactions; the screen's own submit is [`login_input`]'s.
 fn drive_policy(
     mut attempt: Attempt,
     realm_list_up: Res<crate::realm_select::Realms>,
@@ -465,33 +375,22 @@ fn drive_policy(
     mut exit: MessageWriter<AppExit>,
 ) {
     let now = time.elapsed_secs();
-    // A harness run (env creds, and not the smoke — the smoke owns its own verdict) may have
-    // nobody at the keyboard: a login failure no resubmit can change would leave it parked on a
-    // dialog for its whole wall-clock, and every retry a runner grants it is spent the same way.
-    // Those failures exit non-zero instead, on one greppable marker — "login: FATAL" — that
-    // a leg runner keys on (decision 1371).
-    //
-    // **Nobody is here only if the run says so** (decision 1769). Whether the client may end the
-    // run itself is [`crate::run_mode::fatal_when_driverless`]'s to answer; the two facts this
-    // scope adds are local ones. The smoke owns its own verdict, so it is never ours to end.
+    // A driverless run exits non-zero ("login: FATAL") on a failure no resubmit can change, as
+    // [`crate::run_mode::fatal_when_driverless`] decides; the smoke owns its own verdict.
     let smoke = std::env::var_os("WOW_LOGIN_SMOKE").is_some();
     let empty = GlueStrings::default();
     let strings = strings.as_deref().unwrap_or(&empty);
 
-    // The env fast path, once (decision 0539 §3): WOW_USER and WOW_PASS both set → auto-submit
-    // them, so every probe/smoke/harness invocation keeps working. There is no default account.
-    // The login smoke drives its own credentials instead.
+    // The env fast path, once: `WOW_USER` and `WOW_PASS` both set auto-submit, except under the
+    // login smoke, which drives its own credentials. There is no default account.
     if !attempt.intent.env_read {
         attempt.intent.env_read = true;
-        // Purely "are the credentials in the environment?" (decision 1769) — whether anybody is
-        // here to *react* is a different fact with a different home, `run_mode::unattended`.
         if crate::run_mode::env_login() && std::env::var_os("WOW_LOGIN_SMOKE").is_none() {
             let user = std::env::var("WOW_USER").unwrap_or_default();
             let pass = std::env::var("WOW_PASS").unwrap_or_default();
-            // The account guard (decision 0649): a vmangos login KICKS whoever holds the account,
-            // so an unattended run authenticates as the account its checkout declares
-            // (`.probe-identity`) and nothing else. Only the *automated* path is gated — a typed
-            // login is the player's own and is never second-guessed.
+            // A vmangos login kicks whoever holds the account, so the automated path logs in
+            // only as the checkout's declared account (`.probe-identity`); a typed login is not
+            // gated.
             match crate::run_mode::account_guard(&user) {
                 Ok(()) => {
                     info!("login: env fast path — auto-submitting as {user}");
@@ -506,8 +405,7 @@ fn drive_policy(
                 Err(why) => {
                     error!("login: REFUSING the env fast path — {why} Set WOW_ALLOW_ACCOUNT=1 if the cross-account login is deliberate.");
                     dialog.open_error(&why);
-                    // The refusal is deterministic — the slot is baked into the binary — so the
-                    // run can never get past this screen (the 1371 legs burned 3 × timeout on it).
+                    // The refusal is deterministic, so the run can never get past this screen.
                     if crate::run_mode::fatal_when_driverless(
                         "the account guard refused the only credentials this run has",
                     ) {
@@ -523,16 +421,13 @@ fn drive_policy(
             dialog.set_text(stage_text(strings, msg.stage));
         }
     }
-    // The realm list answers the same question the status dialog is asking ("what are we
-    // connecting to?"), and the reference does not stack them: reaching the realm list means the
-    // login state moved past `LOGIN_STATE_CONNECTING`, and `CGlueMgr::UpdateGlueDialog` clears
-    // the dialog when it does. Ours would otherwise sit behind the list saying "Connecting".
+    // Reaching the realm list moves the login state past `LOGIN_STATE_CONNECTING`, and
+    // `CGlueMgr::UpdateGlueDialog` (`0x46b140`) then clears the status dialog.
     if realm_list_up.shown && matches!(dialog.kind, Some(DialogKind::Status)) {
         dialog.close();
     }
-    // **The queue** (decision 1681): each packet is one sample, and the first one turns the
-    // connecting dialog into the queue dialog. A queue is not a failure — the attempt is still in
-    // flight and `in_flight` deliberately stays set, so nothing resubmits underneath it.
+    // Each queue packet is one sample; the first turns the connecting dialog into the queue
+    // dialog. `in_flight` stays set, so nothing resubmits under a queue.
     for msg in queued.read() {
         if !matches!(dialog.kind, Some(DialogKind::Queued)) {
             dialog.open_queued(msg.realm.clone());
@@ -547,7 +442,7 @@ fn drive_policy(
                 .map_or_else(|| "unknown".to_string(), |p| p.to_string()),
         );
     }
-    // The countdown is live between packets, so the text is recomputed every frame it is up.
+    // The estimate moves between packets, so the text is recomputed every frame.
     if matches!(dialog.kind, Some(DialogKind::Queued)) {
         let text = dialog.queue.text(
             queue_now_ms(&time),
@@ -559,17 +454,12 @@ fn drive_policy(
     for msg in failures.read() {
         attempt.intent.in_flight = false;
         attempt.intent.park = IoPark::AtLogin;
-        // A terminal failure names something no resubmit can change (the server requires Warden,
-        // say) — show the server's own words and drop the credentials so nothing retries.
-        // **Did a person submit the attempt that just failed?** `announced` is set by the login
-        // screen's own submit and by nothing else — the env fast path and every paced resubmit
-        // leave it false — so it is direct evidence rather than an inference about the room, and
-        // `LoginIntent::clear` below deliberately does not reset it. A typed attempt is attended
-        // by definition, and an attended failure gets the reference's answer: the dialog, and
-        // another go. Only an attempt nobody typed may kill the process.
+        // `announced` is set only by the screen's submit, and `LoginIntent::clear` leaves it, so
+        // it says a person typed this attempt; only an untyped attempt may end the run.
         let typed = attempt.intent.announced;
         let may_end_the_run = !typed && !smoke;
         if msg.terminal {
+            // No resubmit can change it: show the server's words and drop the credentials.
             warn!("login: {}", msg.reason);
             attempt.intent.clear();
             dialog.open_error(&msg.reason);
@@ -585,8 +475,7 @@ fn drive_policy(
         }
         match msg.refusal {
             Some(refusal) => {
-                // A refusal — from EITHER server: surface it (even on the silent path, since the
-                // credentials went stale) and never auto-retry against it.
+                // A refusal from either server: shown even on the silent path, never retried.
                 let byte = refusal.byte();
                 warn!("login: refused ({refusal:?}, {byte:#04x}) — {}", msg.reason);
                 attempt.intent.clear();
@@ -604,7 +493,7 @@ fn drive_policy(
                 dialog.open_error(&fail_text(strings, None, msg.dial.as_ref()));
             }
             None => {
-                // Silent transport failure with pending intent: schedule the paced resubmit.
+                // A silent transport failure schedules the paced resubmit.
                 debug!("login: transport failure ({}) — retrying", msg.reason);
                 if attempt.intent.creds.is_some() {
                     attempt.intent.retry_at = Some(now + RETRY_DELAY_SECS);
@@ -613,15 +502,11 @@ fn drive_policy(
         }
     }
     for msg in disconnects.read() {
-        // The IO thread is heading back to its pre-logon park.
         attempt.intent.park = IoPark::AtLogin;
         attempt.intent.in_flight = false;
         if msg.session_over {
-            // The reference's `DISCONNECTED_FROM_SERVER` (decision 1262): `GlueParent.lua` answers
-            // it with `SetGlueScreen("login")` + `GlueDialog_Show("DISCONNECTED")` — the account
-            // screen and one Okay button. Nothing retries, and the credentials go with the session:
-            // a client that re-authenticates on its own steals the account back from whoever just
-            // displaced it, which is the ping-pong the report described.
+            // `DISCONNECTED_FROM_SERVER`: `GlueParent.lua` shows the login screen and the
+            // `DISCONNECTED` dialog. The credentials go, so nothing takes the account back.
             warn!(
                 "login: {} — session over, back to the login screen",
                 msg.reason
@@ -630,9 +515,7 @@ fn drive_policy(
             dialog.open_error(strings.text("DISCONNECTED", "Disconnected from server"));
             continue;
         }
-        // Otherwise the session continues through the park and the re-auth is silent: immediate
-        // after a clean logout (the roster IS the select screen the app now shows), paced after a
-        // stream death an unattended run must recover from on its own (0065, paced app-side).
+        // Otherwise a silent re-auth: at once after a logout, paced after a stream death.
         if attempt.intent.creds.is_some() {
             let delay = if msg.end == benilla_protocol::SessionEnd::LoggedOut {
                 0.0
@@ -643,7 +526,6 @@ fn drive_policy(
         }
     }
 
-    // The silent (re)submit tick.
     if attempt.intent.park == IoPark::AtLogin
         && !attempt.intent.in_flight
         && attempt.intent.retry_at.is_some_and(|t| now >= t)
@@ -656,9 +538,8 @@ fn drive_policy(
     }
 }
 
-/// The roster's arrival is the login flow's success edge: the attempt settled, the IO thread is
-/// parked at select — leave the login screen for CharSelect (only from `Login`; a reconnect's
-/// roster lands while `InWorld` and must not flip the screen).
+/// The roster is the login's success edge: go to CharSelect, but only from `Login`, since a
+/// reconnect's roster lands while `InWorld`.
 fn to_select_on_roster(
     mut msgs: MessageReader<CharListMessage>,
     mut intent: ResMut<LoginIntent>,
@@ -672,12 +553,8 @@ fn to_select_on_roster(
     intent.in_flight = false;
     intent.park = IoPark::Active;
     intent.retry_at = None;
-    // **Only the dialogs the roster ANSWERS.** This used to close whatever was up, which was
-    // right while the only dialog that could be up here was this screen's own "Connecting…". It
-    // stopped being right when a refused *character* login started raising an `Error` on the
-    // select screen: the refusal's relist produces a roster a second later, and closing on it
-    // would take the message off the screen before the player had read it — the same silent
-    // refusal, one layer up. An `Error` is dismissed by its Okay, never by an arriving packet.
+    // Only the dialogs the roster answers: a refused character login's relist brings a roster,
+    // and its `Error` is dismissed by its Okay, never by a packet.
     if matches!(dialog.kind, Some(DialogKind::Status | DialogKind::Queued)) {
         dialog.close();
     }
@@ -696,11 +573,8 @@ pub(super) enum Field {
     Password,
 }
 
-/// The typed form: both boxes, the focus, and the Remember checkbox. Each box is a real
-/// [`EditBoxState`] — the same byte-verified model the chat box uses — so the login fields get
-/// caret movement, selection, Ctrl+A and the clipboard from the shared law rather than the
-/// three-case imitation they used to carry (decision 0704). The caret clock lives in the box too
-/// (`blink_accum`/`caret_shown`), so it blinks on the client's own 0.5 s period.
+/// The typed form: both boxes, the focus and the Remember checkbox. Each box is the shared
+/// [`EditBoxState`], caret blink (the client's 0.5 s period) included.
 #[derive(Resource)]
 pub(crate) struct LoginForm {
     pub(super) account: EditBoxState,
@@ -713,7 +587,7 @@ impl Default for LoginForm {
     fn default() -> Self {
         LoginForm {
             account: textinput::field(MAX_LETTERS, false),
-            // `password` masks the *display* only; the real text is never rendered or copied.
+            // Masks the display; the real text is never rendered or copied.
             password: textinput::field(MAX_LETTERS, true),
             focus: Field::default(),
             save: false,
@@ -722,41 +596,19 @@ impl Default for LoginForm {
 }
 
 impl LoginForm {
-    /// Give `field` the keyboard **and select everything already in it** — dropping the selection
-    /// on the box being left.
+    /// Give `field` the keyboard, select all its text and collapse the selection in the box left.
     ///
-    /// **A knowing divergence** (director's call, 2026-08-28), and the reference half of it is
-    /// byte-settled rather than inferred. The reference does the *opposite* on a click:
-    /// `OnMouseDown` (`0x77b800`) hit-tests the click to a byte index, **collapses** the selection
-    /// onto it (`0x77b86f call 0x77ccf0`) and only then calls `SetFocus` — so a fresh click-focus
-    /// leaves an EMPTY selection at the character you clicked. And `SetFocus` itself writes no
-    /// selection field at all; `0x77e3f6` being the only instruction image-wide that grants focus
-    /// makes *every* focus gain selection-neutral, TAB included. Losing focus likewise touches
-    /// nothing (`0x77af50` raises only the cursor dirty bit).
-    ///
-    /// So we diverge in both directions, deliberately: the reference collapses where we select, and
-    /// leaves stale where we collapse. The reason is the same one for both — the thing a player does
-    /// after clicking into a login field is *replace* what is there, a remembered account name or a
-    /// mistyped password, and having to select-all or backspace it out first is friction the
-    /// reference only avoids by being what everyone was used to in 2006.
-    ///
-    /// **A divergence owes both halves.** 1682 shipped only the select; nothing ever unselected,
-    /// so the box you left kept a grey highlight behind you and the screen showed two selections at
-    /// once (the director's report, 2026-08-29). Selecting on focus is only coherent if the
-    /// selection *means* "this is the box the keyboard is in" — which makes collapsing the outgoing
-    /// box not a second feature but the other half of this one. It runs the client's own
-    /// collapse-to-cursor (`0x77ccf0`), the same primitive every delete path uses.
-    ///
-    /// The selection uses the client's own `HighlightText(0, -1)` (`0x77cca0`), which resets the
-    /// blink on its way, so the box still opens on a solid caret — the property the old
-    /// `reset_blink()` calls at these sites existed to preserve.
+    /// Deviation: select on focus and collapse on leaving, because a player entering a login
+    /// field means to replace what is there. The reference's focus gain (`0x77e3f6`) and loss
+    /// (`0x77af50`) leave the selection alone, and its click collapses it (`0x77b800` calls
+    /// `0x77ccf0` before `SetFocus`). `HighlightText(0, -1)` (`0x77cca0`) also resets the blink,
+    /// so the caret opens solid.
     fn focus(&mut self, field: Field) {
         self.focused().collapse();
         self.focus = field;
         self.focused().highlight_text(0, -1);
     }
 
-    /// The box that currently owns the keyboard.
     fn focused(&mut self) -> &mut EditBoxState {
         match self.focus {
             Field::Account => &mut self.account,
@@ -765,13 +617,12 @@ impl LoginForm {
     }
 }
 
-/// The armed quit (`gsTitleQuit` needs [`QUIT_GRACE_SECS`] to be audible before `AppExit`).
+/// The armed quit: `gsTitleQuit` gets [`QUIT_GRACE_SECS`] before `AppExit`.
 #[derive(Resource, Default)]
 struct QuitArm(Option<f32>);
 
-/// Entering the login screen: the ref's `AccountLogin_OnShow` — prefill the saved account name,
-/// clear the password, focus account when empty / password otherwise, checkbox = saved-name
-/// exists — and stand the `UI_MainMenu` scene up.
+/// `AccountLogin_OnShow`: prefill the saved account, clear the password, focus the first empty
+/// box, check Remember when a name is saved; then show the `UI_MainMenu` scene.
 fn enter_login(mut form: ResMut<LoginForm>, mut preview: ResMut<GluePreview>) {
     let saved = load_saved_account();
     form.save = !saved.is_empty();
@@ -782,9 +633,8 @@ fn enter_login(mut form: ResMut<LoginForm>, mut preview: ResMut<GluePreview>) {
     };
     form.account.set_text(&saved);
     form.password.set_text("");
-    // `SetFocus` starts the caret solid — the screen never opens mid-blink-off (`set_text` alone
-    // wouldn't do it: it no-ops when the saved name is already in the box) — and selects, so a
-    // remembered account name is typed over rather than appended to.
+    // Focus starts the caret solid (`set_text` no-ops on an unchanged name) and selects, so a
+    // remembered name is typed over.
     let focus = form.focus;
     form.focus(focus);
     preview.scene = Some(GlueScene::MainMenu);
@@ -792,9 +642,8 @@ fn enter_login(mut form: ResMut<LoginForm>, mut preview: ResMut<GluePreview>) {
     preview.yaw = 0.0;
 }
 
-/// The screen's input: typing into the focused box (the ref's 16-letter cap), Tab cycling, Enter
-/// submits, Esc quits (dialog-first — an open dialog's Esc is its Cancel/Okay), clicks focus the
-/// boxes / press the buttons / toggle the checkbox.
+/// The screen's input: typing, Tab, Enter submits, Esc quits (an open dialog takes it first),
+/// and clicks on the boxes, buttons and checkbox.
 #[allow(clippy::type_complexity)]
 fn login_input(
     realms: Res<crate::realm_select::Realms>,
@@ -802,7 +651,6 @@ fn login_input(
     clicks: Res<crate::glue::GlueClicks>,
     mut keyboard: MessageReader<KeyboardInput>,
     keys: Res<ButtonInput<KeyCode>>,
-    // The host pasteboard + the window handle the Wayland backend needs (decision 0702).
     mut clipboard: NonSendMut<HostClipboard>,
     raw_handle: Query<&bevy::window::RawHandleWrapper, With<bevy::window::PrimaryWindow>>,
     mut form: ResMut<LoginForm>,
@@ -814,9 +662,8 @@ fn login_input(
     mut commands: Commands,
     time: Res<Time>,
 ) {
-    // The realm list stands **over** this screen rather than replacing it (the reference's
-    // `RealmList` is a DIALOG-strata frame, not a glue screen), so while it is up the boxes,
-    // buttons and keys underneath are inert — including ESCAPE, which is its Cancel, not our Quit.
+    // The reference's `RealmList` is a DIALOG-strata frame over this screen, so while it is up
+    // everything here is inert, Escape included (it is the list's Cancel).
     if realms.shown {
         return;
     }
@@ -826,32 +673,22 @@ fn login_input(
     let mut do_login = false;
     let mut do_quit = false;
 
-    // While a dialog is up it owns the input; the box/button surface underneath is inert.
     let dialog_open = dialog.kind.is_some();
 
-    // **The edit boxes focus on the PRESS**, and only they. The reference's `CEditBox` takes focus
-    // from its own OnMouseDown handler (`0x77b800`), unconditionally and autoFocus-independent —
-    // an edit box is not a Button and does not wait for the release. Every *button* on this
-    // screen fires from the release loop below (1533).
     for (entity, action, interaction) in &presses {
         if dialog_open {
             continue;
         }
-        // **The edit boxes focus on the PRESS**, and only they: the reference's `CEditBox` takes
-        // focus from its own OnMouseDown handler (`0x77b800`), unconditionally and
-        // autoFocus-independent — an edit box is not a Button and does not wait for the release.
-        // `Ref` supplies the press *edge* the old `Changed<Interaction>` filter gave, without
-        // costing this system a second query.
+        // The edit boxes focus on the press: `CEditBox`'s OnMouseDown (`0x77b800`) takes focus
+        // unconditionally, without waiting for a release.
         if interaction.is_changed() && *interaction == Interaction::Pressed {
             match action {
-                // A click takes the focus the same way TAB does — the solid caret, and the
-                // select-all that makes the next keystroke replace what is in the box.
                 LoginAction::FocusAccount => form.focus(Field::Account),
                 LoginAction::FocusPassword => form.focus(Field::Password),
                 _ => {}
             }
         }
-        // Everything else on this screen is a Button, and a Button fires on the RELEASE (1533).
+        // Everything else here is a Button, which fires on the release.
         if !clicks.hit(entity) {
             continue;
         }
@@ -859,27 +696,20 @@ fn login_input(
             LoginAction::FocusAccount | LoginAction::FocusPassword => {} // focused on the press
             LoginAction::Login => do_login = true,
             LoginAction::Quit => do_quit = true,
-            // The realmlist control (1667) — the button and the address readout under it are
-            // the same action, so clicking either opens the editor.
             LoginAction::Realmlist => {
-                // `gsLoginNewAccount` — what the reference plays for the other buttons in this
-                // corner (`AccountLogin_ManageAccount`, `AccountLogin_LaunchCommunitySite`), which
-                // is the closest authored answer for a button it does not have. It replaces a
-                // `gsClick` I invented in 1667: no such SoundEntries kit exists, so that press was
-                // silently playing nothing at all.
+                // `gsLoginNewAccount`, which the reference plays for this corner's other buttons
+                // (`AccountLogin_ManageAccount`, `AccountLogin_LaunchCommunitySite`).
                 sounds.write(GlueSound("gsLoginNewAccount"));
                 if attempt.realmlist.pinned_by_env() {
-                    // A harness/dev run owns the address for the session (`cvars`' env-override
-                    // law). Say so rather than opening an editor whose Okay would be a silent
-                    // no-op — the trap that shape would set.
+                    // `$WOW_HOST` owns the address for the session; say so rather than open an
+                    // editor whose Okay would do nothing.
                     dialog.open_error(&format!(
                         "$WOW_HOST is set for this session, so the realmlist is fixed at {}.",
                         attempt.realmlist.address(),
                     ));
                 } else {
                     dialog.open_realmlist(
-                        // The reference's own registered help text for `realmList`, byte-verified
-                        // in `WoW.exe` beside the CVar's name and default.
+                        // The reference's registered help text for the `realmList` CVar.
                         "Address of realm list server",
                         attempt.realmlist.address(),
                     );
@@ -887,8 +717,8 @@ fn login_input(
             }
             LoginAction::ToggleSave => {
                 form.save = !form.save;
-                // Verbatim ref quirk (`AccountLoginSaveAccountName` OnClick): checked plays the
-                // "Off" kit, unchecked the "On" kit.
+                // As `AccountLoginSaveAccountName`'s OnClick: checked plays the "Off" kit,
+                // unchecked the "On" kit.
                 sounds.write(GlueSound(if form.save {
                     "igMainMenuOptionCheckBoxOff"
                 } else {
@@ -897,18 +727,15 @@ fn login_input(
                 if !form.save {
                     save_account("");
                 }
-            } // The dialog's own buttons are `crate::glue::dialog`'s, and this loop is
-              // skipped entirely while one is open.
+            }
         }
     }
 
     let mods = textinput::mods_now(&keys);
     let wl = textinput::wayland_display(raw_handle.iter().next());
     for ev in keyboard.read() {
-        // A dialog with an edit box owns the keyboard while it is up — the ref's `GlueDialog` is
-        // `toplevel` with `enableKeyboard="true"`, so the boxes behind it hear nothing. ENTER and
-        // ESCAPE still come back unclaimed; [`crate::glue::dialog::drive_glue_dialog`] reads
-        // them as its two buttons.
+        // An open dialog owns the keyboard (`GlueDialog` is `toplevel`, `enableKeyboard`);
+        // Enter and Escape are read by [`crate::glue::dialog::drive_glue_dialog`] as its buttons.
         if dialog_open {
             if dialog.kind.is_some_and(DialogKind::has_edit_box) {
                 textinput::feed_key(
@@ -922,9 +749,8 @@ fn login_input(
             }
             continue;
         }
-        // The shared law first (editing, caret, selection, the clipboard trio); only what it
-        // hands back unclaimed is the screen's own — TAB cycles the two boxes, ENTER/ESCAPE are
-        // handled below off `just_pressed`.
+        // The shared edit box first; what it leaves unclaimed is the screen's (Tab here, Enter
+        // and Escape below).
         if textinput::feed_key(
             form.focused(),
             ev,
@@ -958,16 +784,11 @@ fn login_input(
     }
 
     if do_login && !attempt.intent.in_flight {
-        // **`gsLogin` first, always** — `AccountLogin_Login` plays it before it calls
-        // `DefaultServerLogin`, so the reference clicks even when the attempt is about to be
-        // refused for an empty box. Ours played it only on the path that reached the wire, so a
-        // Login press with a field still blank was silent and the dialog appeared out of nowhere
-        // (the director's "the sound of the popup is sometimes missing"). It sits OUTSIDE the
-        // match on purpose: a sound that is structurally unconditional cannot go missing on some
-        // branch again.
+        // `gsLogin` on every press: `AccountLogin_Login` plays it before `DefaultServerLogin`,
+        // so an empty-box refusal clicks too.
         sounds.write(GlueSound("gsLogin"));
         match login_press(&form) {
-            // The ref's own guards: empty account / empty password get their dialog, no wire.
+            // The reference's empty-box guards: a dialog, nothing on the wire.
             LoginPress::NeedAccount => {
                 dialog.open_error(
                     strings.text("LOGIN_ENTER_NAME", "Please enter your account name."),
@@ -979,8 +800,8 @@ fn login_input(
                 );
             }
             LoginPress::Submit => {
-                // `AccountLogin_Login`: save or clear the account name per the checkbox, clear the
-                // password box after grabbing it.
+                // `AccountLogin_Login`: save or clear the name per the checkbox, then clear the
+                // password box.
                 if form.save {
                     save_account(&form.account.text);
                 } else {
@@ -1000,20 +821,8 @@ fn login_input(
     }
 }
 
-/// The caret's clock. Exactly one box owns the keyboard, so the focused one is the one that blinks
-/// — on the shared law's 0.5 s period, so the login caret keeps time with the create-name box, the
-/// delete dialog and the chat box (decision 0704). It keeps blinking under an open dialog: a dialog
-/// eats the keys, not the clock.
-///
-/// Its own system, not a line inside [`login_input`]: a blink is a clock, not input, and as a
-/// system it can be run on its own in a test — which is the only thing that can catch this tick
-/// going missing again. It went missing once already, and nothing but an eye noticed: the box's
-/// `caret_shown` simply never left its `true` default, so the login caret was the one glue caret
-/// that sat solid.
-///
-/// **A dialog with an edit box takes the focus with the keys** (1667): its box blinks and the
-/// form's stops, so the screen never shows two live carets at once. Every other dialog leaves the
-/// form's caret running — a dialog eats the keys, not the clock.
+/// The focused box's caret clock, on the shared 0.5 s period. A dialog with an edit box takes
+/// the blink, so only one caret is live; any other dialog leaves the form's caret running.
 fn tick_login_caret(mut form: ResMut<LoginForm>, mut dialog: ResMut<GlueDialog>, time: Res<Time>) {
     let dt = time.delta_secs();
     let in_dialog = dialog.kind.is_some_and(DialogKind::has_edit_box);
@@ -1023,8 +832,8 @@ fn tick_login_caret(mut form: ResMut<LoginForm>, mut dialog: ResMut<GlueDialog>,
     }
 }
 
-/// Editing the account box away from the saved name clears the save + unchecks (the ref's
-/// `OnTextChanged`).
+/// Editing the account box away from the saved name clears the save and unchecks
+/// (`OnTextChanged`).
 fn on_account_edited(form: &mut LoginForm) {
     if form.save {
         let saved = load_saved_account();
@@ -1035,7 +844,7 @@ fn on_account_edited(form: &mut LoginForm) {
     }
 }
 
-/// Fire the armed quit once its grace elapsed (so `gsTitleQuit` is heard).
+/// Fire the armed quit once its grace has elapsed.
 fn drive_quit(arm: Option<Res<QuitArm>>, time: Res<Time>, mut exit: MessageWriter<AppExit>) {
     if let Some(arm) = arm {
         if arm.0.is_some_and(|t| time.elapsed_secs() >= t) {
@@ -1046,17 +855,13 @@ fn drive_quit(arm: Option<Res<QuitArm>>, time: Res<Time>, mut exit: MessageWrite
 
 // ── The GlueDialog (connecting / error) ──────────────────────────────────────────────────────────
 
-/// What the realmlist dialog says when the box holds something that is not an address. It replaces
-/// the prompt in place and **leaves the typed text alone**, so the fix is an edit rather than a
-/// retype — the reason a bad value does not close the dialog or become an error dialog of its own.
+/// The realmlist dialog's prompt for a value that is not an address; the typed text stays for
+/// editing.
 const REALMLIST_BAD: &str =
     "That is not a server address.\nTry  logon.example.org  or  127.0.0.1:3724";
 
-/// **What a glue-dialog press means, on this screen.** The widget itself
-/// ([`crate::glue::dialog::drive_glue_dialog`]) owns the tree, the keys and the click sound, and
-/// ends an `Error` on its own; everything below is behaviour only the login screen can define, and
-/// none of it is reachable from any other screen — `Status`, `Queued` and `Realmlist` can only be
-/// *opened* from here.
+/// What a glue-dialog press means on this screen; the widget
+/// ([`crate::glue::dialog::drive_glue_dialog`]) owns the tree, keys and sound, and ends an `Error`.
 fn answer_dialog(
     mut commands: Commands,
     mut answers: MessageReader<crate::glue::dialog::GlueDialogAnswer>,
@@ -1068,13 +873,11 @@ fn answer_dialog(
 ) {
     for answer in answers.read() {
         match answer.kind {
-            // The widget's own — it has already dismissed it.
+            // Already dismissed by the widget.
             DialogKind::Error => {}
             DialogKind::Realmlist => {
-                // Okay: take the typed address, or say why it cannot be taken and stay open with
-                // the text as typed — the fix is then an edit, not a retype. **The only press
-                // that does not end its dialog**, which is exactly why the widget cannot own
-                // this arm. Cancel (button 2, or ESCAPE, which this kind routes to it) closes.
+                // Okay takes the address or stays open with the text as typed, the one press
+                // that does not end its dialog. Cancel (or Escape) closes.
                 if answer.button1 {
                     let typed = dialog.edit.text.clone();
                     if accept_realmlist(&typed, &mut realmlist, script.as_deref_mut()) {
@@ -1087,8 +890,7 @@ fn answer_dialog(
                 }
             }
             DialogKind::Status | DialogKind::Queued => {
-                // Cancel: the next stage boundary discards the attempt; a canceled manual attempt
-                // must not silently resubmit later.
+                // Cancel: the next stage boundary discards the attempt, and nothing resubmits.
                 abandon.0.fetch_add(1, Ordering::SeqCst);
                 intent.in_flight = false;
                 intent.clear();
@@ -1098,16 +900,9 @@ fn answer_dialog(
     }
 }
 
-/// Take the realmlist dialog's Okay: normalize what was typed, point the session at it, and mirror
-/// it into the `realmList` CVar so it is still there next launch. `false` = the box holds nothing
-/// usable and the caller should keep the dialog open.
-///
-/// The persistence leg is `char_select`'s `lastCharacterIndex` pattern exactly (1131/1293): an
-/// **engine-side** write rides the change queue like a Lua `SetCVar`, so `cvars::sync_cvars` folds
-/// it into the knob and marks the file dirty, and `save_config` writes `config.toml`. A write to a
-/// name the VM has not registered yet is a deliberate silent no-op there, so this reports that
-/// case rather than claiming a save that did not happen — the **session** value stands either way,
-/// which is the half that matters for the login about to be attempted.
+/// Take the realmlist dialog's Okay: normalize, point the session at it, and write the
+/// `realmList` CVar so it persists; `false` keeps the dialog open. A CVar the VM has not
+/// registered yet is not saved, but the session value stands.
 fn accept_realmlist(
     typed: &str,
     realmlist: &mut crate::realmlist::Realmlist,
@@ -1137,10 +932,9 @@ fn accept_realmlist(
     true
 }
 
-// ── The saved account name (decision 0539 §4) ────────────────────────────────────────────────────
+// ── The saved account name ────────────────────────────────────────────────────
 
-/// Read the saved account name from `base` (missing file/dir = empty). Takes the *file* rather
-/// than resolving one, so the round-trip is testable from a tempdir.
+/// Read the saved account name at `path`; a missing file reads empty.
 fn load_saved_account_from(path: &std::path::Path) -> String {
     std::fs::read_to_string(path)
         .map(|s| s.trim().to_string())
@@ -1163,16 +957,14 @@ fn save_account_to(path: &std::path::Path, name: &str) {
     }
 }
 
-/// The ref's `GetSavedAccountName`. The path is [`crate::local_state`]'s — this module computed its
-/// own until decision 1181, which is how the account name ended up in a different folder from every
-/// other setting, and how a capture came to read one off the host machine.
+/// `GetSavedAccountName`, at [`crate::local_state`]'s path.
 fn load_saved_account() -> String {
     crate::local_state::saved_account_path()
         .map(|p| load_saved_account_from(&p))
         .unwrap_or_default()
 }
 
-/// The ref's `SetSavedAccountName` (empty clears).
+/// `SetSavedAccountName`; empty clears.
 fn save_account(name: &str) {
     if let Some(path) = crate::local_state::saved_account_path() {
         save_account_to(&path, name);
@@ -1183,23 +975,17 @@ fn save_account(name: &str) {
 mod tests {
     use super::*;
 
-    /// Stand `drive_policy` up on its own with the env fast path already spent, so the policy
-    /// under test is the disconnect arm and nothing else — and so an ambient `WOW_USER` in
-    /// whatever shell runs the suite cannot seed credentials behind the assertions.
+    /// `drive_policy` alone with the env fast path spent, so an ambient `WOW_USER` cannot seed
+    /// credentials.
     fn policy_app() -> (App, crossbeam_channel::Receiver<LoginRequest>) {
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut app = App::new();
         app.init_resource::<Time>()
             .init_resource::<LoginIntent>()
-            // The dialog is `GluePlugin`'s resource now (2084), so a harness that stands this
-            // screen's systems up without that plugin has to seat it.
+            // `GluePlugin`'s resource, seated here without the plugin.
             .init_resource::<GlueDialog>()
-            // The policy asks whether the realm list is standing over this screen; in a harness
-            // that never raises one the answer is a default `Realms` — always "no".
             .init_resource::<crate::realm_select::Realms>()
-            // Literal, not Default: `Realmlist::default()` reads `$WOW_HOST`, and every probe
-            // recipe in this repo exports it — a suite run from such a shell would otherwise
-            // assert against whatever that shell happened to be pointing at.
+            // Not `Realmlist::default()`, which reads `$WOW_HOST` from the shell.
             .insert_resource(crate::realmlist::Realmlist::unpinned(
                 crate::realmlist::DEFAULT_REALMLIST,
             ))
@@ -1213,20 +999,12 @@ mod tests {
             .add_message::<DisconnectedMessage>()
             .add_systems(Update, drive_policy);
         app.world_mut().resource_mut::<LoginIntent>().env_read = true;
-        // The receiver is RETURNED rather than leaked: a dropped one turns every submit into an
-        // `Err` and hides a policy that sent one, and holding it is also what lets a test read
-        // back the request that went out.
+        // Returned, not dropped: a dropped receiver turns every submit into an `Err`.
         (app, rx)
     }
 
-    /// **A lost session does not log itself back in** (decision 1262).
-    ///
-    /// This is the whole of the displacement report: log into the same account from the reference
-    /// client, vmangos kicks us with a bare socket close, and 0065's paced resubmit — which cannot
-    /// see *why* the socket died, because nothing on the wire says — re-authenticated three seconds
-    /// later and kicked the client that had just displaced us. The account ping-ponged. The
-    /// reference's `GlueParent.lua` answers `DISCONNECTED_FROM_SERVER` with the login screen and a
-    /// one-button dialog, and retries nothing.
+    /// A lost session does not log itself back in: a displaced client's resubmit would kick the
+    /// client that displaced it. `GlueParent.lua` retries nothing.
     #[test]
     fn a_lost_session_clears_the_credentials_and_shows_the_dialog() {
         let (mut app, _requests) = policy_app();
@@ -1248,14 +1026,12 @@ mod tests {
         assert!(intent.retry_at.is_none(), "and nothing is scheduled");
         let dialog = app.world().resource::<GlueDialog>();
         assert_eq!(dialog.kind, Some(DialogKind::Error));
-        // The fallback literal: this App has no GlueStrings, and the table's own row is
-        // `DISCONNECTED = "Disconnected from server";` (GlueStrings.lua) — the same words.
+        // The fallback, the same words as `GlueStrings.lua`'s `DISCONNECTED`.
         assert_eq!(dialog.text, "Disconnected from server");
     }
 
-    /// A **clean logout's** teardown rides the same message and must keep its silent relist: the
-    /// IO thread returns to the pre-logon park, and the roster it comes back with IS the character
-    /// select the player asked for. Breaking this would strand `/logout` on the login screen.
+    /// A logout rides the same message and keeps its silent relist; its roster is the character
+    /// select the player asked for.
     #[test]
     fn a_logout_teardown_still_relists_at_once() {
         let (mut app, _requests) = policy_app();
@@ -1284,14 +1060,8 @@ mod tests {
         );
     }
 
-    /// **A roster does not take a refusal off the screen.**
-    ///
-    /// [`to_select_on_roster`] closes the dialog because a roster is the answer to this screen's
-    /// "Connecting…" — but since a refused *character* login raises an `Error` on the SELECT
-    /// screen, and its own relist produces a roster a second later, an unscoped close would wipe
-    /// the message before it could be read. That is the original bug (a refusal nobody sees) one
-    /// layer up, and nothing else would catch it: the build is green either way and the window is
-    /// a second long.
+    /// A refused character login's relist brings a roster a second later; it must not close
+    /// the refusal's `Error`.
     #[test]
     fn an_arriving_roster_closes_the_connecting_dialog_but_not_an_error() {
         let mut app = App::new();
@@ -1315,7 +1085,7 @@ mod tests {
         assert_eq!(dialog.kind, Some(DialogKind::Error));
         assert_eq!(dialog.text, "World server is down");
 
-        // …and the connecting dialog the roster IS the answer to still closes.
+        // The connecting dialog still closes.
         app.world_mut()
             .resource_mut::<GlueDialog>()
             .open_status("Connecting");
@@ -1327,8 +1097,7 @@ mod tests {
         assert!(app.world().resource::<GlueDialog>().kind.is_none());
     }
 
-    /// An **unattended** run keeps 0065's paced reconnect on a lost session — the verdict rides
-    /// the message, so the policy honours it without re-reading the environment.
+    /// An unattended run still reconnects on a lost session; the verdict rides the message.
     #[test]
     fn an_unattended_run_still_reconnects_on_its_own() {
         let (mut app, _requests) = policy_app();
@@ -1351,10 +1120,7 @@ mod tests {
         assert!(app.world().resource::<GlueDialog>().kind.is_none());
     }
 
-    /// **The submitted attempt dials the configured realmlist** (decision 1667) — the whole
-    /// point of the setting. Before this, the address was latched out of `$WOW_HOST` once at
-    /// process start and the request had no say in it; now the request carries it, so a change
-    /// made between attempts is the one the next attempt uses.
+    /// Each attempt dials the realmlist current at its submit.
     #[test]
     fn a_submitted_attempt_carries_the_configured_realmlist() {
         let (mut app, requests) = policy_app();
@@ -1362,7 +1128,6 @@ mod tests {
             .insert_resource(crate::realmlist::Realmlist::unpinned(
                 "logon.example.org:3725",
             ));
-        // Credentials pending with the retry due: the policy's silent submit tick.
         {
             let mut intent = app.world_mut().resource_mut::<LoginIntent>();
             intent.creds = Some(("player".into(), "secret".into()));
@@ -1377,7 +1142,6 @@ mod tests {
             "the attempt dials what the realmlist says, not a value latched at spawn",
         );
 
-        // And a change between attempts is picked up by the next one, with no relaunch.
         app.world_mut()
             .insert_resource(crate::realmlist::Realmlist::unpinned(
                 "elsewhere.example.org",
@@ -1394,10 +1158,7 @@ mod tests {
         );
     }
 
-    /// The dialog's Okay: what the box holds becomes the session's address, including the
-    /// `realmlist.wtf` line a player pastes off a server's setup page. No VM here, so the
-    /// persistence leg is the `None` arm — the session value is what this asserts, and it is the
-    /// half the next login attempt reads.
+    /// A pasted `realmlist.wtf` line becomes the session's address; with no VM, nothing persists.
     #[test]
     fn the_realmlist_dialog_takes_what_was_typed() {
         let mut realmlist = crate::realmlist::Realmlist::unpinned("localhost");
@@ -1409,8 +1170,6 @@ mod tests {
         assert_eq!(realmlist.address(), "logon.example.org");
     }
 
-    /// …and a box holding something that is not an address changes nothing and reports it, so the
-    /// caller keeps the dialog open over the text as typed rather than closing on a silent no-op.
     #[test]
     fn a_bad_address_leaves_the_realmlist_alone() {
         let mut realmlist = crate::realmlist::Realmlist::unpinned("localhost");
@@ -1423,12 +1182,7 @@ mod tests {
         }
     }
 
-    /// **The seam the move opened** (2084): the widget publishes a press, this screen answers it.
-    ///
-    /// `accept_realmlist` and the cancel bookkeeping are each covered on their own above, and the
-    /// widget's keys and kinds are covered in `crate::glue::dialog` — but nothing covered the
-    /// *wiring* between them, which is the one thing the move could break silently. A dialog whose
-    /// press reaches nobody looks exactly like a dialog that works until you click it.
+    /// The wiring from the widget's published press to this screen's answer.
     #[test]
     fn a_published_press_reaches_the_login_screens_answer() {
         use crate::glue::dialog::GlueDialogAnswer;
@@ -1444,8 +1198,7 @@ mod tests {
             .add_message::<GlueDialogAnswer>()
             .add_systems(Update, answer_dialog);
 
-        // The status dialog's Cancel: the attempt is abandoned and the credentials forgotten, so
-        // nothing resubmits behind the player's back.
+        // The status dialog's Cancel abandons the attempt and forgets the credentials.
         app.world_mut().resource_mut::<LoginIntent>().creds =
             Some(("player".into(), "secret".into()));
         app.world_mut().resource_mut::<LoginIntent>().in_flight = true;
@@ -1496,8 +1249,7 @@ mod tests {
         );
         assert!(app.world().resource::<GlueDialog>().kind.is_none());
 
-        // …and its Okay over a bad address keeps the dialog up, with the text replaced — the one
-        // press in the whole widget that does not end its own dialog.
+        // Okay over a bad address keeps the dialog up with the prompt replaced.
         app.world_mut()
             .resource_mut::<GlueDialog>()
             .open_realmlist("Address of realm list server", "logon.example.org");
@@ -1523,8 +1275,7 @@ mod tests {
         );
     }
 
-    /// Opening the editor seats the current address in the box, selected whole — so typing a new
-    /// server replaces the old one instead of appending to it.
+    /// The editor opens on the current address, selected whole.
     #[test]
     fn opening_the_editor_preselects_the_current_address() {
         let mut dialog = GlueDialog::default();
@@ -1539,17 +1290,15 @@ mod tests {
         assert!(!dialog.edit.password, "an address is not a secret");
     }
 
-    /// Did this update ask the app to quit?
     fn exited(app: &mut App, cursor: &mut bevy::ecs::message::MessageCursor<AppExit>) -> bool {
         let msgs = app.world().resource::<Messages<AppExit>>();
         cursor.read(msgs).next().is_some()
     }
 
-    /// Drive one refusal through the policy and report whether it killed the process.
+    /// Drive one refusal through the policy; whether it exited.
     fn refusal_exits(typed: bool) -> bool {
         let (mut app, _requests) = policy_app();
         let mut cursor = bevy::ecs::message::MessageCursor::<AppExit>::default();
-        // Drain whatever the first update writes before the message under test.
         app.update();
         let _ = exited(&mut app, &mut cursor);
         app.world_mut().resource_mut::<LoginIntent>().announced = typed;
@@ -1568,25 +1317,17 @@ mod tests {
         exited(&mut app, &mut cursor)
     }
 
-    /// **A typo must not kill the client**, and **env credentials alone must not either.**
-    ///
-    /// The reported crash: `login: FATAL — refused (code 0x04) … exiting`, on a password typed at
-    /// the screen, because `$WOW_CHAR` was set and the old predicate read any env credential as
-    /// "a harness". Two answers, both here, because they close the hole from both ends: whether
-    /// an *attempt* was typed is direct evidence (`announced`, set by the screen's own submit and
-    /// by nothing else), and whether the *run* is driverless is a declaration the run makes
-    /// (`WOW_UNATTENDED`, decision 1769) — never an inference off credentials the director's own
-    /// launch line carries.
+    /// Neither a typed refusal nor env credentials alone end the run: only an untyped attempt in
+    /// a run that declares `WOW_UNATTENDED` does.
     #[test]
     fn a_typed_password_refusal_never_exits() {
         let _lock = crate::local_state::test_env::ENV_LOCK.lock();
         let _smoke = crate::local_state::test_env::EnvGuard::unset("WOW_LOGIN_SMOKE");
 
-        // 1 · The director's actual launch line, verbatim from `.cargo/config.toml`'s example.
-        //     Nothing here says anybody is absent, so nothing may end the run — typed or not.
+        // A person's own launch line (as `.cargo/config.toml`'s example), declaring nobody absent.
         let _user = crate::local_state::test_env::EnvGuard::set("WOW_USER", "player");
         let _pass = crate::local_state::test_env::EnvGuard::set("WOW_PASS", "secret");
-        let _char = crate::local_state::test_env::EnvGuard::set("WOW_CHAR", "One");
+        let _char = crate::local_state::test_env::EnvGuard::set("WOW_CHAR", "Hero");
         let _decl = crate::local_state::test_env::EnvGuard::unset("WOW_UNATTENDED");
         let _cap = crate::local_state::test_env::EnvGuard::unset("WOW_CAPTURE");
         let _rig = crate::local_state::test_env::EnvGuard::unset("WOW_RIG");
@@ -1599,7 +1340,7 @@ mod tests {
             "an env-credentialled run with a person in it shows the dialog, it does not exit",
         );
 
-        // 2 · A run that declares itself driverless keeps decision 1371's leg guarantee.
+        // A run that declares itself driverless.
         let _decl = crate::local_state::test_env::EnvGuard::set("WOW_UNATTENDED", "1");
         assert!(
             refusal_exits(false),
@@ -1611,11 +1352,9 @@ mod tests {
         );
     }
 
-    /// **The dead web address comes off** (director's call) — at the clause, so the sentence in
-    /// front of it survives.
     #[test]
     fn a_dead_url_is_cut_at_its_clause() {
-        // The reported one, verbatim from `GlueStrings.lua`.
+        // `LOGIN_UNKNOWN_ACCOUNT`, verbatim from `GlueStrings.lua`.
         assert_eq!(
             without_dead_url(
                 "The information you have entered is not valid.  Please check the spelling of the \
@@ -1626,7 +1365,6 @@ mod tests {
              account name and password.  If you need help in retrieving a lost or stolen password \
              and account.",
         );
-        // A whole trailing sentence goes when the address is what the sentence is for.
         assert_eq!(
             without_dead_url(
                 "This World of Warcraft account has been closed and is no longer available for \
@@ -1635,7 +1373,7 @@ mod tests {
             ),
             "This World of Warcraft account has been closed and is no longer available for use.",
         );
-        // Nothing to cut: left exactly alone, and borrowed rather than rebuilt.
+        // Nothing to cut: borrowed, not rebuilt.
         let clean = "You have used up your prepaid time for this account.";
         assert!(matches!(
             without_dead_url(clean),
@@ -1644,20 +1382,17 @@ mod tests {
         assert_eq!(without_dead_url(clean), clean);
     }
 
-    /// The guard that stops the trim eating a string whose address has no clause in front of it —
-    /// `AUTH_BANNED`, where the URL sits behind a dash. Better untrimmed than truncated to nothing.
+    /// `AUTH_BANNED`'s address sits behind a dash, with no clause to cut at.
     #[test]
     fn an_address_with_no_clause_boundary_is_left_alone() {
         let banned = "This account has been banned for violating the Terms of Use Agreement - \
                       www.worldofwarcraft.com/termsofuse.shtml. Please contact our GM department.";
         assert_eq!(without_dead_url(banned), banned);
-        // …and the degenerate case cannot produce an empty dialog.
+        // The degenerate case cannot produce an empty dialog.
         assert_eq!(without_dead_url("www.example.com"), "www.example.com");
         assert_eq!(without_dead_url(". www.example.com"), ". www.example.com");
     }
 
-    /// The Login press's two guards, in the reference's order: a wholly empty form asks for the
-    /// account name first.
     #[test]
     fn the_login_press_asks_for_the_account_before_the_password() {
         let mut form = LoginForm::default();
@@ -1666,14 +1401,11 @@ mod tests {
         assert_eq!(login_press(&form), LoginPress::NeedPassword);
         form.password.set_text("secret");
         assert_eq!(login_press(&form), LoginPress::Submit);
-        // And a password-only form still asks for the account, not the password.
         let mut only_pass = LoginForm::default();
         only_pass.password.set_text("secret");
         assert_eq!(login_press(&only_pass), LoginPress::NeedAccount);
     }
 
-    /// **Focusing a box selects it** (director's call, diverging from the reference) — and leaves
-    /// the caret solid, which is what the `reset_blink` calls this replaced were for.
     #[test]
     fn focusing_a_box_selects_all_of_it() {
         let mut form = LoginForm::default();
@@ -1685,10 +1417,7 @@ mod tests {
         assert_eq!(form.account.selected_text().as_deref(), Some("remembered"));
         assert!(form.account.caret_shown, "a fresh focus starts solid");
 
-        // TAB to the other box selects that one whole too. Checked as a RANGE, not as text: a
-        // password box's `selected_text` hands back the `*` mask, because the real characters are
-        // never rendered or copied (decision 0704's box law) — which is the correct answer and
-        // exactly why the assertion cannot ask for them.
+        // Checked as a range: a password box's `selected_text` returns the `*` mask.
         form.focus(Field::Password);
         assert_eq!(
             (form.password.sel_start, form.password.sel_end),
@@ -1696,15 +1425,12 @@ mod tests {
             "the whole password is selected even though it cannot be read back",
         );
 
-        // **And the box we left is no longer selected.** The other half of the divergence: with
-        // the selection standing for "the keyboard is here", exactly one box can carry one.
         assert_eq!(
             form.account.selected_text(),
             None,
             "the box that lost the keyboard keeps no highlight",
         );
 
-        // Typing then replaces rather than appends — the point of the divergence.
         form.focused().insert("x");
         assert_eq!(form.password.text, "x");
 
@@ -1716,24 +1442,17 @@ mod tests {
         );
     }
 
-    /// The code→string map quotes the client's own strings for the vmangos-verified rows.
-    /// The realmd map, against the client's table (`0x5b2c90` → key table `0x836b78`).
-    ///
-    /// Every row of this changed in decision 1679: the codes were always right and the string
-    /// FAMILY was always wrong, so each of these used to answer with the terse `AUTH_*` twin of
-    /// the string it now gives.
+    /// The realmd map, against the client's table (`0x5b2c90`, key table `0x836b78`).
     #[test]
     fn fail_text_maps_the_verified_codes() {
-        let strings = GlueStrings::default(); // empty table → the fallback literals
+        let strings = GlueStrings::default(); // empty table: the fallback literals
         let logon = |b| fail_text(&strings, Some(LoginRefusal::Logon(b)), None);
 
-        // 0x04 and 0x05 share one jump-table arm — the client cannot say "wrong password", and
-        // this is the string a player actually gets for a typo.
+        // 0x04 and 0x05 share one jump-table arm.
         assert!(logon(0x04).starts_with("The information you have entered is not valid."));
         assert_eq!(logon(0x05), logon(0x04), "one arm, byte-identical");
         assert!(logon(0x04).contains("account name and password"));
 
-        // The four "no usable connection" codes share `LOGIN_FAILED` with a bare transport failure.
         assert_eq!(fail_text(&strings, None, None), "Unable to connect");
         for code in [0x01, 0x02, 0x0B, 0x0D] {
             assert_eq!(logon(code), "Unable to connect", "code {code:#04x}");
@@ -1745,17 +1464,14 @@ mod tests {
         assert!(logon(0x0C).contains("temporarily suspended"));
         assert!(logon(0x0F).contains("parental controls"));
 
-        // Past 0x0F the byte-index table saturates onto the disconnect arm — so an unknown code
-        // reads as a disconnect, not as an authentication message.
+        // Past 0x0F the byte-index table saturates onto the disconnect arm.
         for code in [0x10, 0x11, 0x12, 0xEE] {
             assert_eq!(logon(code), "Disconnected from server", "code {code:#04x}");
         }
     }
 
-    /// **The two result enums are different enums**, and the same byte must not mean the same
-    /// thing in both. 0x0C is `AUTH_LOGON_FAILED_SUSPENDED` to realmd and `AUTH_OK` to the world
-    /// server; 0x05 is a bad password to realmd and nothing at all to the world server. A single
-    /// `Option<u8>` could not tell them apart, which is why `LoginRefusal` exists.
+    /// The realmd and world result enums share bytes with different meanings: 0x0C is
+    /// `AUTH_LOGON_FAILED_SUSPENDED` to realmd and `AUTH_OK` to the world server.
     #[test]
     fn the_two_auth_enums_do_not_share_a_byte() {
         use benilla_protocol::messages as m;
@@ -1763,13 +1479,11 @@ mod tests {
         let logon = |b| fail_text(&strings, Some(LoginRefusal::Logon(b)), None);
         let world = |b| fail_text(&strings, Some(LoginRefusal::World(b)), None);
 
-        // 0x0C: "suspended" to realmd, and to the world server it is AUTH_OK — success, which
-        // never reaches a refusal string at all.
         assert!(logon(0x0C).contains("temporarily suspended"));
         assert_eq!(world(m::AUTH_BILLING_ERROR), "Billing system error");
         assert_ne!(logon(0x0C), world(0x0C));
 
-        // Every world row is the client's own dispatch (`0x5aa960`), transcribed.
+        // The client's world dispatch (`0x5aa960`).
         assert_eq!(world(m::AUTH_INCORRECT_PASSWORD), "Incorrect Password");
         assert_eq!(world(m::AUTH_SESSION_EXPIRED), "Session Expired");
         assert_eq!(world(m::AUTH_SERVER_SHUTTING_DOWN), "Server Shutting Down");
@@ -1778,17 +1492,15 @@ mod tests {
             world(m::AUTH_UNAVAILABLE),
             "System unavailable - Please try again later"
         );
-        // The five codes the reference's URL dialog keys on — reachable only from this enum.
+        // Rows of the reference's `OKAY_WITH_URL` table.
         assert!(world(m::AUTH_BANNED).contains("banned"));
         assert!(world(m::AUTH_SUSPENDED).contains("temporarily suspended"));
         assert!(world(m::AUTH_PARENTAL_CONTROL).contains("parental controls"));
-        // A code this client does not know still lands on the authored catch-all.
+        // An unknown code lands on the catch-all.
         assert_eq!(world(0xEE), "Authentication failed");
     }
 
-    /// **The report that prompted this** — a dead local server read as a bad address, twice, because
-    /// "Unable to connect" cannot tell the two apart. Each dial verdict now gets the reference's own
-    /// string for that exact condition, with the address under it so there is nothing left to guess.
+    /// Each dial verdict gets the reference's string for its condition, with the address under it.
     #[test]
     fn a_dial_failure_says_which_failure_it_was() {
         let strings = GlueStrings::default();
@@ -1810,16 +1522,14 @@ mod tests {
             "Invalid Login Server\nlogon.nonesuch.example:3724",
             "the name resolved to nothing — this one IS the address",
         );
-        // A refusal still wins its own authored string; the dial verdict only speaks for the dial.
+        // A refusal keeps its own string.
         assert!(fail_text(&strings, Some(LoginRefusal::Logon(0x05)), None)
             .starts_with("The information you have entered is not valid."));
     }
 
-    /// Save → load → clear round-trips through the dot-file (the ref's Get/SetSavedAccountName).
+    /// Save, load and clear round-trip through the file (`Get`/`SetSavedAccountName`).
     #[test]
     fn saved_account_round_trips() {
-        // A FILE, not a folder: since decision 1181 these two take the resolved path
-        // (`local_state::saved_account_path`) rather than a base to join `account` onto.
         let dir = std::env::temp_dir().join(format!(
             "benilla-login-test-{}-{:?}",
             std::process::id(),
@@ -1828,29 +1538,22 @@ mod tests {
         let path = dir.join("account");
         let _ = std::fs::remove_dir_all(&dir);
         assert_eq!(load_saved_account_from(&path), "");
-        // The write creates the folder on its way, exactly as a first run must.
-        save_account_to(&path, "ONE");
-        assert_eq!(load_saved_account_from(&path), "ONE");
+        // The write creates the folder, as a first run must.
+        save_account_to(&path, "PLAYER");
+        assert_eq!(load_saved_account_from(&path), "PLAYER");
         save_account_to(&path, "");
         assert_eq!(load_saved_account_from(&path), "");
         assert!(!path.exists(), "clearing the name removes the file");
         let _ = std::fs::remove_dir_all(&dir);
     }
 
-    /// The clock system toggles the FOCUSED box on the shared 0.5 s period and leaves the other
-    /// one alone. It guards the system's behaviour, not its registration (that is the one
-    /// `tick_login_caret` line in [`LoginPlugin`], and a login screen with no clock is
-    /// indistinguishable from one whose caret is in its ON half forever — `caret_shown` defaults
-    /// to `true`, which is exactly how this went unnoticed).
+    /// The focused box blinks on the shared 0.5 s period; the other is left alone.
     #[test]
     fn the_focused_box_caret_blinks() {
         let mut app = App::new();
         app.init_resource::<Time>()
             .init_resource::<LoginForm>()
             .init_resource::<GlueDialog>()
-            // The clock now asks which box owns the focus (1667): a dialog with an edit box takes
-            // it. No dialog is open here, so the form's box keeps it — which is the case this
-            // asserts.
             .add_systems(Update, tick_login_caret);
 
         let past_the_period = |app: &mut App| {
@@ -1861,11 +1564,10 @@ mod tests {
             app.world().resource::<LoginForm>().account.caret_shown
         };
 
-        // Account has the focus by default; one period each way is on → off → on.
+        // Account has the focus by default.
         assert!(!past_the_period(&mut app), "the first period turns it off");
         assert!(past_the_period(&mut app), "the second turns it back on");
-        // The box that doesn't own the keyboard never accumulates, so switching focus to it lands
-        // on a solid caret rather than wherever its own clock would have drifted to.
+        // The unfocused box never accumulates, so focusing it lands on a solid caret.
         assert_eq!(
             app.world().resource::<LoginForm>().password.blink_accum,
             0.0
diff --git a/crates/benilla-app/src/login/queue.rs b/crates/benilla-app/src/login/queue.rs
index 812ef297..32b1a8ae 100644
--- a/crates/benilla-app/src/login/queue.rs
+++ b/crates/benilla-app/src/login/queue.rs
@@ -1,33 +1,20 @@
-//! **The login queue** — our place in line for a full realm, and the reference's own estimate of
-//! how long it will take (decision 1681).
+//! The login queue: our place in line for a full realm and the reference's estimate of the wait.
+//! `SMSG_AUTH_RESPONSE(AUTH_WAIT_QUEUE)` carries a position, is re-sent as the line moves, and
+//! ends with `AUTH_OK`; it is a wait, not a refusal.
 //!
-//! The realm server answers a login to a full realm with `SMSG_AUTH_RESPONSE(AUTH_WAIT_QUEUE)` and
-//! a position, re-sending as the line moves and ending with `AUTH_OK` when we are admitted. It is
-//! a **wait, not an outcome** — which is what benilla got wrong until this module: the world
-//! handshake treated the code as a refusal, so a busy server was simply unreachable.
-//!
-//! Everything here is the reference's arithmetic, transcribed (`CGlueMgr::UpdateQueuePosition`
-//! `0x46ae50`). It is worth transcribing rather than reinventing because the estimate is visibly
-//! wrong in a *specific* way — it divides before it multiplies, so it truncates per-person seconds
-//! before scaling them by the whole queue — and a "better" estimator would disagree with the
-//! reference by minutes on a long queue.
-//!
-//! Three things about it are deliberately NOT reproduced, each named at its site: the unguarded
-//! 32-bit overflow, the stale-position redisplay on a truncated packet ([`benilla_protocol`]'s
-//! parser), and the leading blank line the reference's composite prints.
+//! The arithmetic is the reference's (`CGlueMgr::UpdateQueuePosition`, `0x46ae50`), including
+//! its divide-before-multiply truncation. Three reference defects are not reproduced: the 32-bit
+//! overflow, the leading blank line and the stale-position redisplay on a truncated packet
+//! ([`benilla_protocol`]'s parser).
 
-/// How many `(tick, position)` samples the estimate is formed from — the reference's ring, exactly
-/// (`0xb41cf8..0xb41d14` ticks, `0xb41d18..0xb41d34` positions).
+/// The reference's ring of `(tick, position)` samples (`0xb41cf8..0xb41d14` ticks,
+/// `0xb41d18..0xb41d34` positions).
 const SAMPLES: usize = 8;
 
-/// A minute, in the milliseconds everything here counts in.
 const MINUTE_MS: i64 = 60_000;
 
 /// The reference's queue-estimate ring: `[0]` is the newest sample, `[SAMPLES - 1]` the oldest.
-///
-/// Sampled **once per queue packet, on no timer at all** — so the estimate's whole notion of time
-/// is the server's send cadence. A `tick[SAMPLES - 1]` still zero means fewer than eight packets
-/// have arrived and no estimate exists yet.
+/// Sampled once per queue packet, on no timer, so its only clock is the server's send cadence.
 #[derive(Debug, Default, Clone)]
 pub(crate) struct QueueEstimate {
     tick_ms: [u32; SAMPLES],
@@ -35,11 +22,8 @@ pub(crate) struct QueueEstimate {
 }
 
 impl QueueEstimate {
-    /// Fold one queue packet in at `now_ms`.
-    ///
-    /// **A position that has not moved does not shift the ring** once it is full — it only restamps
-    /// the newest tick. That is the reference's own guard, and it is what stops a chatty server
-    /// that keeps repeating the same position from flushing the history the estimate is made of.
+    /// Fold one queue packet in at `now_ms`. Once the ring is full, a repeated position only
+    /// restamps the newest tick (the reference's guard), so a repeating server keeps the history.
     pub(crate) fn sample(&mut self, position: u32, now_ms: u32) {
         let repeat = position == self.position[0] && self.tick_ms[SAMPLES - 1] != 0;
         if !repeat {
@@ -50,26 +34,16 @@ impl QueueEstimate {
         self.tick_ms[0] = now_ms;
     }
 
-    /// Our latest known position, or `None` before any packet.
     pub(crate) fn position(&self) -> Option<u32> {
         (self.tick_ms[0] != 0).then_some(self.position[0])
     }
 
-    /// The estimated wait in milliseconds, or `None` while one cannot be formed.
+    /// The estimated wait in ms: `floor((now - oldest_tick) / (oldest_pos - newest_pos)) *
+    /// newest_pos`, dividing first (`idiv` at `0x46aed3` before `imul` at `0x46aed5`). None
+    /// until the ring is full and the queue has moved forward, as in the reference.
     ///
-    /// `floor((now - oldest_tick) / (oldest_pos - newest_pos)) * newest_pos` — **divide first**,
-    /// truncating, then scale. The reference emits `idiv` at `0x46aed3` and `imul` at `0x46aed5`,
-    /// in that order, and the order is load-bearing: at 30 s per person and 100 people ahead,
-    /// dividing first gives the same answer, but at 90 s per two people it discards the remainder
-    /// once for every person in the queue rather than once overall.
-    ///
-    /// Two preconditions, both the reference's: the ring must be full, and the queue must have
-    /// **moved forward** (the oldest position strictly greater than the newest). A queue that has
-    /// not moved, or has moved backwards, yields nothing rather than a negative or infinite wait.
-    ///
-    /// The arithmetic is done in `i64` where the reference uses 32-bit signed and does not guard
-    /// the multiply. That overflow is a defect, not a behaviour: reproducing it would put an
-    /// absurd countdown on screen for a queue long enough to trigger it.
+    /// Computed in `i64`: the reference's 32-bit multiply overflows unguarded, which on a long
+    /// queue shows an absurd countdown.
     pub(crate) fn estimate_ms(&self, now_ms: u32) -> Option<i64> {
         if self.tick_ms[SAMPLES - 1] == 0 {
             return None; // fewer than SAMPLES packets so far
@@ -83,25 +57,15 @@ impl QueueEstimate {
         Some(per_place * i64::from(self.position[0]))
     }
 
-    /// What the dialog says right now.
+    /// The dialog text. The reference reads `realm` from the `realmName` CVar it wrote on the way
+    /// in, so the `_NAME` variants are the ones that render in practice.
     ///
-    /// `realm` is the realm's name when we know it — the reference reads the `realmName` CVar it
-    /// wrote on the way in, and since that is the only door into the queued state, the **`_NAME`
-    /// variants are what its players actually saw**; the plain "Realm is Full" forms need an empty
-    /// name and effectively never render.
+    /// The shown wait, `tick[0] + estimate - now`, is not a countdown: `estimate` grows with
+    /// `now`, so a silent queue's figure climbs (slope `places_left / places_moved - 1`) until
+    /// the next packet, as in the reference.
     ///
-    /// What is displayed is `tick[0] + estimate - now`. That reads like a countdown and **is not
-    /// one**: `estimate` is itself recomputed from `now`, against a divisor fixed by the last eight
-    /// packets, so a silent queue's figure *climbs* — its slope is `places_left / places_moved - 1`,
-    /// positive whenever more people are ahead of you than the ring saw move. The next packet
-    /// re-anchors it. Verified, reproduced deliberately, and pinned by
-    /// `a_silent_queue_inflates_its_own_estimate`: a client that counted down smoothly here would
-    /// disagree with the reference by minutes.
-    ///
-    /// **One stated divergence.** The reference composes this as `"%s\n%s"` with an empty first
-    /// half — the status leg it means to print is suppressed by a guard sixteen instructions
-    /// earlier — so its dialog carries a leading blank line for two of the three states and not the
-    /// third. That is a defect of an empty string, not a layout, and it is not reproduced.
+    /// The reference composes `"%s\n%s"` with an always-empty first half, a leading blank line in
+    /// two of three states; that blank line is not reproduced.
     pub(crate) fn text(
         &self,
         now_ms: u32,
@@ -111,7 +75,6 @@ impl QueueEstimate {
         let position = self.position().unwrap_or(0);
         let named = realm.filter(|r| !r.is_empty());
 
-        // `remaining` is what is left of the estimate that was current when the last packet landed.
         let remaining = self.estimate_ms(now_ms).and_then(|est| {
             (est > 0).then(|| i64::from(self.tick_ms[0]) + est - i64::from(now_ms))
         });
@@ -132,7 +95,6 @@ impl QueueEstimate {
         };
         let (key, fallback) = match named {
             Some(_) => (key, fallback),
-            // The nameless twin of whichever leg we picked — same text without the leading `%s`.
             None => match remaining {
                 None => (
                     "QUEUE_TIME_LEFT_UNKNOWN",
@@ -166,11 +128,10 @@ mod tests {
     use super::*;
     use crate::glue_strings::GlueStrings;
 
-    /// Feed packets `step_ms` apart. Returns the ring and **the instant the last one landed**,
-    /// which is the natural moment to read the estimate at.
+    /// Feed packets `step_ms` apart; returns the ring and the instant the last one landed.
     fn ring_of(places: &[u32], step_ms: u32) -> (QueueEstimate, u32) {
         let mut q = QueueEstimate::default();
-        let mut now = 1_000; // never 0 — that is the "no sample yet" sentinel
+        let mut now = 1_000; // never 0, the "no sample yet" sentinel
         let mut last = now;
         for &p in places {
             q.sample(p, now);
@@ -180,7 +141,7 @@ mod tests {
         (q, last)
     }
 
-    /// No estimate until the ring is full — the reference's `tick[7] != 0` precondition.
+    /// The reference's `tick[7] != 0` precondition.
     #[test]
     fn an_estimate_needs_eight_samples() {
         for n in 1..SAMPLES {
@@ -192,7 +153,6 @@ mod tests {
         assert!(q.estimate_ms(last).is_some(), "eight is");
     }
 
-    /// A queue that has not moved yields nothing rather than an infinite wait.
     #[test]
     fn a_stalled_queue_has_no_estimate() {
         let (q, last) = ring_of(&[50; SAMPLES], 1_000);
@@ -203,11 +163,8 @@ mod tests {
         );
     }
 
-    /// **A repeat stops shifting the ring once it is full** — the reference's own guard, and what
-    /// stops a server restating one position from flushing the history the estimate is made of.
-    ///
-    /// The guard is `newPos == pos[0] && tick[7] != 0`, so while the ring is still filling a repeat
-    /// DOES shift; only once the oldest slot is stamped does a repeat become a restamp.
+    /// The reference's guard is `newPos == pos[0] && tick[7] != 0`: a repeat still shifts while
+    /// the ring fills.
     #[test]
     fn a_repeated_position_restamps_rather_than_shifting() {
         let (mut q, last) = ring_of(&[50; SAMPLES], 1_000);
@@ -226,17 +183,14 @@ mod tests {
         assert_eq!(q.tick_ms[0], last + 5_000, "but it does restamp the newest");
     }
 
-    /// Seven moves of one place, a second apart, read as the eighth lands: 7 000 ms over 7 places
-    /// is 1 000 ms each, and 93 are still ahead → 93 000 ms.
+    /// 7 000 ms over 7 places is 1 000 ms each, times 93 still ahead.
     #[test]
     fn the_estimate_is_per_place_times_places_left() {
         let (q, last) = ring_of(&[100, 99, 98, 97, 96, 95, 94, 93], 1_000);
         assert_eq!(q.estimate_ms(last), Some(93_000));
     }
 
-    /// **Divide before multiply**, and a fixture where the two orders actually disagree: 7 places
-    /// over 10 000 ms is 1 428 ms each once truncated, times 93. Multiplying first would keep the
-    /// remainder and land on a different minute at the boundary.
+    /// A fixture where the two orders disagree: 10 000 ms over 7 places truncates to 1 428 ms.
     #[test]
     fn the_estimate_divides_before_it_multiplies() {
         let mut q = QueueEstimate::default();
@@ -253,16 +207,7 @@ mod tests {
         );
     }
 
-    /// **Waiting makes the estimate go UP, not down** — surprising, verified, and the reference's.
-    ///
-    /// The estimate is recomputed every frame from a *growing* elapsed against a divisor fixed by
-    /// the last eight packets, so while the queue is silent the per-place figure inflates. What is
-    /// displayed is `tick[0] + estimate - now`, whose slope is `places_left / places_moved - 1` —
-    /// positive whenever more people are ahead of you than the ring saw move, which is the normal
-    /// case. So a stalled queue's "estimated time" climbs until the next packet re-anchors it.
-    ///
-    /// Not reproduced as a *bug fix*: this is what the reference puts on screen, and a client that
-    /// counted down smoothly here would disagree with it by minutes.
+    /// Waiting raises the estimate, as in the reference: elapsed grows against a fixed divisor.
     #[test]
     fn a_silent_queue_inflates_its_own_estimate() {
         let (q, last) = ring_of(&[100, 99, 98, 97, 96, 95, 94, 93], 1_000);
@@ -274,7 +219,6 @@ mod tests {
         );
     }
 
-    /// The display legs: Calculating before the ring fills, then a minutes figure.
     #[test]
     fn the_text_walks_calculating_then_minutes() {
         let strings = GlueStrings::default();
@@ -294,8 +238,7 @@ mod tests {
         assert!(!minutes.contains("Calculating"), "{minutes}");
     }
 
-    /// The `< 1 minute` leg, which needs the whole remaining wait under a minute — i.e. few enough
-    /// people ahead that the inflation above cannot carry it over the threshold.
+    /// Few enough ahead that the inflation cannot carry the wait past a minute.
     #[test]
     fn a_short_wait_reads_under_a_minute() {
         let strings = GlueStrings::default();
@@ -305,8 +248,6 @@ mod tests {
         assert!(text.contains("< 1 minute"), "{text}");
     }
 
-    /// The nameless twin renders when no realm name is known — and neither form leaves a
-    /// placeholder behind.
     #[test]
     fn a_nameless_realm_uses_the_plain_form() {
         let strings = GlueStrings::default();
diff --git a/crates/benilla-app/src/login/screen.rs b/crates/benilla-app/src/login/screen.rs
index bfd1a970..2e48894e 100644
--- a/crates/benilla-app/src/login/screen.rs
+++ b/crates/benilla-app/src/login/screen.rs
@@ -1,19 +1,9 @@
-//! The login screen's **layout** — the reference `AccountLogin.xml` arrangement rebuilt in Bevy
-//! UI (decision 0539), full-bleed and scaled to the window (`height / 768`, the glue engine's
-//! virtual screen).
+//! The login screen's layout: the reference `AccountLogin.xml` arrangement in Bevy UI, scaled by
+//! `height / 768` (the glue virtual screen), over the `UI_MainMenu` scene. Each control carries
+//! its `AccountLogin.xml` size and anchor at its spawn site.
 //!
-//! Bottom layer: the glue booth's fullscreen render (the `UI_MainMenu` scene — the burning gate,
-//! its authored fog/fires live). Over it: the WoW logo (256×128 at TOPLEFT (3,−7)), the account
-//! box (160×37 at BOTTOM (8,345)) and password box (160×37 at BOTTOM (8,270)) with their
-//! `GlueFontNormal` labels seated just above each (the ref's BOTTOM→TOP (0,−23) anchor on a
-//! 64-tall centered rect ≈ text center 9 px above the box top), Login (`GlueButtonTemplate`
-//! 170×45 at TOP (8,−519)), Quit (`GlueButtonSmallTemplate` 150×38 at BOTTOMRIGHT (−5,29)), the
-//! Remember Account Name checkbox (20×20 at its resolved absolute (17, top 653) with the 10 px
-//! shadowed gold label at LEFT+24), the Blizzard logo (100×100 at BOTTOM (0,8)) under the
-//! `BLIZZ_DISCLAIMER` line (BOTTOM (0,10)), and the version block (BOTTOMLEFT (0,10),
-//! `VERSION_TEMPLATE` filled with the 5875 build facts). The Credits/Cinematics/TOS side of the
-//! reference layout is deliberately absent (decision 0539 §1). The dialog is the ref's shared
-//! `GlueDialog` box (512-wide `UI-DialogBox`, text wrapping at 440, one 200×40 button).
+//! Deviation: the Credits, Cinematics and TOS buttons are absent, because the screen keeps only
+//! what logging in needs.
 
 use bevy::prelude::*;
 use bevy::window::PrimaryWindow;
@@ -31,8 +21,7 @@ use benilla_assets::WorldAssets;
 use super::{ClientState, Field, LoginForm};
 
 const SCREEN_Z: i32 = 1100;
-/// `GlueFontDisableSmall`'s color (GlueFonts.xml) — the grey the reference's own
-/// `AccountLoginRealmName` readout draws in.
+/// `GlueFontDisableSmall`'s color (GlueFonts.xml), the `AccountLoginRealmName` readout's grey.
 const DISABLED_GREY: Color = Color::srgb(0.5, 0.5, 0.5);
 /// `DEFAULT_TOOLTIP_COLOR` (AccountLogin.lua): the edit boxes' backdrop tint (border rgb, bg rgb).
 const BOX_BORDER: Color = Color::srgb(0.8, 0.8, 0.8);
@@ -46,41 +35,35 @@ pub(crate) enum LoginAction {
     Login,
     Quit,
     ToggleSave,
-    /// Open the realmlist editor (decision 1667) — on the button and on the address readout under
-    /// it, so clicking the address you want to change does what it looks like it does.
+    /// Open the realmlist editor, from the button or the address readout under it.
     Realmlist,
 }
 
-/// Root of the login screen (despawned whole on exit); `with_art` mirrors the select screen's
-/// artless-early-spawn upgrade latch; `s` is the glue scale the tree was baked at, so a window
-/// resize (mac fullscreen) rebuilds it.
+/// Root of the login screen; `with_art` and `s` (the glue scale) record what the tree was built
+/// with, so late art or a window resize rebuilds it.
 #[derive(Component)]
 pub(super) struct LoginUi {
     with_art: bool,
     s: f32,
 }
-/// The account box's row items (segments + carets — [`refresh_boxes`] paints them through
-/// [`paint_glue_field`]).
+/// The account box's row items, painted by [`refresh_boxes`].
 #[derive(Component, Clone)]
 pub(super) struct AccountText;
-/// The password box's row items (its display is the `*` mask — the box law's own `password` flag).
+/// The password box's row items, displayed as the `*` mask.
 #[derive(Component, Clone)]
 pub(super) struct PasswordText;
-/// The checkbox's checked overlay (visibility = the form's save flag).
+/// The checkbox's checked overlay, shown while the form's save flag is set.
 #[derive(Component)]
 pub(super) struct CheckMark;
-/// The checkbox's hover highlight (driven by [`refresh_checkbox`] — the checkbox isn't a
-/// `GlueBtn`, so the shared button pass doesn't cover it).
+/// The checkbox's hover highlight, driven by [`refresh_checkbox`].
 #[derive(Component)]
 pub(super) struct CheckHilight;
-/// The realmlist readout under the button — the ref's own `AccountLoginRealmName` slot, rewritten
-/// in place by [`refresh_realmlist`] when the address changes.
+/// The realmlist readout under the button, in the reference's `AccountLoginRealmName` slot.
 #[derive(Component)]
 pub(super) struct RealmlistReadout;
 
-/// Spawn the screen tree once its prerequisites exist (the select screen's boot-order pattern:
-/// the INITIAL state's `OnEnter` fires before the MPQ chain / booth slots do) — and upgrade an
-/// artless early spawn the moment the client art lands.
+/// Spawn the screen tree once its prerequisites exist (the initial state's `OnEnter` fires before
+/// the MPQ chain and booth slots do), and rebuild an artless early spawn when the art lands.
 pub(super) fn materialize_screen(
     mut commands: Commands,
     existing: Query<(Entity, &LoginUi)>,
@@ -103,8 +86,6 @@ pub(super) fn materialize_screen(
     let s = crate::glue::screen_scale(window.single().ok());
     match existing.single() {
         Ok((root, ui)) => {
-            // Rebuild when the art lands after an early artless spawn, or when a window resize
-            // (mac fullscreen, a drag) has changed the glue scale the tree was baked at.
             if (!ui.with_art && with_art) || ui.s != s {
                 commands.entity(root).despawn();
                 spawn_screen(
@@ -147,7 +128,7 @@ fn spawn_screen(
     window: &Query<&Window, With<PrimaryWindow>>,
 ) {
     let font = wow_font(assets);
-    // The edit boxes type in `GlueEditBoxFont` — ARIALN, not FRIZQT (GlueFonts.xml).
+    // The edit boxes type in `GlueEditBoxFont`, ARIALN (GlueFonts.xml).
     let edit_font: Handle<Font> = assets.load("mpq://Fonts/ARIALN.ttf");
     let scene_image = match portraits.0.get(GLUE_SLOT) {
         Some(PortraitSource::Live(h)) => Some(h.clone()),
@@ -173,20 +154,15 @@ fn spawn_screen(
             BackgroundColor(BACKDROP),
         ))
         .with_children(|ui| {
-            // The 3D scene, full-bleed and first — the ref's screen IS the fullscreen ModelFFX
-            // (`UI_MainMenu`); the page tint behind it is the no-art fallback. It stays on the
-            // WINDOW while the chrome below does not: the pillarbox's black bars are the booth
-            // camera's own output clear *inside* this window-sized target (1619 §3), so the pane
-            // that samples the target covers the window and brings the bars with it.
+            // The fullscreen `UI_MainMenu` ModelFFX scene, window-sized: the pillarbox bars are the
+            // booth camera's own clear inside the target, so the pane must cover the window.
             if let Some(image) = scene_image {
                 ui.spawn((ImageNode::new(image), overlay()));
             }
         })
         .id();
 
-    // ...and every piece of chrome hangs off the CANVAS — the boxed scene's own rect (decision
-    // 2091). Anchored to the window instead, the logo, the version line and Realmlist/Quit stood
-    // out in the bars at 21:9 (B377).
+    // The chrome hangs off the canvas, the boxed scene's rect, so it stays out of the bars.
     let mut canvas = commands.spawn((crate::glue::glue_canvas(), ChildOf(root)));
     canvas.with_children(|ui| {
         // The WoW logo (`AccountLoginLogo`, 256×128 at TOPLEFT (3,−7), OVERLAY).
@@ -194,9 +170,8 @@ fn spawn_screen(
             ui.spawn((ImageNode::new(logo.clone()), abs(s, 3.0, 7.0, 256.0, 128.0)));
         }
 
-        // The Blizzard logo (100×100 at BOTTOM (0,8), ARTWORK) with the `BLIZZ_DISCLAIMER`
-        // copyright line at BOTTOM (0,10) drawn over its lower band (the authored overlap — the
-        // wordmark pixels sit above it).
+        // The Blizzard logo (100×100 at BOTTOM (0,8), ARTWORK) under the `BLIZZ_DISCLAIMER`
+        // line at BOTTOM (0,10), an authored overlap.
         if let Some(blizz) = &art.blizzard_logo {
             ui.spawn((Node {
                 position_type: PositionType::Absolute,
@@ -240,9 +215,8 @@ fn spawn_screen(
             s,
         );
 
-        // The version block (`AccountLoginVersion`, GlueFontNormalSmall at BOTTOMLEFT (0,10),
-        // justifyH LEFT): `VERSION_TEMPLATE` = "%s %s (%s) (%s)\n%s" filled with our wire
-        // identity's frozen facts — versionType, version, internalVersion, buildType, date.
+        // `AccountLoginVersion` (GlueFontNormalSmall at BOTTOMLEFT (0,10)): `VERSION_TEMPLATE`
+        // filled with versionType, version, internalVersion, buildType and date.
         let version = {
             let template = strings.text("VERSION_TEMPLATE", "%s %s (%s) (%s)\n%s");
             let build = benilla_protocol::CLIENT_BUILD.to_string();
@@ -278,9 +252,8 @@ fn spawn_screen(
             s,
         );
 
-        // The two edit boxes + their labels. Each box is BOTTOM-anchored with the ref's +8 x
-        // offset (a 16·s left margin inside a centered row shifts the center by 8·s); the label's
-        // resolved seat is text-center ≈ 9 px above the box top (see the module doc).
+        // The account box (160×37 at BOTTOM (8,345)) and password box (160×37 at BOTTOM
+        // (8,270)): a 16·s left margin in a centred row makes the +8 x offset.
         for (bottom, label, action, marker_account) in [
             (
                 345.0,
@@ -295,10 +268,8 @@ fn spawn_screen(
                 false,
             ),
         ] {
-            // The ref hangs the label's FontString off the EDIT BOX (`BOTTOM` ← the box's `TOP`,
-            // offset (0,−23), a 256×64 rect with the text centred in it) — so it is centred on the
-            // box, which sits at the screen centre +8. Centring a full-width node with a left
-            // margin instead put it at +16: eight units right of the box it labels.
+            // The label is a 256×64 centred rect anchored BOTTOM to the box's TOP at (0,−23), so
+            // it centres on the box at +8, the same left margin as the box row.
             outlined_text(
                 ui,
                 Node {
@@ -414,28 +385,13 @@ fn spawn_screen(
                 );
             });
 
-        // **The realmlist control** (decision 1667) — benilla's, in the reference's coordinates.
+        // The realmlist control, not in the reference, takes the absent TOS button's slot:
+        // BOTTOM to `AccountLoginExitButton`'s TOP at (0,80), with the reference's
+        // `AccountLoginRealmName` (256 wide, right-justified) at TOPRIGHT to its BOTTOMRIGHT
+        // (−8,−10). Resolved: button bottom 67 + 80 = 147, right 5; readout top 631, right 13.
         //
-        // The bottom-right column of `AccountLogin.xml` is a stack anchored off the Quit button:
-        // TOS sits BOTTOM ← `AccountLoginExitButton`'s TOP at (0, 80), with Credits and Cinematics
-        // above it. Decision 0539 cut all three, so the slot is empty — and the reference hangs
-        // `AccountLoginRealmName` off exactly that button (a 256-wide right-justified
-        // `GlueFontDisableSmall` at TOPRIGHT ← its BOTTOMRIGHT, (−8, −10)), filled in
-        // `AccountLogin_OnShow` from `GetServerName()`. So the authored layout already reserves a
-        // button here with a server readout beneath it; we put ours in that slot rather than
-        // inventing a spot.
-        //
-        // Resolved: Quit is BOTTOMRIGHT (−5, 29) at 150×38, so its top edge is bottom 67 and the
-        // button lands at bottom 67 + 80 = 147, sharing Quit's right offset of 5. The readout's
-        // top is 10 below the button's bottom (bottom 137 → top 768 − 137 = 631) and its right
-        // edge is 8 further in (5 + 8 = 13).
-        //
-        // The caption is a bare literal, deliberately: the reference has no string for this,
-        // because it has no such control. `CHANGE_REALM` was the near miss and is the wrong
-        // word — it is the *character select* screen's button for picking another realm out of a
-        // list already fetched, which is a different act from repointing the client at a different
-        // logon server. "Realmlist" is what the file, the CVar and every private server's setup
-        // page call it, in every locale.
+        // The caption is a literal because the reference has no string for it; `CHANGE_REALM`
+        // is character select's realm picker, a different act.
         ui.spawn((Node {
             position_type: PositionType::Absolute,
             right: px(5.0),
@@ -454,16 +410,14 @@ fn spawn_screen(
                     GlueBtnKind::Small,
                     s,
                 );
-                // `$WOW_HOST` owns the session, so the button reads disabled — the ref's own
-                // `Enable()`/`Disable()` split, rendered by `glue_button_visuals`. Clicking it
-                // still explains itself ([`super::login_input`]) rather than doing nothing.
+                // Disabled while `$WOW_HOST` owns the session; a click still explains why
+                // ([`super::login_input`]).
                 if realmlist.pinned_by_env() {
                     c.commands()
                         .entity(btn)
                         .insert(crate::glue::widgets::GlueDisabled(true));
                 }
             });
-        // `AccountLoginRealmName`'s seat, right-justified by being anchored on its right edge.
         outlined_text(
             ui,
             Node {
@@ -476,7 +430,7 @@ fn spawn_screen(
             RealmlistReadout,
             GlueText {
                 text: realmlist.address(),
-                size: 12.0, // GlueFontDisableSmall = GlueFontNormalSmall's 12, in grey
+                size: 12.0, // GlueFontDisableSmall
                 color: DISABLED_GREY,
                 wrap: false,
             },
@@ -484,9 +438,8 @@ fn spawn_screen(
             s,
         );
 
-        // The Remember Account Name checkbox (20×20 at the resolved absolute (17, top 653) —
-        // the ref anchors it under the Community button we cut; the spot is the same) + its
-        // 10 px shadowed gold label at LEFT+24.
+        // The Remember Account Name checkbox (20×20 at (17, top 653), resolved from its anchor
+        // under the absent Community button) and its label at LEFT+24.
         ui.spawn((Node {
             position_type: PositionType::Absolute,
             left: px(17.0),
@@ -579,8 +532,7 @@ fn spawn_screen(
     });
 }
 
-/// Paint both boxes from their [`EditBoxState`]s — segments, selection highlight, and the caret at
-/// the cursor — through the shared [`paint_glue_field`] (decision 0704).
+/// Paint both boxes from their [`EditBoxState`]s through the shared [`paint_glue_field`].
 #[allow(clippy::type_complexity)]
 pub(super) fn refresh_boxes(
     form: Res<LoginForm>,
@@ -602,14 +554,9 @@ pub(super) fn refresh_boxes(
     );
 }
 
-/// The realmlist readout, rewritten in place when the address changes (the ref's own
-/// `AccountLoginRealmName:SetText`). `sync_outlines` carries the write into the eight outline
-/// copies, so the whole nine-string stack follows.
-///
-/// An unconditional compare rather than a `Res::is_changed` gate: it is one string comparison
-/// against one entity, and the gate would silently depend on the screen tree never being spawned
-/// **after** the last change to the resource — which is exactly what a rebuild on a window resize
-/// does. Cheap beats subtly order-dependent.
+/// The realmlist readout, rewritten in place when the address changes
+/// (`AccountLoginRealmName:SetText`); `sync_outlines` carries it to the outline copies. It
+/// compares every frame, not on `Res::is_changed`, because a rebuilt tree can postdate the change.
 pub(super) fn refresh_realmlist(
     realmlist: Res<crate::realmlist::Realmlist>,
     mut texts: Query<&mut Text, With<RealmlistReadout>>,
@@ -621,8 +568,8 @@ pub(super) fn refresh_realmlist(
     }
 }
 
-/// The checkbox's visuals: the checked overlay tracks the form's save flag; the ADD hover ring
-/// tracks the button's interaction (the checkbox isn't a `GlueBtn`, so the shared pass skips it).
+/// The checkbox's checked overlay and hover ring; it is not a `GlueBtn`, so the shared button
+/// pass skips it.
 #[allow(clippy::type_complexity)]
 pub(super) fn refresh_checkbox(
     form: Res<LoginForm>,
@@ -666,7 +613,7 @@ pub(super) fn exit_login(
     for e in &roots {
         commands.entity(e).despawn();
     }
-    // The next screen re-establishes its own scene the same frame (select's per-frame feed).
+    // The next screen sets its own scene the same frame.
     preview.scene = None;
     preview.look = None;
     if let Some(root) = dialog.root.take() {
@@ -675,9 +622,7 @@ pub(super) fn exit_login(
     dialog.close();
 }
 
-/// The login-screen shot instrument (`WOW_LOGIN_SHOT_OUT=<path>`, decision 0539 §7): once the
-/// screen has been up a few seconds (art + scene settled), write one PNG via Bevy's framebuffer
-/// readback. Inert without the env.
+/// `WOW_LOGIN_SHOT_OUT=<path>`: one PNG of the login screen once it has settled.
 pub(super) fn debug_login_shot(
     mut commands: Commands,
     state: Res<State<ClientState>>,
diff --git a/crates/benilla-app/src/login/smoke.rs b/crates/benilla-app/src/login/smoke.rs
index d7d3197a..8b46d8a5 100644
--- a/crates/benilla-app/src/login/smoke.rs
+++ b/crates/benilla-app/src/login/smoke.rs
@@ -1,5 +1,4 @@
-//! The login smoke (`WOW_LOGIN_SMOKE`) — the headless prover for the screen's own submit path.
-//! Split from `mod.rs` when the file outgrew its budget; the policy and the screen stay there.
+//! The login smoke (`WOW_LOGIN_SMOKE`): a headless run of the screen's own submit path.
 
 use bevy::prelude::*;
 
@@ -7,10 +6,8 @@ use super::Attempt;
 use crate::char_select::ClientState;
 use crate::net::LoginFailedMessage;
 
-/// Split `WOW_LOGIN_SMOKE=user:pass[:Character]` into its three fields. **Three-way, once**: a
-/// `split_once(':')` here would hand the character name to the password, which is exactly what it
-/// did on this instrument's first live run (`result 0x04`, and the wrong-password path is what
-/// this smoke exists to prove, so it looked plausible).
+/// Split `WOW_LOGIN_SMOKE=user:pass[:Character]` three ways: a `split_once(':')` would hand the
+/// character name to the password, a refusal indistinguishable from a wrong password.
 fn smoke_spec(spec: &str) -> (&str, &str, Option<&str>) {
     let mut parts = spec.splitn(3, ':');
     let user = parts.next().unwrap_or_default();
@@ -19,25 +16,15 @@ fn smoke_spec(spec: &str) -> (&str, &str, Option<&str>) {
     (user, pass, character)
 }
 
-/// The optional third field — the body to enter as, or `None` for the plain
-/// reach-character-select smoke. [`crate::char_select`]'s roster policy is what actually answers
-/// the roster with it.
+/// The optional third field, the character to enter as; [`crate::char_select`]'s roster policy
+/// acts on it.
 pub(crate) fn smoke_character(spec: &str) -> Option<String> {
     smoke_spec(spec).2.map(str::to_string)
 }
 
-/// The login smoke (`WOW_LOGIN_SMOKE=user:pass[:Character]`, decision 0539 §7): once the screen is
-/// up, submit those credentials through the real screen path; exit success on reaching CharSelect,
-/// log + exit failure on a refusal — the wrong-password path is provable headlessly.
-///
-/// **Naming a character keeps the run going into the world instead of exiting** (decision 1262).
-/// It was the only headless way to reach the world down the *player's* path, back when setting
-/// `WOW_CHAR` also made the run unattended and so switched the very branch a session test wanted
-/// to exercise; decision 1769 severed that, and `WOW_CHAR` now says nothing about who is in the
-/// room. The seat stays because it is the smoke's own way in, and because a run that declares
-/// `WOW_UNATTENDED=1` still needs a way to name a character without taking it. The pick itself
-/// stays `char_select`'s (`apply_roster_policy` reads the third field the same way it reads
-/// `WOW_CHAR`); this only declines to exit. Pair with `WOW_PROBE_EXIT_AT` to bound the run.
+/// Submits `WOW_LOGIN_SMOKE` through the real screen path once it is up: exits success at
+/// CharSelect, failure on a refusal. Naming a character keeps the run going into the world
+/// instead; bound it with `WOW_PROBE_EXIT_AT`.
 pub(super) fn debug_login_smoke(
     state: Res<State<ClientState>>,
     mut attempt: Attempt,
@@ -63,9 +50,7 @@ pub(super) fn debug_login_smoke(
                     "login-smoke: FAILED refusal={:?} reason={}",
                     f.refusal, f.reason
                 );
-                // `WOW_LOGIN_SMOKE_HOLD=1`: keep running on a refusal instead of exiting — the
-                // error dialog stays up, so a shot instrument can photograph it (the dialog is
-                // otherwise unreachable headlessly; pair with `WOW_PROBE_EXIT_AT`).
+                // `WOW_LOGIN_SMOKE_HOLD=1` keeps the error dialog up for a capture.
                 if std::env::var_os("WOW_LOGIN_SMOKE_HOLD").is_none() {
                     exit.write(AppExit::error());
                 }
@@ -91,10 +76,7 @@ pub(super) fn debug_login_smoke(
 mod tests {
     use super::*;
 
-    /// The smoke spec splits three ways — the character name must never end up in the password.
-    /// A `split_once` did exactly that on the instrument's first live run, and the refusal it
-    /// produced (`0x04`) is indistinguishable from the wrong-password case this smoke exists to
-    /// exercise.
+    /// The character name must never end up in the password.
     #[test]
     fn the_smoke_spec_splits_three_ways() {
         assert_eq!(
@@ -102,9 +84,8 @@ mod tests {
             ("probe1", "secret", Some("Probeone"))
         );
         assert_eq!(smoke_spec("probe1:secret"), ("probe1", "secret", None));
-        // A trailing colon names no body; a password may not itself contain one (the client caps
-        // both fields at 16 letters and vmangos accounts have none).
-        assert_eq!(smoke_spec("one:pass:"), ("one", "pass", None));
-        assert_eq!(smoke_spec("one"), ("one", "", None));
+        // A trailing colon names no character; vmangos account passwords hold no colon.
+        assert_eq!(smoke_spec("player:pass:"), ("player", "pass", None));
+        assert_eq!(smoke_spec("player"), ("player", "", None));
     }
 }
diff --git a/crates/benilla-app/src/minimap/blips/dots.rs b/crates/benilla-app/src/minimap/blips/dots.rs
index 265b36b5..fb1afb07 100644
--- a/crates/benilla-app/src/minimap/blips/dots.rs
+++ b/crates/benilla-app/src/minimap/blips/dots.rs
@@ -1,8 +1,5 @@
-//! The `ObjectIcons.blp` **dot layer** — the per-object cell lists of the classifier
-//! `0x4eaa90` (quest gold cell 3, tracking gold/red cells 0/1, party blue cell 4). Split from
-//! the blip layer's landmark/arrow half; the shared frame geometry ([`BlipCtx`]), hover slot,
-//! and size basis live in the parent module (the byte law and its provenance are in the
-//! parent's module doc).
+//! The `ObjectIcons.blp` dots of the classifier `0x4eaa90`: quest gold cell 3, tracking gold and
+//! red cells 0 and 1, party blue cell 4.
 
 use std::collections::HashMap;
 
@@ -20,56 +17,42 @@ use crate::ui_pass::{UiQuad, UiQuads, UvRect};
 
 use super::{party_member_pos, BlipCtx, MinimapBlipHover, TrackedCandidates, BLIP_BASIS_PX};
 
-/// The quest dot's quad: 8 × 8 px (`bc82a8 = base·0.00625` × 1280, ctor-frozen; the per-cell
-/// scale table `{1,1,1,1,1.3}` leaves quest cell 3 at 1.0 — only the party cell 4 is 1.3×).
+/// The quest dot's quad, 8 px (`0xbc82a8`, frozen by the ctor); the per-cell scale table
+/// `{1,1,1,1,1.3}` scales only the party cell 4.
 const QUEST_DOT_PX: f32 = 8.0;
 /// The party dot's quad: the same 8-px base at the cell table's 1.3× party scale.
 const PARTY_DOT_PX: f32 = 8.0 * 1.3;
-/// `ObjectIcons.blp` cell 4 — the blue party-member dot (col 0, row 1 of the 4×4 grid).
+/// `ObjectIcons.blp` cell 4, the blue party dot (col 0, row 1 of the 4×4 grid).
 const PARTY_DOT_CELL: [f32; 4] = [0.0, 0.25, 0.25, 0.5];
-/// `ObjectIcons.blp` cell 0 — the gold tracked-RESOURCE dot (col 0, row 0): a GameObject
-/// passing the resource-tracking predicate (Find Herbs/Minerals; `0x5ed2b0`).
+/// `ObjectIcons.blp` cell 0, the gold dot of a GameObject passing resource tracking (`0x5ed2b0`).
 const TRACKED_GO_CELL: [f32; 4] = [0.0, 0.25, 0.0, 0.25];
-/// `ObjectIcons.blp` cell 1 — the red tracked-UNIT dot (col 1, row 0): a unit passing the
-/// creature-tracking predicate (Track Beasts/Humanoids/…; `0x5ed210`).
+/// `ObjectIcons.blp` cell 1, the red dot of a unit passing creature tracking (`0x5ed210`).
 const TRACKED_UNIT_CELL: [f32; 4] = [0.25, 0.5, 0.0, 0.25];
-/// `UNIT_DYNAMIC_FLAGS` bit 0x2 — the per-viewer "always show on minimap" flag (vmangos
-/// `UNIT_DYNFLAG_TRACK_UNIT`; the server sets it on a Hunter's Mark victim for the caster).
-/// Byte-verified as `0x5ed210`'s first clause (`+0x224 & 0x2`, the 0564 fold-back).
+/// `UNIT_DYNAMIC_FLAGS` bit 0x2, set per viewer on a Hunter's Mark victim for its caster; one of
+/// `0x5ed210`'s two always-show clauses (`+0x224 & 0x2`).
 const UNIT_DYNFLAG_TRACK_UNIT: u32 = 0x2;
-/// Creature type 7 — Humanoid: the resolver's player/race fallback. Byte-verified via the
-/// shipped `ChrRaces.dbc` (col 9 = 7 for all nine playable races, read by `0x605570`; the 0564
-/// fold-back) — also the `<= 0` fallback of the shapeshift override.
+/// Creature type 7, Humanoid: a player's type (`ChrRaces.dbc` col 9 is 7 for all nine playable
+/// races, read by `0x605570`) and the `<= 0` fallback of the shapeshift override.
 const CREATURE_TYPE_HUMANOID: u32 = 7;
 
-/// `ObjectIcons.blp` cell for a DIALOG_STATUS — **status 7 only** (`cmp [obj+0xcb8],7` at
-/// `0x4eac31`, VERIFIED): the gold cell 3. Every other status draws no quest dot.
+/// Only DIALOG_STATUS 7 draws a quest dot, the gold cell 3 (`cmp [obj+0xcb8],7` at `0x4eac31`).
 fn quest_dot_cell(status: u32) -> Option<[f32; 4]> {
     (status == 7).then_some([0.75, 1.0, 0.0, 0.25])
 }
 
-/// The three preconditions `0x4eaa90` applies to a **UNIT or PLAYER** before either dot category
-/// is even chosen (decision 1906). They sit upstream of the `cmp [edi+0xcb8],7` at `0x4eac31`,
-/// whose only predecessor is the fall-through, so they gate the gold **quest** dot (cell 3) and the
-/// red **tracking** dot (cell 1) alike. They do **not** touch the GameObject leg (cell 0) or the
-/// party dots (cell 4), which are reached by other paths entirely.
-///
-/// A candidate with no descriptor yet fails, which is the same answer the reference's own read of
-/// an un-streamed unit would give (a zeroed health field is `<= 0`) — and it lasts one drain, since
-/// `net/apply` seeds the store at the tail of the drain that spawned the entity.
+/// The three gates `0x4eaa90` applies to a unit or player ahead of the status-7 compare at
+/// `0x4eac31`, so they bar the quest dot and the tracking dot alike, never a GameObject or party
+/// dot. A unit with no descriptor yet fails, as a zeroed health field does in the reference.
 fn unit_dot_eligible(store: Option<&ObjectStore>, me: Option<u64>) -> bool {
     let Some(f) = store.map(|s| &s.0) else {
         return false;
     };
-    // 1. `0x4eac19 mov ecx,[eax+0x40]; test ecx,ecx; 0x4eac1e 0f 8e jle` — a **signed** `<= 0` on
-    //    `UNIT_FIELD_HEALTH` (`0f 8e`, not `0f 86`). The dead get no dot of any kind.
+    // 1. A signed `<= 0` on `UNIT_FIELD_HEALTH` (`jle` at `0x4eac1e`): the dead get no dot.
     if f.unit_health().unwrap_or(0) as i32 <= 0 {
         return false;
     }
-    // 2. `UNIT_FIELD_CHARMEDBY` when non-zero, else `UNIT_FIELD_SUMMONEDBY`, both halves compared
-    //    against the active player's guid (`0x468550`) — and **equality is the reject**: your own
-    //    pet, minion or charmed victim is never a blip. (This is not the classifier's self-GUID
-    //    check; there are two other, separate ones.)
+    // 2. The owner, `UNIT_FIELD_CHARMEDBY` when non-zero else `UNIT_FIELD_SUMMONEDBY`, equal to
+    //    our guid (`0x468550`) rejects: our own pet, minion or charmed unit is never a blip.
     let owner = match f.unit_charmed_by() {
         Some(g) if g != 0 => g,
         _ => f.unit_summoned_by().unwrap_or(0),
@@ -77,18 +60,12 @@ fn unit_dot_eligible(store: Option<&ObjectStore>, me: Option<u64>) -> bool {
     if owner != 0 && Some(owner) == me {
         return false;
     }
-    // 3. `byte [eax+0x213] & 4` — `UNIT_FIELD_BYTES_1` byte 3 bit 2, the only `& 4` site on that
-    //    byte image-wide. The bit is verified; its *name* is vmangos's.
+    // 3. `byte [eax+0x213] & 4`, `UNIT_FIELD_BYTES_1` byte 3 bit 2 (vmangos's untrackable name).
     !f.unit_is_untrackable()
 }
 
-/// Draw a gold dot per quest-giver at status 7, at the unit's live position, hard-culled at
-/// the view radius in 3-D world distance (`range² < dx²+dy²+dz²` skips — no rim ride);
-/// records a hover hit with the guid. Called AFTER the player arrow: dots draw last, on top.
-///
-/// Walks the candidate set rather than the status map — the classifier's own shape (it is a
-/// per-object callback, not a per-status one), and the only way to reach each object's descriptor,
-/// which [`unit_dot_eligible`] needs.
+/// Draw a gold dot per quest giver at status 7, culled at the view radius in 3-D distance with
+/// no rim arrow. Runs after the player arrow, so the dots draw on top.
 pub(in crate::minimap) fn emit_quest_dots(
     ctx: &BlipCtx,
     statuses: &HashMap<u64, u32>,
@@ -103,7 +80,7 @@ pub(in crate::minimap) fn emit_quest_dots(
     for (guid, net, tf, store) in candidates.iter() {
         let npc = guid.0;
         if !matches!(net.kind, EntityKind::Unit | EntityKind::Player) {
-            continue; // the GameObject leg (`0x4eab43`) never reaches the `== 7` compare
+            continue; // the GameObject leg (`0x4eab43`) never reaches the status-7 compare
         }
         let Some(cell) = statuses.get(&npc).copied().and_then(quest_dot_cell) else {
             continue;
@@ -117,11 +94,8 @@ pub(in crate::minimap) fn emit_quest_dots(
         if d3 > ctx.radius_yd {
             continue;
         }
-        // The cross-interior GREY (`0xffb0b0b0`, byte-pinned render value): the classifier
-        // greys entries whose colorFlag is set — the "indoor/subzone distinction" via the
-        // containment query `0x670540`. Implemented as the indoor-containment MISMATCH (the
-        // same down-ray the entity light classifier uses); the exact compare is INTERIM
-        // pending its scoped pin.
+        // The grey `0xffb0b0b0` marks a dot across an interior boundary; the reference decides
+        // through `0x670540`, untraced, and this uses an indoor-containment mismatch.
         let grey = unit_indoors(tf.translation()) != player_indoors;
         let tint = if grey { 0xb0 as f32 / 255.0 } else { 1.0 };
         let rect = Rect::from_center_size(
@@ -144,11 +118,9 @@ pub(in crate::minimap) fn emit_quest_dots(
     }
 }
 
-/// The resource-tracking predicate (the classifier's `0x5ed2b0` leg): does this GameObject's
-/// lock match the active `PLAYER_TRACK_RESOURCES` mask? The GO's template lockId resolves
-/// through `Lock.dbc`; ANY skill-keyed slot whose `LockType.dbc` id `n` has mask bit
-/// `1 << (n − 1)` set matches (the server sets exactly that bit from the tracking aura's
-/// MiscValue — vmangos `HandleAuraTrackResources`). Lock-less GOs (lockId 0) never track.
+/// Resource tracking (`0x5ed2b0`): any skill-keyed `Lock.dbc` slot of the lock whose `LockType`
+/// `n` has bit `1 << (n − 1)` set in `PLAYER_TRACK_RESOURCES`, the bit the server sets from the
+/// aura's MiscValue (vmangos `HandleAuraTrackResources`).
 fn tracked_resource(mask: u32, lock_id: u32, locks: &LockCatalog) -> bool {
     if mask == 0 || lock_id == 0 {
         return false;
@@ -162,8 +134,7 @@ fn tracked_resource(mask: u32, lock_id: u32, locks: &LockCatalog) -> bool {
     })
 }
 
-/// Our own tracking state, read once off the SelfPlayer descriptor: the two masks + the
-/// track-stealthed bit (`PLAYER_FIELD_BYTES & 0x2`).
+/// Our tracking masks and the track-stealthed bit (`PLAYER_FIELD_BYTES & 0x2`).
 #[derive(Clone, Copy, Default)]
 pub(in crate::minimap) struct SelfTracking {
     pub(in crate::minimap) creatures: u32,
@@ -171,11 +142,9 @@ pub(in crate::minimap) struct SelfTracking {
     pub(in crate::minimap) stealthed: bool,
 }
 
-/// The creature-tracking predicate — `0x5ed210` (the 0564 fold-back): two always-show clauses
-/// first — `UNIT_DYNFLAG_TRACK_UNIT` (Hunter's Mark) and *our* track-stealthed bit against the
-/// target's CREEP vis-flag (the TRACK_STEALTHED(151) consumer) — then the unit's creature type
-/// against `PLAYER_TRACK_CREATURES` (bit `creatureType − 1`). No alive/dead or faction gate
-/// (byte-verified: neither predicate tests either).
+/// Creature tracking (`0x5ed210`): either always-show clause, `UNIT_DYNFLAG_TRACK_UNIT` or our
+/// track-stealthed bit (aura 151) with the unit's CREEP flag, else the creature type's bit
+/// `type − 1` in `PLAYER_TRACK_CREATURES`. The predicate itself tests no alive/dead or faction.
 fn tracked_creature(
     tracking: SelfTracking,
     creature_type: Option<u32>,
@@ -193,11 +162,8 @@ fn tracked_creature(
             .is_some_and(|t| (1..=32).contains(&t) && tracking.creatures & (1u32 << (t - 1)) != 0)
 }
 
-/// The client's creature-type resolver, transcribed — `0x605570` (3-way, the 0564
-/// fold-back): a nonzero shapeshift form reads `SpellShapeshiftForm.dbc`'s creatureType FIRST
-/// (`<= 0` → Humanoid — a cat-form druid is a Beast); else an NPC reads its cached creature
-/// template, a player its race → Humanoid (`ChrRaces.dbc` col 9 = 7 for all nine playable
-/// races, dumped from the shipped file).
+/// The creature-type resolver `0x605570`: a shapeshift form's `SpellShapeshiftForm.dbc` type
+/// first (`<= 0` reads Humanoid), else an NPC's cached template, else Humanoid for a player.
 fn creature_type_of(
     kind: EntityKind,
     shapeshift_form: u8,
@@ -223,12 +189,9 @@ fn creature_type_of(
     }
 }
 
-/// Draw the tracking dots (decision 0560): the gold cell-0 dot per tracked GameObject, then
-/// the red cell-1 dot per tracked unit — the classifier's fall-through for objects NOT at
-/// quest status 7 (those draw the quest dot instead; the `==7` branch is tested first,
-/// byte-verified `0x4eac31`). Same hard 3-D radius cull, cross-interior grey, and hover law
-/// as the quest dots; drawn just before them (the draw walks the cell lists in order, so
-/// cells 0/1 sit under a same-spot quest or party dot).
+/// Draw the tracking dots, gold cell 0 per GameObject then red cell 1 per unit not at quest
+/// status 7 (`0x4eac31` tests that first). Drawn before the quest and party dots, as the cell
+/// lists draw in order.
 pub(in crate::minimap) fn emit_tracking_dots(
     ctx: &BlipCtx,
     tracking: SelfTracking,
@@ -245,10 +208,7 @@ pub(in crate::minimap) fn emit_tracking_dots(
     quads: &mut UiQuads,
     hover: &mut MinimapBlipHover,
 ) {
-    // NB the unit pass runs even with an empty creature mask — the two always-show clauses
-    // need no tracking aura bit in it (Hunter's Mark marks the victim, not the caster;
-    // track-stealthed rides PLAYER_FIELD_BYTES, not the mask).
-    // A candidate's dot, shared by both passes: range-cull, grey, push, hover.
+    // The unit pass runs even with an empty creature mask: the always-show clauses need none.
     let mut dot = |guid: u64, tf: &GlobalTransform, cell: [f32; 4], name: DotName| {
         let w = bevy_to_wow(tf.translation());
         let d3 =
@@ -279,16 +239,8 @@ pub(in crate::minimap) fn emit_tracking_dots(
             }
         }
     };
-    // Cell 0 — tracked GameObjects (gold): template lockId through Lock.dbc.
-    //
-    // **No quest-status precedence on this leg** (decision 1872). This loop used to skip a
-    // GameObject whose status was 7, mirroring the unit loop below — but the classifier's
-    // `cmp dword ptr [edi+0xcb8],7` at `0x4eac31` is reachable **only** from the UNIT and PLAYER
-    // legs (machine-enumerated predecessors): the GameObject leg at `0x4eab43` falls straight
-    // into `0x5ed2b0`, GameObject *tracking*, and emits category 0. A GameObject never draws a
-    // quest dot in the reference, so nothing about a quest status may suppress its tracking dot —
-    // and a GameObject can no longer *hold* a status here anyway (`net/apply` drops it, as
-    // `0x5dc9f0` does).
+    // Cell 0, GameObjects. No quest-status check: the GameObject leg (`0x4eab43`) goes straight
+    // to `0x5ed2b0` and never reaches the status-7 compare.
     if tracking.resources != 0 {
         if let Some(locks) = locks {
             for (guid, net, tf, _) in candidates.iter() {
@@ -296,7 +248,7 @@ pub(in crate::minimap) fn emit_tracking_dots(
                     continue;
                 }
                 let Some(t) = templates.get(guid.0) else {
-                    continue; // template not answered yet — no lock to test
+                    continue; // template not answered yet
                 };
                 if tracked_resource(tracking.resources, t.lock_id, locks) {
                     dot(guid.0, tf, TRACKED_GO_CELL, DotName::Known(t.name.clone()));
@@ -304,13 +256,11 @@ pub(in crate::minimap) fn emit_tracking_dots(
             }
         }
     }
-    // Cell 1 — tracked units (red): the 3-way creature-type resolver + the always-show pair.
+    // Cell 1, units.
     for (guid, net, tf, store) in candidates.iter() {
         if !matches!(net.kind, EntityKind::Unit | EntityKind::Player) {
             continue;
         }
-        // The same three preconditions the quest dot passes — they are upstream of the branch
-        // that chooses between the two categories (`0x4eac31`), so neither category outruns them.
         if !unit_dot_eligible(store, self_guid) {
             continue;
         }
@@ -346,10 +296,8 @@ enum DotName {
     Known(String),
 }
 
-/// The party **dots** — the in-range half of the party blip placement `0x6dad10`: the blue
-/// `ObjectIcons` cell 4 at the member's true position, at the cell table's 1.3× scale (10.4 px on
-/// the frozen basis). Drawn last with the object dots (`0x4ed7b7`'s order: above the arrows and the
-/// player arrow).
+/// The party dots, the in-range half of the party placement `0x6dad10`: blue cell 4 at 1.3×,
+/// drawn last with the object dots, above every arrow (`0x4ed7b7`).
 pub(in crate::minimap) fn emit_party_dots(
     ctx: &BlipCtx,
     group: &crate::ui_party::GroupState,
@@ -364,7 +312,7 @@ pub(in crate::minimap) fn emit_party_dots(
         };
         let d = ((x - ctx.wx).powi(2) + (y - ctx.wy).powi(2)).sqrt();
         if d / ctx.radius_yd > super::BLIP_EDGE_RATIO {
-            continue; // out of range — the arrow pass drew it
+            continue; // out of range: the arrow pass drew it
         }
         quads.overlays.push(UiQuad {
             rect: Rect::from_center_size(
@@ -384,13 +332,7 @@ pub(in crate::minimap) fn emit_party_dots(
 mod tests {
     use super::*;
 
-    /// **The three preconditions upstream of BOTH dot categories** (decision 1906). They live in
-    /// `0x4eaa90` between the type gate and the `cmp [edi+0xcb8],7`, whose only predecessor is
-    /// the fall-through — so a unit that fails any of them draws neither the gold quest dot nor
-    /// the red tracking dot. benilla had none of them.
-    ///
-    /// The control is the first row: an ordinary live creature still passes, which is what would
-    /// catch a predicate written one bit too wide and blanked the minimap.
+    /// The first row is the control: an ordinary live creature still passes.
     #[test]
     fn the_dead_our_own_minions_and_the_untrackable_draw_no_dot_of_either_kind() {
         use crate::net::ObjectStore;
@@ -400,7 +342,7 @@ mod tests {
         const FIELD_SUMMONEDBY: u16 = 12; // UNIT_FIELD_SUMMONEDBY (2 dwords)
         const FIELD_CHARMEDBY: u16 = 10; // UNIT_FIELD_CHARMEDBY (2 dwords)
         const FIELD_BYTES_1: u16 = 138;
-        /// `UNIT_FIELD_BYTES_1` byte 3 bit 2 — the `& 4` the classifier tests.
+        /// `UNIT_FIELD_BYTES_1` byte 3 bit 2, the `& 4` the classifier tests.
         const UNTRACKABLE: u32 = 0x4 << 24;
         const ME: u64 = 0x0000_0000_0000_0007;
         const SOMEONE_ELSE: u64 = 0x0000_0000_0000_0042;
@@ -452,7 +394,7 @@ mod tests {
                 Some(&with(&[
                     (FIELD_CHARMEDBY, lo(ME)),
                     (FIELD_CHARMEDBY + 1, hi(ME)),
-                    // A non-zero CHARMEDBY wins outright — SUMMONEDBY is only the fallback.
+                    // A non-zero CHARMEDBY wins; SUMMONEDBY is only the fallback.
                     (FIELD_SUMMONEDBY, lo(SOMEONE_ELSE)),
                     (FIELD_SUMMONEDBY + 1, hi(SOMEONE_ELSE)),
                 ])),
@@ -466,8 +408,7 @@ mod tests {
         );
     }
 
-    /// Only status 7 dots (the gold cell 3). Status 6 — despite the vmangos "red dot"
-    /// comment — draws nothing on the 1.12 client (byte-verified `==7` at 0x4eac31).
+    /// Status 6 draws nothing on the 1.12 client despite vmangos's "red dot" comment (`0x4eac31`).
     #[test]
     fn quest_dot_is_status_seven_only_gold_cell_three() {
         assert_eq!(quest_dot_cell(7), Some([0.75, 1.0, 0.0, 0.25]));
@@ -476,15 +417,11 @@ mod tests {
         }
     }
 
-    /// The tracking predicates' mask-bit law (decision 0560): bit `1 << (n − 1)` where `n` is
-    /// the GO lock's skill-slot `LockType` id (resources) or the unit's creature type
-    /// (creatures) — the exact bit the server sets from the tracking aura's MiscValue — plus
-    /// the always-show dyn-flag clause that needs no mask at all.
+    /// Bit `1 << (n − 1)`, `n` the lock's skill-slot `LockType` or the creature type.
     #[test]
     fn tracking_predicates_follow_the_mask_bit_law() {
         use benilla_formats::{LockSlot, LOCK_KEY_ITEM, MAX_LOCK_SLOTS};
-        // A mining-vein-shaped lock (one SKILL slot, Mining LockType 3) and a key-ITEM lock
-        // whose index happens to collide numerically.
+        // A Mining (LockType 3) skill slot, and a key-item slot with the same index.
         let mut vein = [LockSlot::default(); MAX_LOCK_SLOTS];
         vein[0] = LockSlot {
             key_type: LOCK_KEY_SKILL,
@@ -538,9 +475,8 @@ mod tests {
             !tracked_creature(beasts, None, 0, false),
             "type not cached yet — no dot"
         );
-        // The always-show pair (`0x5ed210`): Hunter's Mark forces the dot with no
-        // tracking aura on us; track-stealthed lights only a CREEP-flagged unit — and only
-        // the conjunction of the two bits does.
+        // The always-show pair: Hunter's Mark needs no tracking aura; track-stealthed needs
+        // both our bit and the unit's CREEP flag.
         assert!(tracked_creature(
             SelfTracking::default(),
             None,
@@ -559,9 +495,6 @@ mod tests {
         );
     }
 
-    /// The creature-type resolver's 3-way (`0x605570`, the 0564 fold-back): shapeshift
-    /// override first (`<= 0` → Humanoid), then the cached template for NPCs, the Humanoid
-    /// fallback for players.
     #[test]
     fn creature_type_resolver_prefers_the_shapeshift_override() {
         use benilla_formats::ShapeshiftForm;
@@ -583,7 +516,7 @@ mod tests {
             ),
         ]
         .into();
-        // A cat-form PLAYER is a Beast; unshifted, a player is a Humanoid.
+        // A cat-form player is a Beast; unshifted, a Humanoid.
         assert_eq!(
             creature_type_of(EntityKind::Player, 1, None, &names, Some(&forms)),
             Some(1)
@@ -592,13 +525,11 @@ mod tests {
             creature_type_of(EntityKind::Player, 0, None, &names, Some(&forms)),
             Some(CREATURE_TYPE_HUMANOID)
         );
-        // A <=0 creatureType row resolves Humanoid, not the race/template path.
         assert_eq!(
             creature_type_of(EntityKind::Player, 16, None, &names, Some(&forms)),
             Some(CREATURE_TYPE_HUMANOID)
         );
-        // An unshifted NPC with no cached template yet resolves nothing (no dot until the
-        // ask-once query answers); a GameObject never resolves a creature type.
+        // An NPC with no cached template yet resolves nothing.
         assert_eq!(
             creature_type_of(EntityKind::Unit, 0, Some(69), &names, Some(&forms)),
             None
@@ -609,10 +540,8 @@ mod tests {
         );
     }
 
-    /// The whole client-side chain against the REAL 5875 data (skips without it): the
-    /// tracking spell's `EffectMiscValue` → the server's mask bit → the gathering node's
-    /// `Lock.dbc` skill slot. Find Minerals lights a Copper Vein, Find Herbs a Peacebloom —
-    /// and neither lights the other's node.
+    /// The tracking spell's `EffectMiscValue`, the server's mask bit and the node's `Lock.dbc`
+    /// skill slot, on the install's data.
     #[test]
     fn real_find_minerals_lights_a_copper_vein_not_an_herb() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -622,8 +551,7 @@ mod tests {
         let forms =
             benilla_formats::load_shapeshift_forms(&mut chain).expect("SpellShapeshiftForm.dbc");
 
-        // The server's mask law, applied to the real spell row: bit `1 << (MiscValue − 1)` of
-        // the aura-`kind` effect (44 TRACK_CREATURES / 45 TRACK_RESOURCES).
+        // Bit `1 << (MiscValue − 1)` of the aura-`kind` effect (44 creatures, 45 resources).
         let mask_of = |spell_id: u32, kind: u32| -> u32 {
             let s = spells.get(spell_id).expect("spell row");
             (0..3)
@@ -637,19 +565,16 @@ mod tests {
                 .expect("tracking effect present")
         };
 
-        // Find Minerals 2580 ↔ Copper Vein (gameobject_template 1731, chest lockId 38 —
-        // vmangos world DB — whose Lock.dbc row is the Mining LockType 3 skill slot).
+        // Find Minerals 2580 and a Copper Vein (vmangos `gameobject_template` 1731, lockId 38).
         let minerals = mask_of(2580, 45);
         assert_eq!(minerals, 1 << 2, "Find Minerals' MiscValue is Mining (3)");
         assert!(tracked_resource(minerals, 38, &locks));
-        // Find Herbs 2383 ↔ Peacebloom/Silverleaf (lockId 29, Herbalism LockType 2).
+        // Find Herbs 2383 and Peacebloom or Silverleaf (lockId 29, Herbalism LockType 2).
         let herbs = mask_of(2383, 45);
         assert!(tracked_resource(herbs, 29, &locks));
         assert!(!tracked_resource(minerals, 29, &locks), "cross-profession");
         assert!(!tracked_resource(herbs, 38, &locks), "cross-profession");
-        // Track Beasts 1494: TRACK_CREATURES MiscValue 1 = Beast — a wolf dots red, a
-        // humanoid doesn't. And through the shapeshift override on the REAL
-        // SpellShapeshiftForm.dbc, a cat-form (1) druid IS a Beast to it.
+        // Track Beasts 1494 (MiscValue 1, Beast) lights a cat-form (1) druid.
         let beasts = SelfTracking {
             creatures: mask_of(1494, 44),
             ..Default::default()
diff --git a/crates/benilla-app/src/minimap/blips/mod.rs b/crates/benilla-app/src/minimap/blips/mod.rs
index 0ec5af3d..4d5bf2ce 100644
--- a/crates/benilla-app/src/minimap/blips/mod.rs
+++ b/crates/benilla-app/src/minimap/blips/mod.rs
@@ -1,77 +1,33 @@
-//! The minimap **blip layer** (decision 0203 phase 3; the byte law per the fold-back,
-//! decision 0337): AreaPOI landmarks + quest dots + the hover tooltip.
+//! The minimap blip layer: AreaPOI landmarks, quest and tracking dots, rim arrows and the hover
+//! tooltip.
 //!
-//! **Landmarks** (selection `0x6d9a90`, candidates `0x6d8e10`, draw `0x4ed148`/`0x4ee170`):
-//! - **Candidates**: `ContinentID == current map` AND `Flags & 1` — nothing else (no faction,
-//!   no importance gate; both factions' rows are candidates).
-//! - **In-range** (`d/viewRadius ≤ 0.8`): draws the `POIIcons.blp` cell indexed by the DBC
-//!   `Icon` column at the POI's true position — but **only** rows with `Flags & 2` (in 5875
-//!   data that is exactly the 32 world-PvP tower rows, e.g. the EPL towers). An ordinary
-//!   in-range landmark (town/city, `Flags & 2` clear) draws nothing.
-//! - **Out-of-range**, `d ≤ 694.444`: the nearest **3**, ranked by (`Importance` **signed**
-//!   asc, dist asc) — the rank key is Importance, NOT AreaID (the fold-back's C2 correction) —
-//!   drawn ON the 0.8 rim, each **rotated to point at its POI** (the client bakes direction +
-//!   `0.8·radius` into the arrow frame's matrix), in the art its **source** calls for: see
-//!   [`RimArrow`], the four-way table 1519 pinned.
+//! Landmarks (selection `0x6d9a90`, candidates `0x6d8e10`, draw `0x4ed148`/`0x4ee170`):
+//! - Candidates: `ContinentID` is the current map and `Flags & 1`, no faction or importance gate.
+//! - In range (`d / viewRadius ≤ 0.8`): the `POIIcons.blp` cell of the `Icon` column, only for
+//!   rows with `Flags & 2` (the world-PvP towers in 1.12 data); other rows draw nothing.
+//! - Out of range within 694.444 yd: the first 3 by (`Importance` signed ascending, distance),
+//!   on the 0.8 rim, each rotated to point at its POI in its source's art ([`RimArrow`]).
 //!
-//! **Quest dots** — the ObjectIcons classifier `0x4eaa90`: reads the SAME per-guid
-//! DIALOG_STATUS cache the overhead `!`/`?` markers mirror (one `SMSG_QUESTGIVER_STATUS`, two
-//! consumers), and draws a dot **only for status == 7** (REWARD2) → the gold **cell 3**.
-//! Status 6 draws NO dot (the vmangos "6 = red dot" comment is server intent, not this
-//! client; blue cell 4 is party members, green cell 2 is never populated in 1.12.1). Dots
-//! hard-cull at the live zoom radius in **3-D** world distance (no rim ride), and draw
-//! LAST — above every arrow.
+//! Dots come from the ObjectIcons classifier `0x4eaa90`. A unit or player must first be alive, not
+//! our own charm or summon, and trackable ([`dots`]'s `unit_dot_eligible`). Then quest status 7
+//! draws the gold cell 3 (status 6 draws nothing; green cell 2 is never used in 1.12), and every
+//! other object falls through to tracking: a GameObject passing `0x5ed2b0` draws gold cell 0, a
+//! unit passing `0x5ed210` red cell 1, against the `PLAYER_TRACK_CREATURES`/`RESOURCES` masks.
+//! Party members are blue cell 4. Dots cull at the view radius in 3-D distance and draw last.
 //!
-//! **Tracking dots** (decisions 0560/0564) — the classifier's fall-through for objects NOT
-//! at quest status 7: a GameObject passing `0x5ed2b0` draws the gold **cell 0**
-//! (Find Herbs/Minerals), a unit passing `0x5ed210` the red **cell 1**. The
-//! masks are the `PLAYER_TRACK_CREATURES`/`PLAYER_TRACK_RESOURCES` descriptor mirror
-//! (fields 1104/1105 — `values[UNIT_END] + 0x394/0x395`, byte-exact) with one bit per
-//! active tracking aura's MiscValue. A GO tests its lockId → `Lock.dbc` skill-slot
-//! `LockType`; a unit its creature type via the 3-way resolver `0x605570` (shapeshift-form
-//! override → cached creature template → race/Humanoid), behind two always-show clauses:
-//! `UNIT_DYNFLAG_TRACK_UNIT` (Hunter's Mark) and our track-stealthed bit vs the target's
-//! CREEP vis-flag (the TRACK_STEALTHED consumer). No alive/dead or faction gate.
+//! Blip sizes are frozen once by the CGMinimapFrame ctor (`0x4edbc0`) against a 140.8-px basis.
 //!
-//! **Sizes are byte-pinned** (`0x4edbc0`, the 0342 fold-back): every blip constant is
-//! frozen once by the CGMinimapFrame ctor against the stock widget's 140.8-px screen basis —
-//! dot 8 px, POI icon 16 px, orbit 0.8 × the 70.4-px half-disc; the arrows render their M2
-//! models at 768 px/unit (rim, modelScale 0.6) and 1280 px/unit (player). Both arrow models
-//! are plain textured quads (measured from the real M2s), so the flat-sprite stand-in is
-//! geometry-exact at the model's own quad size — no uv crop, the padding is authored. The rim
-//! model stacks six of them, but only ever shows one at a time ([`RimArrow`]).
+//! Not built: the landmark `WorldStateID` gate (`0x6d9b27`); the per-source rim-arrow z-order
+//! (bottom to top landmark, party, quest, gossip, corpse, from `+0x48` as a frame-level offset),
+//! which conflicts with `0x4ed7b7` drawing the dots last and is unsettled; and static blip slot 0,
+//! `SelectQuestLogEntry()`'s gold guide arrow at the quest's POI (`0x4def70`).
 //!
-//! **The guard's directions marker** ([`crate::poi_marker`], decisions 1514/1516) is a landmark
-//! candidate like any other, appended after the DBC filter the way the reference appends its
-//! static blip slot — everything above applies to it unchanged, except the one thing that is
-//! *about* being a different kind of thing: its rim arrow is the gold guide arrow ([`RimArrow`]).
+//! Deviation: dots re-project every frame, where the reference draws coordinates about 1 s
+//! stale, because that staleness is a throttle quirk.
 //!
-//! Remaining residue: one gate the landmark selection here does NOT implement, recorded in 1516
-//! and belonging to the DBC rows rather than the marker — a `WorldStateID` gate at `0x6d9b27`.
-//!
-//! Three more from 1525, all recorded rather than built (each is a visible change to a
-//! feature that is not the arrow art, and one is contested):
-//! - **The corpse is in the wrong array and the pet blip is missing** — see [`emit_party_arrows`].
-//! - **Rim arrows have a per-source z-order we flatten.** `+0x48` doubles as a frame-level offset
-//!   (`[minimap+0xc4]+3+kind`, POI frames re-levelled every draw at `0x4ed344`; party frames once
-//!   at creation), giving bottom→top: landmark, party/pet, quest, gossip, corpse. We paint every
-//!   arrow at one `z_key` in emission order, which happens to agree on landmark-under-party and
-//!   disagrees above that. **NOT built because two findings conflict**: `0x4ed7b7` has the
-//!   object dots drawing LAST, above every arrow, while this table puts gossip and corpse above the
-//!   quest dot. Frame level vs. the parent's own draw order is a compositing question neither
-//!   finding settles, and guessing would move a look on a coin flip.
-//! - **Static blip slot 0 is `SelectQuestLogEntry()`'s marker** (`0x4def70`, cleared by
-//!   `0x4df0e0`): selecting a quest in the log drops a gold guide arrow at that quest's POI —
-//!   `flags = 0`, so it is **arrow-only**, showing nothing once you are inside the 0.8 rim. Live
-//!   code, not a dead hook, and a feature we do not have. (Its `PointX/PointY` source is INFERRED
-//!   from use, not byte-derived.)
-//!
-//! Also: dots re-project every frame where the reference draws ~1 Hz-stale
-//! snapshot coords verbatim (a throttle quirk, deliberately not aped — positions agree for
-//! standing NPCs); the subzone grey tint (`0xffb0b0b0`) on dots and their tooltip is drawn
-//! from the indoor-containment MISMATCH — the exact `0x670540` compare is INTERIM and still
-//! open; the tooltip anchor beside the map is an eyeball (the engine handler `0x4eb0c0`
-//! law gives content, not the exact seat).
+//! The cross-interior grey (`0xffb0b0b0`) comes from an indoor-containment mismatch; the
+//! reference's compare (`0x670540`) is untraced. The tooltip sits at the cursor; its exact seat
+//! is untraced, since `0x4eb0c0` gives only its content.
 
 mod dots;
 
@@ -91,99 +47,53 @@ use crate::names::NameCache;
 use crate::net::{Embodied, Guid, GuidIndex, NetCommands, NetEntity, ObjectStore, SelfPlayer};
 use crate::ui_pass::{UiQuad, UiQuads, UvRect};
 
-/// The landmark rank radius in yards (`0x8116cc` = 694.444, VERIFIED).
+/// The landmark rank radius in yards (`0x8116cc`).
 const LANDMARK_RANK_YD: f32 = 694.444;
-/// The in/out-of-range split ratio (`0x811730` = 0.8, VERIFIED): at or under it a POI is
-/// in-range (icon path); over it, an edge-arrow candidate riding the rim — whose radius is
-/// byte-pinned as 0.8 × the frozen 70.4-px half-disc = 56.32 px at stock (= 0.4 × side, the
-/// same expression the placement below uses).
+/// The in-range split and the rim radius as a fraction of the half-disc (`0x811730`).
 const BLIP_EDGE_RATIO: f32 = 0.8;
-/// AreaPOI `Flags` bit 0 — the candidacy gate (`zone_rebuild 0x6d8e10`, VERIFIED).
+/// AreaPOI `Flags` bit 0, the candidacy gate (`0x6d8e10`).
 const FLAG_CANDIDATE: u32 = 0x1;
-/// AreaPOI `Flags` bit 1 — "draw the in-range icon" (`0x6d9a90`, VERIFIED); the world-PvP
-/// tower class in 5875 data.
+/// AreaPOI `Flags` bit 1, draw the in-range icon (`0x6d9a90`).
 const FLAG_IN_RANGE_ICON: u32 = 0x2;
-/// The frozen basis the client bakes every blip-size constant against: the CGMinimapFrame
-/// ctor (`0x4edbc0`) computes them ONCE from the stock 140-XML-unit widget —
-/// which lands at 140.8 screen px on the 1024×768 reference — and never recomputes. Sizes
-/// below are that table's byte-derived pixel values over this basis, so at stock geometry we
-/// render them exactly and any resized widget scales proportionally.
+/// The basis every blip size is frozen against: the stock 140-unit widget at 140.8 px on the
+/// 1024×768 screen, computed once by the CGMinimapFrame ctor (`0x4edbc0`).
 pub(super) const BLIP_BASIS_PX: f32 = 140.8;
-/// The player arrow's quad: `MinimapArrow.m2` is a single full-texture 0.0262 × 0.0263-unit
-/// quad rendered at 1280 px per model unit — 33.6 px at stock. Its authored centre sits
-/// (+0.0004, +0.00135) model units off the frame origin: ≈(+0.5 right, 1.7 up) screen px,
-/// rotating with the facing (model +y = screen-up at zero rotation).
-/// The player arrow's art — the minimap ring's and, since decision 1980, the world map's: the stock
-/// `WorldMapFrame.lua` `SetModel`s an anonymous pane to the same M2 and the app draws that pane as
-/// this sprite (`ui_script::extract`).
+/// The player arrow's art, on the minimap and the world map, whose stock `WorldMapFrame.lua`
+/// `SetModel`s a pane to the same M2.
 pub(crate) const PLAYER_ARROW_TEXTURE: &str = "Interface\\Minimap\\MinimapArrow";
+/// `MinimapArrow.m2` is one 0.0262 × 0.0263-unit quad at 1280 px per model unit.
 pub(crate) const PLAYER_ARROW_QUAD_PX: f32 = 33.6;
+/// The quad's authored centre, (+0.0004, +0.00135) model units off the origin; it turns with
+/// facing.
 pub(crate) const PLAYER_ARROW_OFFSET_PX: bevy::math::Vec2 = bevy::math::Vec2::new(0.51, -1.73);
-/// The rim arrow's on-screen quad: the `Rotating-MinimapArrow.m2` geometry is a stack of six
-/// full-texture 0.0500-unit quads (measured from the real M2's 24 vertices, z 0/0.0145/0.0291),
-/// and the frame renders at 768 px per model unit (modelScale 0.6 × 1280 px/unit):
-/// 0.0500 · 768 = 38.4 px. The full 32² texture maps onto it (uv 0..1 on every layer), so the
-/// flat-sprite stand-in needs NO uv crop — the art's transparent padding is authored into the
-/// model's own quad.
-///
-/// The six quads are **not** an alpha-layering trick on one texture, as this note used to say
-/// (1519): they carry six *different* textures, four of which are the four arrow arts, and the
-/// sequence played picks which one is opaque. See [`RimArrow`] — that is why only one of the six
-/// ever draws, and why the stand-in is a single sprite rather than a stack.
+/// The rim arrow's quad: `Rotating-MinimapArrow.m2`'s 0.0500-unit full-texture quads at 768 px
+/// per model unit (modelScale 0.6 × 1280), so the sprite needs no uv crop.
 const ARROW_QUAD_PX: f32 = 38.4;
 
-/// **Which rim-arrow art a blip source draws** — the reference's four, and why they look like one.
+/// Which rim-arrow art a blip source draws. The minimap's one arrow model,
+/// `Rotating-MinimapArrow.m2`, picks among four arrow layers by sequence (`0x4ed349`): in each
+/// looping sequence exactly one layer's stepped alpha is 1.0, untinted, so one flat sprite per
+/// source is exact. `AnimationData.dbc` names them 165 `GroupArrow`, 166 `Arrow`, 167
+/// `CorpseArrow`, 168 `GuideArrow`.
 ///
-/// `Rotating-MinimapArrow.mdx` is the *only* arrow model the minimap owns (`0x4ee2b0` binds it to
-/// `minimapArrowModel` for both the party frames and the POI frames), so a reader naturally
-/// concludes there is one arrow art. There are four, and the model picks between them **by
-/// animation**: `0x4ed349`–`0x4ed37b` hands `0x76cf50` — the SetSequence arm, `0x76cf50(this, seq)`
-/// → `0x7121a0(model, -1, seq, -1, 0, 1.0, 0, 1)` — an `AnimationData.dbc` id chosen off the
-/// output record's `+0x48`, and `0x4ee170` arms the 5 party frames with `0xa5`. That argument is
-/// a sequence id, not a "model id" for one of four `.mdx` variants, and there is one model.
-///
-/// The model is what proves the mapping, and it is measured, not inferred: the install's own
-/// `Rotating-MinimapArrow.m2` authors **six** textured quads — the four arrow arts below, plus a
-/// glow and `Spells\Star4` — and exactly eight sequences, `0xa5`/`0xa6`/`0xa7`/`0xa8` (1 s, looping)
-/// and `0xcc`–`0xcf` (2 s, one-shot arrival flashes). Every layer's M2Color **alpha** track is
-/// `interp = 0` (step), and in each looping band exactly one arrow layer steps to 1.0 while the
-/// other three sit at 0.0 — so "play sequence `0xa8`" *is* "draw the guide arrow". The four arrow
-/// layers' RGB tracks are a single `[1,1,1]` key (untinted: the art's own colour), and the glow and
-/// star layers hold alpha 0 through all four loops — they light only in the one-shot flashes, which
-/// this call site never plays. So one flat sprite per source is colour- and geometry-exact.
-/// [`tests::each_rim_arrow_sequence_lights_exactly_its_own_layer`] re-measures all of that against
-/// the real file.
-///
-/// `AnimationData.dbc` names the four rows outright — 165 `GroupArrow`, 166 `Arrow`, 167
-/// `CorpseArrow`, 168 `GuideArrow` (1525). Four arbitrary-looking ids landing on four names that
-/// describe their callers exactly is why this is settled rather than merely likely.
-///
-/// **The selector is a default, not an enumeration** (1525): `0xa7` if `+0x48 == 2`, else
-/// `0xa6 + 2·(v != -2)`. Only a DBC landmark and the corpse are special-cased; **everything else
-/// draws the gold guide arrow**, including static slot 0. So [`Self::Guide`] is the right art for
-/// any future non-DBC candidate we append, and the two named rows are the exceptions to it.
+/// The selector is `0xa7` when the output record's `+0x48 == 2`, else `0xa6 + 2·(v != -2)`, so
+/// everything but a DBC landmark and the corpse draws the guide arrow.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) enum RimArrow {
-    /// An `AreaPOI.dbc` landmark — sequence `0xa6`, output record `+0x48 == -2`. The white one.
+    /// An `AreaPOI.dbc` landmark: sequence `0xa6`, `+0x48 == -2`, the white one.
     Landmark,
-    /// A party/raid member **or your pet** — sequence `0xa5`, armed once at `0x4ee1e3` and never
-    /// re-armed: neither draw loop touches it, and a dead/offline/zoned-out member is hidden
-    /// upstream rather than re-skinned (1525). Permanently the group arrow.
+    /// A party or raid member, or your pet: sequence `0xa5`, armed once at `0x4ee1e3` and never
+    /// re-armed.
     Group,
-    /// Your own corpse — sequence `0xa7`, output record `+0x48 == 2`.
+    /// Your own corpse: sequence `0xa7`, `+0x48 == 2`.
     Corpse,
-    /// The guard's directions ([`crate::poi_marker`]) — sequence `0xa8`, the default arm. The gold
-    /// one: the guard is your *guide*, and the art is named for it.
+    /// The guard's directions ([`crate::poi_marker`]): sequence `0xa8`, the default arm, gold.
     Guide,
 }
 
 impl RimArrow {
-    /// The `AnimationData.dbc` sequence the reference plays to select this art.
-    ///
-    /// Nothing in our draw path needs it — we resolve to a flat sprite and never play a sequence —
-    /// so it exists for the one job only the id can do: asking the real model what that sequence
-    /// shows, which is what pins [`Self::texture`] to something better than a guess. Test-only for
-    /// the same reason `poi_marker`'s `ICON_POI_REDFLAG` is.
+    /// The `AnimationData.dbc` sequence the reference plays for this art; the test checks the
+    /// model against it.
     #[cfg(test)]
     pub(crate) const fn anim_id(self) -> u16 {
         match self {
@@ -194,7 +104,7 @@ impl RimArrow {
         }
     }
 
-    /// The `.blp` that sequence lights — the layer whose M2Color alpha steps to 1.0 in its band.
+    /// The `.blp` that sequence lights.
     pub(crate) const fn texture(self) -> &'static str {
         match self {
             Self::Landmark => "Interface\\Minimap\\Rotating-MinimapArrow",
@@ -208,8 +118,7 @@ impl RimArrow {
     pub(crate) const ALL: [Self; 4] = [Self::Landmark, Self::Group, Self::Corpse, Self::Guide];
 }
 
-/// The four rim-arrow textures, loaded once — the flat-sprite stand-in for the one model the
-/// reference re-animates. A missing slot draws no arrow for that source rather than the wrong one.
+/// The four rim-arrow textures; a missing one draws no arrow for its source, never another's.
 #[derive(Default)]
 pub(crate) struct RimArrowArt([Option<Handle<Image>>; 4]);
 
@@ -222,41 +131,29 @@ impl RimArrowArt {
         self.0[kind as usize].as_ref()
     }
 
-    /// Any art at all — the landmark pass runs on the arrow art alone (it draws the guard marker
-    /// even with no `AreaPOI.dbc`), so it needs to know whether the load found anything.
+    /// Any art at all: the landmark pass runs without `AreaPOI.dbc`, for the guard marker.
     pub(super) fn any(&self) -> bool {
         self.0.iter().any(Option::is_some)
     }
 }
-/// An in-range POI icon's quad: 16 × 16 px (`bc7658 = base·0.0125` × 1280, ctor-frozen).
+/// An in-range POI icon's quad, 16 px (`[0xbc7658]`, frozen by the ctor).
 const POI_ICON_PX: f32 = 16.0;
-// The dot-layer constants (cell coords, dot sizes, the tracking-predicate constants) live
-// with the dot emitters in [`dots`].
 
-/// The blip under the cursor this frame — written by `emit_minimap`'s blip passes, consumed
-/// by [`drive_blip_tooltip`]. A quest dot carries the guid (the name resolves at the drive,
-/// where the ask-once `NameCache` lives).
+/// The blip under the cursor this frame, for [`drive_blip_tooltip`].
 #[derive(Resource, Default)]
 pub(crate) enum MinimapBlipHover {
     #[default]
     None,
-    /// A landmark's name + the cursor's UI-space point at detection (the tooltip's seat).
+    /// A landmark's name and the cursor's UI-space point, the tooltip's seat.
     Landmark(String, Vec2),
-    /// A unit dot's guid (quest gold or tracked red — both resolve through the name cache,
-    /// the classifier's own `GetName()` route) + cursor point + whether the dot rendered
-    /// GREY (cross-interior — the tooltip line grey-wraps the same way, `|cffb0b0b0`).
+    /// A unit dot's guid, resolved through the name cache, the cursor point, and whether the dot
+    /// drew grey; the tooltip line greys the same way (`|cffb0b0b0`).
     Npc(u64, Vec2, bool),
-    /// A tracked GameObject dot: its template name (known synchronously — the same string
-    /// `GetName()` returns for a GO) + cursor point + the grey flag.
+    /// A tracked GameObject dot: its template name, the cursor point and the grey flag.
     TrackedGo(String, Vec2, bool),
 }
 
-/// The blip layer's system inputs, tupled so `emit_minimap` stays under Bevy's 16-param
-/// ceiling: the quest-status store, the guid→entity index + unit positions, the cursor's
-/// window, the hover-out slot, the party state, and the tracking-dot inputs (candidates,
-/// our own descriptor's masks, the creature/GO template caches, `Lock.dbc`), plus the
-/// `uiScale` dial the tooltip's cursor seat converts through, and the guard-directions marker
-/// the landmark pass draws as a candidate.
+/// The blip layer's system inputs, tupled to keep `emit_minimap` under Bevy's 16-parameter cap.
 pub(super) type BlipInputs<'w, 's> = (
     Res<'w, crate::ui_quest::QuestGiver>,
     Res<'w, GuidIndex>,
@@ -276,8 +173,7 @@ pub(super) type BlipInputs<'w, 's> = (
     Option<NonSendMut<'w, UiScript>>,
 );
 
-/// Every streamed object the tracking classifier considers (our own avatar excluded — the
-/// player is the arrow, never a dot).
+/// Every streamed object the classifier considers; our own avatar is the arrow, never a dot.
 pub(super) type TrackedCandidates<'w, 's> = Query<
     'w,
     's,
@@ -290,36 +186,30 @@ pub(super) type TrackedCandidates<'w, 's> = Query<
     Without<Embodied>,
 >;
 
-/// The shared frame geometry the blip emitters draw in: the widget centre/side, the active
-/// branch's world→px scale and view radius, the paint key, and the player's WoW position.
+/// The frame geometry the blip emitters draw in; `wx`, `wy`, `wz` are the player's position.
 pub(super) struct BlipCtx {
     pub(super) center: Vec2,
     pub(super) side: f32,
     pub(super) px_per_yd: f32,
-    /// The live view radius in yards (the active zoom's half-extent / interior radius) —
-    /// the in/out-of-range split's denominator and the dot cull's range.
+    /// The live view radius in yards: the in-range split's denominator and the dot cull.
     pub(super) radius_yd: f32,
     pub(super) z: u64,
     pub(super) alpha: f32,
     pub(super) wx: f32,
     pub(super) wy: f32,
     pub(super) wz: f32,
-    /// Window cursor in the same y-down logical px as the quad rects; `None` = off-window.
+    /// The cursor in the quads' y-down logical px.
     pub(super) cursor: Option<Vec2>,
-    /// The same cursor in UI space (y-up, from the window bottom-left) — the tooltip's
-    /// anchor point (the reference seats the blip tooltip at the cursor; director-verified,
-    /// exact engine offset pending the anchor-law pin).
+    /// The cursor in y-up UI space; the reference seats the blip tooltip at the cursor, its exact
+    /// offset untraced.
     pub(super) cursor_ui: Option<Vec2>,
-    /// THE seam scale (decision 0582): **window px per UI unit**. Everything else in this struct
-    /// is window px; anything arriving from Lua ([`Minimap:PingLocation`](super::ping)) is in UI
-    /// units, and this is the one number that crosses them. Mixing the two silently is decision
-    /// 1596's first root cause.
+    /// Window px per UI unit: everything else here is window px, while Lua
+    /// ([`Minimap:PingLocation`](super::ping)) speaks UI units.
     pub(super) seam: f32,
 }
 
 impl BlipCtx {
-    /// A WoW world point → its screen offset from the widget centre (north-up: up = +X north,
-    /// left = +Y west — the same mapping the tiles and the corpse blip use).
+    /// A WoW world point's screen offset from the widget centre, north up (+X up, +Y left).
     pub(super) fn offset(&self, w: [f32; 3]) -> Vec2 {
         Vec2::new(
             (self.wy - w[1]) * self.px_per_yd,
@@ -328,25 +218,17 @@ impl BlipCtx {
     }
 }
 
-/// The landmark selection's two draw lists (`0x6d9a90`'s split).
+/// The landmark selection's two draw lists (`0x6d9a90`).
 pub(super) struct LandmarkSelection<'a> {
-    /// In-range rows with [`FLAG_IN_RANGE_ICON`]: the `Icon` POIIcons cell at true position.
+    /// In-range rows with [`FLAG_IN_RANGE_ICON`], drawn at their position.
     pub(super) icons: Vec<&'a AreaPoi>,
-    /// The out-of-range nearest-3 `(dist, poi, art)` in rank order: rim arrows. The art is the
-    /// reference's `+0x48` read ([`RimArrow`]) — a DBC row draws the white landmark arrow, the
-    /// appended guard marker the gold guide arrow.
+    /// The rim arrows `(dist, poi, art)` in rank order.
     pub(super) arrows: Vec<(f32, &'a AreaPoi, RimArrow)>,
 }
 
-/// The byte-verified landmark selection: candidacy (`ContinentID` + `Flags&1`), the 0.8
-/// in/out split against the live view radius, and the out-of-range nearest-3 ranked by
-/// (`Importance` signed asc, dist asc) within 694.444 yd.
-///
-/// `marker` is the guard-directions POI ([`crate::poi_marker`]) — the reference appends its
-/// static blip slot to the candidate list *after* the DBC scan, so it bypasses the candidacy
-/// gate and then competes as an equal for the rim slots. Equal, and no more: it gets **no**
-/// exemption from the 694.444-yd rank cut (that belongs to the corpse slot `0xcea848`, the only
-/// candidate `0x6d9cc2` spares).
+/// The landmark selection (module doc). `marker`, the guard-directions POI, is appended after
+/// the DBC scan as the reference appends its static blip slot: it skips the candidacy gate but
+/// not the 694.444-yd cut, which `0x6d9cc2` spares only the corpse slot `0xcea848`.
 pub(super) fn select_landmarks<'a>(
     pois: impl Iterator<Item = &'a AreaPoi>,
     marker: Option<&'a AreaPoi>,
@@ -380,8 +262,7 @@ pub(super) fn select_landmarks<'a>(
     LandmarkSelection { icons, arrows }
 }
 
-/// `POIIcons.blp` cell for a DBC `Icon` index as `[l, r, t, b]` tex coords — the 8×8 grid of
-/// 16-px cells, gated `Icon < 0x40` exactly like the client (`0x4ed15e`).
+/// The `POIIcons.blp` 8×8-grid cell for an `Icon`, gated `Icon < 0x40` (`0x4ed15e`).
 fn poi_icon_cell(icon: u32) -> Option<[f32; 4]> {
     if icon >= 64 {
         return None;
@@ -390,9 +271,7 @@ fn poi_icon_cell(icon: u32) -> Option<[f32; 4]> {
     Some([c / 8.0, (c + 1.0) / 8.0, r / 8.0, (r + 1.0) / 8.0])
 }
 
-/// Draw the landmark layer: in-range POI icons at position, then the nearest-3 rim arrows,
-/// each rotated to point at its POI. Records a hover hit (later-drawn wins, matching draw
-/// order).
+/// Draw the in-range POI icons, then the rim arrows; the later-drawn hover hit wins.
 pub(super) fn emit_landmarks(
     ctx: &BlipCtx,
     cat: Option<&AreaPoiCatalog>,
@@ -436,8 +315,6 @@ pub(super) fn emit_landmarks(
         }
     }
     for (_d, poi, art) in &sel.arrows {
-        // No art for this source ⇒ no arrow. Drawing another source's would be a lie about
-        // which kind of thing is out there, which is the whole job of the four arts.
         let Some(tex) = arrows.get(*art) else {
             continue;
         };
@@ -450,13 +327,8 @@ pub(super) fn emit_landmarks(
     }
 }
 
-/// One rim arrow: parked on the 0.8 rim in the target's direction and spun to point at it.
-/// Returns its screen rect, for the hover hit-test.
-///
-/// ONE pass of the texture. The model authors six quads, but replaying a stack as flat UI quads
-/// read as solid blobs (director, 2026-07-13 — the reference runs it through the model material
-/// pipeline, whose blend mode is unread); the single soft pass is the approved look, and 1519's
-/// measurement says it is also the exact one — only a single layer is ever opaque.
+/// One rim arrow on the 0.8 rim, pointing at its target, drawn in one pass as only one of the
+/// model's layers is ever opaque. Returns its rect for the hover test.
 fn push_rim_arrow(
     ctx: &BlipCtx,
     target: [f32; 3],
@@ -465,8 +337,7 @@ fn push_rim_arrow(
 ) -> Rect {
     let dir = ctx.offset(target).normalize_or_zero();
     let pos = ctx.center + dir * (ctx.side * 0.5 * BLIP_EDGE_RATIO);
-    // Point the arrow at its target: quad rotation is clockwise on a y-down screen, and the
-    // authored art reads screen-up at zero, so up→dir is atan2(x, -y).
+    // Quad rotation is clockwise on a y-down screen and the art points up at zero.
     let rotation = dir.x.atan2(-dir.y);
     let rect = Rect::from_center_size(pos, Vec2::splat(ctx.side * (ARROW_QUAD_PX / BLIP_BASIS_PX)));
     quads.overlays.push(UiQuad {
@@ -480,9 +351,8 @@ fn push_rim_arrow(
     rect
 }
 
-/// A party member's blip position: the live streamed transform wins; out of visibility range the
-/// `PARTY_MEMBER_STATS` snapshot position covers (the wire truncates to i16 — yard precision,
-/// invisible at minimap scale). No source → no blip (offline members carry no position).
+/// A party member's position: the streamed transform, else the `PARTY_MEMBER_STATS` position
+/// (whole yards on the wire).
 pub(crate) fn party_member_pos(
     m: &benilla_protocol::messages::GroupMemberEntry,
     group: &crate::ui_party::GroupState,
@@ -500,29 +370,13 @@ pub(crate) fn party_member_pos(
         .map(|(x, y)| (f32::from(x), f32::from(y)))
 }
 
-/// The party/corpse **rim arrows** — the out-of-range half of the party blip placement
-/// (`0x6dad10`): `d = √(dx²+dy²)`; over `0.8·radius` the member rides the 0.8 rim,
-/// rotated to the atan2 bearing (the 5-slot sibling array `this+0x320`). Drawn with the POI arrows
-/// — before the player arrow; the in-range members become dots in [`emit_party_dots`], drawn last
-/// with the object dots.
+/// The party and corpse rim arrows, the out-of-range half of the party placement `0x6dad10`,
+/// drawn before the player arrow.
 ///
-/// **The two sources draw different art** (1519), which this pass used to get wrong twice over: it
-/// drew both with `MinimapArrow` — the *player* arrow, not a rim arrow at all. A member is the
-/// party frames' `0xa5` ⇒ [`RimArrow::Group`]; your corpse is the corpse blip's `0xa7` ⇒
-/// [`RimArrow::Corpse`], the art named for it. Both confirmed at the bytes (1525).
-///
-/// **But the corpse does not belong in this array, and the slot it occupies belongs to your PET**
-/// (1525, VERIFIED — recorded here, not yet built, because it is a visible change to the corpse
-/// blip 0308 rather than to this session's arrow art). `0x6dad10`'s loop splits at
-/// `0x6dad60 cmp edi,4`: slots 0–3 are the party GUIDs via `0x4e81a0`, and slot **4** reads
-/// `UNIT_FIELD_CHARM` else `UNIT_FIELD_SUMMON` off the descriptor base — the pet. Both legs fetch
-/// with typemask UNIT (`mov ecx,8`), and a `CGCorpse` is typemask `0x80`, so a corpse could never
-/// resolve there. The corpse reaches the minimap **only** as static blip slot 2 on the
-/// POI path, which is a materially different producer: `Importance = -1` (so it outranks every
-/// landmark and *takes* one of the three rim slots rather than adding a fourth), and the sole
-/// exemption from the 694.444-yd cut at `0x6d9cc2`. Two consequences we currently get wrong — we
-/// can draw four rim arrows where the reference draws three — and one feature we are missing
-/// outright: the **pet blip**.
+/// This differs from the reference, not built yet: its slot 4 is the pet (`UNIT_FIELD_CHARM`,
+/// else `UNIT_FIELD_SUMMON`, at `0x6dad60`), and the corpse is static blip slot 2 on the POI path,
+/// at `Importance` -1 and exempt from the 694.444-yd cut, taking one of the three rim slots.
+/// So there is no pet blip here, and four rim arrows can draw where the reference draws three.
 pub(super) fn emit_party_arrows(
     ctx: &BlipCtx,
     group: &crate::ui_party::GroupState,
@@ -540,7 +394,7 @@ pub(super) fn emit_party_arrows(
     for ((x, y), art) in members.chain(corpse) {
         let d = ((x - ctx.wx).powi(2) + (y - ctx.wy).powi(2)).sqrt();
         if d / ctx.radius_yd <= BLIP_EDGE_RATIO {
-            continue; // in range — the dot pass draws it
+            continue; // in range: the dot pass draws it
         }
         let Some(tex) = arrows.get(art) else {
             continue;
@@ -549,13 +403,9 @@ pub(super) fn emit_party_arrows(
     }
 }
 
-/// Push the hovered blip's name tooltip: a landmark's AreaPOI name or a tracked GO's template
-/// name outright, a unit dot's (quest or tracked) name through the ask-once `NameCache` (the
-/// first hover may show one frame late while the `SMSG_NAME_QUERY` answer lands — the
-/// reference resolves the guid through its own name cache the same way). Hover loss arms the
-/// world tooltip fade, never an instant hide. Runs after
-/// the mouseover drive (`UnitFeed`) so a same-frame world-hover→blip transition ends with the
-/// blip tooltip shown.
+/// Show the hovered blip's name; a unit's resolves through the name cache. Hover loss fades the
+/// tooltip, never hides it at once. Runs after `UnitFeed`, so a same-frame move from a world
+/// hover to a blip ends on the blip's tooltip.
 pub(super) fn drive_blip_tooltip(
     script: Option<NonSendMut<UiScript>>,
     hover: Res<MinimapBlipHover>,
@@ -576,8 +426,7 @@ pub(super) fn drive_blip_tooltip(
         MinimapBlipHover::TrackedGo(name, at, grey) => Some((name.clone(), *at, *grey)),
     };
     match (&show, &*last) {
-        // Same blip, cursor drifted: the plate FOLLOWS the pointer (anchor-only re-seat —
-        // the reference's blip tooltip tracks the cursor; director-verified).
+        // Same blip: the reference's blip tooltip follows the cursor.
         (Some((t, at, _)), Some((lt, lat))) if t == lt => {
             if at != lat {
                 script.world_tooltip_move(at.x, at.y);
@@ -600,16 +449,7 @@ pub(super) fn drive_blip_tooltip(
 mod tests {
     use super::*;
 
-    /// **The whole [`RimArrow`] table, re-measured against the install's own model.**
-    ///
-    /// This is the fact the feature rests on, and it is not one you can read off the reference's
-    /// call site: `0x4ed349`–`0x4ed37b` only proves *which id* each blip source plays. What that id
-    /// draws lives in `Rotating-MinimapArrow.m2`, so the model is the authority, and asserting
-    /// against it means a wrong row here fails rather than shipping the wrong arrow.
-    ///
-    /// It checks both directions on purpose: each sequence lights **exactly one** layer (a table
-    /// that merely named a texture the sequence happens to show would pass a one-sided check while
-    /// three other arrows drew on top of it), and that layer is the one this table claims.
+    /// The call site gives only the sequence id; the model says what it draws.
     #[test]
     fn each_rim_arrow_sequence_lights_exactly_its_own_layer() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -652,11 +492,7 @@ mod tests {
         }
     }
 
-    /// The real Northshire shape (5875 AreaPOI.dbc rows, distances from a player near the
-    /// abbey, the default zoom's 133-yd radius): Echo Ridge Mine (Flags 4, no bit 0) is not a
-    /// candidate at all; Northshire Abbey (Flags 5, in-range, bit 1 clear) draws neither icon
-    /// nor arrow; Stormwind and Goldshire (out-of-range, both Importance 3) become the rim
-    /// arrows in distance order.
+    /// Real 1.12 AreaPOI rows near Northshire Abbey at the default zoom's 133-yd radius.
     #[test]
     fn northshire_shape_under_the_byte_law() {
         let rows = [
@@ -671,9 +507,7 @@ mod tests {
         assert_eq!(names, ["Stormwind", "Goldshire"]);
     }
 
-    /// The rank key is Importance (signed asc), distance only as the tiebreak — a nearer row
-    /// of higher Importance ranks BELOW a farther low-Importance one (the fold-back's C2
-    /// correction: the key is DBC column 1, not AreaID).
+    /// The rank key is `Importance` (DBC column 1), not AreaID; distance only breaks ties.
     #[test]
     fn arrow_rank_is_importance_then_distance_capped_at_three() {
         let rows = [
@@ -688,10 +522,7 @@ mod tests {
         assert_eq!(names, ["minor-near", "minor-far", "city-near"]);
     }
 
-    /// The guard's directions marker ([`crate::poi_marker`]) is a landmark candidate like any
-    /// other — and, carrying the reference's `Importance 0`, it takes a rim slot ahead of the
-    /// town/city rows a capital is thick with. Out of the four here only three arrows draw, and
-    /// the marker is one of them despite being the farthest.
+    /// The marker carries `Importance` 0, so it outranks the cities though farthest.
     #[test]
     fn the_guard_marker_competes_for_a_rim_slot_and_outranks_the_cities() {
         let cities = [
@@ -707,8 +538,6 @@ mod tests {
             ["Stormwind Warrior Trainer", "Stormwind", "Goldshire"],
             "Importance 0 ranks the marker first; the third city is crowded out"
         );
-        // …and it is drawn in gold, not in the cities' white: the reference's `+0x48` read
-        // (1519). A rim slot won with the wrong art would look like just another town.
         let arts: Vec<RimArrow> = sel.arrows.iter().map(|&(_, _, a)| a).collect();
         assert_eq!(
             arts,
@@ -717,9 +546,7 @@ mod tests {
         );
     }
 
-    /// In range, the marker draws its own `POIIcons` cell at its true position — `Flags & 2` is
-    /// set on every 5875-era `points_of_interest` row (99 = 0x63), so unlike an ordinary town it
-    /// keeps drawing once you are close.
+    /// Every 1.12 `points_of_interest` row carries flags 99 (0x63), so `Flags & 2` is set.
     #[test]
     fn the_guard_marker_draws_its_icon_in_range() {
         let marker = poi(0, 0x63, 50.0, "The Bank");
@@ -733,19 +560,15 @@ mod tests {
         );
     }
 
-    /// The marker bypasses the candidacy gate the DBC rows pass through — the reference appends
-    /// its static blip slot *after* the scan. It is the caller ([`crate::poi_marker::PoiMarker`]'s
-    /// `on_map`) that decides the marker belongs to this map, not this filter.
+    /// The caller ([`crate::poi_marker::PoiMarker`]'s `on_map`) decides the marker's map.
     #[test]
     fn the_guard_marker_skips_the_candidacy_filter() {
-        let mut marker = poi(0, 0, 300.0, "The Inn"); // Flags bit 0 CLEAR — a DBC row would drop
+        let mut marker = poi(0, 0, 300.0, "The Inn"); // Flags bit 0 clear: a DBC row would drop
         marker.continent_id = 571; // and a continent that isn't the displayed one
         let sel = select_landmarks(std::iter::empty(), Some(&marker), 0, 0.0, 0.0, 133.0);
         assert_eq!(sel.arrows.len(), 1, "appended unconditionally");
     }
 
-    /// An in-range row draws the icon only with Flags bit 1; the `Icon < 64` gate and the
-    /// 8×8 cell math match the client's table build.
     #[test]
     fn in_range_icons_gate_on_flag_bit1_and_the_atlas_bound() {
         let mut tower = poi(0, 0x87, 50.0, "Crown Guard Tower");
diff --git a/crates/benilla-app/src/minimap/composite.rs b/crates/benilla-app/src/minimap/composite.rs
index 7a8640db..46475873 100644
--- a/crates/benilla-app/src/minimap/composite.rs
+++ b/crates/benilla-app/src/minimap/composite.rs
@@ -1,32 +1,13 @@
-//! The WMO-interior minimap's **offscreen composite** — the client's own compositing pipeline
-//! (decision 1466).
+//! The WMO-interior minimap's offscreen composite, the reference's own pipeline: tiles drawn into
+//! a 256 × 256 target (`0x4eda42`/`0x4eda48`) under an ortho half-extent of 1.5 × the view radius
+//! (`0x4ec130`, the factor at `0x80308c`), cleared colour-only to opaque black (unpacked at
+//! `0x59b910`), blending off and alpha-tested at `GEQUAL 224/255`; the blit shows the middle
+//! two-thirds, netting 1.0 × radius on screen.
 //!
-//! Indoors the reference does not draw the group tiles onto the screen. It draws them into a fixed
-//! **256 × 256** render target created once at `0x4eda42`/`0x4eda48`, under an ortho half-extent of
-//! **1.5 × the view radius** (`0x4ec130`, the `× 1.5` at `0x80308c`), cleared **colour-only** to
-//! opaque black (the packed `0xAARRGGBB` unpacked at `0x59b910`), with **blending disabled** and an
-//! **alpha test** at `GEQUAL 224/255` — then blits the **middle two-thirds** of that target, which
-//! is what nets the `1.0 × radius` on screen.
-//!
-//! **Both halves of that are load-bearing, and they only work together.** The alpha test is what
-//! stops two group tiles that meet along a shared wall from leaving the clear colour between them
-//! (blended, each contributes a filtered partial edge and up to 25% of the black shows through —
-//! B141's "odd black lines", at *every* joint). But the target's resolution is what stops the
-//! **genuine** gaps in the bake from reading: `3 · radius / 256` model-yd per texel is 0.703 yd at
-//! the default indoor zoom against the tiles' authored 0.5 — a ~1.4× **minification before the
-//! test**, in which a one-texel bake gap is simply never sampled. Drawing the tiles alpha-tested
-//! straight to the screen, where we rasterise ~1.85× *finer* than the client ever did, turns those
-//! same gaps from a soft grey line into a hard black one — measured, and the reason this module
-//! exists rather than just the render state (1466's "why part 1 alone makes it worse").
-//!
-//! Mechanically: [`super::emit_minimap`]'s interior branch fills [`MinimapComposite`] with this
-//! frame's tiles in **target space** instead of pushing them at the screen; [`drive_composite`]
-//! materialises them as pooled quads on the composite camera's own render layer; and the interior
-//! branch draws ONE screen quad sampling the target, masked to the minimap circle as usual.
-//!
-//! The tiles ride a **shared unit-quad mesh and a per-texture material**, moving on their
-//! `Transform` alone (1463's law): the composite re-aims every frame the player walks, and
-//! rebuilding ~50 meshes a frame to express a pan is exactly the churn that pass avoids.
+//! The alpha test and the target's resolution only work together: the test keeps the clear from
+//! showing where two tiles meet at a shared wall, and the coarse target (0.703 yd per texel at the
+//! default indoor zoom, against the bake's 0.5) minifies before the test, so a one-texel gap in
+//! the bake is never sampled. Alpha-tested straight to the screen, those gaps read as black lines.
 
 use bevy::asset::RenderAssetUsages;
 use bevy::camera::visibility::RenderLayers;
@@ -37,66 +18,56 @@ use bevy::render::render_resource::{Extent3d, TextureDimension, TextureFormat, T
 use crate::portrait::MINIMAP_COMPOSITE_LAYER;
 use crate::ui_pass::UiQuadMaterial;
 
-/// The composite target's edge, in texels — the client's `mov edx,0x100` at `0x4eda42`. It is a
-/// **fidelity constant, not a quality knob**: raising it re-opens the hairlines this module exists
-/// to close, because the bake's own one-texel gaps stop being sub-texel (see the module docs).
+/// The target's edge in texels (`0x4eda42`). A fidelity constant, not a quality knob: a larger
+/// target samples the bake's one-texel gaps and draws them as hairlines.
 pub(super) const RT_SIZE: u32 = 256;
 
-/// The composite's ortho half-extent as a multiple of the on-screen view radius (`0x80308c`). The
-/// target holds 1.5 × what is shown; the blit takes the middle two-thirds back out.
+/// The target's ortho half-extent as a multiple of the on-screen view radius (`0x80308c`).
 pub(super) const RT_HALF_EXTENT_SCALE: f32 = 1.5;
 
-/// The fraction of the target's edge the blit shows — `1 / RT_HALF_EXTENT_SCALE`, i.e. the middle
-/// two-thirds, which is what nets `1.0 × radius` on screen.
+/// The fraction of the target's edge the blit shows, netting 1.0 × radius on screen.
 pub(super) const RT_BLIT_FRACTION: f32 = 1.0 / RT_HALF_EXTENT_SCALE;
 
-/// One tile to composite, already in **target space**: the camera's y-up units, origin at the
-/// target's centre (= the player), `RT_SIZE / 2` units to an edge.
+/// One tile in target space: y-up, origin at the target's centre (the player), `RT_SIZE / 2`
+/// units to an edge.
 pub(super) struct CompositeTile {
     pub(super) texture: Handle<Image>,
     /// Centre, in target units.
     pub(super) center: Vec2,
     /// Size, in target units.
     pub(super) size: Vec2,
-    /// The placement yaw, as a **clockwise-on-screen** angle (what the screen path uses); negated
-    /// on the way into the camera's y-up frame.
+    /// The placement yaw, clockwise on screen; negated into the camera's y-up frame.
     pub(super) rotation: f32,
-    /// Draw order within the composite — ascending draws later (on top), matching the group sort.
+    /// Ascending draws later (on top), matching the group sort.
     pub(super) order: usize,
 }
 
-/// This frame's interior composite: the tiles to draw and whether the composite is live at all.
-/// Written by [`super::emit_minimap`], consumed by [`drive_composite`].
+/// This frame's interior composite, filled by [`super::emit_minimap`] for [`drive_composite`].
 #[derive(Resource, Default)]
 pub(super) struct MinimapComposite {
-    /// `false` = outdoors (or no minimap widget): the camera is switched off and the pool retires.
+    /// `false` outdoors or with no minimap widget: the camera is off and the pool empties.
     pub(super) active: bool,
     pub(super) tiles: Vec<CompositeTile>,
 }
 
-/// The composite's durable pieces: the target image, its camera, the shared quad mesh, the
-/// per-texture material cache and the entity pool.
+/// The composite's durable pieces: target, camera, shared quad, material cache and entity pool.
 #[derive(Resource)]
 pub(super) struct CompositeRig {
-    /// The render target — sampled by the blit quad on the screen lane.
+    /// The render target, sampled by the blit quad.
     pub(super) image: Handle<Image>,
     camera: Entity,
     quad: Handle<Mesh>,
-    /// Materials keyed by tile texture. A WMO's tile set is small and stable while you are inside
-    /// it, so this fills once per building rather than per frame.
+    /// Materials by tile texture; a building's tile set is small, so this fills once per building.
     materials: bevy::platform::collections::HashMap<AssetId<Image>, Handle<UiQuadMaterial>>,
     pool: Vec<Entity>,
 }
 
 /// Build the target, its camera and the shared quad once, at startup.
 ///
-/// The target is **un-encoded** and float, exactly like the portrait booths' (decisions 0254/0804):
-/// the UI arc composites in gamma bytes and does its one sRGB encode at the end, so a target that
-/// pre-encoded would land a second encode downstream — and quantising un-encoded values to 8 bits
-/// is B126's banding collapse, which a map of large flat colour fields would show as plainly as the
-/// glue screens did. The tile draw therefore writes the sampled texel **un-encoded** (the
-/// [`UiQuad::alpha_test`](crate::ui_pass::UiQuad::alpha_test) arm in `ui_quad.wgsl`), and the blit
-/// quad encodes it on the way to the screen like any other UI texture.
+/// The target is float and un-encoded, like the portrait booths': the UI pass does its one sRGB
+/// encode at the end, and un-encoded 8-bit values band. The tile draw writes the texel un-encoded
+/// (the [`UiQuad::alpha_test`](crate::ui_pass::UiQuad::alpha_test) arm in `ui_quad.wgsl`) and the
+/// blit quad encodes it like any other UI texture.
 pub(super) fn setup_composite(
     mut commands: Commands,
     mut images: ResMut<Assets<Image>>,
@@ -117,29 +88,24 @@ pub(super) fn setup_composite(
         TextureUsages::TEXTURE_BINDING | TextureUsages::COPY_DST | TextureUsages::RENDER_ATTACHMENT;
     let image = images.add(image);
 
-    // A 1×1 quad centred on the origin: every tile is this mesh under its own Transform, so a
-    // panning composite never rewrites a vertex buffer (1463). Its layout is a pipeline key axis
-    // and pipe_warm warms the same mesh, so the builder has one author (2262).
+    // A 1×1 quad at the origin, every tile a Transform of it. `pipe_warm` warms this same mesh (its
+    // layout is a pipeline key axis), so both take it from one builder.
     let quad = meshes.add(crate::ui_pass::tile_quad_mesh());
 
     let camera = commands
         .spawn((
             Name::new("minimap composite camera"),
             Camera2d,
-            // **No MSAA** — the client's target is a plain RGBA8 surface with none, and here it is
-            // load-bearing rather than cosmetic: multisampling an alpha-TESTED edge hands back
-            // partial coverage, and partial coverage over an opaque black clear is precisely the
-            // grey seam this whole module exists to remove. The test's whole point is that a
-            // fragment is all or nothing.
+            // No MSAA, like the reference's plain RGBA8 target: multisampling an alpha-tested edge
+            // gives partial coverage over the black clear, the grey seam this target removes.
             bevy::render::view::Msaa::Off,
             RenderLayers::layer(MINIMAP_COMPOSITE_LAYER),
             RenderTarget::Image(image.clone().into()),
             Camera {
-                // The client's clear: colour only, opaque black (`0x4ec8ef`, mask 1). Everything
-                // the bake does not cover reads as this — including, faithfully, the exterior
-                // group's whole footprint, which has no authored tile at all.
+                // The reference's clear: colour only, opaque black (`0x4ec8ef`, mask 1). Anything
+                // the bake leaves uncovered reads black, the exterior group's footprint included.
                 clear_color: ClearColorConfig::Custom(Color::BLACK),
-                // Off until the player is indoors; `drive_composite` owns the switch.
+                // Off until indoors; `drive_composite` owns the switch.
                 is_active: false,
                 ..default()
             },
@@ -165,8 +131,8 @@ pub(super) fn setup_composite(
     });
 }
 
-/// Materialise [`MinimapComposite`] onto the composite camera: one pooled entity per tile, each the
-/// shared quad under a Transform, each wearing its texture's cached material.
+/// Draw [`MinimapComposite`] on the composite camera: one pooled entity per tile, the shared quad
+/// under a Transform with its texture's cached material.
 pub(super) fn drive_composite(
     mut composite: ResMut<MinimapComposite>,
     rig: Option<ResMut<CompositeRig>>,
@@ -189,8 +155,7 @@ pub(super) fn drive_composite(
         return;
     }
 
-    // Ascending order draws later. The composite camera's own ortho spans ±0.5·RT_SIZE in z by
-    // default, so keep the span well inside it however many tiles a zoom level asks for.
+    // Ascending order draws later; z stays within -50..50 whatever the tile count.
     let count = composite.tiles.len().max(1);
     for (i, tile) in composite.tiles.iter().enumerate() {
         let material = rig
diff --git a/crates/benilla-app/src/minimap/interior.rs b/crates/benilla-app/src/minimap/interior.rs
index 90240a06..e7d05045 100644
--- a/crates/benilla-app/src/minimap/interior.rs
+++ b/crates/benilla-app/src/minimap/interior.rs
@@ -1,48 +1,33 @@
-//! The WMO-interior minimap's group selection — the portal flood-fill + the tile-name stem
-//! (split from the tile renderer; the mechanism and its byte provenance are unchanged).
+//! The WMO-interior minimap's group selection (the portal flood-fill) and tile-name stem.
 
 use bevy::math::{Affine3A, Vec3};
 
 use benilla_assets::coords::{bevy_to_wow, wow_to_bevy};
 use benilla_assets::WmoModel;
 
-/// MOGP group flags read by the interior flood-fill: `EXTERIOR` (an outdoor shell group — not part of
-/// the interior tile flood) and `UNREACHABLE`/no-render (`0x80`) which also suppresses tile emit. The
-/// client skips `& 0x8` at the flood level (`0x6a5020`) and `& 0x88` at the emit level
+/// MOGP flags: the flood skips `& 0x8` exterior groups (`0x6a5020`), the emit skips `& 0x88`
 /// (`0x6a5270`).
 const GROUP_EXTERIOR: u32 = 0x8;
 const GROUP_NO_EMIT: u32 = 0x88;
 
-/// The `md5translate.trs` key stem for a WMO's interior minimap tiles, from its `.wmo` asset path.
-/// The reference builds the tile name by stripping the `World\` prefix and the `.wmo` extension off
-/// the model filename (name builder `0x6da330`), e.g.
-/// `World\wmo\KhazModan\Cities\Ironforge\Ironforge.wmo` → `wmo\khazmodan\cities\ironforge\ironforge`.
-/// Backslash-separated + lowercased (the trs lookup is case-insensitive). `None` if not a
-/// `World\…\*.wmo`.
+/// The `md5translate.trs` key stem of a WMO's interior tiles: the model path without `World\` and
+/// `.wmo` (name builder `0x6da330`), backslashed and lowercased, the trs lookup being
+/// case-insensitive. `None` if not a `World\…\*.wmo`.
 pub(super) fn wmo_minimap_stem(wmo_path: &str) -> Option<String> {
     let p = wmo_path.replace('/', "\\").to_ascii_lowercase();
     let stem = p.split_once("world\\")?.1.strip_suffix(".wmo")?;
     Some(stem.to_string())
 }
 
-/// The interior minimap's group selection: a **portal flood-fill** from the player's current group,
-/// gated by a player-centred query box — the client mechanism (the flood `0x6a5020`). Returns, per
-/// absolute group index, whether that group's tiles should be drawn (reached through portals AND
-/// its bbox overlaps the view in XY). Replaces the naive draw-every-group-in-the-window, which
-/// painted unreachable/far floors over the current one.
+/// Which groups' tiles draw, per absolute group index: the reference's portal flood-fill from the
+/// player's group (`0x6a5020`) inside a player-centred query box.
 ///
-/// The query box (WoW **world** axes; the client builds it in the WMO model frame, but the overlap
-/// decisions are frame-agnostic so we test in world space — the group bboxes and portal polygons are
-/// transformed by the placement to match): XY = the view window grown to `±2·radius`; **Z is
-/// asymmetric, `[player.z − 1.5·radius, player.z + radius]`** — mostly *below* the eye, so from a floor
-/// you reach the storey just under it through a stairwell but not the whole tower. A group EMITS when
-/// its bbox overlaps the box in **XY only** (no per-group Z test — the client has none). The **same
-/// XY overlap gates the portal RECURSION** (a miss returns at `0x6a51f4`): a group that fails the
-/// XY test neither emits nor floods onward. For an XY-passing group, each portal is CROSSED when
-/// its polygon is not fully outside any of the box's **6 planes** (a 3-D outcode cull *including Z*
-/// — the only per-floor Z gate the client applies; stacked floors share an XY footprint, so an
-/// adjacent storey passes its own XY gate and is reached through the stairwell portal). `EXTERIOR`
-/// (`0x8`) groups are not interior-flooded; `0x88` groups emit no tiles.
+/// The box is XY `±2·radius` and Z `[z − 1.5·radius, z + radius]`, mostly below the player, so a
+/// stairwell reaches the storey below but not the whole tower. A group whose bbox misses the box in
+/// XY neither emits nor floods onward (`0x6a51f4`); there is no per-group Z test. A portal is
+/// crossed unless its polygon lies wholly outside one of the box's six planes, the only Z gate.
+/// The reference builds the box in model space; testing in world space with the bboxes and portals
+/// transformed gives the same answers.
 pub(super) fn interior_group_selection(
     model: &WmoModel,
     world_from_local: &Affine3A,
@@ -60,10 +45,10 @@ pub(super) fn interior_group_selection(
     let box_min = [pw[0] - 2.0 * c, pw[1] - 2.0 * c, pw[2] - 1.5 * c];
     let box_max = [pw[0] + 2.0 * c, pw[1] + 2.0 * c, pw[2] + c];
 
-    // A model-space point → world (WoW axes), the frame the query box lives in.
+    // A model point to world (WoW axes), the query box's frame.
     let to_world = |m: [f32; 3]| bevy_to_wow(world_from_local.transform_point3(wow_to_bevy(m)));
-    // A group's model bbox → its world AABB (8 transformed corners) — a conservative superset under a
-    // rotated placement, fine for the emit gate (an over-included far group is window-culled at draw).
+    // A group's model bbox as a world AABB: a superset under a rotated placement, and the draw's
+    // window cull trims the excess.
     let world_aabb = |bmin: [f32; 3], bmax: [f32; 3]| {
         let (mut lo, mut hi) = ([f32::INFINITY; 3], [f32::NEG_INFINITY; 3]);
         for &x in &[bmin[0], bmax[0]] {
@@ -82,7 +67,7 @@ pub(super) fn interior_group_selection(
     let xy_overlap = |lo: [f32; 3], hi: [f32; 3]| {
         lo[0] <= box_max[0] && hi[0] >= box_min[0] && lo[1] <= box_max[1] && hi[1] >= box_min[1]
     };
-    // 6-plane outcode of a world point against the box (1 bit per face it is outside of).
+    // 6-plane outcode of a world point against the box, one bit per face it is outside.
     let outcode = |w: [f32; 3]| {
         let mut o = 0u8;
         for k in 0..3 {
@@ -105,21 +90,18 @@ pub(super) fn interior_group_selection(
         visited[g] = true;
         let gn = &model.group_nav[g];
         if gn.flags & GROUP_EXTERIOR != 0 {
-            continue; // an outdoor shell group — not part of the interior flood
+            continue; // an exterior group is not flooded
         }
         let (lo, hi) = world_aabb(gn.bbox_min, gn.bbox_max);
-        // XY-OVERLAP GATE (a miss returns at `0x6a51f4`): a group whose model-XY bbox misses the
-        // query window emits NOTHING and does NOT flood onward — the gate blocks emit AND recursion
-        // both. Stacked storeys share an XY footprint, so an adjacent floor still passes it (and is
-        // reached via the stairwell portal's 3-D cull below).
+        // The XY gate blocks emit and recursion both (`0x6a51f4`); a stacked storey shares the XY
+        // footprint and passes it.
         if !xy_overlap(lo, hi) {
             continue;
         }
         if gn.flags & GROUP_NO_EMIT == 0 {
             drawable[g] = true;
         }
-        // PORTAL RECURSION: cross a portal iff its polygon is not fully outside any box plane (3-D,
-        // Z included). This is the only place a floor above/below is gated out.
+        // Cross a portal unless its polygon is wholly outside one box plane, Z included.
         let start = gn.ref_start as usize;
         let end = (start + gn.ref_count as usize).min(model.portal_refs.len());
         for r in &model.portal_refs[start..end] {
@@ -138,7 +120,7 @@ pub(super) fn interior_group_selection(
             for v in poly {
                 and &= outcode(to_world(*v));
                 if and == 0 {
-                    break; // not fully outside any one plane ⇒ the portal reaches into the box
+                    break; // outside no single plane: the portal reaches into the box
                 }
             }
             if and == 0 {
@@ -151,15 +133,9 @@ pub(super) fn interior_group_selection(
 
 #[cfg(test)]
 mod tests {
-    /// The interior flood-fill's two gates, on a synthetic 4-group building (all sharing one XY
-    /// footprint except `far`, which sits 1000 yd away):
-    ///   `player(g0)` ──floor-hole portal──> `cellar(g1)`  both under the query box ⇒ both drawn
-    ///   `player(g0)` ──in-box portal─────-> `far(g2)`      reached, bbox misses XY ⇒ NOT drawn
-    ///   `far(g2)`    ──portal────────────-> `behind(g3)`   must NOT be reached: the XY gate that
-    ///                                                      rejected g2 also blocks flooding THROUGH it
-    /// The last leg is the reference's recursion gate (the XY gate blocks emit *and* recursion,
-    /// `0x6a51f4`). `behind`'s own bbox does overlap the box, so it would draw if recursion had
-    /// leaked through `far`.
+    /// A 4-group building: g0 (the player's) and g1 (a cellar) join by a floor hole and both draw;
+    /// g2 sits 1000 yd off in XY, reached but not drawn; g3 overlaps the box but is reachable only
+    /// through g2, by a portal inside the box, so only g2's XY gate keeps it out (`0x6a51f4`).
     #[test]
     fn interior_flood_fill_gates_on_xy_and_blocks_recursion_through_a_missed_group() {
         use super::interior_group_selection;
@@ -188,13 +164,7 @@ mod tests {
         let mut portal_vertices = Vec::new();
         portal_vertices.extend(poly(0.0, 0.0)); // portal 0: g0<->g1, a floor hole at the player
         portal_vertices.extend(poly(4.0, 1.0)); // portal 1: g0<->g2, well inside the query box
-                                                // portal 2: g2<->g3, deliberately placed INSIDE the query box, so the 3-D outcode cull would
-                                                // happily cross it. The ONLY thing that stops g3 being reached is g2 failing its own XY gate
-                                                // — which is exactly the behaviour under test (a
-                                                // box-outside portal would pass this test even with
-                                                // the pre-correction emit-only gate, and so would
-                                                // prove nothing).
-        portal_vertices.extend(poly(3.0, 1.0));
+        portal_vertices.extend(poly(3.0, 1.0)); // portal 2: g2<->g3, also inside the box
         let info = |start: u16| WmoPortalInfo {
             start_vertex: start,
             count: 4,
@@ -267,8 +237,8 @@ mod tests {
         );
     }
 
-    /// The box's Z extent is what keeps a distant storey out: put the connecting portal far below the
-    /// box floor and the 3-D outcode cull stops the flood before it.
+    /// The box's Z extent keeps a distant storey out: a portal far below the box floor is not
+    /// crossed.
     #[test]
     fn interior_flood_fill_rejects_a_portal_outside_the_query_box_z_extent() {
         use super::interior_group_selection;
@@ -350,8 +320,8 @@ mod tests {
     #[test]
     fn wmo_stem_strips_world_prefix_and_extension() {
         use super::wmo_minimap_stem;
-        // The interior tile key stem = the .wmo path minus `World\` and `.wmo`, lowercased. Appending
-        // `_001_00_00.blp` reproduces the trs key `WMO\KhazModan\Cities\Ironforge\ironforge_001_00_00.blp`.
+        // The stem plus `_001_00_00.blp` is the trs key
+        // `WMO\KhazModan\Cities\Ironforge\ironforge_001_00_00.blp`.
         assert_eq!(
             wmo_minimap_stem("World/wmo/KhazModan/Cities/Ironforge/Ironforge.wmo").as_deref(),
             Some("wmo\\khazmodan\\cities\\ironforge\\ironforge"),
diff --git a/crates/benilla-app/src/minimap/mod.rs b/crates/benilla-app/src/minimap/mod.rs
index 55a82c94..c25f66c8 100644
--- a/crates/benilla-app/src/minimap/mod.rs
+++ b/crates/benilla-app/src/minimap/mod.rs
@@ -1,39 +1,20 @@
-//! The HUD minimap renderer (decision 0203 phase 1) — the app half of the `<Minimap>` widget.
+//! The HUD minimap renderer, the app half of the `<Minimap>` widget: [`emit_minimap`] fills the
+//! widget's `QuadContent::Minimap` hole with the tiles around the player, masked to
+//! `MinimapMask.blp`, and the player arrow on top; the widget's FrameXML children draw above.
 //!
-//! The engine side (benilla-ui) carries the widget's rect + zoom and emits a
-//! `QuadContent::Minimap` hole at the frame's own draw slot; `ui_script::extract::paint_script` parks that
-//! in [`MinimapWidget`], and [`emit_minimap`] (in the [`UiQuadAppend`] window) fills it: the
-//! streamed tile window around the player, clipped to the widget rect and masked to the
-//! `MinimapMask.blp` circle at present time, with the player arrow rotating on top. Children of
-//! the widget (border art, buttons, zone text — `MinimapCluster.xml`) draw above per the normal
-//! z order.
-//!
-//! Mechanism per the reference client (transcribed here):
-//! - **Tile grid**: one 256² minimap BLP per ADT tile (533.33 yd), named `map<X>_<Y>.blp` in the
-//!   map's directory and resolved through `md5translate.trs` to a hashed file under
-//!   `textures\Minimap\` ([`benilla_formats::MinimapTranslate`]). Index order = the ADT order
-//!   (chain-verified, see the formats re-export note).
-//! - **Zoom → world radius** (0x6da9b0): the client keeps **two** zoom indices,
-//!   selected by whether the player is inside a WMO. **Outdoors** the chunk-count table
-//!   `{14,12,10,8,6,4} · 0.5 · 33.333` yd of half-extent; **indoors** the radius table
-//!   `{150,120,90,60,40,25}` yd outright ([`INTERIOR_ZOOM_RADIUS`]). Each index persists separately
-//!   (CVars `minimapZoom` / `minimapInsideZoom`).
-//! - **North-up orientation**: screen up = world +X (north), screen left = world +Y (west).
-//!
-//! Tiles stream through the `mpq://` async asset source (the terrain streamer's hitch-free bulk
-//! path); handles cache per tile in [`MinimapTileCache`] and reset on a map change.
-//!
-//! Submodules: [`interior`] — the WMO-interior group selection (portal flood-fill) + tile-name
-//! stem; [`blips`] — the phase-3 blip layer (AreaPOI landmark arrows, quest-giver dots, the
-//! hover tooltip).
+//! - Tiles: one 256² BLP per ADT tile (533.33 yd), `map<X>_<Y>.blp` resolved through
+//!   `md5translate.trs` ([`benilla_formats::MinimapTranslate`]), indexed in ADT order.
+//! - Zoom to radius (`0x6da9b0`): two zoom indices, picked by WMO containment, each persisted
+//!   (`minimapZoom`, `minimapInsideZoom`); outdoors a chunk-count half-extent, indoors
+//!   [`INTERIOR_ZOOM_RADIUS`] yards.
+//! - North up: screen up is world +X, screen left world +Y.
 
 pub(crate) mod blips;
-/// The party blip's position law, shared with the world map (report B320): one function decides
-/// where a member is, so the two surfaces can never disagree about it.
+/// Where a party member is, shared with the world map so the two surfaces never disagree.
 pub(crate) use blips::party_member_pos;
 mod composite;
 mod interior;
-/// The minimap ping (decision 1596) — engine-owned and pinned to a world point.
+/// The minimap ping, engine-owned and pinned to a world point.
 mod ping;
 pub(crate) use ping::MinimapPing;
 
@@ -64,34 +45,20 @@ use benilla_world::world_map::CurrentMap;
 const TILE_YARDS: f32 = 533.333_3;
 const CHUNK_YARDS: f32 = TILE_YARDS / 16.0;
 
-/// The north-up zoom table (`0x8116d0`): view **diameter** in chunks per
-/// zoom index; half-extent = `chunks · 0.5 · 33.333` yd (0x6da9b0's unlocked leg).
-/// This is the **outdoor** zoom basis.
+/// The outdoor zoom table (`0x8116d0`): view diameter in chunks per zoom index; half-extent =
+/// `chunks · 0.5 · 33.333` yd (`0x6da9b0`).
 const ZOOM_CHUNKS: [f32; 6] = [14.0, 12.0, 10.0, 8.0, 6.0, 4.0];
 
-/// The **interior** minimap view radius per *indoor* zoom index, in yards — the client's radius table
-/// `0x8116e8`, indexed by the separate indoor zoom index `0x86f69c` (CVar `minimapInsideZoom`).
-/// Indoors the minimap has its **own zoom state**: a different index, a different table, and a
-/// radius in raw yards rather than the outdoor chunk half-extent. That is the "different zoom states
-/// inside vs outside" the director reported (2026-07-09).
+/// The indoor view radius in yards per indoor zoom index: table `0x8116e8`, indexed by `0x86f69c`
+/// (`minimapInsideZoom`). The on-screen radius is exactly this (the composite at `1.5·c`,
+/// `0x4ec090`, blits its middle two-thirds, `0x4ec440`), and the same `c` sizes the selection box
+/// (`0x6d96b6`).
 ///
-/// On-screen radius is exactly this value (the client composites the interior to an offscreen
-/// target at `1.5·c` in `0x4ec090` and blits its middle two-thirds in `0x4ec440`, netting `1.0·c`).
-/// The **same `c`** sizes the tile-selection query box (`0x6d96b6`), so selection and draw stay
-/// coherent.
-///
-/// NB the interior scale is not a compile-time constant (`10.0f` ⇒ a fixed 15 yd,
-/// zoom-independent): that `10.0f`, at `0x4ed9eb`, is only the *static initializer*, and the
-/// per-frame write `mov [esi+0xc], radiusTable[indoorZoom]` (`0x6d98f5`) reaches the field through
-/// a computed pointer. Do not "restore" a constant here.
+/// Not a constant: the `10.0f` at `0x4ed9eb` is only the field's static initializer, and
+/// `0x6d98f5` writes `radiusTable[indoorZoom]` into it whenever the zoom or indoor state changes.
 const INTERIOR_ZOOM_RADIUS: [f32; 6] = [150.0, 120.0, 90.0, 60.0, 40.0, 25.0];
 
-/// **How far the map reaches, in yards** — the one function that answers it. Indoors that is the
-/// interior radius table indexed by the *indoor* zoom; outdoors the chunk-count table's half-extent
-/// indexed by the outdoor zoom. Both branches of [`emit_minimap`] and the ping's world→normalized
-/// relay go through here, so "the view radius" can only ever mean one thing (the twin of
-/// [`blips::party_member_pos`]'s reason for existing: two surfaces disagreeing about the same
-/// number is a bug you find months later).
+/// How far the map reaches, in yards; both branches of [`emit_minimap`] and the ping read it here.
 fn view_radius_yd(zoom: u8, inside_zoom: u8, inside: bool) -> f32 {
     let clamp = |z: u8| usize::from(z.min(5));
     if inside {
@@ -101,17 +68,13 @@ fn view_radius_yd(zoom: u8, inside_zoom: u8, inside: bool) -> f32 {
     }
 }
 
-/// The **outer-edge bleed**: a minimap tile on the boundary of its group's grid is drawn 1.0 yd
-/// larger on that side, so a group's art extends 1 yd past its bbox all the way round and two
-/// groups whose boxes touch overlap by 2 yd. Interior cell edges are shared exactly. Byte-verified
-/// (`0x6a549e`…`0x6a54db`, the constant `0xca8098` built in the emitter as `0.5 + 0.5`) and fitted
-/// to the reference's captured quads with zero error.
+/// The outer-edge bleed: a tile on its group grid's boundary grows 1 yd on that side, so groups
+/// whose bboxes touch overlap by 2 yd (`0x6a549e`…`0x6a54db`, `0xca8098` = `0.5 + 0.5`).
 const EDGE_BLEED_YD: f32 = 1.0;
 
-/// The client's half-texel UV inset, as the quad scale that reproduces it: a tile spanning
-/// `extent` yards is baked at [`YD_PER_TEXEL`](benilla_assets::minimap_grid::YD_PER_TEXEL), so it
-/// is `W = extent / 0.5` texels wide, and mapping texel *centres* to the quad's edges instead of
-/// texel *edges* stretches it by `W / (W − 1)`. See the call site for why it matters.
+/// The reference's half-texel UV inset as a quad scale: a tile of `extent` yd baked at
+/// [`YD_PER_TEXEL`](benilla_assets::minimap_grid::YD_PER_TEXEL) is `W` texels wide, and mapping
+/// texel centres to the quad's edges stretches it by `W / (W − 1)`.
 fn texel_stretch(extent_yd: f32) -> f32 {
     let texels = extent_yd / benilla_assets::minimap_grid::YD_PER_TEXEL;
     if texels > 1.0 {
@@ -121,24 +84,17 @@ fn texel_stretch(extent_yd: f32) -> f32 {
     }
 }
 
-/// The interior tile draw's **alpha-test reference** — `224/255`, the client's
-/// `glAlphaFunc(GL_GEQUAL, 0.87843144)`. It is never set explicitly: the tile draw sets EGxBlend
-/// **1** (whose applicator `glDisable`s blending), and `SetRenderState`'s id-7→id-8 cascade reads
-/// `.data 0x85ad20[1] = 224` and multiplies by the f32 reciprocal of 255 — `0x3F60E0E2`, one ULP
-/// above `224/255`.
-/// Written as the exact f32 the client computes rather than the ratio, because that ULP is the
-/// value fragments are compared against.
+/// The interior tile draw's alpha-test reference, the reference's `GL_GEQUAL` 224/255. EGxBlend 1
+/// (blending off) leaves it to `SetRenderState`'s cascade, `.data 0x85ad20[1] = 224` times the f32
+/// reciprocal of 255: one ULP above 224/255, and fragments are compared against those exact bits.
 pub(crate) const INTERIOR_TILE_ALPHA_REF: f32 = f32::from_bits(0x3F60_E0E2);
 
-/// The corpse blip's edge as a fraction of the widget side (the POIIcons cell is authored 16px on
-/// a 140px minimap ≈ 0.11; INTERIM eyeball beside [`ARROW_FRACTION`]'s).
+/// The corpse blip's edge as a fraction of the widget side (the POIIcons cell's 16 px on a 140 px
+/// minimap); an estimate, the reference's in-range corpse blip size being untraced.
 const CORPSE_BLIP_FRACTION: f32 = 0.11;
 
-/// The day-night tint the reference MODULATEs the **outdoor** (ADT) minimap tiles by before drawing
-/// — the tiles are NOT drawn at full white (that reads too bright). Verified in the CWorldFrame
-/// minimap draw (tile draw `0x4eccdd`–`0x4ecd69`): from the two global
-/// day-night light colours — `color_a` = the Direct/Diffuse band (`LightIntBand` 0 = the light
-/// table's `table[0]`), `color_b` = the Ambient band (band 1 = `table[1]`):
+/// The day-night tint the reference modulates outdoor tiles by (tile draw `0x4eccdd`–`0x4ecd69`),
+/// from `color_a`, the Direct band (`LightIntBand` 0), and `color_b`, the Ambient band (1):
 ///
 /// ```text
 ///   L  = luma601(color_b)                # (r·77 + g·151 + b·28) >> 8, on 0..255 bytes
@@ -147,13 +103,10 @@ const CORPSE_BLIP_FRACTION: f32 = 0.11;
 ///   A' = lerp(color_a, B', 0.75) = 0.25·color_a + 0.75·B'
 /// ```
 ///
-/// Inputs and output are **gamma-space** (`WowLighting`'s sRGB 0..1 convention); handed to the UI
-/// quad as its vertex colour, whose own linearize→re-encode reproduces the client's gamma-space
-/// MODULATE (decision 0089). Interior (WMO) tiles are drawn full white and skip this.
+/// Gamma-space in and out, handed to the UI quad as its vertex colour. Interior tiles draw white.
 fn minimap_day_tint(ambient: [f32; 3], diffuse: [f32; 3]) -> [f32; 3] {
     let (color_a, color_b) = (diffuse, ambient);
-    // Rec.601 luma on 0..255 bytes: the weights (77,151,28) sum to 256, so the parenthesised sum is
-    // a 0..1 weighted average; ×255 lifts it to the byte the client's `>> 8` produces.
+    // Rec.601 luma: the weights sum to 256, so ×255/256 gives the byte the reference's `>> 8` does.
     let l_byte = 255.0 * (color_b[0] * 77.0 + color_b[1] * 151.0 + color_b[2] * 28.0) / 256.0;
     let t = (l_byte + 96.0).min(255.0) / 256.0;
     let mut out = [0.0_f32; 3];
@@ -164,15 +117,11 @@ fn minimap_day_tint(ambient: [f32; 3], diffuse: [f32; 3]) -> [f32; 3] {
     out
 }
 
-/// A `.map()` adaptor over a `md5translate.trs` hit: stream the hashed tile off-thread (like a
-/// terrain tile) but as a **minimap tile** (`BlpVariant::MapTile`: gamma bytes with no sRGB decode
-/// — the reference sampler's `GL_SKIP_DECODE_EXT` — clamp, mip 0, LINEAR). Gamma bytes move the
-/// sRGB decode to AFTER the filter, so every consumer must say so or draw the tile ~2× too bright
-/// through the UI pass: the outdoor quads carry
+/// Stream a `md5translate.trs` hit off-thread as a minimap tile (`BlpVariant::MapTile`: gamma
+/// bytes, no sRGB decode, as the reference's `GL_SKIP_DECODE_EXT` sampler; clamp, mip 0, linear).
+/// Every consumer must decode after the filter or draw ~2× too bright: the outdoor quads set
 /// [`UiQuad::gamma_texel`](crate::ui_pass::UiQuad::gamma_texel), and the interior composite's
-/// alpha-test arm decodes explicitly for its un-encoded target. The invariant `benilla-assets`'
-/// `minimap_tile_settings_reach_the_async_loader` guards these settings reaching the async loader.
-/// Shared by the terrain and interior tile paths.
+/// alpha-test arm decodes itself.
 fn load_tile(asset_server: &AssetServer) -> impl Fn(&str) -> Handle<Image> + '_ {
     move |hash: &str| {
         asset_server.load_with_settings(
@@ -184,14 +133,8 @@ fn load_tile(asset_server: &AssetServer) -> impl Fn(&str) -> Handle<Image> + '_
     }
 }
 
-/// The **headless probe's** minimap widget. `WOW_MM_PROBE` drops the player inside a building in a
-/// server-less capture ([`crate::capture`]), but the real slot comes from the FrameXML `<Minimap>`
-/// extraction, which needs a logged-in UI — so without this the interior branch never runs and the
-/// composite cannot be looked at offline. Under the probe (and only then) we synthesise the slot the
-/// script would have published: a square in the top-right corner at the client's default zoom.
-///
-/// This is the instrument the B141 arc needed and did not have — the interior composite was being
-/// argued about from screenshots because nothing could render it without a server.
+/// Under `WOW_MM_PROBE` alone, a synthetic minimap slot for a server-less capture
+/// ([`crate::capture`]), which has no FrameXML to publish one: a top-right square at zoom 3.
 fn probe_minimap_widget(mut widget: ResMut<MinimapWidget>, windows: Query<&Window>) {
     if widget.0.is_some() || std::env::var("WOW_MM_PROBE").is_err() {
         return;
@@ -209,37 +152,28 @@ fn probe_minimap_widget(mut widget: ResMut<MinimapWidget>, windows: Query<&Windo
     });
 }
 
-/// This frame's extracted `<Minimap>` widget slot, written by `ui_script::extract::paint_script` (the
-/// `QuadContent::Minimap` arm) — `None` when no Minimap widget is visible (cluster hidden, no XML).
+/// This frame's `<Minimap>` slot, from `ui_script::extract::paint_script`; `None` when hidden.
 #[derive(Resource, Default)]
 pub(crate) struct MinimapWidget(pub(crate) Option<MinimapSlot>);
 
-/// The player's WMO-containment verdict as of this frame — [`feed_minimap_inside`]'s answer, kept
-/// so anything that has to know "which zoom table is live" can read it instead of re-running the
-/// portal flood-fill. The client keeps one flag for both consumers (`0xceaa60`) and so do we.
+/// The player's WMO containment this frame, [`feed_minimap_inside`]'s verdict; the reference keeps
+/// one flag (`0xceaa60`) for the draw and the zoom buttons.
 #[derive(Resource, Default)]
 pub(crate) struct MinimapInside(pub(crate) bool);
 
-/// The **persisted** half of the minimap zoom (decision 1131) — the client's two CVar objects
-/// `minimapZoom` / `minimapInsideZoom`, whose registered default is `"3"` in both cases (at the
-/// `RegisterCVar 0x63db90` argument slot). The *live* indices are the widget's
-/// ([`benilla_ui::widget::MinimapState`]); this is the durable knob [`crate::cvars`] loads out of
-/// `config.toml` and saves back into it. It is **read once** — when the in-game UI materializes and
-/// the fresh widget is seeded from it (`UiScript::set_minimap_zoom`) — and written whenever
-/// `Minimap:SetZoom` reports a new level, which is exactly the client's own split: `set_zoom` writes
-/// the live index *and* the CVar, and the minimap reset path re-seeds the index from the CVar.
+/// The persisted zoom, CVars `minimapZoom` and `minimapInsideZoom` (default `"3"`, `0x63db90`):
+/// read once to seed a fresh widget, written on every `Minimap:SetZoom`, as the reference's
+/// `set_zoom` writes both the live index and the CVar.
 #[derive(Resource)]
 pub(crate) struct MinimapZoom {
-    /// `minimapZoom` — the outdoor index (the chunk table's).
+    /// `minimapZoom`, the outdoor index.
     pub(crate) outdoor: u8,
-    /// `minimapInsideZoom` — the indoor index (the radius table's), persisted separately so zooming
-    /// indoors never disturbs the outdoor level.
+    /// `minimapInsideZoom`, the indoor index, persisted apart from the outdoor level.
     pub(crate) inside: u8,
 }
 
-/// The two zoom indices' change callback (1131, 2303): each index lands on its own field,
-/// clamped exactly like the client's `set_zoom` (`0x6daa10`: clamp at 5) — the widget clamps
-/// again on the way in, so a hand-edited level lands in range whichever path it takes.
+/// The zoom CVars' change callback: each lands on its own field, clamped at 5 like the reference's
+/// `set_zoom` (`0x6daa10`).
 pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut zoom: ResMut<MinimapZoom>) {
     match ev.key().as_str() {
         "minimapzoom" => zoom.outdoor = zoom_index(ev.num()),
@@ -248,8 +182,7 @@ pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut zoom: ResMut<Minima
     }
 }
 
-/// A stored minimap zoom level → a valid index: truncate to int and clamp into
-/// `[0, MINIMAP_ZOOM_LEVELS)`, the client's own `set_zoom` clamp.
+/// A stored zoom level to an index, truncated and clamped into `[0, MINIMAP_ZOOM_LEVELS)`.
 fn zoom_index(v: f32) -> u8 {
     v.clamp(0.0, f32::from(benilla_ui::widget::MINIMAP_ZOOM_LEVELS - 1)) as u8
 }
@@ -263,45 +196,37 @@ impl Default for MinimapZoom {
     }
 }
 
-/// One extracted Minimap widget: where it sits on screen (y-down logical px), its paint key, and
-/// its live widget state.
+/// One extracted Minimap widget: its rect (y-down logical px), paint key and live state.
 pub(crate) struct MinimapSlot {
     pub(crate) rect: Rect,
     pub(crate) z: u64,
-    /// The outdoor zoom index (chunk table); `inside_zoom` is its indoor twin (radius table). The
-    /// client persists both and picks by WMO containment — see [`INTERIOR_ZOOM_RADIUS`].
+    /// The outdoor zoom index; `inside_zoom` is the indoor one, picked by WMO containment.
     pub(crate) zoom: u8,
     pub(crate) inside_zoom: u8,
     pub(crate) alpha: f32,
 }
 
-/// The loaded minimap fixtures: the tile hash catalog + the circular mask + the arrow art.
-/// Inserted at startup once the chain is open; absent = the minimap draws nothing (its XML
-/// children still render).
+/// The loaded minimap fixtures; absent, the map draws nothing and its XML children still render.
 #[derive(Resource)]
 struct MinimapAssets {
     translate: MinimapTranslate,
     mask: Option<Handle<Image>>,
     arrow: Option<Handle<Image>>,
-    /// The shared POI atlas (`Interface\Minimap\POIIcons`) — the corpse blip's skull cell
-    /// (decision 0308 §5) and any later POI rides it.
+    /// The POI atlas (`Interface\Minimap\POIIcons`), for the corpse skull.
     poi: Option<Handle<Image>>,
-    /// The **four** rim-arrow arts — the flat `.blp` stand-ins for the one `minimapArrowModel`
-    /// (`Rotating-MinimapArrow.mdx`) the reference re-animates per blip source. See
-    /// [`blips::RimArrow`] for the sequence→layer table and why there are four of them.
+    /// The four rim-arrow arts: the reference's one `minimapArrowModel`
+    /// (`Rotating-MinimapArrow.mdx`) shows exactly one of these layers per blip source's looping
+    /// sequence, so one flat sprite each draws the same ([`blips::RimArrow`]).
     rim_arrows: blips::RimArrowArt,
-    /// The unit-blip atlas (`Interface\Minimap\ObjectIcons`, five 32-px dot cells) — the
-    /// quest-giver dots.
+    /// The unit-blip atlas (`Interface\Minimap\ObjectIcons`, five 32-px dot cells).
     object_icons: Option<Handle<Image>>,
-    /// `SpellShapeshiftForm.dbc` — the tracking dots' creature-type override (a cat-form
-    /// druid is a Beast; decision 0564). `None` = no override (unshifted resolution only).
+    /// `SpellShapeshiftForm.dbc`, the tracking dots' creature-type override (a cat-form druid is a
+    /// Beast).
     forms: Option<HashMap<u32, benilla_formats::ShapeshiftForm>>,
 }
 
-/// Async tile handles by ADT index, for the [`CurrentMap`] it was filled on. `None` = the tile has
-/// no authored minimap art (open ocean) — cached so the translate lookup doesn't re-run per frame.
-/// The interior half caches the WMO tiles by `(group, col, row)` for the WMO whose `stem` (its
-/// `md5translate.trs` path stem) is resident, cleared when the player enters a different building.
+/// Tile handles by ADT index for one [`CurrentMap`], `None` for a tile with no art (open ocean);
+/// the interior half by `(group, col, row)` for the building whose tile stem is resident.
 #[derive(Resource, Default)]
 struct MinimapTileCache {
     map_id: Option<u32>,
@@ -310,7 +235,7 @@ struct MinimapTileCache {
     interior: HashMap<(usize, u32, u32), Option<Handle<Image>>>,
 }
 
-/// Loads the translate catalog + the mask/arrow art once the patch chain is open.
+/// Load the translate catalog and the minimap art once the patch chain is open.
 fn setup_minimap(
     mut commands: Commands,
     world_assets: Option<ResMut<WorldAssets>>,
@@ -362,26 +287,15 @@ fn setup_minimap(
     }
 }
 
-/// The minimap's **one** containment verdict — which map family draws, and (through
-/// [`feed_minimap_inside`]) which zoom index the +/- buttons drive. The client keeps a single flag
-/// for both (`0xceaa60`), so this must be computed once and shared: two probes drifting apart is
-/// how the map ends up drawn at the wrong scale for the family it is showing.
+/// The minimap's one containment verdict: the placement, model, tile stem and seed group of the
+/// WMO the player is in, or `None` for terrain. Indoors the reference draws the building's own
+/// tiles and no terrain, and the same flag (`0xceaa60`) picks the zoom index.
 ///
-/// The reference hard-switches map families on interior containment: standing inside a WMO group it
-/// draws that building's OWN minimap tiles and SUPPRESSES the terrain (mutually exclusive, not a
-/// transparent overlay). Returns the placement, model, `md5translate.trs` path stem and seed group
-/// of the WMO the player is in, or `None` for the terrain family.
-///
-/// **The gate is the client's one indoor byte** (`0xbc8300`), and that byte is the CGLight node's
-/// down-ray bit `[node+0x90] & 1` (`0x670547` — not a containment group's `0x10`, which is a
-/// ctor-set class tag, not a group flag). The predicate is a **position cast, faces only**: the
-/// nearest surface within 1000 yd straight down — terrain racing the WMO faces, closer wins and the
-/// WMO wins ties — is a WMO face whose group lacks MOGP `0x8`. Terrain below ⇒ outdoors, whatever
-/// building you are geometrically inside. That is exactly [`CurrentAreaInterior`]'s law
-/// (`wmo_portal::area_down_ray`, the zone-text bit), so the gate reads it rather than re-deriving
-/// one: the portal-crossing leg in [`down_ray_seeds`] belongs to the CAMERA's current-group system
-/// and claiming an interior through a doorway plane under the eye is the abbey-yard bug's shape.
-/// [`down_ray_seeds`] still supplies the flood SEED once the gate has said indoors.
+/// The gate is the reference's indoor byte (`0xbc8300`), the CGLight node's down-ray bit
+/// `[node+0x90] & 1` (`0x670547`): the nearest face within 1000 yd straight down, terrain racing
+/// and the WMO winning ties, belongs to a group without MOGP `0x8`. That is the zone-text claim
+/// `CurrentAreaInterior`, read through `world.area_interior()`; [`down_ray_seeds`] only supplies
+/// the flood seed once the gate says indoors.
 fn minimap_interior<'a>(
     player: &Player,
     instances: &Query<&WmoPortalInstance>,
@@ -393,8 +307,7 @@ fn minimap_interior<'a>(
         return None;
     }
     let eye = player.pos + Vec3::Y * INTERIOR_PROBE_HEIGHT;
-    // The down-ray races the terrain, exactly as the interior/zone tracker does — standing on the
-    // grass above a mine's tunnels is not standing in the mine.
+    // The down-ray races the terrain, as the zone tracker does: grass above a mine is not in it.
     let terrain = world.terrain_height_under(eye);
     instances.iter().find_map(|inst| {
         let model = wmos.get(&inst.handle)?;
@@ -412,9 +325,8 @@ fn minimap_interior<'a>(
     })
 }
 
-/// Fills the extracted widget hole: the visible tile quads (clipped to the widget, masked to the
-/// circle) and the player arrow, appended at the widget's own z (stable sort keeps append order
-/// within a key, so the arrow rides above the tiles and below the widget's children).
+/// Fill the widget hole: the tiles masked to the circle, then the blips and the player arrow, at
+/// the widget's z (a stable sort keeps append order, so all sit below the widget's children).
 fn emit_minimap(
     widget: Res<MinimapWidget>,
     assets: Option<Res<MinimapAssets>>,
@@ -451,12 +363,10 @@ fn emit_minimap(
         mut ping,
         script,
     ) = blip_inputs;
-    // Hover resets every frame; the blip pass below re-establishes it while the map draws.
+    // Hover resets every frame; the blip pass re-establishes it while the map draws.
     *blip_hover = blips::MinimapBlipHover::None;
-    // Drain this frame's `Minimap:PingLocation` click BEFORE any early return below, so it is
-    // always spent in the frame it was made. Held across frames it would seat against geometry
-    // the player never clicked on; and a click made on a frame the map does not draw is simply
-    // not a ping (decision 1596).
+    // Drain the `Minimap:PingLocation` click before any early return: it is spent in the frame it
+    // was made, and a click on a frame the map does not draw is not a ping.
     let click = script.and_then(|mut s| s.take_minimap_ping_request());
     let (Some(slot), Some(assets), Some(map), Some(catalog)) =
         (widget.0.as_ref(), assets, map, catalog)
@@ -473,9 +383,7 @@ fn emit_minimap(
     let Some(rt_image) = rig.map(|r| r.image.clone()) else {
         return; // the composite rig's Startup system has not run yet
     };
-    // `WOW_MM_ZOOM=0..5` forces the zoom level of whichever map is showing — a capture instrument
-    // (pairs with the `WOW_MM_PROBE` interior probe). Indoors and outdoors each carry their own
-    // persisted index, so the override stands in for both.
+    // `WOW_MM_ZOOM=0..5` forces both zoom indices, a capture instrument.
     static ZOOM_OVERRIDE: std::sync::OnceLock<Option<u8>> = std::sync::OnceLock::new();
     let zoom_override = *ZOOM_OVERRIDE.get_or_init(|| {
         std::env::var("WOW_MM_ZOOM")
@@ -488,8 +396,7 @@ fn emit_minimap(
 
     let wow = bevy_to_wow(player.pos);
     let (wx, wy) = (wow[0], wow[1]);
-    // The active branch's world→px scale, for the point blips drawn after the tiles (the corpse
-    // marker below; both branches share the same north-up point mapping around `center`).
+    // The drawn family's world-to-px scale, for the point blips drawn after the tiles.
     let mut blip_px_per_yd = 0.0_f32;
 
     let mask = assets.mask.as_ref().map(|m| UiQuadMask {
@@ -499,68 +406,46 @@ fn emit_minimap(
 
     let interior = minimap_interior(&player, &instances, &wmos, &world, &asset_server);
 
-    // The player's containment verdict, kept as a bool for the quest-dot grey (the branch
-    // below consumes `interior` itself).
+    // For the dots' indoor test; the branch below consumes `interior`.
     let player_indoors = interior.is_some();
-    // How far the map reaches this frame — decided once, by the one function that decides it, and
-    // used by whichever family draws below.
     let view_radius = view_radius_yd(zoom, inside_zoom, player_indoors);
     if let Some((world_from_local, model, stem, in_group)) = interior {
-        // INTERIOR: the WMO's own per-group tiles, drawn FULL WHITE (the day-night tint is outdoor-
-        // only). The tiles are baked in the WMO's MODEL frame (north = model +X, sized to the model
-        // footprint — verified against the 97°-yaw Goldshire Inn: group 3's tile is 64×32 px = its
-        // model bbox, not the world AABB). So place each tile at its model-space centre mapped
-        // through the placement, and rotate the WHOLE set by ONE placement-yaw angle — not per-tile
-        // world AABBs (one orientation basis, `0x6da180`). Cached by `(group, col, row)`.
+        // Interior: the WMO's own per-group tiles, drawn white. They are baked in the model frame
+        // (north = model +X), so each sits at its model-space centre through the placement and the
+        // whole set turns by one placement yaw (`0x6da180`).
         if cache.interior_stem.as_deref() != Some(stem.as_str()) {
             cache.interior.clear();
             cache.interior_stem = Some(stem.clone());
         }
-        // INTERIOR ZOOM: indoors has its OWN zoom index and its own table — the view radius is
-        // `radiusTable[inside_zoom]` in raw yards (150 widest … 25 tightest), not the outdoor chunk
-        // half-extent. The zoom buttons drive `inside_zoom` while you're inside, and it persists
-        // separately from the outdoor level (index `0x86f69c`, table `0x8116e8`).
         let radius = view_radius;
         let px_per_yd = (side * 0.5) / radius;
         blip_px_per_yd = px_per_yd;
 
-        // The tiles are composited into the client's own 256² TARGET, not drawn at the screen —
-        // both halves of the mechanism matter and only work together (decision 1466; the module
-        // docs in [`composite`] carry the why). Target space: y-UP, origin at the target's centre
-        // (= the player), and `RT_HALF_EXTENT_SCALE · radius` yards to an edge.
+        // The tiles go into the reference's 256² target (`composite`), not the screen. Target
+        // space: y-up, origin at the player, `RT_HALF_EXTENT_SCALE · radius` yd to an edge.
         #[allow(clippy::cast_precision_loss)] // 256 is exact in f32
         let units_per_yd =
             (composite::RT_SIZE as f32 * 0.5) / (composite::RT_HALF_EXTENT_SCALE * radius);
-        // A model point → its north-up target position (through the placement to world, then the
-        // same north-up map the terrain tiles use: up = world +X north, left = +Y west).
+        // A model point to its north-up target position: placement to world, then up = +X north,
+        // left = +Y west.
         let to_target = |m: [f32; 3]| {
             let w = bevy_to_wow(world_from_local.transform_point3(wow_to_bevy(m)));
             Vec2::new((wy - w[1]) * units_per_yd, (w[0] - wx) * units_per_yd)
         };
-        // The one placement rotation: where the model +X axis points, as a CLOCKWISE-on-screen
-        // angle (the target's y-up frame negates it at the Transform). Same for every tile.
+        // The one placement rotation: where model +X points, clockwise on screen (negated into the
+        // target's y-up frame at the Transform).
         let x_axis = to_target([1.0, 0.0, 0.0]) - to_target([0.0, 0.0, 0.0]);
         let rotation = (-x_axis.y).atan2(x_axis.x);
-        // The target's own edge, in target units, for the window cull below.
         #[allow(clippy::cast_precision_loss)]
         let rt_half = composite::RT_SIZE as f32 * 0.5;
         composite.active = true;
 
-        // GROUP SELECTION: the portal flood-fill from the player's current group (`0x6a5020`) —
-        // NOT draw-every-group. Only the groups
-        // reached through portals within the query box, whose bbox overlaps the view in XY, are drawn.
-        // This is what stops floors the player can't reach (or that are far outside the view) from
-        // painting over the current one.
-        // The selection query box uses the SAME `c` as the draw radius (`0x6d96b6`) — so we never
-        // load tiles we cannot show, and zooming in indoors tightens the box's Z extent too, which
-        // is what trims how many stacked floors bleed through.
+        // The portal flood-fill from the player's group (`0x6a5020`). Its query box uses the draw
+        // radius (`0x6d96b6`), so zooming in also tightens the box's Z extent.
         let drawable =
             interior_group_selection(model, &world_from_local, player.pos, radius, in_group);
-        // Draw ORDER (`0x4ebeb0`, keyed at `0x6d9e30`): the composite is Z-sorted ascending by
-        // `Zmidpoint − playerZ`, with the player's OWN group forced to the top (the client keys it
-        // FLT_MAX). So floors below draw at the bottom, floors above over them, and the player's
-        // current floor LAST of all — a stacked storey shows only through its transparent stairwell
-        // gaps, never occluding the room you're in ("basement on top the kitchen", director).
+        // Draw order (`0x4ebeb0`, keyed at `0x6d9e30`): ascending by `Zmidpoint − playerZ`, the
+        // player's own group keyed `FLT_MAX`, so it draws last and no storey covers the room.
         let player_z = bevy_to_wow(world_from_local.inverse().transform_point3(player.pos))[2];
         let sort_key = |gi: usize| -> f32 {
             if gi == in_group {
@@ -581,24 +466,11 @@ fn emit_minimap(
             let mid_z = 0.5 * (gn.bbox_min[2] + gn.bbox_max[2]);
             for col in 0..nx {
                 for row in 0..ny {
-                    // The tile's world rect: the grid cell PLUS the client's outer-edge BLEED. The
-                    // cells themselves stride exactly `tw`, sharing their interior edges — but a
-                    // cell on the grid's boundary is grown by 1.0 yd on that side alone
-                    // (`0x6a549e`/`0x6a54ae`/`0x6a54be`/`0x6a54d1`, each an `fsub`/`fadd` of
-                    // `0xca8098 = 0.5 + 0.5`; fitted to the reference's own captured quads with
-                    // zero error on every bound). A 1×1 grid is therefore `tw + 2` across, an
-                    // end cell `tw + 1`, an interior cell exactly `tw`.
-                    //
-                    // THIS is what makes the joints work. The bleed grows every group's art 1 yd
-                    // past its bbox on each outer side, so two groups whose boxes touch OVERLAP by
-                    // 2 yd. Without it their art merely abuts — and abutting art does not survive
-                    // the composite's alpha test: `GEQUAL 224/255` on a LINEAR-filtered silhouette
-                    // reaches only 0.122 of a texel past the last opaque texel centre (nearest
-                    // would reach the texel edge, 0.5), so an abutting pair loses ~0.38 texel and
-                    // the black clear reads through the strip for the length of the wall. That is
-                    // B141's dashed hairline; a 2 yd overlap absorbs the same erosion with four
-                    // texels to spare. In the reference's captured frame 16 of 220 inter-group
-                    // tile contacts exist ONLY because of the bleed.
+                    // The grid cell plus the outer-edge bleed: a boundary cell grows 1 yd on its
+                    // outer side (`0x6a549e`/`0x6a54ae`/`0x6a54be`/`0x6a54d1`, each an `fsub` or
+                    // `fadd` of `0xca8098`). The bleed matters: `GEQUAL 224/255` on a linear-
+                    // filtered edge reaches only 0.122 texel past the last opaque texel centre, so
+                    // merely abutting groups would show the black clear along the wall.
                     let x0 = gn.bbox_min[0] + col as f32 * tw_x
                         - if col == 0 { EDGE_BLEED_YD } else { 0.0 };
                     let x1 = gn.bbox_min[0]
@@ -610,9 +482,7 @@ fn emit_minimap(
                         + (row + 1) as f32 * tw_y
                         + if row + 1 == ny { EDGE_BLEED_YD } else { 0.0 };
                     let tc = to_target([0.5 * (x0 + x1), 0.5 * (y0 + y1), mid_z]);
-                    // Window cull: skip tiles whose centre lands well outside the TARGET (which
-                    // holds 1.5× what the blit shows, so this is wider than the visible disc —
-                    // deliberately: the client composites the same margin).
+                    // Cull against the target, which holds 1.5× the visible disc.
                     if tc.length() > rt_half + tw_x.max(tw_y) * units_per_yd {
                         continue;
                     }
@@ -627,14 +497,9 @@ fn emit_minimap(
                     composite.tiles.push(composite::CompositeTile {
                         texture: handle.clone(),
                         center: tc,
-                        // The client's HALF-TEXEL UV INSET, expressed as the scale it is: it
-                        // samples `[0.5/W, 1−0.5/W]` across the rect above (verified on the
-                        // captured quads — every one carries exactly that UV rect), and sampling
-                        // that range across a quad of size `Q` is the same as sampling `[0, 1]`
-                        // across `Q·W/(W−1)` about the same centre. So the shared unit mesh keeps
-                        // its UVs and the inset rides the Transform like everything else here, and
-                        // the texel centres land where the client's do. `W` comes from the TILE
-                        // (`tw / 0.5`), never from the bled rect.
+                        // The reference's half-texel UV inset, `[0.5/W, 1−0.5/W]`, as the equal
+                        // quad scale `W/(W−1)`, so the shared mesh keeps its UVs. `W` comes from
+                        // the tile (`tw / 0.5`), never the bled rect.
                         size: Vec2::new(
                             (x1 - x0) * units_per_yd * texel_stretch(tw_x),
                             (y1 - y0) * units_per_yd * texel_stretch(tw_y),
@@ -646,10 +511,8 @@ fn emit_minimap(
             }
         }
 
-        // `WOW_MM_STATS=1` reports what the interior branch actually put in the target this frame —
-        // how many groups the flood-fill kept out of how many, and how many tiles that came to. The
-        // reference's own Stormwind capture emitted 57 tiles at indoor zoom 3, which is the number
-        // this is here to be compared against.
+        // `WOW_MM_STATS=1` prints the kept groups and tiles; the reference's Stormwind capture
+        // emitted 57 tiles at indoor zoom 3.
         static MM_STATS: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
         if *MM_STATS.get_or_init(|| std::env::var_os("WOW_MM_STATS").is_some()) {
             eprintln!(
@@ -660,11 +523,8 @@ fn emit_minimap(
             );
         }
 
-        // THE BLIT: the target's middle two-thirds, which is what nets `1.0 · radius` on screen
-        // (the client's `0x4ec440` under EGxBlend 2). One quad, masked to the minimap circle — the
-        // round cut belongs HERE and not to the tiles, exactly as the reference's does. The target
-        // is opaque everywhere (its clear is opaque black), so this quad IS the black backing the
-        // screen path used to push separately.
+        // The blit: the target's middle two-thirds (`0x4ec440`, EGxBlend 2), masked to the circle
+        // here and not on the tiles, as the reference does. The opaque target is also the backing.
         let lo = 0.5 - composite::RT_BLIT_FRACTION * 0.5;
         let hi = 0.5 + composite::RT_BLIT_FRACTION * 0.5;
         quads.overlays.push(UiQuad {
@@ -677,8 +537,7 @@ fn emit_minimap(
             ..default()
         });
     } else if let Some(dir) = catalog.0.directory(map.0) {
-        // OUTDOOR: the ADT terrain tiles, MODULATEd by the day-night light tint (not full white —
-        // else too bright, the reference's CWorldFrame minimap draw). Absent lighting ⇒ white.
+        // Outdoor: the ADT tiles, modulated by the day-night tint; white without lighting.
         let half_extent = view_radius;
         let px_per_yd = (side * 0.5) / half_extent;
         blip_px_per_yd = px_per_yd;
@@ -703,7 +562,7 @@ fn emit_minimap(
                         .map(load_tile(&asset_server))
                 });
                 let Some(handle) = handle else {
-                    continue; // unauthored tile (open ocean) — the mask shows the clear color
+                    continue; // unauthored tile (open ocean): the clear colour shows
                 };
                 // The tile's max-x/max-y world corner is its north-west corner = screen top-left.
                 let (tile_north, tile_west) = tile_to_world(tx, ty);
@@ -719,16 +578,11 @@ fn emit_minimap(
                     z_key: slot.z,
                     texture: Some(handle.clone()),
                     color: [tint[0], tint[1], tint[2], slot.alpha],
-                    // The tile is a SKIP_DECODE upload (gamma bytes — [`load_tile`]), so the
-                    // day-night MODULATE above lands on the authored byte, exactly the reference's
-                    // fixed-function stage. Without this the ordinary arm re-encodes an
-                    // already-encoded byte — the outdoor minimap reads visibly too bright.
+                    // A skip-decode tile (`load_tile`): the tint modulates the authored byte, as
+                    // the reference's fixed-function stage does; the ordinary arm would re-encode.
                     gamma_texel: true,
-                    // No CPU clip (1463): the mask shader already zeroes everything outside
-                    // `mask_rect` (`ui_quad.wgsl`'s `inside` test), and clipping a PANNING tile
-                    // re-cut its quad every frame — constant positions, churning UVs — which is
-                    // exactly the shape the batcher's pan gate cannot ride on a `Transform`.
-                    // Unclipped, the tile is a pure translation and never rewrites its mesh.
+                    // No CPU clip: the mask shader zeroes everything outside `mask_rect`, and an
+                    // unclipped panning tile is a pure translation that never rewrites its mesh.
                     mask: mask.clone(),
                     ..default()
                 });
@@ -736,13 +590,11 @@ fn emit_minimap(
         }
     }
 
-    // ── The blip layer (decision 0203 phase 3; byte law per the 0337 fold-back): landmarks
-    // draw under the player arrow; the quest dots draw LAST — above it (the client's own draw
-    // order). Hover lands in [`blips::MinimapBlipHover`] for the tooltip drive.
-    // Our own descriptor's tracking state (PRIVATE fields — only ever on the self entity).
+    // ── The blip layer: landmarks under the player arrow, the dots above it (the reference's
+    // order).
+    // Our own descriptor's tracking state (private fields, only on the self entity).
     let me = self_store.iter().next();
-    // Our own guid — the classifier compares a candidate's charm/summon owner against it, so our
-    // own pet and minions never take a dot (`0x4eac0d`).
+    // Our own guid: our own pet and minions never take a dot (`0x4eac0d`).
     let self_guid = me.map(|(_, g)| g.0);
     let tracking = me
         .map(|(s, _)| blips::SelfTracking {
@@ -770,13 +622,9 @@ fn emit_minimap(
         let win = window.iter().next();
         let cursor = win.and_then(|w| w.cursor_position());
         let seam = win.map_or(1.0, |w| crate::ui_script::seam_scale(w.height(), ui_scale.0));
-        // The player's pan term, quantized to a half-logical-pixel grid (one device px at 2×):
-        // every blip offset — and the rim arrows' bearing — derives from `wx`/`wy`, so the whole
-        // blip layer steps together a few times a second instead of re-emitting sub-pixel-shifted
-        // quads every frame while walking (1463; a 0.07 px/frame slide on a 16 px icon is not a
-        // visible motion, but each slide rewrote the batch mesh and armed the world's
-        // `AssetChanged` scans). The blips' world positions stay exact — only the shared pan
-        // origin snaps.
+        // The pan origin snapped to a half-logical-pixel grid: every blip offset and rim bearing
+        // derives from `wx`/`wy`, so the layer steps together instead of rewriting the batch mesh
+        // every frame while walking. Blip world positions stay exact.
         let q = 0.5 / blip_px_per_yd;
         blips::BlipCtx {
             center,
@@ -789,8 +637,8 @@ fn emit_minimap(
             wy: (wy / q).round() * q,
             wz: wow[2],
             cursor,
-            // The same point in UI space (y-up, ÷s through the 0582/0584 seam — the tooltip's
-            // anchor resolves in the VM's 768-virtual units, not window px): the cursor seat.
+            // The cursor in UI space (y-up, ÷ the seam scale): the tooltip anchor resolves in
+            // 768-virtual units, not window px.
             cursor_ui: cursor
                 .zip(win)
                 .map(|(c, w)| Vec2::new(c.x / seam, (w.height() - c.y) / seam)),
@@ -799,9 +647,8 @@ fn emit_minimap(
     });
     let mut hover = blips::MinimapBlipHover::None;
     if let Some(ctx) = &blip_ctx {
-        // The guard-directions marker rides this pass as a landmark candidate, the way the
-        // reference appends its static blip slot after the DBC scan — so it draws even when
-        // `AreaPOI.dbc` failed to load, and the pass runs on the arrow art alone.
+        // The guard-directions marker rides this pass as a landmark, as the reference appends its
+        // static blip slot after the DBC scan, so it draws even without `AreaPOI.dbc`.
         if assets.rim_arrows.any() {
             blips::emit_landmarks(
                 ctx,
@@ -813,8 +660,8 @@ fn emit_minimap(
                 &mut quads,
                 &mut hover,
             );
-            // The party/corpse rim arrows (0434 phase 6b, the out-of-range half of `0x6dad10`)
-            // draw with the POI arrows — before the player arrow, per the client's order.
+            // The party and corpse rim arrows (the out-of-range half of `0x6dad10`), before the
+            // player arrow, in the reference's order.
             let corpse = death_net
                 .corpse
                 .filter(|cp| cp.display_map == map.0 as i32)
@@ -835,9 +682,8 @@ fn emit_minimap(
     // growing counterclockwise (toward west = screen left); our quad rotation is clockwise on
     // screen, so the arrow angle is the negated facing.
     if let Some(arrow) = &assets.arrow {
-        // Byte-pinned quad (blips::PLAYER_ARROW_QUAD_PX): the MinimapArrow.m2 single quad at
-        // 1280 px/unit on the frozen 140.8 basis, its authored centre offset rotating with
-        // the facing (clockwise screen rotation, so the offset rotates by the same angle).
+        // `blips::PLAYER_ARROW_QUAD_PX`: MinimapArrow.m2's single quad at 1280 px/unit on the
+        // 140.8 basis, its authored centre offset rotating with the facing.
         let s = side * (blips::PLAYER_ARROW_QUAD_PX / blips::BLIP_BASIS_PX);
         let rotation = -player.facing();
         let (sin, cos) = rotation.sin_cos();
@@ -854,9 +700,8 @@ fn emit_minimap(
         });
     }
 
-    // The object dots draw LAST — above the player arrow (the client's draw order, 0x4ed7b7):
-    // tracking dots (cells 0/1) first, then quest dots (cell 3) and party dots (cell 4) — the
-    // draw's own cell-list order.
+    // The object dots draw last, above the player arrow (`0x4ed7b7`): tracking dots (cells 0/1),
+    // then quest (3) and party (4) dots.
     if let Some(ctx) = &blip_ctx {
         if let Some(icons) = &assets.object_icons {
             blips::emit_tracking_dots(
@@ -882,25 +727,20 @@ fn emit_minimap(
                 self_guid,
                 icons,
                 player_indoors,
-                // A dot NPC's own containment — the same faces-only down-ray the entity light
-                // classifier stands on (dots are few; the per-frame rays are cheap).
+                // A dot NPC's own containment, the faces-only down-ray the entity lights use.
                 |feet| world.indoors_at(feet),
                 &mut quads,
                 &mut hover,
             );
-            // The in-range party dots (blue cell 4, 1.3×) draw with the object dots — last.
+            // The in-range party dots (blue cell 4, 1.3×), last.
             blips::emit_party_dots(ctx, &group, &guids, &unit_pos, icons, &mut quads);
         }
     }
     *blip_hover = hover;
 
-    // The corpse blip (decision 0308 §5): in range, the POIIcons skull cell (the same art the
-    // ref's world-map corpse uses; the engine-drawn in-range minimap corpse art is INTERIM until
-    // named) at the corpse's true position, through the same north-up point mapping as the
-    // tiles. OUT of range the corpse is the fifth slot of `0x6dad10`'s placement — the rotating
-    // rim arrow drawn with the party arrows above (the byte law replaced the old 0.92
-    // edge-clamped skull). Same-map only (the display coords are the entrance for a dungeon
-    // corpse).
+    // The corpse blip in range: the POIIcons skull, the reference's world-map corpse art (its
+    // in-range minimap art is untraced). Out of range it is the rim arrow above, the fifth slot
+    // of `0x6dad10`. Same map only: a dungeon corpse's display coords are the entrance.
     if let (Some(poi), Some(cp)) = (&assets.poi, death_net.corpse) {
         if cp.display_map == map.0 as i32 && blip_px_per_yd > 0.0 {
             let off = Vec2::new(
@@ -922,32 +762,18 @@ fn emit_minimap(
         }
     }
 
-    // A `Minimap:PingLocation` click is seated here, against the geometry standing right here,
-    // this frame (decision 1596). The marker itself is the stock `MiniMapPing` `<Model>`, a Lua
-    // child of the Minimap that composites over everything the engine drew into the widget's
-    // hole — rendered by `crate::ui_models` since decision 2008.
+    // Seat the click against this frame's geometry; the marker is the stock `MiniMapPing`
+    // `<Model>`, drawn over the widget by `crate::ui_models`.
     if let Some(ctx) = &blip_ctx {
         ping::seat_click(ctx, &mut ping, click);
     }
 }
 
-/// Push the player's WMO-containment state onto the Minimap widget (the client's `0xceaa60`), so the
-/// zoom buttons drive the **indoor** zoom index while indoors and the outdoor one while outside, each
-/// persisting across the transition. Runs before the script tick, so a `SetZoom` fired from a button
-/// handler this frame routes to the right index. The verdict is [`minimap_interior`]'s — the SAME
-/// one [`emit_minimap`] draws by, because the client keeps one flag for both (it used to read the
-/// camera-eye `CurrentWmoInterior` instead, which is a different ray *and*, since 1466, a different
-/// mask: the buttons would have kept driving the indoor index on a Stormwind street the map was
-/// drawing from terrain tiles).
-/// The state is pushed on the inside↔outside *edge* and whenever the VM's Minimap-creation count
-/// moved (the cluster XML loads late, and an addon can build one whenever it likes — the counter
-/// is what keeps "a widget created after the last transition is still told" true without walking
-/// the ~3k-frame arena every frame; the memo resets with a fresh VM, whose rebuilt widgets bump
-/// the fresh counter). On the edge we also fire `MINIMAP_UPDATE_ZOOM`: the active zoom index just switched
-/// to the other (independent) level, so the cluster must re-sync the +/- buttons' enabled state to it
-/// — the client's own signal for "the effective zoom changed" (FrameXML `Minimap_OnEvent`). Without it
-/// the buttons keep the level you left (e.g. `ZoomIn` greyed from an outdoor max-zoom, still greyed
-/// indoors at level 3), which is the director's report (2026-07-09).
+/// Push the player's WMO containment onto the Minimap widget (`0xceaa60`), so the zoom buttons
+/// drive the indoor index indoors and the outdoor one outside; the verdict is [`emit_minimap`]'s,
+/// as the reference keeps one flag. Pushed on the edge and whenever the VM's Minimap-creation
+/// count moves, so a widget built later is still told. The edge also fires `MINIMAP_UPDATE_ZOOM`,
+/// on which the stock `Minimap_OnEvent` re-syncs the +/- buttons to the other index's level.
 fn feed_minimap_inside(
     script: Option<bevy::ecs::system::NonSendMut<benilla_ui::script::UiScript>>,
     world: benilla_world::world_point::WorldPoint,
@@ -974,17 +800,8 @@ fn feed_minimap_inside(
     }
 }
 
-/// Swap the disc's mask when an addon has asked for a different one — `Minimap:SetMaskTexture`.
-///
-/// The renderer already masks the map through its own `UiQuadMask`; this only decides which
-/// texture that is, so the whole feature is a load and a handle swap. It is what makes pfUI's
-/// square minimap — the single most recognisable thing it does to the default UI — actually
-/// square, and it is a real 1.12 method rather than a pfUI invention.
-///
-/// Memoised on the path, so the load happens on the edge and never per frame; a VM restart resets
-/// the memo and re-reads, because the fresh VM's widget starts at the engine default again. A path
-/// that fails to load leaves the current mask standing and says so once — a missing file must not
-/// silently unmask the map into a square, which is what dropping the handle would do.
+/// Swap the disc's mask for the one `Minimap:SetMaskTexture` names (a 1.12 method). Memoised on the
+/// path and re-read with a fresh VM; a path that fails to load keeps the current mask and warns.
 fn feed_minimap_mask(
     script: Option<bevy::ecs::system::NonSendMut<benilla_ui::script::UiScript>>,
     assets: Option<ResMut<MinimapAssets>>,
@@ -1013,21 +830,10 @@ fn feed_minimap_mask(
     }
 }
 
-/// Push the player's world facing onto the Minimap's engine-owned player-arrow `Model` — the
-/// client's `CMinimap::SetPlayerFacing 0x4eb8e0`, which writes it verbatim into the arrow's
-/// `[+0x39c]`, the field `Model:GetFacing()` reads.
-///
-/// **Every frame, not on an edge**, because the value is continuous: the reference calls it from
-/// the per-frame minimap update with the player's live `GetFacing()`, and an addon polling it in an
-/// OnUpdate (which is what reads it — Questie's `GetPlayerFacing`, pfQuest's `compat/client.lua`)
-/// would otherwise steer off a stale heading. It costs one arena lookup per Minimap widget, which
-/// is what `WidgetArena::minimap_kinds` exists to make true.
-///
-/// **The one transform, and why it is not a fudge.** `player.facing()` is benilla's `face_yaw`, an
-/// unbounded accumulator — a mouse-turn just adds to it — whereas the client's unit orientation is
-/// a normalized field, and the same normalization already happens on the wire (`movement_net`'s
-/// `[0, 2π)` rule, which vmangos's `VerifyMovementInfo` requires). So the value published here is
-/// the wire value, and an addon reading it back sees the same number the server does.
+/// Push the player's facing onto the Minimap's player-arrow `Model` every frame, as the reference's
+/// per-frame `CMinimap::SetPlayerFacing` (`0x4eb8e0`) writes `[+0x39c]`, what `Model:GetFacing()`
+/// reads. `player.facing()` is an unbounded accumulator, so it is normalized to `[0, 2π)`, the
+/// wire value vmangos's `VerifyMovementInfo` requires.
 fn feed_minimap_player_facing(
     script: Option<bevy::ecs::system::NonSendMut<benilla_ui::script::UiScript>>,
     player: Res<Player>,
@@ -1036,11 +842,8 @@ fn feed_minimap_player_facing(
     script.set_minimap_player_facing(player.facing().rem_euclid(std::f32::consts::TAU));
 }
 
-/// Push the live game clock into the VM when the game minute ticks — `GetGameTime()`'s backing
-/// globals (the zone-text family's shape). The reference's GameTimeFrame re-reads GetGameTime
-/// every OnUpdate and compares the packed minute against its cached `timeOfDay`, so a
-/// minute-granular push is exactly the API's own resolution (the binding returns no seconds).
-/// Before the first `SMSG_LOGIN_SETTIMESPEED` the globals stay at their 0:00 stdlib seed.
+/// Push the game clock into `GetGameTime()`'s backing globals when the minute ticks, the API's own
+/// resolution. Before the first `SMSG_LOGIN_SETTIMESPEED` they hold 0:00.
 fn feed_game_time(
     script: Option<bevy::ecs::system::NonSendMut<benilla_ui::script::UiScript>>,
     time: Res<crate::net::ServerTime>,
@@ -1063,11 +866,9 @@ fn feed_game_time(
     }
 }
 
-/// The app half of the `<Minimap>` widget (decision 0203 phase 1) — see the module doc. The zone
-/// LABEL feed lives with the rest of the zone-text data plane (`crate::area`, decision 0287's
-/// fold-back): the client updates the minimap line and fires `MINIMAP_ZONE_CHANGED` from the same
-/// area-update pass as the ZONE_CHANGED family (`0x494970` beside `0x494780`), and so does
-/// benilla.
+/// The app half of the `<Minimap>` widget. The zone label feed is `crate::area`'s: the reference
+/// fires `MINIMAP_ZONE_CHANGED` from the same area-update pass as the `ZONE_CHANGED` family
+/// (`0x494970` beside `0x494780`).
 pub(crate) struct MinimapPlugin;
 
 impl Plugin for MinimapPlugin {
@@ -1090,42 +891,27 @@ impl Plugin for MinimapPlugin {
                     probe_minimap_widget
                         .in_set(UiQuadAppend)
                         .before(emit_minimap),
-                    // Deliberately NOT on the lighting resolve's read side, though it reads
-                    // `WowLighting` (decision 2032): joining `LightingConsumeSet` would put a
-                    // 178th engine item through the world API wall, and what it buys is one
-                    // frame of the right day-night tint on a 140 px map — invisible even on a
-                    // submersion crossing, which is the one moment that value jumps.
+                    // Not in `LightingConsumeSet` though it reads `WowLighting`: at most one frame
+                    // of late tint on a 140 px map, not worth a world API item.
                     emit_minimap.in_set(UiQuadAppend),
-                    // After the emit that fills it: the composite camera draws what THIS frame's
-                    // interior branch asked for, so the target the blit quad samples is never a
-                    // frame behind the pan.
+                    // After the emit that fills it, so the blit never samples a frame-old target.
                     composite::drive_composite.after(UiQuadAppend),
-                    // Before the script tick, so a zoom button pressed this frame routes to the
-                    // indoor/outdoor index that matches where the player actually is.
+                    // Before the script tick, so a zoom button routes to the live index.
                     feed_minimap_inside.in_set(crate::ui_script::UiFeed),
-                    // Before the script tick, so an addon's OnUpdate steers off this frame's
-                    // heading rather than last frame's.
+                    // Before the script tick, so an addon's OnUpdate reads this frame's heading.
                     feed_minimap_player_facing.in_set(crate::ui_script::UiFeed),
-                    // After the tick that can call `Minimap:SetMaskTexture`, before the emit that
-                    // reads `MinimapAssets::mask`: a mask set this frame is the one this frame
-                    // draws with.
+                    // After the tick that can set the mask, before the emit that draws with it.
                     feed_minimap_mask
                         .after(crate::ui_script::UiInput)
                         .before(UiQuadAppend),
-                    // Before the script tick, and after the containment verdict it reads: the
-                    // `MINIMAP_PING` event and `Minimap:GetPingPosition()`'s value land in the
-                    // same tick, on a ping the renderer already drew at the end of last frame.
-                    // Gated on the interface being up (decision 2279): a group member's
-                    // `MSG_MINIMAP_PING` can land in the same drain as the login burst, and the
-                    // `fresh` latch it sets is spent by this system's take — on the boot VM, with
-                    // no `MiniMapPing` frame to show it, if this ran in 2214's one-frame window.
-                    // Gated, the latch simply waits for the first frame with an interface.
+                    // Before the script tick, after the containment verdict it reads. Gated on the
+                    // in-game UI: a member's ping in the login burst would otherwise spend its
+                    // `fresh` latch on the boot VM, which has no `MiniMapPing` frame.
                     ping::drive_minimap_ping
                         .after(feed_minimap_inside)
                         .in_set(crate::ui_script::UiFeed)
                         .run_if(crate::ui_script::ingame_ui_up),
-                    // Before the script tick, so GameTimeFrame's OnUpdate reads this frame's
-                    // minute, not last frame's.
+                    // Before the script tick, so GameTimeFrame reads this frame's minute.
                     feed_game_time.in_set(crate::ui_script::UiFeed),
                     // After the world-mouseover drive (UnitFeed): a same-frame world-hover→blip
                     // transition must end with the blip tooltip shown, not the fade.
@@ -1155,9 +941,8 @@ mod tests {
 
     #[test]
     fn default_light_dims_tiles_below_white() {
-        // The client's no-light default: ambient = gray 0x40 (≈0.251), diffuse = white. The tint is
-        // ≈0.79, NOT 1.0 — i.e. drawing tiles at flat white is ≈1.27× too bright (the director's
-        // report). 0.25·1 + 0.75·lerp(0.251, 1, (64+96)/256=0.625) = 0.25 + 0.75·0.719 ≈ 0.789.
+        // The reference's no-light default, ambient grey 0x40 (≈0.251) and diffuse white:
+        // 0.25·1 + 0.75·lerp(0.251, 1, (64+96)/256=0.625) = 0.25 + 0.75·0.719 ≈ 0.789.
         let t = minimap_day_tint([0.251; 3], [1.0; 3]);
         approx(t, [0.789; 3]);
         assert!(t[0] < 0.95, "flat white would be too bright");
@@ -1165,7 +950,7 @@ mod tests {
 
     #[test]
     fn pitch_black_light_still_tints_partway_to_white() {
-        // The +96 luma floor keeps the map dimly visible even with zero light: 0.75·(0+1·0.375) ≈ 0.28.
+        // The +96 luma floor keeps the map dimly visible with no light: 0.75·(0+1·0.375) ≈ 0.28.
         approx(minimap_day_tint([0.0; 3], [0.0; 3]), [0.281; 3]);
     }
 }
diff --git a/crates/benilla-app/src/minimap/ping.rs b/crates/benilla-app/src/minimap/ping.rs
index 6e63b7ed..c218c756 100644
--- a/crates/benilla-app/src/minimap/ping.rs
+++ b/crates/benilla-app/src/minimap/ping.rs
@@ -1,54 +1,27 @@
-//! The minimap **ping** (decision 1596; the feature 0471 paused and this brings back).
+//! The minimap ping, engine-owned and pinned to a world point.
 //!
-//! ## The pin
+//! The world `(x, y)` is the only stored position: the stock `Minimap_OnUpdate` re-seats the
+//! `MiniMapPing` frame every frame from `GetPingPosition()`, the normalized offset
+//! [`drive_minimap_ping`] republishes against the live view radius, so the marker follows the pan
+//! and the zoom with no second copy to fall out of step.
 //!
-//! A ping marks a **place in the world**, so a world point `(x, y)` is the only thing this module
-//! stores. Where it lands on screen is *derived* — by the stock `Minimap_OnUpdate`, which
-//! re-seats the `MiniMapPing` frame every frame from `GetPingPosition()`, the normalized offset
-//! [`drive_minimap_ping`] republishes from the pin against the live view radius. It therefore
-//! cannot drift from the map, cannot lag the pan by a frame, and cannot survive a zoom change at
-//! the old scale: there is no second copy of the position to fall out of step with.
+//! - In: the stock `Minimap_OnClick` calls `Minimap:PingLocation(dx, dy)` in UI units from the
+//!   centre; the renderer converts it with the geometry of the frame it draws: UI units × the seam
+//!   scale = window px, ÷ `px_per_yd` = yards.
+//! - Across: our ping sends `MSG_MINIMAP_PING` (raw world floats, relayed to the rest of the group
+//!   only, `GroupHandler.cpp:384-391`); a member's seats the same way. A ping seats locally at
+//!   click time, so a solo ping works.
+//! - Out: `MINIMAP_PING (unitToken, nx, ny)` fires with the relay `0x4ee330`'s offsets
+//!   `(−dy·k, dx·k)`, `k = 1/(2·radius)`; `Minimap:GetPingPosition()` reads them back.
 //!
-//! That is the whole difference from the first attempt (decision 0453 / 0471), which stored the
-//! world point in the engine but drew the marker from **Lua** off a stale push; 1596 §2 has the
-//! autopsy.
+//! The reference keeps the world point in two statics nothing clears (`0xbc787c`/`0xbc7880`), and
+//! the stock `Minimap.lua` owns everything visible: it shows the `MiniMapPing` `<Model>`
+//! (`Interface\MiniMap\Ping\MinimapPing.mdx`, rendered by `crate::ui_models`), holds it 5 s and
+//! fades it 0.5 s (`MINIMAPPING_TIMER`, `MINIMAPPING_FADE_TIMER`). `WorldMapPing` is the same model
+//! on the world map.
 //!
-//! ## The three legs
-//!
-//! - **In** — a click reaches Lua's `Minimap_OnClick` (the stock one, hookable: the corpus's
-//!   `CleanMinimap` replaces that global outright), which calls `Minimap:PingLocation(dx, dy)`
-//!   with centre-relative offsets in **UI units**. [`seat_click`]'s caller drains it in the *same
-//!   frame it draws the map*, converting through that frame's own geometry: UI units × the 0582
-//!   seam scale = window px, ÷ `px_per_yd` = yards. (Skipping that seam multiply is what put the
-//!   first version's ping ~27 % too far from the player at 1080p.)
-//! - **Across** — our own ping sends `MSG_MINIMAP_PING` (raw world floats; the server relays them
-//!   verbatim to the rest of the group and nowhere else). A group member's arrives through the
-//!   session event and seats the same way. A ping is seated **locally at click time**, never
-//!   waited for off the wire: vanilla pings work solo.
-//! - **Out** — `MINIMAP_PING (unitToken, nx, ny)` fires for addons, with the same normalized
-//!   offsets the relay `0x4ee330` hands Lua (`(−dy·k, dx·k)`, `k = 1/(2·radius)`).
-//!   `Minimap:GetPingPosition()` reads the live value back.
-//!
-//! ## Lifetime and pixels — the stock `Minimap.lua`'s and its `<Model>`'s, not ours
-//!
-//! The reference splits the ping in two: the engine stores the world point in a pair of statics
-//! **nothing ever clears** (`0xbc787c`/`0xbc7880` — six instructions touch those cells
-//! and the only zeroing is a CRT initializer), and FrameXML owns everything visible — the
-//! `MiniMapPing` `<Model>` it shows on `MINIMAP_PING`, re-seats every frame from
-//! `GetPingPosition()`, holds 5 s (`MINIMAPPING_TIMER`), "fades" 0.5 s through a `SetAlpha(255·t)`
-//! that clamps to full until the last ~2 ms, and hides. Since 1751's swap that file runs here
-//! verbatim (1974), and since decision 2013 the `<Model>` it shows **renders its own file**
-//! (`Interface\MiniMap\Ping\MinimapPing.mdx`, through `crate::ui_models`): the spinner on its
-//! global-sequence clock, the static centre, the ring on the looping Stand — the model's own
-//! bones, weight tracks and additive quads, on the pane's private clock that runs only while the
-//! frame is shown (decision 2007). The sprite this module used to draw in their place (1596/1599's
-//! byte-measured re-expression of those quads) is gone with it, and so is the world-map ping gap
-//! 1980 named: `WorldMapPing` is the same file on the map sheet.
-//!
-//! What is *not* a lifetime: proximity. The first version applied the client's 10-yd
-//! `d² < 100` auto-clear to the party ping, and that clear belongs to the **`SMSG_GOSSIP_POI`
-//! marker** — a different feature in a different slot (`0x6d99aa`–`0x6d9a4c`). Walking to your
-//! own ping used to delete it mid-hold.
+//! Reaching a ping does not clear it: the reference's 10-yd `d² < 100` auto-clear belongs to the
+//! `SMSG_GOSSIP_POI` marker (`0x6d99aa`–`0x6d9a4c`).
 
 use bevy::prelude::*;
 
@@ -59,50 +32,37 @@ use super::blips::BlipCtx;
 use crate::net::{ClientCommand, Guid, NetCommands, SelfPlayer};
 use crate::player::Player;
 
-/// The stored ping — the reference's two statics. One, never cleared: the reference keeps no
-/// list, and no map tag either (a worldport mid-ping re-projects the old point against the new
-/// map's player position, which the stock Lua's disc test then hides — reproduced as is).
+/// The stored ping, the reference's two statics: one, never cleared, with no map tag (after a
+/// worldport the old point re-projects and the stock Lua's disc test hides it).
 struct LivePing {
-    /// **The pin**: the WoW `(x, y)` this ping marks. The only stored position; the screen seat is
-    /// re-derived from it every frame.
+    /// The WoW `(x, y)` this ping marks; the screen seat is re-derived from it every frame.
     world: (f32, f32),
-    /// The pinger's guid, `0` = ourselves — resolved to the `MINIMAP_PING` event's unit token, and
-    /// the test for "this is ours, put it on the wire".
+    /// The pinger's guid, `0` for ourselves: the event's unit token, and whether it is sent.
     sender: u64,
 }
 
-/// The engine-owned ping state (decision 1596). Seated by a click (drained in the renderer, with
-/// that frame's geometry) or by a group member's `MSG_MINIMAP_PING`; announced by
-/// [`drive_minimap_ping`]; drawn by the stock `MiniMapPing` frame for exactly as long as that
-/// frame shows itself.
+/// The engine-owned ping, seated by a click or a group member's `MSG_MINIMAP_PING`, announced by
+/// [`drive_minimap_ping`] and drawn by the stock `MiniMapPing` frame.
 #[derive(Resource, Default)]
 pub(crate) struct MinimapPing {
     live: Option<LivePing>,
-    /// A ping seated since the last [`drive_minimap_ping`] — it still owes the world an outbound
-    /// `MSG_MINIMAP_PING` (if it is ours) and a `MINIMAP_PING` event (either way).
+    /// Seated since the last [`drive_minimap_ping`]: owes a `MINIMAP_PING` event, and the wire send
+    /// if ours.
     fresh: bool,
 }
 
 impl MinimapPing {
-    /// Seat a ping at a world point. Re-pinging replaces: the reference tolerates the same, and a
-    /// group echo of our own click lands on the spot we already drew (`Minimap_SetPing` twice on
-    /// one spot just restarts the timer).
+    /// Seat a ping at a world point, replacing the live one, as the reference's re-ping does.
     pub(crate) fn seat(&mut self, world: (f32, f32), sender: u64) {
         self.live = Some(LivePing { world, sender });
         self.fresh = true;
     }
 }
 
-/// Convert a `Minimap:PingLocation(x, y)` click into the world point it names, drain-side.
-///
-/// `ui` is centre-relative in **UI units** (x right, y up — `GetCursorPosition()`'s space);
-/// `seam` is window px per UI unit ([`crate::ui_script::seam_scale`]), and `ctx` is the geometry
-/// of the map **as drawn this frame**. The mapping is [`BlipCtx::offset`]'s inverse: screen right
-/// = −WoW y (west), screen up = +WoW x (north).
-///
-/// `None` when the click is outside the disc — the reference's `Minimap_OnClick` makes the same
-/// test in Lua (`sqrt(x² + y²) < width/2`), stated here in yards because that is the space the
-/// answer lives in.
+/// A `Minimap:PingLocation(x, y)` click to the world point it names: `ui` is centre-relative UI
+/// units (x right, y up), `seam` window px per UI unit ([`crate::ui_script::seam_scale`]), `ctx`
+/// the map as drawn this frame. The inverse of [`BlipCtx::offset`]: screen right is −WoW y, screen
+/// up +WoW x. `None` outside the disc, the stock test (`Minimap.lua:135`) in yards.
 fn click_to_world(ctx: &BlipCtx, ui: (f32, f32), seam: f32) -> Option<(f32, f32)> {
     if ctx.px_per_yd <= 0.0 || seam <= 0.0 {
         return None;
@@ -115,25 +75,16 @@ fn click_to_world(ctx: &BlipCtx, ui: (f32, f32), seam: f32) -> Option<(f32, f32)
     Some((ctx.wx + up_yd, ctx.wy - right_yd))
 }
 
-/// Seat this frame's `Minimap:PingLocation` click — inside the renderer, against the geometry
-/// the player actually clicked on and the map actually drew at.
-///
-/// The seat happens here rather than in a system of its own precisely so there is no window in
-/// which a click is held against a *stale* view scale: the first version parked the click for a
-/// separate system that read the scale the renderer had left behind on the previous frame, and
-/// dropped the click outright whenever that leftover was still zero. (The *drain* is the caller's,
-/// one step earlier, so the click is spent even on a frame that draws no map — see there.)
+/// Seat this frame's `Minimap:PingLocation` click inside the renderer, against the geometry the
+/// map drew this frame, so a click is never converted at a stale scale.
 pub(super) fn seat_click(ctx: &BlipCtx, ping: &mut MinimapPing, click: Option<(f32, f32)>) {
     if let Some(world) = click.and_then(|c| click_to_world(ctx, c, ctx.seam)) {
         ping.seat(world, 0);
     }
 }
 
-/// Announce a fresh ping and republish the position — everything that is *not* geometry.
-///
-/// Runs before the script tick so the `MINIMAP_PING` event and the position behind
-/// `Minimap:GetPingPosition()` land in the same tick, and so an addon's handler sees a ping that
-/// is already seated (the renderer seated it at the end of the previous frame).
+/// Republish the ping's normalized position and announce a fresh ping. Runs before the script
+/// tick, so the `MINIMAP_PING` event and `Minimap:GetPingPosition()` land in the same tick.
 pub(super) fn drive_minimap_ping(
     script: Option<bevy::ecs::system::NonSendMut<UiScript>>,
     mut ping: ResMut<MinimapPing>,
@@ -149,11 +100,8 @@ pub(super) fn drive_minimap_ping(
         return;
     };
 
-    // The normalized offsets, recomputed from the pin every tick against the live view radius —
-    // the byte-verified relay's own `(−dy·k, dx·k)`, `k = 1/(2·radius)`. With the map hidden there
-    // is no live index to read (the extract publishes no slot), so the event's numbers fall back
-    // to the registered default zoom: an addon still hears the ping, at the scale the map would
-    // have if it were up.
+    // The relay's `(−dy·k, dx·k)`, `k = 1/(2·radius)`, recomputed every tick. With the map hidden
+    // there is no live zoom, so the registered default stands in.
     let wow = bevy_to_wow(player.pos);
     let radius = super::view_radius_yd(
         widget
@@ -176,18 +124,16 @@ pub(super) fn drive_minimap_ping(
     let Some(live) = ping.live.as_ref() else {
         return;
     };
-    // Ours goes on the wire — raw world floats — but only when there is a group to relay them to.
-    // The reference gates its send the same way (`PingLocation` `0x4eeca0` sends only when
-    // grouped, VERIFIED) while still pinging locally, which is why a solo ping works at all and
-    // why the marker is drawn at click time rather than awaited off the wire.
+    // Ours goes on the wire only when grouped, as the reference's `PingLocation` (`0x4eeca0`)
+    // sends; the local ping stands either way.
     if live.sender == 0 && group.in_group {
         let _ = commands.0.send(ClientCommand::MinimapPing {
             x: live.world.0,
             y: live.world.1,
         });
     }
-    // The event's unit token: ourselves, or the sender's party slot. A sender we cannot resolve
-    // (they left the group mid-flight) still pings — the reference's own Lua ignores arg1.
+    // The event's unit token: ourselves or the sender's party slot. An unresolved sender still
+    // pings; the stock handler ignores arg1.
     let self_guid = self_q.iter().next().map(|g| g.0);
     let token = if live.sender == 0 || Some(live.sender) == self_guid {
         "player".to_string()
@@ -207,8 +153,7 @@ pub(super) fn drive_minimap_ping(
     );
 }
 
-/// Register the ping's packet handler — called from [`super::MinimapPlugin`] (in the net handler
-/// table since 2313).
+/// Register the ping's packet handler.
 pub(super) fn register(app: &mut App) {
     use crate::net::NetHandlerApp;
     app.net_handler(
@@ -217,10 +162,7 @@ pub(super) fn register(app: &mut App) {
     );
 }
 
-/// A group member pinged (decision 1596). The wire carries raw world floats and the relay is
-/// stateless in the reference too — we seat them as the pin and the minimap derives the rest.
-/// The server only relays a ping between people who are grouped, and a ping from another map
-/// would be dropped by the renderer's own map test anyway.
+/// A group member's ping: raw world floats, seated as the pin.
 fn on_minimap_ping(In(ev): In<benilla_protocol::SessionEvent>, mut ping: ResMut<MinimapPing>) {
     if let benilla_protocol::SessionEvent::MinimapPing { guid, x, y } = ev {
         ping.seat((x, y), guid);
@@ -251,16 +193,13 @@ mod tests {
         }
     }
 
-    /// **The first version's ping landed in the wrong place** (decision 1596 §2.1): the click
-    /// arrives in UI units and the map's `px_per_yd` is in *window* px, and it divided one by the
-    /// other. At the shipped default (0.9 uiScale on a 1080p window) the seam is ≈1.27, so every
-    /// ping seated ≈27 % further from the player than the player clicked — worse the further out
-    /// you clicked, which is exactly what "it pings somewhere else" looks like.
+    /// The click is in UI units and `px_per_yd` in window px: at 0.9 uiScale on a 1080p window the
+    /// seam is ≈1.27, and a conversion that skips it seats every ping ≈27 % too far out.
     #[test]
     fn a_click_converts_through_the_seam_scale() {
         let c = ctx();
         let seam = 1080.0 / 768.0 * 0.9; // the shipped default at 1080p
-                                         // 20 UI units right of centre → 20·seam window px → ÷ px_per_yd yards WEST (−y).
+                                         // 20 UI units right → 20·seam px → yards west (−y).
         let (x, y) = click_to_world(&c, (20.0, 0.0), seam).expect("inside the disc");
         let expect_yd = 20.0 * seam / c.px_per_yd;
         assert!((x - 0.0).abs() < 1e-3, "no northing from a due-east click");
@@ -269,7 +208,7 @@ mod tests {
             "screen right is WoW −y (west): {y} vs {}",
             -expect_yd
         );
-        // The bug: dropping the seam multiply shortens every click by the same factor.
+        // Without the seam multiply every click lands off by the same factor.
         let naive = 20.0 / c.px_per_yd;
         assert!(
             (expect_yd - naive).abs() > 5.0,
@@ -277,7 +216,7 @@ mod tests {
         );
     }
 
-    /// Screen up is WoW +x (north) — [`BlipCtx::offset`]'s inverse, so a ping seated from a click
+    /// Screen up is WoW +x (north), [`BlipCtx::offset`]'s inverse, so a ping seated from a click
     /// draws back under the cursor.
     #[test]
     fn a_click_round_trips_through_the_blip_mapping() {
@@ -303,8 +242,8 @@ mod tests {
         );
     }
 
-    /// **The pin.** The stored form is a world point, so walking moves the marker across the map
-    /// by exactly the player's displacement — no re-seating, no second copy to drift.
+    /// The stored form is a world point, so walking moves the marker by exactly the player's
+    /// displacement.
     #[test]
     fn the_marker_tracks_the_world_as_the_player_walks() {
         let mut c = ctx();
@@ -322,11 +261,9 @@ mod tests {
         );
     }
 
-    /// **No proximity clear** (decision 1596 §2.2). The first version applied the client's 10-yd
-    /// `d² < 100` auto-clear to the party ping; that clear belongs to the `SMSG_GOSSIP_POI` marker
-    /// (`0x6d99aa`–`0x6d9a4c`), and `MSG_MINIMAP_PING` has no C-side storage to clear at all.
-    /// Standing on your own ping must not delete it — and a frame with no click seats nothing
-    /// over it.
+    /// No proximity clear: the 10-yd `d² < 100` auto-clear is the `SMSG_GOSSIP_POI` marker's
+    /// (`0x6d99aa`–`0x6d9a4c`), and the ping's statics are never cleared. A frame with no click
+    /// seats nothing over it.
     #[test]
     fn reaching_the_ping_does_not_clear_it() {
         let mut c = ctx();
@@ -354,9 +291,7 @@ mod tests {
         assert!(ping.fresh, "a seat owes the world its event");
     }
 
-    /// A degenerate frame (the widget has not drawn yet) drops the click rather than seating a
-    /// ping at a garbage point — and, unlike the first version, that is the *only* case in which
-    /// a click is dropped for want of a scale.
+    /// A click before the map has drawn (no scale) is dropped, not seated at a garbage point.
     #[test]
     fn a_click_before_the_map_has_drawn_is_dropped() {
         let mut c = ctx();
diff --git a/crates/benilla-app/src/name_persist.rs b/crates/benilla-app/src/name_persist.rs
index 4718eeb5..466e499f 100644
--- a/crates/benilla-app/src/name_persist.rs
+++ b/crates/benilla-app/src/name_persist.rs
@@ -1,43 +1,19 @@
-//! **The name cache, kept across sessions** (decision 1689) — the load/save half of
-//! [`crate::names::NameCache`], and benilla's answer to the reference's `WDB/*.wdb` files.
+//! The creature-template half of [`crate::names::NameCache`], kept across sessions: benilla's
+//! `creaturecache.wdb`.
 //!
-//! ## Why this exists at all
+//! The reference persists only `'WNPC'`; `'WNAM'` and `'WPNM'` (player and pet names) are built
+//! with persistence off (`0x554cd0`) and cleared at world-session start
+//! ([`NameCache::clear_world_session`]). A template entry keeps its meaning, while a player guid
+//! or pet number can come to name another character or spawn.
 //!
-//! Three of benilla's caches are filled by a server round trip: player names, creature templates
-//! and pet names. **The reference persists exactly one of the three** — `creaturecache.wdb` — and
-//! that is what this module keeps. `'WNAM'` and `'WPNM'` are constructed with persistence
-//! **disabled** (`0x554cd0`'s three `push 0x0`, against `'WNPC'`/`'WIDB'`'s `push 0x1; push 0x1`)
-//! and are cleared at world-session start instead; a real 1.12 install's `WDB/` holds
-//! `creaturecache.wdb`, `npccache.wdb`, `itemcache.wdb` … and no `namecache.wdb`. 1689 read the
-//! reference as "all three" and wrote player and pet names to disk too, which is what answered a
-//! wiped server's brand-new character with a deleted one's name (B386); **decision 2223** took them
-//! back out and put the wipe in ([`NameCache::clear_world_session`]).
+//! From `DBCache.cpp` (`0x554b00`-`0x5738c0`): the 20-byte header
+//! `[FourCC | build 0x16f3 | locale | recordSize | version 1]` is compared by equality, with no
+//! checksum or TTL, and a mismatch discards the file ([`NameCache::to_tsv`] writes ours).
+//! Eviction is explicit only: a high-bit key in a response, or `SMSG_INVALIDATE_PLAYER` (`0x31C`).
 //!
-//! What survives is the half that carried the value anyway: a city's worth of creature-template
-//! queries on zone-in, answered from disk instead of the wire. The **key** is the whole argument —
-//! a template entry means the same creature on every realm forever, while a player guid means one
-//! character and a pet number one live spawn.
-//!
-//! ## The law, from the reference
-//!
-//! Two contracts of the reference's `DBCache.cpp` machine (`0x554b00`–`0x5738c0`) are the ones a
-//! re-implementation must honour, and both are about what the cache does *not* do:
-//!
-//! - **The header is compared by equality, and carries no checksum, no timestamp and no TTL.** Its
-//!   20 bytes are `[FourCC | build 0x16f3 | locale | recordSize | version 1]`. A mismatch discards
-//!   the file wholesale. Ours is a header line with the same job ([`NameCache::to_tsv`]).
-//! - **Eviction is explicit only** — a high-bit key in a response, or `SMSG_INVALIDATE_PLAYER`
-//!   (`0x31C`). Nothing ages out. That is survivable for a record whose key cannot change meaning,
-//!   which is precisely why the stores whose keys *can* are not persisted at all.
-//!
-//! ## Where it lives, and the one place we deviate
-//!
-//! The reference writes `WDB/` **inside the install**, which is precisely where benilla may not
-//! write (`docs/METHOD.md`'s read-only rule). Ours goes to `benilla-config/cache/<realm>.tsv` through
-//! [`crate::local_state`], like every other thing we persist — and it is **realm-scoped**, which
-//! the reference's is not. That is a fix rather than a preference: every key is realm-local (a
-//! player guid, a creature entry, a pet number), so one shared file would serve another realm's
-//! names to this one.
+//! Deviation: the file is `benilla-config/cache/<realm>.tsv` through [`crate::local_state`], not
+//! `WDB/` in the install, because the install is read-only; and it is per realm, because another
+//! server may hold a different template under the same entry.
 
 use std::path::PathBuf;
 
@@ -46,10 +22,7 @@ use bevy::prelude::*;
 use crate::char_select::Roster;
 use crate::names::NameCache;
 
-/// How long a run of landed answers is allowed to accumulate before it is written. The cache is
-/// worth keeping but never worth a stall: names arrive in bursts (a city's worth of creature
-/// queries on zone-in), and writing the whole file per answer would turn a burst into hundreds of
-/// rewrites. A crash inside the window costs re-asking, which is exactly what the cache is for.
+/// Seconds between writes: answers arrive in bursts on zone-in, and a crash costs only re-asking.
 const SAVE_DEBOUNCE: f32 = 10.0;
 
 pub(crate) struct NamePersistPlugin;
@@ -58,8 +31,7 @@ impl Plugin for NamePersistPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<NameCacheFile>()
             .add_systems(Update, (load_name_cache, save_name_cache).chain());
-        // The exit edge (decision 1528): the last burst of answers is worth the one write, and it
-        // is the only chance to take it — the debounce above will not fire again.
+        // The exit write catches the last burst, which the debounce would not.
         crate::shutdown::on_app_exit(app, save_on_exit.into_configs());
     }
 }
@@ -67,18 +39,15 @@ impl Plugin for NamePersistPlugin {
 /// Where this realm's cache lives and what we last wrote there.
 #[derive(Resource, Default)]
 pub(crate) struct NameCacheFile {
-    /// The realm the loaded file belongs to; `None` before the first login. A *change* is what
-    /// triggers a load — logging into a second realm must not keep the first's names.
+    /// The realm the loaded file belongs to; a change triggers a load.
     realm: Option<String>,
     path: Option<PathBuf>,
-    /// [`NameCache::generation`] as of the last successful write. The cache's own landed-answer
-    /// counter is the dirty bit — it ticks on an arrival and never on an ask, which is exactly the
-    /// edge worth writing on.
+    /// [`NameCache::generation`] at the last write: the dirty bit, which ticks on an answer.
     saved_generation: u64,
     since_save: f32,
 }
 
-/// Load the realm's cache the first frame its identity is known, and on any realm change.
+/// Loads the realm's cache the first frame its identity is known, and on a realm change.
 fn load_name_cache(
     roster: Res<Roster>,
     mut file: ResMut<NameCacheFile>,
@@ -95,23 +64,16 @@ fn load_name_cache(
     file.path = path.clone();
     file.saved_generation = names.generation();
     let Some(path) = path else {
-        return; // a hermetic capture, or no state folder — session-only, exactly as before
+        return; // a hermetic capture, or no state folder: session-only
     };
     let Ok(text) = std::fs::read_to_string(&path) else {
-        return; // no cache yet: the ordinary first-run path, not an error
+        return; // no cache yet
     };
     match NameCache::from_tsv(&text, &realm) {
         Some(loaded) => {
             let n = loaded.len();
-            // **The file's own records go in; nothing else is touched** (decision 2260). This used
-            // to be `*names = loaded`, on the premise stated here that "world entry clears the
-            // guid-keyed stores a moment later regardless" — and the ordering is the other way
-            // round. This loader fires the first frame `identity` answers, which is the frame the
-            // *pick* is in flight; `connected` does its world-session clear and then seeds our own
-            // name in the same neighbourhood. Whichever ran second won, and when it was this one
-            // the player's own name went with it — `UnitName("player")` nil for a wire round-trip,
-            // once per process, on the first login of a fresh start. See
-            // [`NameCache::install_persisted`].
+            // Install only the file's records: this runs as the pick is in flight, beside the
+            // login's clear and seed of our own name, and must not replace them.
             names.install_persisted(loaded);
             file.saved_generation = names.generation();
             debug!(
@@ -119,9 +81,7 @@ fn load_name_cache(
                 path.display()
             );
         }
-        // The header did not match — a different build, locale or format. Discarding the whole
-        // file is the reference's own rule, and the file is left on disk to be overwritten by the
-        // first save rather than deleted out from under a player who may be switching back.
+        // A header mismatch discards the file, as the reference does; the first save overwrites it.
         None => debug!(
             "names: discarding {} — header is not this build/locale/format",
             path.display()
@@ -129,7 +89,7 @@ fn load_name_cache(
     }
 }
 
-/// Write the cache when answers have landed since the last write and the debounce has elapsed.
+/// Writes the cache when answers have landed and the debounce has elapsed.
 fn save_name_cache(time: Res<Time>, mut file: ResMut<NameCacheFile>, names: Res<NameCache>) {
     file.since_save += time.delta_secs();
     if file.since_save < SAVE_DEBOUNCE {
@@ -139,8 +99,7 @@ fn save_name_cache(time: Res<Time>, mut file: ResMut<NameCacheFile>, names: Res<
     write_now(&mut file, &names);
 }
 
-/// The exit-edge write (decision 1528) — unconditional on the debounce, because there is no next
-/// frame to defer to.
+/// The exit write, regardless of the debounce.
 fn save_on_exit(mut file: ResMut<NameCacheFile>, names: Res<NameCache>) {
     write_now(&mut file, &names);
 }
@@ -163,8 +122,6 @@ fn write_now(file: &mut NameCacheFile, names: &NameCache) {
             file.saved_generation = names.generation();
             debug!("names: wrote {} records to {}", names.len(), path.display());
         }
-        // A cache we could not write is a cache we re-fill next session — worth a line, never
-        // worth failing a session over.
         Err(e) => warn!("names: cannot write {}: {e}", path.display()),
     }
 }
@@ -174,8 +131,8 @@ mod tests {
     use super::*;
     use crate::local_state::test_env::{EnvGuard, ENV_LOCK};
 
-    /// A roster with a pick in flight and no realm — [`crate::ui_macro::identity`] then answers
-    /// `("Realm", <name>)`, which is the identity the loader keys the file by.
+    /// A roster with a pick in flight and no realm: [`crate::ui_macro::identity`] answers
+    /// `("Realm", <name>)`.
     fn roster_with_pick(name: &str, guid: u64) -> Roster {
         Roster::with_pending_pick(
             vec![benilla_protocol::Character {
@@ -207,22 +164,12 @@ mod tests {
         )
     }
 
-    /// **The director's report, at the seam that produced it** (decision 2260).
-    ///
-    /// The realm cache is read off disk the first frame the pick's identity is known, and the
-    /// login's seed of our OWN name lands in the same neighbourhood — so the two race, and the
-    /// loader used to win by overwriting the whole cache (`*names = loaded`). What that cost was
-    /// `UnitName("player")` answering **nil** for one wire round-trip on the first login of a
-    /// fresh start, because the feed's player snapshot carries the cache's answer and a `None`
-    /// there replaces the roster seat the UI loaded under. KLHThreatMeter reads it on its first
-    /// `OnUpdate` and indexes a table with it: `KTM_Tables.lua:198: table index is nil`.
-    ///
-    /// The load runs here *after* the seed on purpose: that is the losing order, and it must now
-    /// be survivable rather than merely unlikely.
+    /// The load runs after the login's seed of our own name, the order that would lose it, which
+    /// left `UnitName("player")` nil on the first login.
     #[test]
     fn the_disk_load_installs_templates_without_touching_the_live_session() {
         use benilla_protocol::guid;
-        /// `counter | (entry << 24) | (high << 48)` — the server's own composition.
+        /// `counter | (entry << 24) | (high << 48)`, the server's composition.
         fn compose(high: u16, entry: u32, counter: u32) -> u64 {
             u64::from(counter) | (u64::from(entry) << 24) | (u64::from(high) << 48)
         }
@@ -240,8 +187,7 @@ mod tests {
         let _capture = EnvGuard::unset("WOW_CAPTURE");
         let _home = EnvGuard::set("BENILLA_HOME", tmp.to_str().expect("utf-8 temp path"));
 
-        // A realm file with one creature template in it — written the way the saver writes it, so
-        // the header the loader gates on is this build's by construction.
+        // A realm file with one creature template, written by the saver so the header matches.
         let mut on_disk = NameCache::default();
         on_disk.insert_creature(
             CREATURE_ENTRY,
@@ -261,8 +207,7 @@ mod tests {
         std::fs::create_dir_all(path.parent().expect("cache dir")).expect("cache dir");
         std::fs::write(&path, on_disk.to_tsv("Realm")).expect("write the realm cache");
 
-        // The live session: the login has already seeded our own name (and a pet's), exactly as
-        // `net::session::connected` does a moment after the pick goes out.
+        // The login has already seeded our own name and a pet's, as `net::session::connected` does.
         let mut names = NameCache::default();
         names.insert_player(me, "Nelprifour".into(), None);
         names.insert_pet(PET_NUMBER, "Fluffy".into());
diff --git a/crates/benilla-app/src/nameplates.rs b/crates/benilla-app/src/nameplates.rs
index 49d43d91..c950c19e 100644
--- a/crates/benilla-app/src/nameplates.rs
+++ b/crates/benilla-app/src/nameplates.rs
@@ -1,71 +1,23 @@
-//! **Overhead unit names** — the 1.12.1 overhead-name system, incl. the color/occlusion corrections
-//! the director's reference A/B forced:
+//! Overhead unit names, the 1.12 world-text name system.
 //!
-//! - **World-pass geometry, depth-tested.** The name batch is created depth-test + depth-write ON
-//!   (`0x6c7470 → 0x5c1d60(1,1)`; flush `0x5c8b70` → `GxRsSet(GL_DEPTH_TEST, 1)`) and drawn inside
-//!   the world/model 3-D pass — **walls occlude names**. (The floating combat text batch is
-//!   created `(0,0)`: an overlay, through walls — our combat text stays as-is.) So a name here is
-//!   a real **world billboard mesh**: glyph quads in name-local pitch units, camera-facing,
-//!   world-scaled — occlusion, the distance shrink, and exact centering all fall out of the world
-//!   pass. Named divergence: `AlphaMode::Blend` depth-tests but doesn't depth-write; name-vs-name
-//!   overlap resolves by transparent-pass sorting instead — visually equivalent.
-//! - **Reaction-colored** (the A/B falsified the earlier "constant white"): the render `0x6c6e90`
-//!   fetches `unit->vtable[0x2c]` = `CGUnit::GetSelectionCircleColor 0x605960` — the SAME selector
-//!   as the ground selection ring. NPC: dead gray, else reaction red/orange/yellow/green; player:
-//!   hostile red, else the `¬X∧¬Y` split — PvP-flagged green (party pale-green), unflagged the
-//!   soft blue (party pale-blue). benilla does not re-derive any of that: it calls the ring's own
-//!   [`ring_variant`] and paints what it answers, because "the SAME selector" above is the literal
-//!   claim (decision 0659 — a hand-copied mirror had drifted and a flagged player wore a green
-//!   ring under a blue name). The selector's **first-priority branch** — the combat-flash
-//!   red↔orange pulse — is live too: [`CombatFlash`] (recomputed per frame from the selection +
-//!   our server-echoed attack bracket, exactly the client's per-frame `[unit+0xc58]` bit 0x10)
-//!   overrides the whole palette while we melee this unit.
-//! - **Anchor**: the posed PlayerName attachment ([`overhead_anchor`]), re-read **every frame in
-//!   lockstep with the mesh pose, no smoothing** (byte-verified: the client memoizes the pose per
-//!   model generation; our per-frame joint read matches).
-//! - **Scale**: `d = anchor.z − feet.z`, `scale = d > 4 ? (d/4)·1.5·0.2 : 0.2` — unit-HEIGHT
-//!   scaling (taller model, bigger name; humanoids all at the 0.2 floor). Pitch : size is 1:1 at
-//!   the desc level (verified).
-//! - **Seat** (the world-mode vertical law, settled after the director's "names too low"
-//!   falsified the first reading): `drawPos.z = anchor.z + lineCount·scale` is the **TOP line's
-//!   BASELINE** and the block **hangs DOWN** from it — line `i`'s baseline at
-//!   `anchor.z + (lineCount − i)·scale` (the line layout `0x5cdc20`'s rotated branch: line 0
-//!   seeded at local-Y 0, one pitch subtracted per line; sign pinned by the raid-marker
-//!   cross-check). So the whole block sits ABOVE the attachment — never "bottom at the anchor",
-//!   which sat every name one line-height too low. Each line's baseline lands on that grid via
-//!   the face's own ascent fraction ([`UiFontAtlas::ascent_ratio`], the `[0x17c]` load_param); the
-//!   sub-pitch ascent/descent extents inside the top/bottom lines remain the gx-boundary
-//!   INFERRED residual (a director A/B pins the exact pixels).
-//! - **Show gate** (`ShouldShowName 0x6070a0`): own unit → `UnitNameOwn` (binary default OFF —
-//!   ours too since 1804 — checked before the rescue; plus a benilla-side fade gate: the own name
-//!   hides with the fully-faded first-person avatar, our reading of the gate's INFERRED
-//!   `vtable+0x58` can-show leg); the **current TARGET shows
-//!   regardless of cvars** — the rescue global `[0xb4e2d8]` is the *selection*; the earlier
-//!   "mouseover" reading of the same global is CORRECTED here; a **dead creature shows only via
-//!   the target rescue** (director-verified on the reference; the byte leg is unconfirmed in the
-//!   binary); players → `UnitNamePlayer` (default ON); NPCs → `UnitNameNPC`
-//!   and own → `UnitNameOwn` (both default OFF, the binary's own — see [`NameConfig`]).
-//! - **Lines** (`0x608f50`): NPC = name + `<Subname>` (an empty wire subname is no line); player =
-//!   [flag prefixes +] name + `<Guild>`. The prefixes are the a1–a3 vtable-slot decorations of the
-//!   line stack (`+0x7c/+0x80/+0x84`), glued straight onto the name by the `%s%s…` assembly —
-//!   `<AFK>`/`<DND>`/`<GM>` in that slot order from `PLAYER_FLAGS` (see [`flag_prefix`]).
-//!   The trio is unique to the overhead name binary-wide
-//!   (`CHAT_FLAG_GM`'s only xref is the a3 slot).
+//! - Geometry: a camera-facing glyph mesh in the world pass, depth-tested like the reference's name
+//!   batch (`0x6c7470` calls `0x5c1d60(1,1)`), so walls occlude names. Deviation:
+//!   `AlphaMode::Blend` writes no depth where the reference does, because overlapping names
+//!   resolving by sort order look the same.
+//! - Colour: the render `0x6c6e90` calls the ground ring's selector (`0x605960`).
+//! - Anchor: the posed PlayerName attachment, re-read every frame with no smoothing, as the
+//!   reference does.
+//! - Seat: the top line's baseline is at `anchor.z + lineCount*scale` and the block hangs down one
+//!   pitch per line (`0x5cdc20`'s rotated branch).
+//! - Show gate (`ShouldShowName`, `0x6070a0`): the own unit by `UnitNameOwn`, before the target
+//!   rescue; the current target (`[0xb4e2d8]`, the selection) regardless of CVars; a dead creature
+//!   only through that rescue; others by `UnitNamePlayer` or `UnitNameNPC`.
+//! - Lines (`0x608f50`): an NPC's name and `<Subname>`; a player's `<AFK>`/`<DND>`/`<GM>` prefixes,
+//!   name and `<Guild>`. The guild (a5) and subname (a6) slots share the format `"\n<%s>"`
+//!   (`0x860f9c`) and are never both reached; a5 alone is CVar-gated (`0x609085`).
 //!
-//!   **The guild line is a5 and the subname line is a6, and the two can never both appear** —
-//!   *branch exclusivity*: the player branch emits a1–3 · a4 · a5 · a8 and
-//!   never reaches a6/a7; the NPC branch emits a1–3 · a4 · a6 · a7 and never reaches a5/a8. Both
-//!   slots share the one format string `"\n<%s>"` (`0x860f9c`), so one `Option<&str>` carries
-//!   whichever the unit's branch supplies ([`lines_current`]'s `bracketed`). a5 alone is
-//!   CVar-gated — mask bit `0x10`, `UnitNamePlayerGuild`, registered `"1"` (`0x609085`); the
-//!   guild NAME comes from the identity cache `GetGuildInfo` reads
-//!   ([`crate::ui_guild::unit_guild_name`]), so an unqueried guild draws no line and the line
-//!   appears when the query answers.
-//!
-//!   **Still absent, and it is a5's twin:** a4's PvP rank/title prefix (`UnitNamePlayerPVPTitle`,
-//!   bit `0x20`) — the rank byte streams, but `PVP_RANK_%d_%d`'s second index is a faction side
-//!   `ui_unit` does not resolve for an arbitrary player yet. a7 (the NPC relationship line) and a8
-//!   (the foreign-server label) have no cross-realm wire here at all.
+//! Not built: the a4 PvP rank prefix (`UnitNamePlayerPVPTitle`, bit `0x20`), whose faction side
+//! `ui_unit` does not resolve for another player; a7 and a8 have no cross-realm wire here.
 
 use std::collections::HashMap;
 
@@ -87,25 +39,15 @@ const SCALE_FLOOR: f32 = 0.2; // [0x80679c]
 const SCALE_KNEE: f32 = 4.0; // [0x8112a8]
 const SCALE_RATE: f32 = 1.5; // [0x8112ac]
 
-/// benilla's nameplate config (the client's `0xce8720` cvar mask, reduced to what streams today),
-/// player-settable since 0992: 1.12's own `UnitNamePlayer`/`UnitNameNPC`/`UnitNameOwn` CVars over
-/// these gates (the Options window's Nameplates page, through the 0954 store — the arms live in
-/// [`crate::cvars`]).
-///
-/// **The defaults are the reference's** (the `0x6c7470` registrar: `UnitNamePlayer` `"1"`,
-/// `UnitNameNPC` `"0"`, `UnitNameOwn` `"0"`). `npc` and `own` shipped ON from 2026-07-12 to
-/// 1804 — a pair of director directives ("figure out text name over NPCs"; "we should show our
-/// name") that were about making the feature *visible while it was being built*, and stayed as
-/// the shipped default long after it worked. Both rows are on the Nameplates page; turning them
-/// back on is a click.
+/// The `UnitNamePlayer`/`UnitNameNPC`/`UnitNameOwn` CVars (the reference's `0xce8720` mask), with
+/// the reference's defaults `"1"`, `"0"`, `"0"` (`0x6c7470`).
 #[derive(Resource, Clone, Copy)]
 pub(crate) struct NameConfig {
     pub(crate) player: bool,
     pub(crate) npc: bool,
     pub(crate) own: bool,
-    /// `UnitNamePlayerGuild` — mask bit `0x10`, registered `"1"`. Unlike the trio above this one
-    /// does **not** gate a whole name: it gates one *line* of the player stack (`0x609085`, the a5
-    /// slot), which is why it reads at the line build rather than in the show ladder.
+    /// `UnitNamePlayerGuild`, mask bit `0x10`, registered `"1"`: gates the a5 guild line
+    /// (`0x609085`), not a whole name.
     pub(crate) player_guild: bool,
 }
 
@@ -120,21 +62,14 @@ impl Default for NameConfig {
     }
 }
 
-/// The player name-line flag decorations — the a1–a3 prefix slots of the line-stack law
-/// (`0x608f50`): the CGPlayer
-/// vtable overrides at `+0x7c/+0x80/+0x84` (`0x5ec9e0/0x5eca40/0x5eca80`) each test one
-/// `PLAYER_FLAGS` bit and resolve one GlobalStrings key — slot order **AFK (0x2) → DND (0x4) →
-/// GM (0x8)**, all set flags stack, bare `%s%s…` concatenation before the name (`<GM>One`, no
-/// space). The base CGUnit slots are `ret 8` stubs — players only, NPCs never decorate.
-/// `PLAYER_FLAGS` is field 190, `UF_FLAG_PUBLIC` (streams for every player in range);
-/// vmangos sets the bits at `/afk`, `/dnd`, `.gm on` (`Player.h:316–318`). The tag strings are
-/// the reference install's own `CHAT_FLAG_AFK/DND/GM` values (patch-2 `GlobalStrings.lua:534–536`
-/// — the exe holds only the keys). Not built: the local player's client-side `/afk` echo
-/// (`[0xb6e5cc]`, role INFERRED) — the wire flag round-trips fast enough.
+/// The a1-a3 prefix slots of the line stack (`0x608f50`), CGPlayer vtable `+0x7c/+0x80/+0x84`
+/// (`0x5ec9e0`, `0x5eca40`, `0x5eca80`): each set `PLAYER_FLAGS` bit (vmangos `Player.h:316-318`)
+/// stacks in slot order with no space before the name; the base CGUnit slots are stubs, so NPCs
+/// never decorate. The tags are `CHAT_FLAG_AFK/DND/GM` (`GlobalStrings.lua:534-536`).
+/// The own player's AFK slot also reads the client-side mirror `[0xb6e5cc]` ([`drive_nameplates`]).
 const FLAG_PREFIXES: [(u32, &str); 3] = [(0x2, "<AFK>"), (0x4, "<DND>"), (0x8, "<GM>")];
 
-/// The concatenated name-line prefix for a player's `PLAYER_FLAGS` — empty for the common
-/// unflagged case (no allocation beyond the empty `String`).
+/// The name-line prefix for a player's `PLAYER_FLAGS`; empty when unflagged.
 fn flag_prefix(player_flags: u32) -> String {
     FLAG_PREFIXES
         .iter()
@@ -143,12 +78,8 @@ fn flag_prefix(player_flags: u32) -> String {
         .collect()
 }
 
-/// Whether `cached` is exactly the line stack [`drive_nameplates`]'s stale arm would build from
-/// these inputs — compared in place, because the steady frame must not allocate three strings per
-/// shown unit just to learn nothing changed. Equivalent to string equality against the built stack
-/// (the differential test pins it): line 0 is the set [`FLAG_PREFIXES`] tags in slot order glued
-/// onto the name, line 1 the `<{bracketed}>` decoration — the a5 guild line for a player, the a6
-/// subname line for an NPC, never both (the module doc's branch exclusivity).
+/// Whether `cached` equals the stack [`drive_nameplates`] would build from these inputs, compared
+/// in place so the steady frame allocates nothing; a differential test pins the equivalence.
 fn lines_current(
     cached: &[String],
     player_flags: u32,
@@ -190,27 +121,20 @@ pub(crate) fn height_scale(d: f32) -> f32 {
     }
 }
 
-/// What a name line is painted with. The classification is **not** ours: the per-frame name render
-/// fetches `unit->vtable[0x2c]` = `CGUnit::GetSelectionCircleColor 0x605960` — literally the same
-/// selector as the ground ring (decision 0156) — so [`ring_variant`] IS the law and this only adds
-/// the flash seat that lives outside the palette.
-///
-/// It used to be a hand-copied mirror of that selector, and the copy went stale: decision 0453
-/// taught the ring the player path's `¬X∧¬Y` legs (PvP-flagged → green, party → pale) and the
-/// mirror kept answering plain blue, so a flagged player drew a green ring under a blue name
-/// (decision 0659). Deleting the mirror is the fix; there is one selector now.
+/// What a name line is painted with: the ring's selector ([`ring_variant`]), which the reference's
+/// name render also calls (`0x605960`), or the combat flash.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 enum NamePaint {
-    /// The selector's own answer — the whole palette.
+    /// The selector's answer.
     Variant(RingVariant),
-    /// The combat-flash pulse — the selector's first-priority branch, which outranks the palette.
-    /// Its material tint is rewritten each frame from [`CombatFlash::color`]; this is the seed.
+    /// The combat-flash pulse, the selector's first-priority branch; its tint is rewritten each
+    /// frame from [`CombatFlash::color`].
     Flash,
 }
 
 impl NamePaint {
-    // GAMMA LANE (0161): `linear_rgb` passes the authored byte values RAW into the gamma
-    // framebuffer (stock-PBR unlit writes base_color as-is; the frame decodes once at FFXGlow).
+    // `linear_rgb` passes the authored bytes raw into the gamma framebuffer: unlit writes
+    // base_color as-is, and the frame decodes once at FFXGlow.
     fn color(self) -> Color {
         match self {
             Self::Variant(v) => v.color(),
@@ -219,44 +143,27 @@ impl NamePaint {
     }
 }
 
-/// The nameplate render caches: one unlit depth-tested material per palette color (built once the
-/// atlas exists), one mesh per distinct line stack (every "Young Wolf" shares one mesh), and the
-/// live per-unit plate entities.
-///
-/// **The meshes are glyph-cell UVs on the GPU, and they die with the cell layout they were built
-/// from** ([`baked_from`]). This is the one place in the codebase that persists glyph UVs across
-/// frames ([`build_name_mesh`] bakes them into `ATTRIBUTE_UV_0`), which makes it the one place that
-/// has to watch [`UiFontAtlas::generation`].
-///
-/// The **materials** used to be on that list and no longer are: they bind the glyph sheet by
-/// handle, and since decision 1342 that texture is written in place and its handle never changes.
-/// It was the old size ladder's re-bake — a whole new image asset per window resize — that made a
-/// bound handle go stale, and drawing new-bake UVs through the old-bake texture is what turned unit
-/// names into fragments of other letters (B272, decision 1339). There is no successor texture now,
-/// so there is nothing for a material to go stale against; only the UVs can move, and only when the
-/// sheet fills and resets.
+/// Materials per colour, meshes per line stack and the live plate per unit. The meshes bake glyph
+/// UVs, so they die when the glyph sheet resets; the sheet's texture handle never changes.
 #[derive(Resource, Default)]
 pub(crate) struct Nameplates {
     materials: HashMap<NamePaint, Handle<StandardMaterial>>,
     meshes: HashMap<Vec<String>, Handle<Mesh>>,
     /// unit → (plate entity, the (lines, color) it was built with).
     live: bevy::ecs::entity::EntityHashMap<(Entity, Vec<String>, NamePaint)>,
-    /// The `UiFontAtlas::generation` the meshes' UVs were built from — `None` before the first
-    /// build. [`drop_stale_glyph_caches`] empties them when it moves.
+    /// The atlas generation the meshes' UVs were built from; `None` before the first build.
     baked_from: Option<u64>,
 }
 
 impl Nameplates {
-    /// Whether `unit` currently shows an overhead name — benilla's equivalent of the client's
-    /// per-unit name object (`unit+0xc7c`) being live. The questgiver marker keys its raised
-    /// (anim 190) bob off this (`0x6076c0` checks `0x6c7950`).
+    /// Whether `unit` shows an overhead name (the reference's `unit+0xc7c` name object is live);
+    /// the questgiver marker's raised (anim 190) bob keys on it (`0x6076c0` checks `0x6c7950`).
     pub(crate) fn shows(&self, unit: Entity) -> bool {
         self.live.contains_key(&unit)
     }
 
-    /// The line count of `unit`'s live overhead name (`None` = no name this frame) — the raid
-    /// marker's seat law reads it (`0x6c70d8`: the marker sits one pitch above the block when the
-    /// name shows, at the bare anchor otherwise).
+    /// The line count of `unit`'s live name, for the raid marker's seat (`0x6c70d8`: one pitch
+    /// above the block, or at the bare anchor when no name shows).
     pub(crate) fn line_count(&self, unit: Entity) -> Option<usize> {
         self.live.get(&unit).map(|(_, lines, _)| lines.len())
     }
@@ -266,39 +173,23 @@ impl Nameplates {
 #[derive(Component)]
 struct NamePlate;
 
-/// Mounted name-rock damping — a **named modernization** (director taste, ref-A/B'd: the
-/// reference name rides the gallop too, so the raw per-frame seat is the faithful behavior;
-/// ours read "a bit more intense", so the mounted plate shows only this fraction of the seat's
-/// oscillation about its slow-tracked mean). `1.0` = the raw faithful seat. On-foot plates are
-/// untouched.
+/// Deviation: a mounted plate keeps only this fraction of its seat's oscillation about a slow
+/// mean, because the raw seat, which the reference also rides, read more intense than the
+/// reference side by side. `1.0` is the raw seat; on-foot plates are untouched.
 const ROCK_KEEP: f32 = 0.7;
-/// The mean tracker's exponential rate (1/s) — slow against the ~1 Hz gallop (the oscillation
-/// stays in the damped residual, not the mean), fast enough to follow a stance drift.
+/// The mean tracker's rate (1/s): slow against the ~1 Hz gallop, fast enough to follow a stance.
 const ROCK_MEAN_RATE: f32 = 1.5;
-/// A residual this large (yd) is a stance change (mount swap, teleport), not gait — snap the
-/// mean to it instead of easing through seconds of misplaced name.
+/// A residual this large (yd) is a stance change (mount swap, teleport): snap the mean to it.
 const ROCK_SNAP: f32 = 1.0;
 
-/// The source size (logical px) the name glyphs are rasterized at for the mesh bake. Only the cell
-/// UVs and the *relative* geometry survive the normalization to pitch units, so this is purely a
-/// resolution dial: the world transform scales the block to its real size, and a bigger source
-/// means crisper letters when a name is close.
-///
-/// The real client's unit-name font is pinned at a 32-px raster and magnifies the cells for every
-/// plate (`UNIT_NAME_FONT` at `0x6c749b`, size `0.99f` with string flag `0x80`, so its
-/// world text was always a stretched bitmap). Rendering the source larger is the same recorded
-/// crispness divergence world text already takes at the [`crate::ui_text::FONTSTRING_EM_CAP`].
+/// The raster size (logical px) of the mesh bake, which only sets crispness. Deviation: larger
+/// than the reference's 32 px `UNIT_NAME_FONT` raster, which it magnifies (`0x6c749b`), because a
+/// larger source is crisper up close.
 const BAKE_PX: f32 = 36.0;
 
-/// Build one name-block mesh in **name-local pitch units**: x centered on 0 (exact centering for
-/// any name length — by construction), y up, one line = 1.0 of pitch, line 0 (the name) on TOP,
-/// each line's **BASELINE at local y = lineCount − i** — so a transform at the anchor with
-/// scale = the world `scale` puts the top baseline exactly at the byte law's
-/// `anchor + lineCount × scale` and the block hangs below it (the world-mode seat; the old
-/// bottom-at-anchor bake sat everything one line too low). Glyphs come from the real layout at
-/// [`BAKE_PX`], normalized by the pitch (= the font size, the verified 1:1); the baseline sits
-/// [`UiFontAtlas::ascent_ratio`] into the layout's cell, the same `[0x17c]` load_param seat the
-/// 2-D path uses.
+/// Build one name-block mesh in pitch units: x centered, y up, line `i`'s baseline at
+/// `lineCount - i`, one pitch being the font size. The baseline sits `TextEngine::ascent_ratio`
+/// into the layout cell (the `[0x17c]` load param), as in the 2-D path.
 fn build_name_mesh(atlas: &mut UiFontAtlas, lines: &[String]) -> Mesh {
     use bevy::asset::RenderAssetUsages;
     use bevy::mesh::{Indices, PrimitiveTopology};
@@ -308,15 +199,10 @@ fn build_name_mesh(atlas: &mut UiFontAtlas, lines: &[String]) -> Mesh {
     let mut normals: Vec<[f32; 3]> = Vec::new();
     let mut indices: Vec<u32> = Vec::new();
     let n = lines.len() as f32;
-    // Where the baseline sits inside the layout's one-pitch cell (the same `round(size ·
-    // asc/(asc+|desc|))` load_param the 2-D path seats with) — needed to hang each line FROM its
-    // baseline. Invariant to the ratio's value: `line_top` shifts with it but the baseline stays
-    // pinned to the byte grid, so this only has to AGREE with `layout_text_quads`, not be exact.
+    // The baseline's place in the one-pitch cell, `round(size * asc/(asc+|desc|))`; it only has to
+    // agree with `layout_text_quads`, since the baseline stays on the grid either way.
     let mut e = atlas.lock();
-    // The size the glyphs are ACTUALLY laid out at: [`BAKE_PX`] rounded to whole device pixels and
-    // back ([`TextEngine::ppem`]). Normalizing by the requested 36 instead would be off by up to
-    // half a device pixel per unit of pitch on a fractional-DPI display — small, but it is exactly
-    // the kind of "close enough" that the size ladder was made of.
+    // The size the glyphs are laid out at: `BAKE_PX` rounded to whole device pixels and back.
     let src = e.drawn_size(BAKE_PX);
     let baseline_frac =
         ((f64::from(src) * f64::from(e.ascent_ratio(None)) + 0.5).floor() / f64::from(src)) as f32;
@@ -337,9 +223,7 @@ fn build_name_mesh(atlas: &mut UiFontAtlas, lines: &[String]) -> Mesh {
                 outline: Outline::None,
                 alpha_gradient: None,
             },
-            // A world billboard: the glyphs are re-seated by ink into name-local pitch units two
-            // statements below, so the UI grid never had anything to say here (the degenerate
-            // rect above already skipped it — this only says so out loud).
+            // A world billboard: the glyphs are re-seated in pitch units below, off the UI grid.
             TextSeat::Exact,
         );
         // Recenter the ink box on x = 0, then normalize px → pitch units, flipping y-down px into
@@ -348,9 +232,8 @@ fn build_name_mesh(atlas: &mut UiFontAtlas, lines: &[String]) -> Mesh {
             continue;
         };
         let cx = (bounds.min.x + bounds.max.x) * 0.5;
-        // The seat: line `i`'s BASELINE must land at local y = n − i (the byte grid). The layout
-        // (degenerate point rect → top placement at px y = 0) puts the baseline `baseline_frac`
-        // of a cell below the cell top, so the cell top maps to n − i + baseline_frac.
+        // Line `i`'s baseline lands at local y = n - i; the layout puts it `baseline_frac` of a
+        // cell below the cell top, so the cell top maps to n - i + baseline_frac.
         let line_top = n - i as f32 + baseline_frac;
         for q in &glyphs {
             let x0 = (q.rect.min.x - cx) / src;
@@ -377,11 +260,8 @@ fn build_name_mesh(atlas: &mut UiFontAtlas, lines: &[String]) -> Mesh {
     mesh
 }
 
-/// Drive the plates: gate → resolve lines + color → (re)build the plate entity on change. Runs in
-/// Update after the camera controller ([`WorldStage::Input`]); all entity/mesh churn stays in
-/// Update (the schedule the mesh pipelines support). The per-frame *placement* is
-/// [`place_nameplates`] (PostUpdate, off this frame's propagated pose) — a fresh plate spawned
-/// here gets its first seat there, same frame (Update commands flush before PostUpdate).
+/// Drive the plates: gate, resolve lines and colour, and rebuild the plate on change, in Update
+/// where mesh churn is supported.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 pub(crate) fn drive_nameplates(
     mut commands: Commands,
@@ -392,29 +272,26 @@ pub(crate) fn drive_nameplates(
         &Transform,
         Option<&ObjectStore>,
         Has<SelfPlayer>,
-        // Whether the body is drawn at all — the ShouldShowName gate's unwritten first term
-        // (decision 1277). A body the exterior-scene election sent to pass 2 never enters the
-        // reference's scene, so there is nothing over which to float a name.
+        // Whether the body is drawn: a unit outside the scene has nothing to float a name over.
         Option<&InheritedVisibility>,
     )>,
     self_store: Query<&ObjectStore, With<SelfPlayer>>,
-    // The optimistic AFK mirror (`[0xb6e5cc]`) — the own-player `<AFK>` override, 2088.
+    // The optimistic AFK mirror (`[0xb6e5cc]`), the own player's `<AFK>` override.
     mirror: Res<crate::ui_chat::AfkMirror>,
-    // The show-gate inputs (one tuple param — Bevy's 16-param ceiling).
+    // The show-gate inputs, one tuple param for Bevy's 16-param ceiling.
     gates: (
         Res<Selection>,
         Res<CombatFlash>,
         Option<Res<crate::player::CameraControl>>,
         Res<crate::vplates::VPlates>,
         Res<crate::chat_bubble::BubblesActive>,
-        // The selector's party roster (`0xbc6f48`) — the `¬X∧¬Y` leg's pale variants.
+        // The selector's party roster (`0xbc6f48`), for the pale party variants.
         Res<crate::ui_party::GroupState>,
-        // The UnitName* cvar mask (0992) — the kind gates below read it.
+        // The UnitName* CVar mask.
         Res<NameConfig>,
     ),
     names: Res<NameCache>,
-    // The guild-identity cache (1257) — the a5 line's text, and the lazy `CMSG_GUILD_QUERY` a
-    // miss sends. `ResMut` because the read IS the ask ([`crate::ui_guild::unit_guild_name`]).
+    // The guild cache, the a5 line's text; `ResMut` because a miss sends `CMSG_GUILD_QUERY`.
     mut guilds: ResMut<crate::ui_guild::GuildState>,
     net_commands: Res<NetCommands>,
     factions: Option<Res<Factions>>,
@@ -424,7 +301,7 @@ pub(crate) fn drive_nameplates(
     mut plates: ResMut<Nameplates>,
     mut meshes: ResMut<Assets<Mesh>>,
     mut materials: ResMut<Assets<StandardMaterial>>,
-    // The overhead-anchor inputs ([`overhead_anchor`]) — the spawn-frame seat only.
+    // The `overhead_anchor` inputs, for the spawn-frame seat only.
     anchor_q: (
         Query<&BoneAttach>,
         Query<&benilla_world::rig_anim::RigPose>,
@@ -437,7 +314,7 @@ pub(crate) fn drive_nameplates(
     let (Ok(cam_tf), Some(atlas)) = (camera.single(), atlas.as_mut()) else {
         return;
     };
-    // A glyph-sheet reset moves every cached UV (see [`Nameplates`]).
+    // A glyph-sheet reset moves every cached UV.
     drop_stale_glyph_caches(&mut plates, atlas.generation, &mut commands);
     // The palette materials, once (they need the atlas image).
     if plates.materials.is_empty() {
@@ -453,29 +330,18 @@ pub(crate) fn drive_nameplates(
                     base_color: kind.color(),
                     base_color_texture: Some(image.clone()),
                     unlit: true,
-                    // Depth-TESTED (the verified world-pass state — walls occlude); Blend skips
-                    // the depth WRITE (the named divergence: name-vs-name resolves by sorting).
+                    // Depth-tested; Blend skips the depth write (the module doc's deviation).
                     alpha_mode: AlphaMode::Blend,
                     cull_mode: None,
-                    // Sort names AFTER every ordinary transparent (Bevy's Transparent3d key is
-                    // `view-z of the mesh center + depth_bias`, sorted ASCENDING = far first, so
-                    // a POSITIVE bias draws last = on top — the sign law is in `sky_order`).
-                    // Without it a WATER chunk whose center sat nearer the camera than the plate
-                    // sorted in front and tinted the name — the "name looks underwater from some
-                    // angles" artifact (director-reported, 2026-07-18; decision 0519). With the
-                    // sign inverted, as 0519 shipped it, deep water (alpha 1.0) erased the
-                    // glyphs outright — the canal report of 2026-07-25 (decision 0639). The ref
-                    // draws its world text late in the frame, after the liquid — this reproduces
-                    // that order; walls still occlude via the depth test, and plate-vs-plate
-                    // ordering is unchanged (uniform bias).
+                    // Sorted after every ordinary transparent (sign law in `sky_order`), as the
+                    // reference draws world text after the liquid; water cannot cover a name.
                     depth_bias: benilla_world::sky_order::Rung::NAMEPLATE,
                     ..default()
                 }),
             );
         }
     }
-    // The flash material rides this frame's wave sample — mutated only while a flash is live, so
-    // the asset isn't dirtied (re-uploaded) every idle frame.
+    // Written only while a flash is live, so an idle frame does not re-upload the material.
     if flash.unit.is_some() {
         if let Some(mat) = plates
             .materials
@@ -489,47 +355,24 @@ pub(crate) fn drive_nameplates(
     let facing = cam_tf.rotation;
     let mut seen = bevy::ecs::entity::EntityHashSet::default();
     for (entity, net, guid, tf, store, is_self, drawn) in &units {
-        // **A name needs a body to float over.** The director, inside Caverns of Time: the Tanaris
-        // mobs 222 yd overhead had correctly stopped drawing, and their names went on hanging in
-        // the rock — this lane walks every net entity with a `Guid` and never asked whether the
-        // unit was in the scene. Ahead of the whole ShouldShowName ladder below, because it is not
-        // one of that gate's terms: it is the precondition for asking at all.
+        // A name needs a drawn body; this precedes the ShouldShowName ladder.
         if !drawn.is_none_or(|v| v.get()) {
             continue;
         }
-        // **There is NO distance cull here, and adding one is the mistake to not make twice.**
-        // The overhead NAME (`CGUnit+0xc7c`, a `PLAYERNAMEDESC`) and the V-key nameplate FRAME
-        // (`CGUnit+0xe60`) are two systems on the same unit, and only the FRAME carries the
-        // 20-yard cap (`0x60f600` vs `[0xc4d988] = 400`) that `vplates.rs` implements. This
-        // lane's own update/cull/build (`0x6c6d40`/`0x6c6e00`/`0x6c6e90`) holds **zero** distance
-        // compares — every early-out is identity/state-based, and the one FP compare is the
-        // height law above, not a depth term.
-        // A far name just gets small: it is a world billboard, apparent size ∝
-        // scale/depth. The effective range is the server's interest management — no CGUnit, no
-        // desc. 1490 item 7 read the frame's law onto this lane and capped it at 20 yd; the
-        // director's Elwynn shot (named wolves up the hill) is the reference's own behaviour, and
-        // it outranked the mis-scoped citation. Superseded by 1492.
-        // The ShouldShowName gate, in the client's own order (own-unit answers its cvar BEFORE
-        // the rescue; everyone else: the current-TARGET bypass — `[0xb4e2d8]` is the selection,
-        // not the mouseover — then the kind cvar). A unit carrying a V-key nameplate never also
-        // draws its floating name (the plate/name mutual exclusion, `0x6070a0`), and neither does
-        // one carrying a live chat bubble (`+0xe64` — the same gate's other handle read).
-        // A DEAD creature's name shows ONLY through the target rescue — director-verified on the
-        // reference (a corpse field isn't a name field; targeting the corpse still names it);
-        // the exact ShouldShowName leg is unconfirmed in the binary — flagged interim.
+        // No distance cull: the name's update, cull and build (`0x6c6d40`, `0x6c6e00`,
+        // `0x6c6e90`) compare none; the 20-yard cap (`0x60f600`) is the V-key frame's.
+        // ShouldShowName's order: own unit by its CVar, the target (`[0xb4e2d8]`), the kind CVar.
+        // A V-key plate or chat bubble (`+0xe64`) suppresses the name (`0x6070a0`). A dead
+        // creature shows only as the target, as in the reference; that gate leg is untraced.
         let show = if vplates.0.contains(&entity) || bubbles.0.contains(&entity) {
             false
         } else if store.is_some_and(|s| s.0.unit_is_ghost_visual()) {
-            // The bytes_1 ghost vis-flag's ONE render effect: overhead-name/plate suppression —
-            // the create-gate `0x607101` and the per-tick gate `0x60f62e` both test `byte3 & 3`
-            // (ghost|creep; the creep leg is the stealth arc's). A released ghost carries no
-            // floating name, target rescue included.
+            // The ghost vis-flag suppresses the name, target rescue included: `0x607101` and
+            // `0x60f62e` both test `bytes_1` byte 3 `& 3`.
             false
         } else if is_self {
-            // The own-unit cvar leg, before the rescue (faithful order: self-targeting still
-            // obeys it) — plus the fade gate: a fully-faded first-person avatar carries no name
-            // (our reading of `ShouldShowName`'s INFERRED `vtable+0x58` can-show leg; a name
-            // floating over an invisible body is the alternative).
+            // The own CVar, before the rescue; no name over a fully faded first-person avatar
+            // (our reading of `ShouldShowName`'s untraced `vtable+0x58` leg).
             name_cfg.own
                 && rig
                     .as_deref()
@@ -549,52 +392,38 @@ pub(crate) fn drive_nameplates(
         if !show {
             continue;
         }
-        // Ask-once resolve, then re-read by reference (`peek`, resolve's read-only twin): holding
-        // resolve's `&mut`-tied return across the subname read below is a borrow conflict, and the
-        // `str::to_owned` that used to break it was a per-unit-per-frame allocation made just to
-        // compare against the cache (the steady arm below no longer builds anything).
+        // Re-read by `peek`: resolve's `&mut`-tied return cannot outlive the subname read.
         if names.resolve_unit(guid.0, store, &net_commands).is_none() {
             continue;
         }
         let Some(name) = names.peek_unit(guid.0, store) else {
             continue;
         };
-        // The player flag decorations (a1–a3): glued straight onto the name line, no space.
+        // The player flag prefixes (a1-a3), glued onto the name with no space.
         let flags = if net.kind == EntityKind::Player {
             store.map_or(0, |s| s.0.player_flags())
         } else {
             0
         };
-        // **The own-player AFK override** (2088). The AFK slot `0x5ec9e0` — and only that slot
-        // — carries a pre-gate: if the subject's GUID is the active player's AND the optimistic
-        // mirror `[0xb6e5cc]` is non-zero, the `<AFK>` tag emits **regardless of the flag bit**
-        // (`0x5ec9fd`/`0x5eca04 jne 0x5eca12`, jumping past the `0x5eca0c test byte [ecx+8],0x2`).
-        // That is what puts `<AFK>` over your own head the instant you type `/afk`, a round trip
-        // before the descriptor confirms it. DND and GM have no such path — pure bit tests.
-        //
-        // Folded into `flags` rather than passed alongside, so `lines_current`'s in-place compare
-        // and `flag_prefix`'s build cannot disagree about it: the differential test that pins
-        // those two to each other keeps holding for free.
+        // The AFK slot `0x5ec9e0` alone emits `<AFK>` for the active player while the mirror
+        // `[0xb6e5cc]` is set, whatever the bit (`0x5ec9fd`). Folded into `flags` so
+        // `lines_current` and `flag_prefix` agree.
         let flags = if is_self && mirror.is_afk() {
             flags | 0x2
         } else {
             flags
         };
-        // The one `"\n<%s>"` slot: a6 (the creature subtitle) on the NPC branch, a5 (the guild)
-        // on the player branch — never both, and never in the other's branch (the module doc's
-        // branch exclusivity). a5 is the only one of the two that a CVar
-        // gates: mask bit `0x10` at `0x609085`.
+        // The one `"\n<%s>"` slot: a6 subtitle for an NPC, a5 guild for a player (CVar-gated).
         let bracketed = match net.kind {
             EntityKind::Unit => benilla_protocol::guid::entry(guid.0)
                 .and_then(|e| names.creature_subname(e))
-                // vmangos ships "" (present-but-empty) for most templates — an empty wire
-                // subname is NO subname, never an empty `<>` line.
+                // vmangos sends "" for most templates: an empty subname is no line.
                 .filter(|s| !s.trim().is_empty()),
             EntityKind::Player if name_cfg.player_guild => store
                 .and_then(|s| crate::ui_guild::unit_guild_name(&s.0, &mut guilds, &net_commands)),
             _ => None,
         };
-        // The color: the ring's byte-verified rank + the shared palette selector.
+        // The colour: the ring's reaction rank and the shared selector.
         let rank = ring_reaction(
             factions.as_deref(),
             &reputations,
@@ -602,13 +431,10 @@ pub(crate) fn drive_nameplates(
             self_store.single().ok(),
         );
         let is_dead = store.is_some_and(|s| s.0.unit_is_dead());
-        // The player path's `¬X∧¬Y` split inputs, exactly as the ring reads them: the unit's own
-        // PvP flag (`UNIT_FIELD_FLAGS` 0x1000) and roster membership by guid — here keyed on THIS
-        // unit's guid, where the ring (which only ever draws the selection) uses the selected one.
+        // The ring's player inputs, for this unit: PvP flag (`UNIT_FIELD_FLAGS` 0x1000) and party.
         let pvp = store.is_some_and(|s| s.0.unit_flags() & 0x1000 != 0);
         let in_party = group.members.iter().any(|m| m.guid == guid.0);
-        // The selector's first-priority branch (shared with the ring): the combat flash
-        // overrides the whole palette while we melee this unit.
+        // The selector's first-priority branch: the combat flash while we melee this unit.
         let color = if flash.unit == Some(entity) {
             NamePaint::Flash
         } else {
@@ -623,9 +449,7 @@ pub(crate) fn drive_nameplates(
 
         seen.insert(entity);
         match plates.live.get(&entity) {
-            // The steady frame — very nearly all of them — compares the cached stack in place
-            // ([`lines_current`]): the line stack used to be BUILT here (three allocations per
-            // shown unit per frame) only to equality-compare against the cache and be dropped.
+            // The steady frame compares the cached stack in place, allocating nothing.
             Some((_, l, c)) if *c == color && lines_current(l, flags, name, bracketed) => {}
             stale => {
                 if let Some((old, _, _)) = stale {
@@ -634,8 +458,7 @@ pub(crate) fn drive_nameplates(
                         e.despawn();
                     }
                 }
-                // Building the stack allocates, and only this arm does it. [`lines_current`]'s
-                // differential test pins the compare above to exactly this shape.
+                // Keep in sync with `lines_current`; its differential test pins this shape.
                 let prefix = flag_prefix(flags);
                 let mut lines = vec![if prefix.is_empty() {
                     name.to_owned()
@@ -652,10 +475,8 @@ pub(crate) fn drive_nameplates(
                     .or_insert_with(|| meshes.add(build_name_mesh(atlas, &lines)))
                     .clone();
                 let material = plates.materials[&color].clone();
-                // The spawn-frame seat only — [`place_nameplates`] re-seats every plate each
-                // frame from the propagated (same-frame) pose. Kept (not `Transform::default()`):
-                // the PostUpdate placement can miss a plate whose unit despawned later this same
-                // Update, and a plate must never render a frame at the origin.
+                // The spawn-frame seat: placement can miss a plate whose unit despawns later
+                // this Update, and a plate must never render at the origin.
                 let anchor = overhead_anchor(
                     entity,
                     tf,
@@ -691,12 +512,8 @@ pub(crate) fn drive_nameplates(
     });
 }
 
-/// Seat every live plate from THIS frame's propagated pose: anchor off the posed joints (fresh
-/// after `TransformSystems::Propagate`), camera-facing rotation, height scale — written to both
-/// `Transform` and `GlobalTransform` (plates are root entities, so the direct global write is
-/// exact; propagation already ran this frame). Running in Update read last-frame joint globals,
-/// so a moving player's name trailed a frame behind and snapped forward on stop — the director's
-/// "lags behind and snaps back". Ordered before `CheckVisibility` so culling sees the fresh seat.
+/// Seat every live plate from this frame's propagated pose, so a moving name does not trail;
+/// plates are roots, so writing `GlobalTransform` directly is exact.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 fn place_nameplates(
     plates: Res<Nameplates>,
@@ -715,7 +532,7 @@ fn place_nameplates(
         Res<Time>,
         Query<(), With<crate::net::SelfPlayer>>,
     ),
-    // unit → the slow mean of (anchor − root) while mounted — the rock-damping state.
+    // unit → the slow mean of (anchor - root) while mounted, the rock-damping state.
     mut rock: Local<bevy::ecs::entity::EntityHashMap<Vec3>>,
 ) {
     let Ok(cam_tf) = camera.single() else {
@@ -726,7 +543,7 @@ fn place_nameplates(
     for (&unit, (plate, ..)) in plates.live.iter() {
         let (Ok(tf), Ok((mut ptf, mut pglobal))) = (units.get(unit), plate_tfs.get_mut(*plate))
         else {
-            continue; // spawned this frame and not yet flushed, or unit despawning — next frame
+            continue; // spawned this frame and not yet flushed, or the unit is despawning
         };
         let raw = overhead_anchor(
             unit,
@@ -737,9 +554,7 @@ fn place_nameplates(
             &anchor_q.3,
             &anchor_q.4,
         );
-        // The mounted rock damp: seat the plate at mean + ROCK_KEEP·residual instead of the raw
-        // gallop-riding anchor. Everything is in root-relative offsets, so the damped plate still
-        // tracks a 7 yd/s run with zero world-space lag (the on-foot trailing lesson).
+        // Mounted: mean + ROCK_KEEP * residual, root-relative so the plate never lags.
         let anchor = if anchor_q.4.contains(unit) {
             let off = raw - tf.translation;
             let mean = rock.entry(unit).or_insert(off);
@@ -753,9 +568,7 @@ fn place_nameplates(
             raw
         };
         if trace.0 .0 && trace.2.contains(unit) {
-            // The numeric feed for an anchor smoothness question (`NAME_TRACE`): the same-frame
-            // root, the SEATED (post-damp) anchor, and the camera — per frame, machine-greppable;
-            // `raw` is the undamped joint read for depth.
+            // Root, seated (damped) anchor and camera per frame; `raw` is the undamped joint read.
             let (r, a, c) = (tf.translation, anchor, cam_tf.translation);
             info!(
                 "NAME_TRACE t={:.4} root=({:.4},{:.4},{:.4}) anchor=({:.4},{:.4},{:.4}) cam=({:.3},{:.3},{:.3}) raw=({:.4},{:.4},{:.4})",
@@ -768,11 +581,7 @@ fn place_nameplates(
             rotation: facing,
             scale: Vec3::splat(scale),
         };
-        // The no-op write gate (decision 1362 — the camera's pattern, at the plate): a parked
-        // unit's seat is bit-stable, but writing it anyway marked every plate's transform changed
-        // every frame. Bit equality, not an epsilon: a real sub-epsilon drift must still land.
-        // The global rides the same branch — a root entity's global IS its transform, so the two
-        // are stale together. The mounted rock-damp seat never settles; the gate just misses there.
+        // Write only on a bit-level change, so a parked plate is not marked changed every frame.
         {
             let t = ptf.bypass_change_detection();
             if *t != place {
@@ -786,18 +595,15 @@ fn place_nameplates(
     rock.retain(|e, _| anchor_q.4.contains(*e));
 }
 
-/// Registers the plate driver (Update — the entity/mesh churn stays in the schedule the mesh
-/// pipelines support) and the per-frame placer (PostUpdate, after transform propagation — the
-/// same-frame pose the render draws, before visibility culling).
+/// Registers the plate driver (Update) and the per-frame placer (PostUpdate, after propagation,
+/// before visibility culling).
 pub(crate) struct NameplatesPlugin;
 
-/// `WOW_PROBE_NAME_TRACE=1`: per-frame `NAME_TRACE` lines for the self player's plate seat —
-/// the numeric instrument for "the name moves weirdly" reports (a smoothness/lag question is
-/// measured, never eyeballed — decision 0404).
+/// `WOW_PROBE_NAME_TRACE=1`: per-frame `NAME_TRACE` lines for the self player's plate seat.
 #[derive(Resource)]
 struct NameAnchorTrace(bool);
 
-/// The overhead-name rows' change callback (decision 2303): the name trio and the guild line.
+/// The overhead-name rows' change callback: the name trio and the guild line.
 pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut names: ResMut<NameConfig>) {
     match ev.key().as_str() {
         "unitnameplayer" => names.player = ev.flag(),
@@ -816,10 +622,7 @@ impl Plugin for NameplatesPlugin {
         ))
         .init_resource::<Nameplates>()
         .init_resource::<NameConfig>()
-        // After the whole targeting chain (the gate + colour read THIS frame's selection and
-        // flash verdicts; the chain is itself after `WorldStage::Input`) and after the V-key
-        // plate + chat-bubble drives (the plate/name and bubble/name mutual exclusions read
-        // their verdicts).
+        // After targeting, V-key plates and chat bubbles: the gate reads their verdicts.
         .add_systems(
             Update,
             drive_nameplates
@@ -837,21 +640,8 @@ impl Plugin for NameplatesPlugin {
     }
 }
 
-/// Empty the UV-bearing caches when the glyph sheet resets — the staleness edge [`Nameplates`]
-/// describes.
-///
-/// A reset repacks the sheet from empty, so every UV baked into a mesh stops pointing at its own
-/// letter. Dropping the mesh map alone is not enough: the live plate entities still hold their old
-/// `Mesh3d` handles, so they are despawned too and rebuilt on this same frame's walk below (which
-/// re-enters every visible unit). That one-frame rebuild is the whole cost of a reset here.
-///
-/// The **materials survive**, because the sheet's texture handle does (decision 1342). Under the
-/// old size ladder this edge fired on every window resize and had to drop them too; now it fires
-/// only when the sheet fills, which the occupancy instrument (`WOW_GLYPH_CACHE=1`) exists to keep
-/// honest.
-///
-/// The **first** build is not an edge — `baked_from: None` seeds to the live generation with
-/// nothing to drop.
+/// Empty the UV-bearing caches when the glyph sheet resets, despawning the live plates too (they
+/// hold the old `Mesh3d`); the materials survive. The first build only seeds.
 fn drop_stale_glyph_caches(plates: &mut Nameplates, generation: u64, commands: &mut Commands) {
     if plates.baked_from == Some(generation) {
         return;
@@ -874,10 +664,7 @@ fn drop_stale_glyph_caches(plates: &mut Nameplates, generation: u64, commands: &
     plates.baked_from = Some(generation);
 }
 
-/// Drop the per-line-stack mesh dedup on a cross-map transition (`world_map::MapChange` — see its
-/// doc): it grows with every distinct name ever seen and the old map's population never comes
-/// back. The palette `materials` stay — they bind the one stable glyph sheet and outlive both this
-/// edge and [`drop_stale_glyph_caches`]'s.
+/// Drop the line-stack mesh dedup on a cross-map transition: the old map's names never return.
 fn evict_name_meshes(
     mut changes: MessageReader<benilla_world::world_map::MapChange>,
     mut plates: ResMut<Nameplates>,
@@ -893,8 +680,7 @@ fn evict_name_meshes(
 mod tests {
     use super::*;
 
-    /// The height-scale law at its pinned points: the 0.2 floor through 4 units, `>` not `>=` at
-    /// the knee, `0.075·d` beyond (the byte behavior — the jump at the knee is real).
+    /// `>` not `>=` at the knee and `0.075*d` beyond: the jump at the knee is the reference's.
     #[test]
     fn height_scale_matches_the_byte_law() {
         assert_eq!(height_scale(1.8), 0.2, "human: the floor");
@@ -904,9 +690,7 @@ mod tests {
         assert!(height_scale(4.1) > 0.2, "past the knee: the jump is real");
     }
 
-    /// The flag decorations against the slot law (`0x608f50`): bare concatenation
-    /// (no space — the `%s%s…` line-stack law), stacking in slot order AFK → DND → GM, empty for
-    /// the common unflagged case, unrelated bits (ghost 0x10, resting 0x20) ignored.
+    /// Bare concatenation in slot order AFK, DND, GM (`0x608f50`); other bits ignored.
     #[test]
     fn flag_prefix_matches_the_slot_law() {
         assert_eq!(flag_prefix(0), "");
@@ -926,17 +710,13 @@ mod tests {
         );
     }
 
-    /// The name paints itself from the ring's own selector — one law, not a copy of one (decision
-    /// 0659). The regression this locks: a **PvP-flagged** friendly player is GREEN, the same
-    /// green the ring under their feet draws. The name used to keep a private mirror of the
-    /// selector that predated the `¬X∧¬Y` legs (0453), so a flagged player wore a green ring under
-    /// a blue name — which is exactly what the director saw.
+    /// A PvP-flagged friendly player's name is the ring's green, not the soft blue.
     #[test]
     fn name_color_is_the_ring_selector_itself() {
         let paint = |rank, is_player, is_dead, pvp, in_party| {
             NamePaint::Variant(ring_variant(rank, is_player, is_dead, pvp, in_party))
         };
-        // The regression: flagged ⇒ green, unflagged ⇒ the soft blue, and the two really differ.
+        // Flagged is green, unflagged the soft blue, and the two differ.
         let flagged = paint(6, true, false, true, false);
         let unflagged = paint(6, true, false, false, false);
         assert_eq!(flagged, NamePaint::Variant(RingVariant::Friendly));
@@ -947,7 +727,6 @@ mod tests {
             Color::linear_rgb(0.0, 1.0, 0.0),
             "0xFF00FF00 — the ring's own green, byte for byte"
         );
-        // The party legs come along for free now.
         assert_eq!(
             paint(6, true, false, true, true),
             NamePaint::Variant(RingVariant::PartyPvp)
@@ -956,7 +735,6 @@ mod tests {
             paint(6, true, false, false, true),
             NamePaint::Variant(RingVariant::Party)
         );
-        // And the rest of the law still holds through the shared selector.
         assert_eq!(paint(0, false, false, false, false).color(), RED);
         assert_eq!(
             paint(6, true, true, false, false),
@@ -972,12 +750,8 @@ mod tests {
 
     const RED: Color = Color::linear_rgb(1.0, 0.0, 0.0);
 
-    /// The steady arm's in-place compare answers exactly "is the cached stack what the stale arm
-    /// would build from these inputs" — pinned differentially against that build itself (every
-    /// pair of cases, both directions), so the two shapes cannot drift apart. This is also the
-    /// keep-vs-rebuild verdict: `true` keeps the plate entity across frames, `false` rebuilds it —
-    /// e.g. a name that merely LOOKS pre-tagged (`<AFK>Bob`, unflagged) still compares equal to a
-    /// flagged `Bob`, exactly as the built strings do.
+    /// Pinned against the build over every pair of cases, both ways: an unflagged `<AFK>Bob`
+    /// equals a flagged `Bob`, as the built strings do.
     #[test]
     fn lines_current_matches_the_built_stack() {
         let build = |flags: u32, name: &str, bracketed: Option<&str>| {
@@ -994,10 +768,7 @@ mod tests {
             (0x2, "Bob", None),
             (0x2 | 0x8, "Bob", None),
             (0, "<AFK>Bob", None),
-            // The a5 slot (2149). It shares the a6 shape exactly, which is the point — the two
-            // are one `"\n<%s>"` and the unit's branch picks which fills it. The guild names
-            // below are the awkward ones: a guild the player left (`None` again), one whose own
-            // name carries the brackets, and one that collides with a subname above.
+            // The a5 guild slot: a bracketed name, and one colliding with a subname above.
             (0, "Bob", Some("Legacy")),
             (0x2, "Bob", Some("Legacy")),
             (0, "Bob", Some("<Legacy>")),
@@ -1015,9 +786,7 @@ mod tests {
         }
     }
 
-    /// The placement write gate (decision 1362's pattern at the plate): a static world's second
-    /// placement leaves the plate's `Transform`/`GlobalTransform` change ticks untouched, and a
-    /// moved unit still lands its write — bit equality, so any real movement passes.
+    /// A parked plate's second placement leaves both change ticks alone; a moved unit still writes.
     #[test]
     fn a_parked_plates_seat_takes_no_write() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1082,17 +851,7 @@ mod tests {
         plates
     }
 
-    /// **A sheet reset empties every UV-bearing cache, live plates included** (B272, decision
-    /// 1339; narrowed by 1342).
-    ///
-    /// The meshes carry glyph-cell UVs in vertex data, and a reset repacks the sheet from empty, so
-    /// every one of them stops pointing at its own letter. Dropping the map is not enough on its
-    /// own: the live plate entities still hold the old `Mesh3d`, so they must be despawned to be
-    /// rebuilt. That is the assertion a map-clear alone would pass and the screen would not.
-    ///
-    /// The materials must **survive** — they bind a texture whose handle never changes. Dropping
-    /// them was right when a re-bake published a new image every window resize; keeping them now is
-    /// the difference between rebuilding a handful of meshes and rebuilding the whole palette.
+    /// The live plates hold the old `Mesh3d`, so a reset must despawn them, not only clear the map.
     #[test]
     fn a_sheet_reset_drops_the_meshes_and_the_live_plates_but_not_the_materials() {
         let mut world = World::new();
@@ -1122,8 +881,7 @@ mod tests {
         assert_eq!(plates.baked_from, Some(8));
     }
 
-    /// The FIRST build is not an edge — there is nothing from a previous cell layout to drop, and
-    /// treating it as one would despawn the plates the same frame they were spawned.
+    /// A reset on the first build would despawn the plates the frame they spawn.
     #[test]
     fn the_first_build_seeds_without_dropping_anything() {
         let mut world = World::new();
@@ -1144,8 +902,6 @@ mod tests {
         assert_eq!(plates.baked_from, Some(0));
     }
 
-    /// The steady frame — every frame that is not a reset, which is very nearly all of them —
-    /// costs nothing and keeps everything.
     #[test]
     fn an_unmoved_generation_is_a_no_op() {
         let mut world = World::new();
diff --git a/crates/benilla-app/src/names.rs b/crates/benilla-app/src/names.rs
index 2dfc3464..04b3b7a3 100644
--- a/crates/benilla-app/src/names.rs
+++ b/crates/benilla-app/src/names.rs
@@ -1,27 +1,11 @@
-//! Unit-name resolution — the query-cache seam of decision 0068 §3.
+//! Unit-name resolution. Descriptors carry no names: a player's answers `CMSG_NAME_QUERY` (by
+//! guid), a creature's `CMSG_CREATURE_QUERY` (by template entry), a pet's or charm's
+//! `CMSG_PET_NAME_QUERY` (by pet number), and which one applies is read off the descriptor as the
+//! reference's `GetUnitName` (`0x609210`) reads it. Each key is asked once while in flight, and a
+//! negative answer is cached so a bad id never loops.
 //!
-//! The 1.12 wire carries **no names in descriptors**: a player's name answers `CMSG_NAME_QUERY`
-//! (keyed by guid), a creature's answers `CMSG_CREATURE_QUERY` (keyed by the template *entry*,
-//! shared by every spawn of that template), a pet's or charm's answers `CMSG_PET_NAME_QUERY`
-//! (keyed by its pet number). Which of the three names a streamed unit is read off its
-//! **descriptor**, as the reference's `GetUnitName` (`0x609210`) reads it — see [`NameKey`]. This
-//! module owns the cache and the **ask-once** discipline: a consumer calls
-//! [`NameCache::resolve_unit`] (or [`NameCache::resolve`] with only a guid), which returns the name
-//! when known and otherwise issues the query (deduped while in flight) and reports "not yet". The net bridge ([`crate::net`]) fills the cache from the
-//! decoded `PlayerName`/`CreatureName` events and clears the in-flight sets on disconnect (a query
-//! dropped by a dead writer must be re-askable after reconnect).
-//!
-//! A *negative* answer (the server doesn't know the guid/entry) is cached too — resolving to
-//! "unknown, and asking again won't help" — so a bad id can never turn into a query loop.
-//!
-//! **Two of the three live for one world session; one persists.** Creature templates are keyed by
-//! a template entry that means the same thing forever, and the reference writes them to
-//! `creaturecache.wdb` — so ours persist too (decision 1689, corrected scope). Player names and
-//! pet names are keyed by a guid and a pet number, which name *one character* and *one spawn*, and
-//! the reference neither writes them to disk nor carries them across a world entry — it clears
-//! both stores at world-session start ([`NameCache::clear_world_session`]). Persisting them was
-//! benilla's own addition, and it is what answered a wiped server's brand-new character with a
-//! deleted one's name (report B386, decision 2223).
+//! Creature templates persist, as the reference's `creaturecache.wdb` does; player and pet names
+//! are never written to disk and are cleared at world-session start, as the reference does.
 
 use std::collections::HashMap;
 
@@ -32,14 +16,9 @@ use benilla_protocol::guid;
 use crate::net::{ClientCommand, NetCommands, ObjectStore};
 use crate::query_cache::QueryCache;
 
-/// The creature template's **`type_flags`** word, bit by bit — the dword the server ships in
-/// `SMSG_CREATURE_QUERY_RESPONSE` and the reference caches at `[CGUnit+0xb30] + 0x14` (its async
-/// creature-query record, **not** a DBC row and **not** `CreatureType.dbc`).
-///
-/// Named because the bits are one-apart neighbours with wholly unrelated meanings, and reading a
-/// literal `& 0x10` at a call site is how the wound gate below spent months testing the faction
-/// tooltip's bit instead of its own (decision 2068). The reference gives each bit its own getter,
-/// which is the shape mirrored here — every consumer names the bit it wants:
+/// The creature template's `type_flags` dword from `SMSG_CREATURE_QUERY_RESPONSE`, cached by the
+/// reference at `[CGUnit+0xb30] + 0x14`. Adjacent bits mean unrelated things, and the reference
+/// gives each its own getter, so every consumer names the bit it reads:
 ///
 /// | bit | reference getter | meaning |
 /// |---|---|---|
@@ -52,119 +31,64 @@ use crate::query_cache::QueryCache;
 /// | `0x40` | `0x60d840` | SPELL_ATTACKABLE / no harmful vertex colouring |
 /// | `0x80` | `0x613230` = `CanInteractWhileDead` | INTERACT_WHILE_DEAD |
 ///
-/// (bit numbering per the readers above; the names corroborated by vmangos
-/// `CreatureDefines.h:146-152`.)
+/// The names of `0x1`-`0x40` follow vmangos `CreatureDefines.h:146-152`.
 pub(crate) mod type_flags {
-    /// `0x8` — **DO_NOT_PLAY_WOUND_ANIM**: this creature has nothing to flinch with. The
-    /// reference refuses the victim wound-flinch overlay outright for it (`0x60ea9f` inside the
-    /// flinch `0x60ea70`), whatever the trigger — a skeleton, a ghost, an elemental takes hits
-    /// without recoiling. It gates **only** the animation: the blood spurt is unaffected
-    /// (the reference has no blood-, creature-type- or display-record-keyed mechanism that
-    /// suppresses it — a skeleton bleeds), and so is the floating combat text. Decision 2068.
+    /// `0x8`: the reference skips the victim wound flinch for it (`0x60ea9f` in `0x60ea70`); the
+    /// blood spurt and the floating combat text still play.
     pub(crate) const DO_NOT_PLAY_WOUND_ANIM: u32 = 0x8;
 
-    /// `0x10` — **NO_FACTION_TOOLTIP**: the unit tooltip drops its faction-name line
-    /// (the reference's `0x612610`, which returns the bit inverted).
+    /// `0x10`: the unit tooltip drops its faction line (`0x612610`, which returns it inverted).
     pub(crate) const NO_FACTION_TOOLTIP: u32 = 0x10;
 
-    /// `0x20` — **MORE_AUDIBLE**: the pass-2 election re-links an off-screen creature for
-    /// tick-only so its combat stays audible (`0x607da0`'s `0x623b70` arm, decision 1482).
+    /// `0x20`: the pass-2 election keeps an off-screen creature ticking so its combat stays
+    /// audible (`0x607da0`'s `0x623b70` arm).
     pub(crate) const MORE_AUDIBLE: u32 = 0x20;
 }
 
-/// The name cache: players by guid, creatures by template entry, plus the in-flight ask-once sets.
-/// Filled by the net bridge; read (and query-triggered) through [`Self::resolve`].
+/// The name cache: players by guid, creatures by template entry, pets by pet number.
 #[derive(Resource, Default)]
 pub(crate) struct NameCache {
-    /// Player names by guid. `Some(None)`-shaped answers are stored as `None`: the server was asked
-    /// and didn't know (an empty wire name) — cached so we never re-ask a dead guid.
+    /// A `None` answer is an empty wire name: the server does not know the guid.
     players: QueryCache<u64, String>,
-    /// `(race, class, gender)` from the same `SMSG_NAME_QUERY_RESPONSE` that carried the name — the
-    /// wire has always sent these three and we used to drop them. Two consumers now: the
-    /// `$`-macro expander's non-player-subject path: the reference resolves a macro subject from
-    /// the object manager first and falls back to **this** cache record when the unit isn't
-    /// streamed (`0x506f70`), so without them `$R`/`$C`/`$G` against an
-    /// off-screen player would silently read race 0.
-    ///
-    /// **An entry here is present only when the server answered for it.** A name learned any other
-    /// way (our own, seeded from the login) has no entry, and that absence is the live shape
-    /// decision 1549 rests on — not a gap to fill with a zero triple.
+    /// `(race, class, gender)` from `SMSG_NAME_QUERY_RESPONSE`, the `$`-macro expander's fallback
+    /// for an unstreamed subject (`0x506f70`). Present only when the server answered: a name
+    /// learned otherwise (our own, seeded at login) has no entry, never a zero triple.
     player_traits: HashMap<u64, (u8, u8, u8)>,
-    /// Creature template records by entry; the outer `None` = the server flagged the entry
-    /// unknown. The subname is the overhead/tooltip title line ("Stable Master", …); the type is
-    /// the `CreatureType.dbc` id the TAB-target critter filter reads; rank/civilian feed the
-    /// unit tooltip's level-line word + CIVILIAN line (decision 0276).
+    /// A `None` answer is an entry the server flagged unknown.
     creatures: QueryCache<u32, CreatureRecord>,
-    /// Pet names by **pet number** — the third naming path (see [`Self::resolve`]'s pet branch).
-    /// No negative entry exists: the server answers for a live pet or says nothing at all, so an
-    /// unanswered ask stays unanswered, exactly as it does for the real client.
+    /// No negative entry: the server answers for a live pet or says nothing.
     pets: QueryCache<u32, String>,
-    /// Bumped by every **landed** answer (and the pet-rename eviction) — never by an ask. The
-    /// gated feeds' watch counter (decision 1439): a feed that resolved a miss re-runs when the
-    /// answer lands, and only then. Born because `is_changed` could not say this while the
-    /// resolves took `&mut self` every frame; 2288 made them `&self` (the in-flight marks live
-    /// behind [`QueryCache`]'s lock), and the counter stays as the one number the three caches
-    /// share.
+    /// Bumped by every landed answer and the pet-rename eviction, never by an ask: the gated
+    /// feeds re-run when it moves.
     generation: u64,
 }
 
-/// One cached creature template head (see [`NameCache::creatures`]).
+/// One cached creature template head.
 #[derive(Clone, Debug)]
 pub(crate) struct CreatureRecord {
     pub(crate) name: String,
     pub(crate) subname: Option<String>,
     pub(crate) creature_type: u32,
-    /// `CreatureFamily.dbc` id — the pet paper doll's family word and, through the row's food
-    /// mask, its diet tooltip (decision 1062). `0` on everything that is neither a tameable beast
-    /// nor a warlock minion, which is most of the table; the family table has no row 0, so a `0`
-    /// resolves to nil without needing a sentinel of its own.
+    /// `CreatureFamily.dbc` id, 0 for anything not a tameable beast or warlock minion (the table
+    /// has no row 0).
     pub(crate) pet_family: u32,
-    /// Elite rank 0..4 **as the template declares it** — read it through [`gated_rank`], never
-    /// directly, unless you specifically want the ungated template value.
+    /// Elite rank 0..4 as the template declares it; read it through [`gated_rank`].
     pub(crate) rank: u32,
-    /// Template type flags — the wire dword, read bit by bit through [`type_flags`]. Never test a
-    /// literal against it: its bits are unrelated neighbours (decision 2068).
+    /// Read bit by bit through [`type_flags`].
     pub(crate) type_flags: u32,
     pub(crate) civilian: bool,
-    /// Racial leader — the tooltip's white LEADER line (`0x6125c0`).
+    /// The tooltip's LEADER line (`0x6125c0`).
     pub(crate) racial_leader: bool,
-    /// `CreatureDisplayInfo.dbc` id — the template's model. The **only** way to draw a creature
-    /// with no world object to read `UNIT_FIELD_DISPLAYID` off, which is exactly a stabled pet
-    /// (decision 1676): its wire row names a template entry and nothing else. `0` when the
-    /// template ships none.
-    ///
-    /// For anything actually on screen the unit's own descriptor field still wins — vmangos picks
-    /// among a template's four display ids at spawn, and this is the first.
-    ///
-    /// **Read by the stable window's model pane** ([`crate::ui_stable`]'s `feed_stable_booth`),
-    /// which is what 1676 deferred and named this field for: the booth points at a
-    /// [`crate::portrait::PortraitStandIn`] built from this id when the selected pet has no world
-    /// object — every stabled pet, and a dismissed one in slot 0.
+    /// `CreatureDisplayInfo.dbc` id, the first of the template's display ids, 0 when it has none.
+    /// The only model for a unit with no world object, such as a stabled pet; an on-screen unit's
+    /// own `UNIT_FIELD_DISPLAYID` wins.
     pub(crate) display_id: u32,
 }
 
-/// The client's **creature-rank getter**, `0x605620` — 33 bytes, and the single source every rank
-/// reader in the real client goes through (decision 0782):
-///
-/// ```text
-/// 605620: mov eax,[ecx+0xb30]   ; the cached creature record
-///         test eax,eax / je  →  0     ; not queried yet
-///         mov ecx,[ecx+0x110]         ; the unit descriptor block
-///         mov edx,[ecx+0x214]         ; UNIT_FIELD_PETNUMBER
-///         test edx,edx / jne →  0     ; somebody's pet or charm
-///         mov eax,[eax+0x20]          ; record->rank
-/// ```
-///
-/// Two gates, and the pet gate is the one nobody expects: a **charmed or enslaved unit reports rank
-/// 0** whatever its template says. Because all three of the client's rank consumers call this one
-/// getter — `UnitClassification` (the target frame's elite/rare border), the unit tooltip's
-/// ELITE/BOSS word, and `UnitLevel`'s world-boss `−1` (the target frame *and* nameplate skull) — a
-/// mind-controlled world boss loses its dragon, its BOSS word and its skull together. Applying the
-/// gate per-reader is how those three silently drift apart, so this function is the only place any
-/// of them may read a rank from.
-///
-/// `store: None` (no descriptor streamed) cannot prove a pet number, so it reads as not-a-pet —
-/// matching the client, whose descriptor block is zero-initialized.
+/// The 1.12 client's creature-rank getter (`0x605620`): 0 before the record is queried and 0 for
+/// any unit with a `UNIT_FIELD_PETNUMBER` (a charmed or enslaved unit), else the template rank.
+/// `UnitClassification`, the tooltip's ELITE/BOSS word and `UnitLevel`'s world-boss -1 all read
+/// through it, so every rank read here goes through this function. No store reads as not-a-pet.
 pub(crate) fn gated_rank(rec: Option<&CreatureRecord>, store: Option<&ObjectStore>) -> u32 {
     match rec {
         Some(rec) if !store.is_some_and(|s| s.0.unit_is_pet_or_charm()) => rec.rank,
@@ -172,36 +96,25 @@ pub(crate) fn gated_rank(rec: Option<&CreatureRecord>, store: Option<&ObjectStor
     }
 }
 
-/// Which of the three caches names a unit, and under which key — the branch of the reference's
-/// `CGUnit_C::GetUnitName` (`0x609210`), which is also what the combat log's `GetObjectName`
-/// (`0x6264e0`) calls for any streamed unit.
+/// Which cache names a unit and under which key: the branch of the reference's `GetUnitName`
+/// (`0x609210`), which the combat log's `GetObjectName` (`0x6264e0`) also calls.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 enum NameKey {
-    /// A player — the `OBJECT_FIELD_TYPE` player bit (`0x609232 shr ecx,4; test cl,1`): the
-    /// name cache by guid.
+    /// The `OBJECT_FIELD_TYPE` player bit (`0x609232`): the name cache by guid.
     Player(u64),
     /// `UNIT_FIELD_PETNUMBER` non-zero (`0x609295`): the pet-name cache under that number.
     Pet(u32),
-    /// `UNIT_FIELD_PETNUMBER` zero (`0x60929d je 0x60934b`): the creature record at `[unit+0xb30]`,
-    /// which is registered under the descriptor's `OBJECT_FIELD_ENTRY` (`0x60b160`).
+    /// `UNIT_FIELD_PETNUMBER` zero (`0x60929d`): the creature record under the descriptor's
+    /// `OBJECT_FIELD_ENTRY` (`0x60b160`).
     Creature(u32),
 }
 
 impl NameKey {
-    /// The key for `guid`, read off its descriptor when one is in hand.
-    ///
-    /// **With a descriptor this is `0x609210` exactly**: the pet number and the template entry are
-    /// the unit's *fields*, never the guid's bits. The two disagree more often than they agree
-    /// outside a hunter's or warlock's own pet — vmangos gives a companion pet a `HIGHGUID_PET`
-    /// guid around a fresh pet number but never files it in the charm info (so `PETNUMBER` is 0 and
-    /// the server would ignore a pet-name query for it); a guardian's `SetPetNumber(n, false)`
-    /// writes 0; a mind-controlled creature keeps a `HIGHGUID_UNIT` guid and gains a non-zero
-    /// number.
-    ///
-    /// **Without one it is the best the guid can say**, and says less: a `HIGHGUID_PET` guid's
-    /// entry slot is taken as the pet number, which is right for a permanent pet (`Pet::Create`
-    /// feeds the same number to both — `SetPetNumber(n, IsPermanentPetFor(owner))`) and cannot name
-    /// a companion or a guardian. A caller that holds the unit's store must pass it.
+    /// With a descriptor this is `0x609210` exactly: the pet number and entry are the unit's
+    /// fields, not the guid's bits (a vmangos companion pet has a `HIGHGUID_PET` guid but
+    /// `PETNUMBER` 0; a charmed creature has a `HIGHGUID_UNIT` guid and a pet number). Without
+    /// one, a `HIGHGUID_PET` guid's entry slot is taken as the pet number, right only for a
+    /// permanent pet.
     fn of(guid_val: u64, unit: Option<&ObjectStore>) -> Option<Self> {
         if guid::is_player(guid_val) {
             return Some(Self::Player(guid_val));
@@ -227,21 +140,14 @@ impl NameKey {
 }
 
 impl NameCache {
-    /// The name for `guid` **when no descriptor for it is in hand**, if known — a roster member, a
-    /// mail sender, a chat speaker, a unit that has left. On a miss, sends the right query (once
-    /// per key per connection) and returns `None` — call again after the answer lands. A guid
-    /// family that has no name on the 1.12 wire (GameObjects resolve via their own query, not
-    /// modeled yet) is `None` without a query.
-    ///
-    /// **A caller holding the unit's [`ObjectStore`] uses [`Self::resolve_unit`]** — the guid
-    /// alone cannot name a companion pet or a guardian ([`NameKey::of`]).
+    /// The name for a guid with no descriptor in hand; on a miss, asks once and returns `None`.
+    /// A caller holding the unit's [`ObjectStore`] uses [`Self::resolve_unit`]: the guid alone
+    /// cannot name a companion pet or a guardian. A game object is `None` without a query.
     pub(crate) fn resolve(&self, guid_val: u64, commands: &NetCommands) -> Option<&str> {
         self.resolve_unit(guid_val, None, commands)
     }
 
-    /// The name for a unit, keyed off its descriptor — the reference's `GetUnitName`
-    /// (`0x609210`, see [`NameKey`]). `unit: None` degrades to [`Self::resolve`]'s guid-only key.
-    /// Same ask-once discipline on every branch.
+    /// The name for a unit keyed off its descriptor, as `0x609210` keys it; asks once on a miss.
     pub(crate) fn resolve_unit(
         &self,
         guid_val: u64,
@@ -256,20 +162,13 @@ impl NameCache {
                     let _ = commands.0.send(ClientCommand::NameQuery { guid: guid_val });
                 })
                 .map(String::as_str),
-            // A pet is a `TYPEID_UNIT` like any creature, but one with a pet number is named
-            // through its own query. Asking the creature query for the number is what left every
-            // summoned pet nameless; asking the pet query for a number the server never filed is
-            // what left every companion pet nameless.
             NameKey::Pet(pet_number) => self.resolve_pet(pet_number, guid_val, commands),
             NameKey::Creature(entry) => self.resolve_creature(entry, guid_val, commands),
         }
     }
 
-    /// The name for a live pet by its `pet_number` — the pet twin of [`Self::resolve_creature`],
-    /// same ask-once discipline. Unlike the creature/player queries this one has **no negative
-    /// answer**: vmangos returns early without a packet when the guid is not a live pet bearing that
-    /// number (`PetHandler.cpp:190-192`), so an unanswered ask simply stays unresolved rather than
-    /// caching a "server doesn't know" — and is re-asked after a reconnect like the others.
+    /// There is no negative answer: vmangos sends nothing when the guid is not a live pet with
+    /// that number (`PetHandler.cpp:190-192`).
     fn resolve_pet(&self, pet_number: u32, guid: u64, commands: &NetCommands) -> Option<&str> {
         self.pets
             .get_or_ask(pet_number, || {
@@ -281,13 +180,8 @@ impl NameCache {
             .map(String::as_str)
     }
 
-    /// The name for a creature template `entry`, if known — the entry-keyed twin of
-    /// [`Self::resolve`]'s creature branch (same cache, same ask-once discipline), for a caller that
-    /// has no live spawn guid to decode an entry from: a quest objective names its kill target only
-    /// by the template's raw `creature_or_go` entry (`crate::ui_quest_log`). `guid` rides along for
-    /// the query body when a real spawn is known, `0` otherwise — the server answers by entry
-    /// regardless of which spawn asked (the same template-only convention as
-    /// [`crate::items::Items::template`]'s `guid: 0`).
+    /// The name for a creature template `entry`; `guid` is 0 when no spawn is known, since the
+    /// server answers by entry alone.
     pub(crate) fn resolve_creature(
         &self,
         entry: u32,
@@ -304,15 +198,12 @@ impl NameCache {
             .map(|r| r.name.as_str())
     }
 
-    /// The cached name for `guid`, read-only — no query on a miss (the trace/diagnostic twin of
-    /// [`Self::resolve`], for callers that must not mutate the ask-once state). Guid-only, with
-    /// [`Self::resolve`]'s limits; [`Self::peek_unit`] is the descriptor-keyed twin.
+    /// The cached name for `guid`, with no query on a miss.
     pub(crate) fn peek(&self, guid_val: u64) -> Option<&str> {
         self.peek_unit(guid_val, None)
     }
 
-    /// The cached name for a unit keyed off its descriptor, read-only — [`Self::resolve_unit`]'s
-    /// no-query twin.
+    /// The cached name for a unit keyed off its descriptor, with no query on a miss.
     pub(crate) fn peek_unit(&self, guid_val: u64, unit: Option<&ObjectStore>) -> Option<&str> {
         match NameKey::of(guid_val, unit)? {
             NameKey::Player(guid_val) => self.players.get(guid_val).map(String::as_str),
@@ -321,18 +212,9 @@ impl NameCache {
         }
     }
 
-    /// Record a player-name answer. An empty wire name means the server doesn't know the guid —
-    /// cached as a negative answer.
-    ///
-    /// `traits` is the `(race, class, gender)` triple that rides `SMSG_NAME_QUERY_RESPONSE`, kept
-    /// for [`Self::player_traits`]. It is `None` for the seams that learn a name **without** that
-    /// packet — the login-time seed of our own name, and the capture fixtures — rather than having
-    /// them invent a zero triple that would read as a real (and wrong) race.
-    ///
-    /// **A `None` therefore *clears* any traits already filed under this guid**, rather than
-    /// leaving them: the triple describes the character the name belongs to, and this call is
-    /// replacing that name. Keeping the old one would leave a record whose name says one character
-    /// and whose race says another — a contradiction manufactured by the cache itself.
+    /// Record a player-name answer; an empty name is a negative answer. `traits` is `None` for a
+    /// name learned without `SMSG_NAME_QUERY_RESPONSE`, and then clears any traits filed for the
+    /// guid, since they belonged to the name being replaced.
     pub(crate) fn insert_player(&mut self, guid: u64, name: String, traits: Option<(u8, u8, u8)>) {
         match traits.filter(|_| !name.is_empty()) {
             Some(t) => self.player_traits.insert(guid, t),
@@ -343,25 +225,10 @@ impl NameCache {
         self.generation = self.generation.wrapping_add(1);
     }
 
-    /// **Drop everything that names one character or one spawn — the reference's world-session
-    /// wipe** (`0x555740`, the `0x5557ad call 0x560400` arm for the player cache).
-    ///
-    /// The reference walks all thirteen `DBCache<T>` singletons at world-session start and clears
-    /// each one **whose persistence is disabled** — the byte at `[cache+0x39]`, tested inverted:
-    /// non-zero skips, zero clears. Four stores pass `0` to the ctor and are therefore both
-    /// never-written-to-disk and wiped here: `'WNAM'` (player names, `0x554cd0` — three `push 0x0`
-    /// against `'WNPC'`/`'WIDB'`'s `push 0x1; push 0x1`), `'WGLD'`, `'WPNM'` and `'WPTN'`. A real
-    /// 1.12 install's `WDB/` holds exactly the enabled ones and none of those four.
-    ///
-    /// The rule behind the list is the key's meaning. A creature template **entry** names the same
-    /// creature on every realm, forever, so its record survives both the wipe and the process. A
-    /// player **guid** names one character on one realm, and a **pet number** names one live spawn
-    /// — and nothing on the 1.12 wire ever says either has been handed to somebody else. So the
-    /// reference does not keep them, and benilla keeping them is what let a server's brand-new
-    /// character wear a deleted one's name (B386, decision 2223).
-    ///
-    /// Called at world entry, **before** the login seeds our own name — the seed is about the
-    /// session we are starting, not the one we just left.
+    /// The reference's world-session wipe (`0x555740`; `0x5557ad call 0x560400` for the player
+    /// cache): every `DBCache` whose persistence byte `[cache+0x39]` is 0 is cleared, which is
+    /// `'WNAM'` (player names, ctor `0x554cd0`), `'WGLD'`, `'WPNM'` (pet names) and `'WPTN'`.
+    /// Called at world entry, before the login seeds our own name.
     pub(crate) fn clear_world_session(&mut self) {
         self.players.clear();
         self.player_traits.clear();
@@ -369,108 +236,63 @@ impl NameCache {
         self.generation = self.generation.wrapping_add(1);
     }
 
-    /// **Install a realm cache read off disk — its CREATURE templates, and nothing else**
-    /// (decision 2260).
-    ///
-    /// The persisted file has carried creature templates alone since 2223, so this is the whole of
-    /// what a load can legitimately say. It used to be spelled `*names = loaded` in
-    /// [`crate::name_persist::load_name_cache`], which is the same thing only when the loader is
-    /// the first writer of the session — and it is not. The loader fires the first frame the realm
-    /// identity is known, which is the frame the *pick* is in flight; the login's
-    /// `SMSG_..._VERIFY_WORLD` seed of our OWN name ([`Self::insert_player`], from
-    /// `net::session::connected`) lands in the same neighbourhood, and whichever arrives
-    /// second wins. When the load won, it discarded the player's own name — so `UnitName("player")`
-    /// answered nil for one wire round-trip while the feed re-asked for a guid it had just been
-    /// told about, and every addon reading it in that window saw nil (the KLHThreatMeter
-    /// `table index is nil` report; reproduced live 3 runs in 4).
-    ///
-    /// Once per process, because `NameCacheFile::realm` only goes `None` → `Some` once — which is
-    /// exactly the "first login of a fresh game start, and never again" shape the report named.
-    ///
-    /// So the rule is not an ordering to get right, it is a *scope*: this touches what the file
-    /// carries. Dropping the guid-keyed stores across a realm change is
-    /// [`Self::clear_world_session`]'s, and it runs at every world entry regardless.
-    ///
-    /// Replace rather than merge — the realm-change case, 2223's own reasoning: the previous
-    /// realm's templates are not this realm's. The generation ticks because a landed record is
-    /// exactly what the gated feeds watch for (1439).
+    /// Install the creature templates read off disk, replacing (not merging) the current ones and
+    /// touching nothing else: the load can land after the login has seeded our own name, which
+    /// must survive it.
     pub(crate) fn install_persisted(&mut self, loaded: NameCache) {
         self.creatures = loaded.creatures;
         self.generation = self.generation.wrapping_add(1);
     }
 
-    /// The landed-answer counter — see the [`Self::generation`] field.
+    /// The landed-answer counter.
     pub(crate) fn generation(&self) -> u64 {
         self.generation
     }
 
-    /// `(race, class, gender)` for a player guid the name query has answered for — the macro
-    /// expander's fallback when the unit isn't streamed. See [`NameCache::player_traits`].
+    /// `(race, class, gender)` for a player guid the name query has answered for.
     pub(crate) fn player_traits(&self, guid: u64) -> Option<(u8, u8, u8)> {
         self.player_traits.get(&guid).copied()
     }
 
-    /// Record a pet-name answer (`SMSG_PET_NAME_QUERY_RESPONSE`), keyed by pet number.
+    /// Record a pet-name answer, keyed by pet number.
     pub(crate) fn insert_pet(&mut self, pet_number: u32, name: String) {
         self.pets.insert(pet_number, Some(name));
         self.generation = self.generation.wrapping_add(1);
     }
 
-    /// Forget a pet's cached name so the next [`Self::resolve`] asks for it again (decision 1066).
-    ///
-    /// **The one hole in the ask-once discipline, and the one place it has to have one.** A player's
-    /// or a creature's name cannot change under a cache entry; a pet's can — its owner renames
-    /// it — and nothing on the wire pushes the new one, because a pet's name does not ride its
-    /// descriptor. What *does* arrive is a bumped `UNIT_FIELD_PET_NAME_TIMESTAMP`, and observing
-    /// that is what calls this (`crate::ui_pet::unit`). Clearing the pending marker matters too: a
-    /// rename racing an in-flight query would otherwise have its re-ask deduped away and leave the
-    /// stale name in place forever.
+    /// Forget a pet's name and its in-flight mark so the next resolve asks again: a rename
+    /// arrives only as a bumped `UNIT_FIELD_PET_NAME_TIMESTAMP`, never as the name.
     pub(crate) fn forget_pet(&mut self, pet_number: u32) {
         self.pets.evict(pet_number);
         self.generation = self.generation.wrapping_add(1);
     }
 
-    /// Record a creature-name answer (`SMSG_CREATURE_QUERY_RESPONSE`); `None` = unknown entry.
+    /// Record a creature-name answer; `None` is an unknown entry.
     pub(crate) fn insert_creature(&mut self, entry: u32, record: Option<CreatureRecord>) {
         self.creatures.insert(entry, record);
         self.generation = self.generation.wrapping_add(1);
     }
 
-    /// The cached subname (the overhead/tooltip title line) for a creature entry — read-only: the
-    /// nameplate asks only after [`Self::resolve`] already returned the name (same answer packet).
+    /// The cached subname, the title line under a creature's name.
     pub(crate) fn creature_subname(&self, entry: u32) -> Option<&str> {
         self.creatures.get(entry)?.subname.as_deref()
     }
 
-    /// The whole cached record for a creature entry — the unit tooltip's read (subtitle, type,
-    /// rank word, civilian — decision 0276's level-line law), and the one route to a live unit's
-    /// [`type_flags`]. Read-only, the subname's ask-once discipline.
-    ///
-    /// **Key it off the unit's descriptor `OBJECT_FIELD_ENTRY`, never the entry in its guid**
-    /// (decision 2068): the reference registers this record under `[[unit+8]+0xc]` (`0x60b160`),
-    /// there is exactly one record per unit, and only the descriptor carries a template entry for
-    /// a `HIGHGUID_PET` guid — whose entry slot holds a pet number instead. A guid-keyed twin of
-    /// this read used to exist and is gone: two keys onto one field is how the readers drift.
-    ///
-    /// `None` = no template answer yet, and **each consumer decides what that means, because the
-    /// reference's per-bit getters do**: the parked-event gate (`MORE_AUDIBLE`, decision 1482)
-    /// fails CLOSED like `0x623b70`'s null leg, the wound gate (`DO_NOT_PLAY_WOUND_ANIM`, 2068)
-    /// fails OPEN like `0x6125f0`'s.
+    /// The cached template record. Key it by the descriptor's `OBJECT_FIELD_ENTRY`, never the
+    /// guid's entry slot, as the reference does (`0x60b160`). On `None` each consumer picks its own
+    /// default as the reference's getters do: `MORE_AUDIBLE` fails closed (`0x623b70`),
+    /// `DO_NOT_PLAY_WOUND_ANIM` fails open (`0x6125f0`).
     pub(crate) fn creature_record(&self, entry: u32) -> Option<&CreatureRecord> {
         self.creatures.get(entry)
     }
 
-    /// The cached `CreatureType.dbc` id for a creature entry — read-only, same ask-once discipline
-    /// as the subname (the TAB-target scan reads it; an unresolved entry is `None`, which the scan
-    /// treats as targetable — the client's own out-of-range skip).
+    /// The cached `CreatureType.dbc` id; the TAB-target scan treats `None` as targetable.
     pub(crate) fn creature_type(&self, entry: u32) -> Option<u32> {
         Some(self.creatures.get(entry)?.creature_type)
     }
 
-    /// Forget the in-flight asks (a disconnect may have dropped them on the writer floor). Resolved
-    /// player/creature names stay — those are identities, stable across sessions. Resolved **pet**
-    /// names do not: a pet number names one live spawn rather than a template, and nothing that
-    /// answered before the disconnect is still on the map after it.
+    /// Forget the in-flight asks a disconnect may have dropped; player and creature names stay,
+    /// pet names go with the spawns they named.
     pub(crate) fn clear_pending(&mut self) {
         self.players.clear_pending();
         self.creatures.clear_pending();
@@ -485,43 +307,24 @@ impl crate::query_cache::AskOnce for NameCache {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Persistence — the `.wdb` law, in benilla's own folder (decision 1689)
+// Persistence
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// The file's first line. Every field is compared by **equality** on load and any mismatch
-/// discards the whole file — the reference's own rule for its `.wdb` header, whose 20 bytes are
-/// `[FourCC | build 0x16f3 | locale | recordSize | version 1]` and carry **no checksum, no
-/// timestamp and no TTL**. Reproducing the *absence* matters as much as the presence: a cache
-/// that expired entries on a clock would re-ask for names the server has no reason to have
-/// changed, and one that trusted a checksum over a build would deserialize last patch's record
-/// layout into this one's struct.
+/// The file's first line; any field that differs on load discards the whole file, the
+/// reference's rule for its `.wdb` header (`[FourCC | build 0x16f3 | locale | recordSize |
+/// version 1]`, no checksum, no timestamp, no TTL).
 const CACHE_MAGIC: &str = "benilla-namecache";
-/// Our own record-layout version — the analogue of the header's `recordSize`+`version` pair. Bump
-/// it whenever a column below is added, removed or reordered; the old file is then discarded
-/// rather than misparsed.
-///
-/// **2** — the player (`P`/`p`) and pet (`E`) records are gone (decision 2223). They were never the
-/// reference's to write: `'WNAM'` and `'WPNM'` are constructed with persistence disabled and are
-/// wiped at world-session start instead ([`NameCache::clear_world_session`]). A version-1 file
-/// still holding them is discarded whole, which is the header's job and exactly the right thing —
-/// its player lines are the stale identities B386 was about.
+/// Our record-layout version; bump it when a column changes. Version 2 holds creature records
+/// only.
 const CACHE_FORMAT: u32 = 2;
-/// The client build the names were answered by — the reference's `0x16f3`. A different build is a
-/// different server protocol, so its answers are not ours.
+/// The client build, the reference's `0x16f3`.
 const CACHE_BUILD: u32 = 5875;
-/// The locale the names are in. benilla is enUS-only today (every DBC read takes locale slot 0),
-/// so this is a constant — but it is *in* the header because that is the reference's law, and the
-/// day benilla speaks a second locale a stale enUS cache must be discarded rather than shown.
+/// In the header as in the reference's; benilla reads DBC locale slot 0 only.
 const CACHE_LOCALE: &str = "enUS";
 
 impl NameCache {
-    /// Serialize the cache as the TSV this module persists — a header line, then one line per
-    /// record. Tab-separated because a name may contain spaces but never a tab or a newline, and
-    /// because a player who opens `benilla-config/` should be able to read what we kept about them.
-    ///
-    /// **`pending_*` is deliberately not written.** An in-flight ask is a fact about this
-    /// connection, not about the names; persisting it would make a cache reloaded mid-query
-    /// believe an answer was coming that never will.
+    /// Serialize as TSV: the header line, then one line per creature record. In-flight asks are
+    /// not written.
     pub(crate) fn to_tsv(&self, realm: &str) -> String {
         let mut out =
             format!("{CACHE_MAGIC}\t{CACHE_FORMAT}\t{CACHE_BUILD}\t{CACHE_LOCALE}\t{realm}\n");
@@ -545,13 +348,11 @@ impl NameCache {
         out
     }
 
-    /// Rebuild a cache from [`Self::to_tsv`]'s output, or `None` if the header does not match this
-    /// build/locale/format **exactly**. A malformed or truncated line is skipped rather than
-    /// failing the load: a half-written cache should cost a re-query, never a broken session.
+    /// Rebuild a cache from [`Self::to_tsv`]'s output, `None` when the header differs; a
+    /// malformed line is skipped.
     pub(crate) fn from_tsv(text: &str, realm: &str) -> Option<Self> {
         let mut lines = text.lines();
         let header: Vec<&str> = lines.next()?.split('\t').collect();
-        // The equality gate. Five fields, all of them, no tolerance — see `CACHE_MAGIC`.
         if header.len() != 5
             || header[0] != CACHE_MAGIC
             || header[1] != CACHE_FORMAT.to_string()
@@ -581,8 +382,7 @@ impl NameCache {
                         entry,
                         Some(CreatureRecord {
                             name: f[9].to_string(),
-                            // An empty subname is NO subname, the same mapping the wire decode
-                            // makes — `Some("")` would paint an empty tooltip line.
+                            // Empty is no subname, as in the wire decode.
                             subname: (!f[10].is_empty()).then(|| f[10].to_string()),
                             creature_type,
                             pet_family,
@@ -605,29 +405,21 @@ impl NameCache {
         Some(cache)
     }
 
-    /// Drop a player's cached name (`SMSG_INVALIDATE_PLAYER`) so the next resolve re-asks — the
-    /// reference's remove-by-key (`0x556ff0`; eviction is **explicit only**, there is no TTL).
-    ///
-    /// This is the safety valve persistence needs. In memory a stale name lasts a session; on disk
-    /// it lasts forever, so the one packet that says "forget this guid" has to be honoured. Note
-    /// that vmangos never sends it — so against our own server this is the mechanism being present
-    /// and correct rather than a path we exercise.
+    /// Drop a player's cached name and traits so the next resolve re-asks: the reference's
+    /// remove-by-key for `SMSG_INVALIDATE_PLAYER` (`0x555600` into `0x560170`).
     pub(crate) fn invalidate_player(&mut self, guid: u64) {
         self.players.evict(guid);
         self.player_traits.remove(&guid);
         self.generation = self.generation.wrapping_add(1);
     }
 
-    /// How many records the cache holds — the persistence layer's "is this worth writing" read.
+    /// How many records the cache holds.
     pub(crate) fn len(&self) -> usize {
         self.players.len() + self.creatures.len() + self.pets.len()
     }
 }
 
-/// The name-query answers (in the net handler table since 2325, moved out of the drain's names
-/// arm file) — the three `*_QUERY_RESPONSE` packets that fill the ask-once cache
-/// (`NameCache::resolve` is what asked for them), and the invalidation that unsticks a player's
-/// name. Registered from [`crate::net::NetPlugin`], which initialises the cache.
+/// The three name-query answers and `SMSG_INVALIDATE_PLAYER`.
 pub(crate) mod net {
     use benilla_protocol::{SessionEvent, SessionEventKind};
     use bevy::prelude::*;
@@ -699,9 +491,7 @@ pub(crate) mod net {
         }
     }
 
-    /// `SMSG_NAME_QUERY_RESPONSE` — a player's name, plus the race/gender/class that ride the same
-    /// answer. Those three now have a consumer: the `$`-macro expander's subject fallback for a player
-    /// who isn't streamed ([`crate::npc_text::subject_for_guid`]).
+    /// `SMSG_NAME_QUERY_RESPONSE`: the name plus race, class and gender.
     fn player_name(
         guid: u64,
         name: String,
@@ -713,25 +503,19 @@ pub(crate) mod net {
         names.insert_player(guid, name, Some((race as u8, class as u8, gender as u8)));
     }
 
-    /// `SMSG_PET_NAME_QUERY_RESPONSE` — keyed by pet *number*, not by template entry.
+    /// `SMSG_PET_NAME_QUERY_RESPONSE`, keyed by pet number.
     fn pet_name(pet_number: u32, name: String, names: &mut NameCache) {
         names.insert_pet(pet_number, name);
     }
 
-    /// `SMSG_INVALIDATE_PLAYER` — drop this guid so the next resolve re-asks (decision 1689).
-    ///
-    /// The name cache has **no TTL** (eviction is explicit only, `0x555600`), so this is the
-    /// one thing that unsticks a player's name. It matters more to benilla than it did before the
-    /// cache persisted: in memory a stale name lasted a session, on disk it lasts until something
-    /// evicts it.
+    /// `SMSG_INVALIDATE_PLAYER`, which vmangos sends after a rename (`CharacterHandler.cpp:839`):
+    /// the only per-player eviction, as in the reference, whose name cache has no TTL (`0x555600`).
     fn invalidate_player(guid: u64, names: &mut NameCache) {
         debug!("net: invalidating cached name for player {guid:#x}");
         names.invalidate_player(guid);
     }
 
-    /// `SMSG_CREATURE_QUERY_RESPONSE` — the template's name plus the hover line's fields. A `None` name
-    /// is the server's "no such entry", cached as such so the ask never repeats; the remaining fields
-    /// then carry their miss defaults.
+    /// `SMSG_CREATURE_QUERY_RESPONSE`; a `None` name is the server's "no such entry".
     fn creature_name(
         entry: u32,
         name: Option<String>,
@@ -777,9 +561,7 @@ mod tests {
         (NetCommands(tx), rx)
     }
 
-    /// The gated feeds' counter (1439): a landed answer (and the rename eviction) moves it; an
-    /// ask-once miss — the read gated feeds run every frame — never does, or the outstanding
-    /// query would hold every name-watching gate open until it answered.
+    /// An ask must not move the counter, or an outstanding query would hold every gated feed open.
     #[test]
     fn the_generation_counts_landings_never_asks() {
         let (cmds, _rx) = commands();
@@ -812,9 +594,8 @@ mod tests {
         );
     }
 
-    /// A summoned pet resolves through `CMSG_PET_NAME_QUERY`, keyed by the pet number in its guid —
-    /// NOT through the creature query, which would ask for a template entry that does not exist and
-    /// leave the pet nameless (the reported bug: an NPC-summoned voidwalker with no name).
+    /// A summoned pet asks `CMSG_PET_NAME_QUERY` by the pet number in its guid; its entry slot
+    /// names no creature template.
     #[test]
     fn a_pet_asks_the_pet_query_not_the_creature_query() {
         let (cmds, rx) = commands();
@@ -829,7 +610,6 @@ mod tests {
                 ..
             })
         ));
-        // Ask-once, like every other name.
         assert_eq!(cache.resolve(voidwalker, &cmds), None);
         assert!(matches!(rx.try_recv(), Err(TryRecvError::Empty)));
 
@@ -841,31 +621,22 @@ mod tests {
         assert_eq!(cache.peek(voidwalker), None);
     }
 
-    /// **A stable list warms the pet-name cache, so an unstabled pet is named on arrival**
-    /// (decision 1688). The list carries the same `(pet_number, name)` pair the pet-name query
-    /// would answer with, and the guid slot benilla reads that number out of is the very one
-    /// vmangos packs it into (`Object::_Create(guidlow, petNumber, HIGHGUID_PET)`).
-    ///
-    /// The window this closes is a Lua error the director hit: `PetStable_Update` hands a bare
-    /// `UnitName("pet")` to `GameTooltip:SetText`, whose byte-pinned signature REQUIRES a string
-    /// and raises on nil. The reference's own line is unguarded too — it survives because
-    /// `petnamecache.wdb` persists across sessions and benilla has no such file.
+    /// A stable list seeds the same `(pet_number, name)` pair the pet-name query answers, so an
+    /// unstabled pet is named on arrival: `PetStable.lua:163` stores `UnitName("pet")` unguarded
+    /// and `:178` hands it to `GameTooltip:SetText`, which raises on nil. vmangos packs the pet
+    /// number into the guid's entry slot (`Pet.cpp:2250`).
     #[test]
     fn a_stable_list_names_the_pet_before_it_is_ever_summoned() {
         let (cmds, rx) = commands();
         let cache = NameCache::default();
-        // The guid the pet will have once summoned: its pet number rides the ENTRY slot.
         let rex = compose(guid::HIGH_PET, 7, 42);
 
-        // Cold: nil, and an ask goes out — the state that raised the error.
         assert_eq!(cache.resolve(rex, &cmds), None);
         assert!(matches!(
             rx.try_recv(),
             Ok(ClientCommand::PetNameQuery { pet_number: 7, .. })
         ));
 
-        // The list lands and seeds the name. Now the pet resolves with NO further query, which is
-        // the whole point: it is named the frame it is summoned, not a round trip later.
         let mut warm = NameCache::default();
         warm.insert_pet(7, "Rex".into());
         assert_eq!(warm.resolve(rex, &cmds), Some("Rex"));
@@ -875,13 +646,7 @@ mod tests {
         );
     }
 
-    /// **The round trip keeps every record kind and every shape of answer** (decision 1689) —
-    /// including the "the server said no" negative, which is the one a naive serializer drops:
-    /// cached as absent, it is what stops us re-asking an unknown entry on every login, forever.
-    ///
-    /// The *player* negative used to be here too and is gone with the player records themselves
-    /// (2223): a guid the server did not know this week is not a guid it will not know next week,
-    /// because the guid may by then belong to somebody it does.
+    /// The negative answer survives too, so an unknown entry is not re-asked every login.
     #[test]
     fn the_cache_round_trips_through_its_file_format() {
         let mut cache = NameCache::default();
@@ -904,7 +669,7 @@ mod tests {
         let text = cache.to_tsv("Hydraxian Waterlords");
         let back = NameCache::from_tsv(&text, "Hydraxian Waterlords").expect("header matches");
 
-        // A cached negative must survive as a negative — present-and-None, not absent.
+        // Present-and-None, not absent.
         assert!(back.creatures.answered(1234));
         let rec = back.creature_record(69).expect("creature survived");
         assert_eq!(rec.name, "Stable Master Kitrik");
@@ -915,8 +680,7 @@ mod tests {
         assert!(back.creature_record(1234).is_none());
         assert_eq!(back.len(), 2);
 
-        // An EMPTY subname must come back as no subname, the same mapping the wire decode makes —
-        // `Some("")` paints an empty tooltip line whose zero-extent slot spills the ones below it.
+        // `Some("")` would paint an empty tooltip line.
         cache.insert_creature(
             70,
             Some(CreatureRecord {
@@ -935,13 +699,8 @@ mod tests {
         assert_eq!(back.creature_record(70).unwrap().subname, None);
     }
 
-    /// **B386 — the file carries creature templates and NOTHING that names one character.**
-    ///
-    /// The reference constructs `'WNAM'` (player names) and `'WPNM'` (pet names) with persistence
-    /// **disabled** — `0x554cd0`'s three `push 0x0` against `'WNPC'`/`'WIDB'`'s `push 0x1; push
-    /// 0x1` — and a real 1.12 install's `WDB/` holds `creaturecache.wdb` and no `namecache.wdb`.
-    /// A creature template entry means the same creature forever; a player guid means one
-    /// character on one realm, and a wiped server hands it to the next one it creates.
+    /// The reference builds `'WNAM'` (ctor `0x554cd0`) and `'WPNM'` with persistence off; a 1.12
+    /// install's `WDB/` holds `creaturecache.wdb` and no `namecache.wdb`.
     #[test]
     fn the_file_keeps_creature_templates_and_no_identities() {
         let mut cache = NameCache::default();
@@ -981,9 +740,8 @@ mod tests {
         );
     }
 
-    /// **World entry drops every guid- and spawn-keyed name, and keeps the templates** — the
-    /// reference's `0x555740`, which clears exactly the stores whose `[cache+0x39]` enable byte is
-    /// zero (tested inverted: `0x55579f`–`0x5557ad` for the player cache at `0xc0e228`).
+    /// The reference's `0x555740` clears the stores whose `[cache+0x39]` byte is 0
+    /// (`0x55579f`-`0x5557ad` for the player cache at `0xc0e228`).
     #[test]
     fn world_entry_clears_the_identities_and_keeps_the_templates() {
         let (cmds, rx) = commands();
@@ -1000,8 +758,7 @@ mod tests {
             cache.creatures.answered(69),
             "templates outlive the world session"
         );
-        // And the ask-once markers went with them, so the next sighting asks rather than sitting
-        // behind a pending flag from a session that is over.
+        // The in-flight marks went too.
         assert_eq!(cache.resolve(0x11, &cmds), None);
         assert!(matches!(
             rx.try_recv(),
@@ -1009,10 +766,6 @@ mod tests {
         ));
     }
 
-    /// **Replacing a name drops the traits that belonged to the old one.** They describe the
-    /// character the name names; leaving them behind manufactures exactly the record the
-    /// descriptor check exists to catch — one whose name says one character and whose race says
-    /// another.
     #[test]
     fn a_name_replaced_without_traits_does_not_keep_the_old_ones() {
         let mut cache = NameCache::default();
@@ -1021,11 +774,6 @@ mod tests {
         assert_eq!(cache.player_traits(0x7), None);
     }
 
-    /// **The header is an equality gate with no tolerance** — the reference's own `.wdb` rule, and
-    /// the reason its cache carries no checksum and no clock. Each field is rejected on its own:
-    /// a different build speaks a different protocol, a different locale means different strings,
-    /// a different format version means these columns are not those columns, and a different realm
-    /// means every key in the file addresses somebody else.
     #[test]
     fn a_header_that_differs_in_any_field_discards_the_whole_file() {
         let mut cache = NameCache::default();
@@ -1033,8 +781,7 @@ mod tests {
         let good = cache.to_tsv("Hydraxian Waterlords");
         assert!(NameCache::from_tsv(&good, "Hydraxian Waterlords").is_some());
 
-        // The realm — the field the reference does NOT have, and the one that would silently
-        // serve another realm's names.
+        // The realm: our field, not the reference's.
         assert!(NameCache::from_tsv(&good, "Another Realm").is_none());
 
         let head = good.lines().next().unwrap();
@@ -1053,18 +800,13 @@ mod tests {
             );
         }
 
-        // Garbage and truncation cost a re-query, never a broken session.
         assert!(NameCache::from_tsv("", "R").is_none());
         assert!(NameCache::from_tsv("nonsense", "R").is_none());
-        // A good header with a mangled record line keeps the header's other records.
         let text = format!("{}\nC\tnotanumber\t1\t2\t0\tX\nc\t1234\n", head);
         let back = NameCache::from_tsv(&text, "Hydraxian Waterlords").expect("header still good");
         assert_eq!(back.len(), 1, "the bad line is skipped, the good one kept");
 
-        // **A version-1 file is discarded whole, and its player lines with it** (2223). The format
-        // field does that on its own — but say it here, because those lines are exactly the stale
-        // identities B386 was about and "the old file is simply dropped" is the property that
-        // matters, not that the `P` arm no longer parses.
+        // A version-1 file, which held player names, is discarded whole.
         let v1 = format!(
             "{CACHE_MAGIC}\t1\t{CACHE_BUILD}\t{CACHE_LOCALE}\tHydraxian Waterlords\n\
              P\t7\t1\t1\t0\tMoamtester\n"
@@ -1072,8 +814,6 @@ mod tests {
         assert!(NameCache::from_tsv(&v1, "Hydraxian Waterlords").is_none());
     }
 
-    /// `SMSG_INVALIDATE_PLAYER`'s eviction — the safety valve persistence needs. The cache ages
-    /// nothing out, so without this a name written to disk would outlive any change to it.
     #[test]
     fn invalidating_a_player_makes_the_next_resolve_ask_again() {
         let (cmds, rx) = commands();
@@ -1094,7 +834,6 @@ mod tests {
             "the traits go with the name"
         );
 
-        // The next resolve is a genuine miss again — it asks.
         assert_eq!(cache.resolve(0x11, &cmds), None);
         assert!(matches!(
             rx.try_recv(),
@@ -1148,7 +887,6 @@ mod tests {
         ));
         cache.insert_player(g, String::new(), None); // server: unknown guid
         assert_eq!(cache.resolve(g, &cmds), None);
-        // …and no re-ask.
         assert!(matches!(rx.try_recv(), Err(TryRecvError::Empty)));
     }
 
@@ -1160,7 +898,7 @@ mod tests {
 
         assert_eq!(cache.resolve(g, &cmds), None);
         let _ = rx.try_recv();
-        // The answer never lands (disconnect); pending cleared → the next resolve re-asks.
+        // A disconnect dropped the answer.
         cache.clear_pending();
         assert_eq!(cache.resolve(g, &cmds), None);
         assert!(matches!(
@@ -1191,12 +929,8 @@ mod tests {
         }
     }
 
-    /// **A companion pet is named by its template, not by the pet number in its guid** —
-    /// `0x609210`'s `UNIT_FIELD_PETNUMBER == 0` leg. vmangos builds a mini-pet as a
-    /// `HIGHGUID_PET` guid around a fresh pet number but never files that number in its charm
-    /// info, so a `CMSG_PET_NAME_QUERY` for it is never answered (`PetHandler.cpp:190-192`) — the
-    /// guid-keyed resolve left every Mechanical Squirrel "Unknown" forever. Its descriptor says
-    /// PETNUMBER 0, and the reference reads the creature record under `OBJECT_FIELD_ENTRY`.
+    /// `0x609210`'s `UNIT_FIELD_PETNUMBER == 0` leg: a vmangos companion pet's guid holds a pet
+    /// number the server never answers for (`PetHandler.cpp:190-192`).
     #[test]
     fn a_companion_pet_is_named_by_its_descriptor_entry() {
         let (cmds, rx) = commands();
@@ -1219,7 +953,6 @@ mod tests {
         );
     }
 
-    /// The cold companion asks the CREATURE query for its descriptor entry — once.
     #[test]
     fn a_cold_companion_pet_asks_the_creature_query_for_its_entry() {
         let (cmds, rx) = commands();
@@ -1236,8 +969,6 @@ mod tests {
         assert!(matches!(rx.try_recv(), Err(TryRecvError::Empty)));
     }
 
-    /// A hunter/warlock pet carries its pet number in the descriptor (`SetPetNumber(n, true)`),
-    /// and that is the key the pet-name query goes out under — not the creature template.
     #[test]
     fn a_permanent_pet_asks_the_pet_query_for_its_descriptor_number() {
         let (cmds, rx) = commands();
@@ -1256,9 +987,7 @@ mod tests {
         assert_eq!(cache.peek_unit(rex, Some(&store)), Some("Rex"));
     }
 
-    /// A mind-controlled creature (`HIGHGUID_UNIT` guid) carries a pet number too
-    /// (`SpellAuras.cpp:3248`, `SetPetNumber(GeneratePetNumber(), true)`), and the reference names
-    /// it through the pet-name cache under that number for as long as the charm holds.
+    /// A charmed creature gets a pet number (`SpellAuras.cpp:3248`) and is named under it.
     #[test]
     fn a_charmed_creature_is_named_by_its_pet_number() {
         let (cmds, rx) = commands();
diff --git a/crates/benilla-app/src/npc_text.rs b/crates/benilla-app/src/npc_text.rs
index 9f7e7750..0d4fc98a 100644
--- a/crates/benilla-app/src/npc_text.rs
+++ b/crates/benilla-app/src/npc_text.rs
@@ -1,74 +1,50 @@
-//! NPC-text macros — the client-side `$`-token expansion the 1.12 wire leaves undone in every
-//! server-authored text the player reads: gossip greetings, questgiver panel texts, and the quest
-//! log's description/objectives (the director's screenshot showed a literal `$N` in a quest
-//! description). One shared mechanism (the 0109 look fix promoted it out of `ui_gossip`); every feed
-//! seam that pushes NPC text into the VM runs it — as the reference does, routing all fourteen of
-//! its call sites through the one expander.
+//! The `$`-token expansion of server-authored NPC text (gossip, questgiver panels, the quest log),
+//! which the client does, not the server; every feed that pushes NPC text into the VM runs it, as
+//! the reference routes its fourteen call sites through one expander (`0x506f70`, token handler
+//! `0x5070a0`).
 //!
-//! The grammar is the reference's (`QuestTextParser.cpp`, driver `0x506f70` → token handler
-//! `0x5070a0`):
+//! - The accepted set is `B C E G N R T W` in either case; anything else re-emits the `$` and
+//!   leaves the letter as text.
+//! - A decimal prefix is consumed ahead of every token, but only `W` and `E` read it.
+//! - Case is the output switch: `$r` is `$R` through `_strlwr`, and likewise `$c` and `$t`.
 //!
-//! - the accepted set is **exactly** `B C E G N R T W`, in either case. Anything else re-emits the
-//!   `$` and lets the letter fall through as ordinary literal text;
-//! - an optional decimal prefix is scanned and consumed ahead of *every* token, but only `W`/`E`
-//!   read it;
-//! - **case is the output switch, not a separate token**: `$R` is the race string verbatim
-//!   (`"Night Elf"`), `$r` is that same string through `_strlwr` (`"night elf"`). Same for
-//!   `$C`/`$c` and `$T`/`$t`; `$N`/`$B`/`$G` are case-insensitive.
-//!
-//! The reference's *other* `$`-expander — spell descriptions, with its `$/N;` scale prefixes and
-//! `$<spellId>` cross-references — is a different function over a different source. Ours is
-//! [`benilla_formats::substitute`], kept separate here exactly as it is there.
+//! Spell descriptions use a separate expander in the reference, as here
+//! ([`benilla_formats::substitute`]).
 
 use bevy::prelude::*;
 
 use crate::names::NameCache;
 use crate::net::{Guid, GuidIndex, NetCommands, ObjectStore, SelfPlayer};
 
-/// The unit a `$`-macro expands against. Every seam we have passes the **self player** (the
-/// reference resolves the subject from the GUID its call site hands over, and only its four chat
-/// sites pass the speaker instead), so the reference's non-player arm — where `$R`/`$C` emit the
-/// unit's *name* in place of a race/class — is not reachable from here.
+/// The unit a `$`-macro expands against: the self player, or the speaker at the reference's four
+/// chat sites.
 pub(crate) struct Subject {
     pub name: String,
-    /// `UNIT_FIELD_BYTES_0` byte 0 / byte 1 — indices into the `ChrRaces`/`ChrClasses` tables the
-    /// reference reads by locale column. Ours are [`crate::ui_unit`]'s hardcoded English rows, which
-    /// were checked character-for-character against the shipped DBCs.
+    /// `UNIT_FIELD_BYTES_0` bytes 0 and 1, into `ChrRaces` and `ChrClasses`, which the reference
+    /// reads at the client's locale column; we read [`crate::ui_unit`]'s rows, the enUS column's.
     pub race: u8,
     pub class: u8,
-    /// `UNIT_FIELD_BYTES_0` byte 2. The `$G`/`$T` branch test is `== 0` → the *first* arm, anything
-    /// else → the second — the reference compares against zero, so this is not "1 = female".
+    /// `UNIT_FIELD_BYTES_0` byte 2; `$G` takes the first arm on 0, the second on anything else.
     pub gender: u8,
 }
 
-/// Everything a `$`-token can read: the [`Subject`] the person-tokens expand against, and the
-/// world-state table `$<n>w`/`$<n>e` index. The reference reads the latter from a process global
-/// (`[0xb71ec8]`); we hold it as a resource, so the expander takes it explicitly — the same shape
-/// the sibling spell expander already uses (`benilla_formats::TokenContext`).
+/// Everything a `$`-token can read; `states` is the reference's global world-state table
+/// (`[0xb71ec8]`).
 pub(crate) struct MacroContext<'a> {
-    /// `None` is the reference's no-subject case — see [`substitute`].
+    /// `None` is the reference's no-subject case.
     pub subject: Option<&'a Subject>,
     pub states: &'a crate::world_state::WorldStates,
 }
 
-/// Substitute the macros in `text` against `ctx` (see the module doc for the grammar). A `None`
-/// subject is the reference's no-subject case: every token that needs one fails, which re-emits the
-/// `$` and leaves the rest of the text literal — so an un-landed player name shows `$N` for the
-/// moment rather than a hole, and the feeds re-substitute when it arrives.
+/// Expands the macros in `text`. With no subject every person-token re-emits its `$`, so a name
+/// not yet known shows `$N` until the feeds re-substitute.
 pub(crate) fn substitute(text: &str, ctx: &MacroContext) -> String {
     substitute_checked(text, ctx).0
 }
 
-/// [`substitute`], plus the reference driver's **return flag**: `true` when no token failed.
-///
-/// The reference's `0x506f70` returns exactly this — "no unrecognized token was hit" — and its
-/// callers branch on it. The panel seams ignore it (they show the `$`-preserving text either way,
-/// which is what [`substitute`] hands back); the **chat** seam must not, because the reference's
-/// chat path never displays a `$` — it drops or defers the line instead. See
-/// `ui_chat::feed`'s use, decision 0759.
-///
-/// Note what the flag does NOT mean: it says nothing about truncation, and a `false` can come
-/// either from an unresolvable subject or from a token outside the accepted set.
+/// [`substitute`] plus `0x506f70`'s return flag, `true` when no token failed (no subject, or a
+/// token outside the set). Panels ignore it; chat must not, since the reference's chat path drops
+/// or defers a line rather than show a `$`.
 pub(crate) fn substitute_checked(text: &str, ctx: &MacroContext) -> (String, bool) {
     let subject = ctx.subject;
     let mut clean = true;
@@ -81,30 +57,24 @@ pub(crate) fn substitute_checked(text: &str, ctx: &MacroContext) -> (String, boo
             i += 1;
             continue;
         }
-        // The decimal prefix is consumed ahead of the token letter whatever the token turns out to
-        // be — so `$5N` is just `$N`, and an unaccepted `$5X` loses the digits on its way out.
+        // An unaccepted `$5X` loses its digits too.
         let mut j = i + 1;
         while chars.get(j).is_some_and(char::is_ascii_digit) {
             j += 1;
         }
-        // `fail` is the reference's `false` return: the `$` comes back and the cursor stays on the
-        // letter, which the literal path then copies.
+        // On a fail the `$` comes back and the letter is copied as text.
         let mut fail = false;
         match chars.get(j).copied() {
-            // Exactly one `\n` (no CR) — the text renderer splits on it. Needs no subject.
+            // Exactly one `\n`, no CR.
             Some('B' | 'b') => {
                 out.push('\n');
                 i = j + 1;
             }
-            // `$<n>W` / `$<n>E` — the world-state table ([`crate::world_state`]), filled by
-            // SMSG_INIT_WORLD_STATES (`0x2C2`) and SMSG_UPDATE_WORLD_STATE (`0x2C3`); `$…E` reads
-            // that same table at the *negated* key, and both render `%d`. A miss prints `"0"` —
-            // which is every lookup until a zone actually sends states, and is what the reference
-            // prints then too.
+            // The world-state table (`SMSG_INIT_WORLD_STATES`, `SMSG_UPDATE_WORLD_STATE`); `E`
+            // reads the negated key; both render `%d`, and a miss prints "0".
             Some(tok @ ('W' | 'w' | 'E' | 'e')) => {
-                // `SStrToInt` over the prefix. No digits at all reads an uninitialized buffer in
-                // the reference (undefined); we take it as key 0, and an id too wide for the
-                // dword the wire carries goes the same way rather than wrapping to a live key.
+                // `SStrToInt` over the prefix. No digits reads an uninitialized buffer in the
+                // reference; we take key 0, as for an id too wide for a dword.
                 let n: u32 = chars[i + 1..j]
                     .iter()
                     .collect::<String>()
@@ -127,8 +97,7 @@ pub(crate) fn substitute_checked(text: &str, ctx: &MacroContext) -> (String, boo
             },
             Some(tok @ ('R' | 'r' | 'C' | 'c')) => match subject {
                 Some(s) => {
-                    // An id outside the table is where the reference dereferences near-NULL and
-                    // faults outright; we emit nothing.
+                    // An id outside the table faults the reference; we emit nothing.
                     let name = if matches!(tok, 'R' | 'r') {
                         crate::ui_unit::race_names(s.race).map_or("", |(display, _)| display)
                     } else {
@@ -143,10 +112,9 @@ pub(crate) fn substitute_checked(text: &str, ctx: &MacroContext) -> (String, boo
                 }
                 None => fail = true,
             },
-            // `$T`/`$t` is the PvP rank title, with this same gender branch as its fallback when the
-            // `PVP_RANK_<rank>_<team>` GlobalString misses — which it always does here, since we
-            // ship no rank titles. So the two tokens share one path, and `$t` lower-cases nothing:
-            // the reference never lower-cases the fallback text either.
+            // `$T` is the PvP rank title, falling back to this gender branch, never lower-cased,
+            // when the `PVP_RANK_<rank>_<team>` GlobalString misses. We ship no rank titles, so it
+            // always misses.
             Some('G' | 'g' | 'T' | 't') => match subject {
                 Some(s) => {
                     let mut k = j + 1;
@@ -158,10 +126,7 @@ pub(crate) fn substitute_checked(text: &str, ctx: &MacroContext) -> (String, boo
                             out.extend(if s.gender == 0 { first } else { second });
                             i = end;
                         }
-                        // A malformed branch swallows the marker and the spaces after it and emits
-                        // nothing at all — its argument survives as plain text, so `$G male female;`
-                        // renders `male female;`. (We used to pass the whole token through; the
-                        // bytes say the marker is consumed.)
+                        // Malformed: the marker and its spaces go, the argument stays as text.
                         None => i = k,
                     }
                 }
@@ -179,9 +144,7 @@ pub(crate) fn substitute_checked(text: &str, ctx: &MacroContext) -> (String, boo
     (out, clean)
 }
 
-/// Parse a `$G`/`$T` branch body `first:second;` starting at `start` (already past the marker and
-/// the spaces behind it), returning the two arms and the index just past the terminating `;`.
-/// `None` — malformed — when there is no `:` before the `;`, or no `;` at all.
+/// Parses a `first:second;` branch body: the two arms and the index past the `;`.
 fn parse_branch(chars: &[char], start: usize) -> Option<(&[char], &[char], usize)> {
     let colon = (start..chars.len()).find(|&j| chars[j] == ':' || chars[j] == ';')?;
     if chars[colon] != ':' {
@@ -195,18 +158,14 @@ fn parse_branch(chars: &[char], start: usize) -> Option<(&[char], &[char], usize
     ))
 }
 
-/// Drop the spaces the reference's branch copy drops: the leading run (after the marker and after
-/// the `:`) and the trailing one. Only `' '` — its skip loops test that byte, not whitespace.
+/// Trims leading and trailing `' '` only, as the reference's branch copy does.
 fn trim_spaces(arm: &[char]) -> &[char] {
     let start = arm.iter().position(|&c| c != ' ').unwrap_or(arm.len());
     let end = arm.iter().rposition(|&c| c != ' ').map_or(start, |p| p + 1);
     &arm[start..end]
 }
 
-/// The self player as a macro [`Subject`] — the name from the [`NameCache`] (a miss queries the
-/// server once, like the unit frames), race/class/gender from the descriptor. `None` until the
-/// player is streamed *and* its name has landed; the feeds diff on the substituted text, so it
-/// re-substitutes when that happens.
+/// The self player as a macro [`Subject`], once it is streamed and its name is known.
 pub(crate) fn player_identity(
     self_q: &Query<(&ObjectStore, &Guid), With<SelfPlayer>>,
     names: &NameCache,
@@ -221,14 +180,8 @@ pub(crate) fn player_identity(
     })
 }
 
-/// A macro [`Subject`] for an **arbitrary** guid — the chat feed's subject, where every other seam
-/// passes the local player.
-///
-/// This is the reference's own two-step (`0x506f70`): look the guid up in the
-/// object manager first and read the unit's descriptors, and only when it isn't streamed fall back
-/// to the **name-cache** record. `None` means the subject could not be resolved at all — the
-/// reference's no-subject case, which fails every person-token and re-emits a literal `$`; that is
-/// also what an untargeted line (guid 0) gets, deliberately.
+/// The chat feed's [`Subject`] for any guid: the object manager's descriptors, else the name
+/// cache (`0x506f70`). Guid 0 has no subject.
 pub(crate) fn subject_for_guid(
     guid: u64,
     index: &GuidIndex,
@@ -249,9 +202,8 @@ pub(crate) fn subject_for_guid(
             gender: store.0.unit_gender().unwrap_or(0),
         });
     }
-    // Not streamed: the name answer's own race/class/gender. A creature guid has no such record and
-    // lands on zeros — which is right, because the reference's non-player arm never reads a
-    // race/class for `$R`/`$C` either; it emits the unit's name instead (`0x50716b`/`0x5071f7`).
+    // A creature lands on zeros, so `$R` and `$C` emit nothing; the reference's non-player arm
+    // emits the unit's name (`0x50716b`, `0x5071f7`), which is not built.
     let (race, class, gender) = names.player_traits(guid).unwrap_or((0, 0, 0));
     Some(Subject {
         name,
@@ -266,7 +218,7 @@ mod tests {
     use super::{substitute, substitute_checked, MacroContext, Subject};
     use crate::world_state::WorldStates;
 
-    /// Thrall the night-elf priest — race 4 / class 5, so both table lookups are real rows.
+    /// Race 4, class 5: both real rows.
     fn subject(gender: u8) -> Subject {
         Subject {
             name: "Thrall".into(),
@@ -276,8 +228,6 @@ mod tests {
         }
     }
 
-    /// Expand against a subject and an empty world-state table — the shape of every test whose
-    /// concern is a person-token.
     fn expand(text: &str, subject: Option<&Subject>) -> String {
         substitute(
             text,
@@ -288,9 +238,6 @@ mod tests {
         )
     }
 
-    /// The driver's return flag ([`substitute_checked`]) — `true` only when no token failed. The
-    /// chat seam branches on it (drop / defer / show raw), so a wrong flag silently loses chat lines
-    /// rather than merely showing a stray `$`. Decision 0759.
     #[test]
     fn the_return_flag_reports_whether_any_token_failed() {
         let s = subject(0);
@@ -300,7 +247,6 @@ mod tests {
             states: &states,
         };
 
-        // No `$` at all, and a token that resolves: clean.
         assert_eq!(
             substitute_checked("plain text", &ctx(None)),
             ("plain text".to_string(), true)
@@ -309,13 +255,11 @@ mod tests {
             substitute_checked("hi $N", &ctx(Some(&s))),
             ("hi Thrall".to_string(), true)
         );
-        // No subject: the person-token fails, the `$` comes back, flag false.
         assert_eq!(
             substitute_checked("hi $N", &ctx(None)),
             ("hi $N".to_string(), false)
         );
-        // Outside the accepted set: fails even WITH a subject — the case the chat path drops
-        // outright rather than deferring, because no name query can fix it.
+        // Outside the set: fails even with a subject.
         assert_eq!(
             substitute_checked("hi $X", &ctx(Some(&s))),
             ("hi $X".to_string(), false)
@@ -340,7 +284,6 @@ mod tests {
         let s = subject(0);
         assert_eq!(expand("A $C of $R", Some(&s)), "A Priest of Night Elf");
         assert_eq!(expand("a $c of $r", Some(&s)), "a priest of night elf");
-        // An id outside the table emits nothing (where the reference faults).
         let unknown = Subject {
             class: 6,
             ..subject(0)
@@ -358,14 +301,11 @@ mod tests {
             expand("Well met, $Glad:lass;.", Some(&subject(1))),
             "Well met, lass."
         );
-        // Not "1 = female": zero picks the first arm and everything else the second.
         assert_eq!(expand("$Glad:lass;", Some(&subject(2))), "lass");
-        // The spaces after the marker, after the `:`, and at each arm's end are dropped.
         assert_eq!(
             expand("Well met, $G lad : lass ;.", Some(&subject(1))),
             "Well met, lass."
         );
-        // `$T` has no rank title to find, so it falls back to this same branch, un-lower-cased.
         assert_eq!(expand("$tLad:Lass;", Some(&subject(0))), "Lad");
     }
 
@@ -382,13 +322,10 @@ mod tests {
         let s = subject(0);
         assert_eq!(expand("$2077w gathered", Some(&s)), "0 gathered");
         assert_eq!(expand("$2077e gathered", Some(&s)), "0 gathered");
-        // A bare `$w` is key 0 — a miss like any other.
+        // A bare `$w` is key 0.
         assert_eq!(expand("$w", Some(&s)), "0");
     }
 
-    /// The point of the table: once a zone's states land, `$<n>w` renders the value rather than the
-    /// standing `"0"`. `$<n>e` reads the SAME table at the negated key, so the two tokens with the
-    /// same digits are different lookups — and a value is rendered `%d`, sign and all.
     #[test]
     fn world_state_tokens_render_received_values() {
         let s = subject(0);
@@ -411,7 +348,7 @@ mod tests {
         assert_eq!(filled("$2077e gathered"), "3 gathered");
         assert_eq!(filled("$2264w"), "-5", "rendered %d, not %u");
         assert_eq!(filled("$9999w"), "0", "an id the zone never sent");
-        // Case is not the output switch here — unlike `$R`/`$C`, `W` and `w` are one token.
+        // `W` and `w` are one token.
         assert_eq!(filled("$2077W"), "12");
     }
 
@@ -419,7 +356,6 @@ mod tests {
     fn unaccepted_tokens_keep_the_dollar() {
         let s = subject(0);
         assert_eq!(expand("A $X here", Some(&s)), "A $X here");
-        // The digits are consumed before the letter is judged, so they are lost with it.
         assert_eq!(expand("A $5X here", Some(&s)), "A $X here");
         assert_eq!(expand("Cost: 5$", Some(&s)), "Cost: 5$");
     }
@@ -428,7 +364,6 @@ mod tests {
     fn no_subject_leaves_the_text_literal() {
         assert_eq!(expand("Greetings $N", None), "Greetings $N");
         assert_eq!(expand("$Glad:lass; $C", None), "$Glad:lass; $C");
-        // `$B` and the world-state tokens need no subject.
         assert_eq!(expand("Hail,$Bfriend $w", None), "Hail,\nfriend 0");
     }
 }
diff --git a/crates/benilla-app/src/opaque2d.rs b/crates/benilla-app/src/opaque2d.rs
index 433c4c84..4df91181 100644
--- a/crates/benilla-app/src/opaque2d.rs
+++ b/crates/benilla-app/src/opaque2d.rs
@@ -1,22 +1,8 @@
-//! **The 2D opaque pass, skipped when it has nothing to draw** (decision 2225).
-//!
-//! bevy's `MainOpaquePass2dNode` opens a command encoder and a render pass whether or not its two
-//! phases hold an item, and on every camera of ours they never do: each player-UI quad is in the
-//! transparent phase (`AlphaMode2d::Blend`, decision 0254), Bevy UI paints through its own node,
-//! egui through its own. 2197 parked the pass as "price it on an immediate-mode GPU"; 2205 priced
-//! its GPU at zero; the crowd profile of 2225 priced its CPU at ~0.2 ms a frame, parked, traced —
-//! an encoder and a pass that wgpu sizes and clears its usage trackers for, empty or not (the
-//! residency term `perf::gpu`'s census names).
-//!
-//! The pass exists in bevy for the clear, and the clear does not need it: whichever pass touches
-//! the view target first clears it (`ColorAttachment`'s first-call semantics, the same rule
-//! `static_gx` and the FFX combine already lean on), and bevy's transparent 2D node opens its pass
-//! unconditionally for exactly that reason. So an empty opaque pass has nothing to do that the
-//! pass after it does not.
-//!
-//! This is bevy's node with one early return, registered under bevy's own label:
-//! `RenderGraph::add_node` is a map insert, so the later registration replaces the node and the
-//! graph's edges — keyed by label — carry over untouched.
+//! Bevy's 2D opaque pass, skipped when both its phases are empty, which on our cameras they always
+//! are (UI quads are transparent, Bevy UI and egui draw in their own nodes). The first pass to
+//! touch the view target clears it, so the transparent pass after it takes the clear.
+//! Registered under Bevy's own label: `add_node` is a map insert, so it replaces the node and the
+//! edges keyed by label carry over.
 
 use bevy::core_pipeline::core_2d::graph::{Core2d, Node2d};
 use bevy::core_pipeline::core_2d::{AlphaMask2d, Opaque2d};
@@ -64,9 +50,8 @@ impl ViewNode for SkipEmptyOpaque2dNode {
         ) else {
             return Ok(());
         };
-        // The one line bevy's node does not have. Nothing to draw means nothing to encode: the
-        // transparent pass that follows opens its own pass unconditionally and takes the target's
-        // first-call clear.
+        // The one line Bevy's node lacks: the transparent pass that follows opens unconditionally
+        // and takes the target's first-call clear.
         if opaque_phase.is_empty() && alpha_mask_phase.is_empty() {
             return Ok(());
         }
@@ -110,9 +95,8 @@ impl ViewNode for SkipEmptyOpaque2dNode {
     }
 }
 
-/// Replaces bevy's 2D opaque node under its own label. Added by [`crate::ui_pass::PlayerUiPlugin`],
-/// which owns every camera that runs the `Core2d` graph, after `DefaultPlugins` has registered the
-/// node it replaces.
+/// Replaces Bevy's 2D opaque node; must be added after `DefaultPlugins` registers the original
+/// (by [`crate::ui_pass::PlayerUiPlugin`]).
 pub(crate) struct SkipEmptyOpaque2dPlugin;
 
 impl Plugin for SkipEmptyOpaque2dPlugin {
diff --git a/crates/benilla-app/src/pending_item_ops.rs b/crates/benilla-app/src/pending_item_ops.rs
index 97ff1448..fd3176d7 100644
--- a/crates/benilla-app/src/pending_item_ops.rs
+++ b/crates/benilla-app/src/pending_item_ops.rs
@@ -1,48 +1,30 @@
-//! The client-side pending-operation lock (decision 0216 §4, byte-verified by decision 0218 §3 —
-//! `item+0x314` bit0: "the send locks both ends", cleared by the resolving field update or a
-//! non-zero `SMSG_INVENTORY_CHANGE_FAILURE"). [`PendingItemOps`] is a Resource wrapping plain
-//! bookkeeping — every method is engine-free (no ECS/Bevy types past the `#[derive(Resource)]`
-//! marker), so the whole lifecycle is unit-tested below without a `World`. The app's per-frame
-//! container feed (`ui_items::feed_containers`) reads it into each pushed
-//! `ContainerSlot::locked`, and the move/split/destroy drains (`ui_items::drain_container_moves`/
-//! `drain_container_destroys`) are the only writers of [`PendingItemOps::add`].
+//! The client-side pending-operation lock, the reference's `item+0x314` bit 0: a send locks both
+//! ends, and the resolving field update or a nonzero `SMSG_INVENTORY_CHANGE_FAILURE` clears it.
+//! Engine-free bookkeeping; `ui_items::feed_containers` reads it into `ContainerSlot::locked`.
 //!
-//! **Baseline is `(guid, stack count)`, not guid alone** — a deliberate widening of 0218's literal
-//! "the resolving field-update watcher" (`0x5ddcf0`, cited generically over "the inventory-slot
-//! field update", not specifically the guid field). Guid-only tracking has a real stuck-lock gap:
-//! a partial split-merge (`SplitContainerItem` onto an existing same-item stack — already a live,
-//! tested path, `container.rs::pickup_place_onto_same_item_merges_and_clears`) and a partial
-//! destroy (`DeleteCursorItem` off a split carry) both settle by changing a slot's **stack count**
-//! while its guid stays exactly the same (the source/destination item is the same object,
-//! narrower/wider). Watching count too closes that gap without weakening anything guid-only
-//! tracking already caught.
+//! The reference keys the lock on the item and its watcher (`0x5ddcf0`) clears on a slot's guid
+//! change alone; here the baseline is `(guid, stack count)` per slot, since a partial split-merge
+//! or a partial destroy settles by changing a slot's count while its guid stays the same.
 
 use bevy::prelude::Resource;
 
-/// One outstanding op's slot set: live-API `(bag, slot)` → the `(item guid, stack count)` that sat
-/// there when the op was sent — named so clippy doesn't read the nested tuple as "very complex"
-/// (the `PendingItemOps` struct doc explains the shape).
+/// One outstanding op: `(bag, slot)` to the `(item guid, stack count)` there at send time.
 type PendingEntry = Vec<((i64, u32), (u64, u32))>;
 
-/// The client-side pending-operation lock. Each outstanding op records the live-API `(bag, slot)`
-/// positions it touches, paired with the `(item guid, stack count)` that sat there when the op was
-/// **sent** (`(0, 0)` = the slot was empty then — a split placed onto an empty destination, say).
-/// A move/split covers both its source and destination ("a send locks both ends"); a destroy
-/// covers only the one slot it touches (there is no displaced item).
+/// The pending-operation lock: per op, the live-API `(bag, slot)`s it touches with their
+/// `(item guid, stack count)` at send time (`(0, 0)` for an empty slot). A move or split covers
+/// both ends, a destroy its one slot.
 #[derive(Debug, Default, Resource)]
 pub(crate) struct PendingItemOps {
     entries: Vec<PendingEntry>,
-    /// One step per change to [`Self::entries`] — the gate input a feed needs to notice that a
-    /// lock **cleared**. `!is_empty()` alone cannot: the frame an op resolves, the set goes empty
-    /// and every "is anything in flight?" gate closes, so a feed that had pushed `locked: true`
-    /// never runs again to correct it. That is the stuck-dark bank bag button of 1771.
+    /// Steps on every change to [`Self::entries`], so a feed notices a lock clearing; the frame
+    /// the set empties, an `!is_empty()` gate alone would never run again to unlock.
     epoch: u64,
 }
 
 impl PendingItemOps {
-    /// Record one outstanding op covering `slots` — `(bag, slot, guid_at_send_time,
-    /// count_at_send_time)` quadruples. Called once per outbound move/split/destroy send,
-    /// covering every slot that send touches.
+    /// Records one outstanding op over `(bag, slot, guid at send, count at send)` quadruples,
+    /// once per move, split or destroy send.
     pub(crate) fn add(&mut self, slots: impl IntoIterator<Item = (i64, u32, u64, u32)>) {
         self.epoch += 1;
         self.entries.push(
@@ -53,34 +35,22 @@ impl PendingItemOps {
         );
     }
 
-    /// No outstanding ops at all — the container feed's gate reads this (decision 1439): while
-    /// anything is in flight the resolving walk must run every frame, and once nothing is, the
-    /// last resolve's own change tick already covered the final unlock.
     pub(crate) fn is_empty(&self) -> bool {
         self.entries.is_empty()
     }
 
-    /// [`Self::epoch`] — the "did the lock set move?" counter a feed's gate watches beside
-    /// `!is_empty()`.
     pub(crate) fn epoch(&self) -> u64 {
         self.epoch
     }
 
-    /// Whether `(bag, slot)` is covered by any outstanding op — the container feed reads this
-    /// building each pushed `ContainerSlot::locked`.
     pub(crate) fn contains(&self, bag: i64, slot: u32) -> bool {
         self.entries
             .iter()
             .any(|e| e.iter().any(|&(pos, _)| pos == (bag, slot)))
     }
 
-    /// The resolving clear (0218: "the field-update watcher"): an entry clears the moment ANY of
-    /// its slots' CURRENT `(guid, count)` (`current` — the same descriptor walk the container feed
-    /// already does) differs from what was recorded at send time (see the module doc for why count
-    /// joins guid). The WHOLE entry clears together (every slot it covered unlocks at once) rather
-    /// than slot-by-slot: a swap's two mutations land in the same field-update batch in practice,
-    /// so waiting for either is the simplest correct read. Returns the deduplicated `(bag, slot)`
-    /// pairs that just unlocked.
+    /// The resolving clear (the field-update watcher, `0x5ddcf0`): a whole entry clears once any
+    /// of its slots' current `(guid, count)` differs from its baseline. Returns the unlocked slots.
     pub(crate) fn resolve(&mut self, current: impl Fn(i64, u32) -> (u64, u32)) -> Vec<(i64, u32)> {
         let mut unlocked = Vec::new();
         self.entries.retain(|entry| {
@@ -100,15 +70,10 @@ impl PendingItemOps {
         unlocked
     }
 
-    /// `SMSG_INVENTORY_CHANGE_FAILURE` (reason ≠ 0 always — reason 0 never reaches
-    /// `benilla_protocol::SessionEvent::InventoryFailure` in the first place, filtered at
-    /// `benilla_protocol::events`'s `if reason != 0` guard, matching 0218's "reason-0 clears
-    /// nothing"): clear every entry naming `item_guid`, or — when the guid is 0 or matches no
-    /// outstanding entry — clear EVERYTHING. INTERIM: the failure event names one item, not the
-    /// operation, so a guid this bookkeeping never recorded (or the ack's own 0) can't be
-    /// attributed to a specific entry; moves are serial in practice, so a blanket clear is the
-    /// safe over-approximation rather than a slot stuck dark forever. Returns the deduplicated
-    /// `(bag, slot)` pairs that unlocked.
+    /// A nonzero-reason `SMSG_INVENTORY_CHANGE_FAILURE` (reason 0 is filtered upstream and clears
+    /// nothing): clears the entries naming `item_guid`, or every entry when the guid is 0 or
+    /// unrecorded, since the failure names an item, not the operation. The reference unlocks both
+    /// guids the packet carries (`0x5e3ac0`, `0x5e3ad3`). Returns the unlocked slots.
     pub(crate) fn clear_by_failure(&mut self, item_guid: u64) -> Vec<(i64, u32)> {
         let matched = item_guid != 0
             && self
@@ -121,13 +86,10 @@ impl PendingItemOps {
         self.clear_by_guid(item_guid)
     }
 
-    /// **`UnlockItem 0x495420`** — clear every entry naming `item_guid`, and nothing else: a guid
-    /// no entry recorded (a corpse, a chest, 0) unlocks nothing, exactly as the reference's
-    /// resolve-as-ITEM (typemask 2) finds nothing to clear for a non-item. The loot close is the
-    /// caller that needs it: an opened lockbox/clam is locked at the `CMSG_OPEN_ITEM` send (0916)
-    /// and, closed with loot left, never changes its slot — so neither [`Self::resolve`] nor a
-    /// failure ever clears it (`0x48f200` @ `48f299`). Returns the
-    /// deduplicated `(bag, slot)` pairs that unlocked.
+    /// `UnlockItem` (`0x495420`): clears the entries naming `item_guid`; a non-item guid or 0
+    /// clears nothing, as the reference's resolve-as-item finds nothing. The loot close calls it
+    /// (`0x48f200` at `0x48f299`): an opened lockbox closed with loot left never changes its slot.
+    /// Returns the unlocked slots.
     pub(crate) fn clear_by_guid(&mut self, item_guid: u64) -> Vec<(i64, u32)> {
         let mut unlocked = Vec::new();
         if item_guid == 0 {
@@ -148,18 +110,14 @@ impl PendingItemOps {
         unlocked
     }
 
-    /// The session end: drop every outstanding entry and report nothing. The lock is item-object
-    /// state in the reference (`item+0x314`), and those objects do not outlive the session; an op
-    /// still in flight when the socket died never gets the field update or failure that would
-    /// settle it, so without this its slots stayed locked for the whole next session. The epoch
-    /// steps so a feed that pushed `locked: true` runs once more to correct it.
+    /// The session end: drops every entry, as the reference's item objects (`item+0x314`) do not
+    /// outlive the session. The epoch steps so a feed corrects a pushed `locked: true`.
     pub(crate) fn clear_session(&mut self) {
         self.entries.clear();
         self.epoch += 1;
     }
 
-    /// Drop every outstanding entry, unconditionally — [`Self::clear_by_failure`]'s
-    /// unmatched/zero fallback.
+    /// Drops every entry: [`Self::clear_by_failure`]'s fallback.
     fn clear_all(&mut self) -> Vec<(i64, u32)> {
         let mut unlocked: Vec<(i64, u32)> = self
             .entries
@@ -175,20 +133,9 @@ impl PendingItemOps {
     }
 }
 
-/// `(bag, slot)` pairs whose app-lock cleared this frame, from ANY clear: the server failure
-/// (`ui_items::net::inventory_failure`, which owns the wire event but has no `UiScript` to
-/// fire `ITEM_LOCK_CHANGED` through), the loot close's item unlock (`ui_loot::net`, the same
-/// shape) and the resolving field-update watch
-/// (`ui_items::feed::resolve_item_locks`, which runs ahead of every feed so that no feed can push
-/// a `locked` the clear has already invalidated). `feed_containers` drains this and fires — the
-/// exact shape `ui_items::EquipErrors` already uses for the same reason.
-///
-/// **Why the resolve is not just done inside the feed that fires** (1771): `feed_char` owns the
-/// doll's and the bank bags' `locked`, and is ordered `.before(feed_containers)` for an unrelated
-/// reason (Bagnon's `BAG_UPDATE` handlers read the inventory surface). With the resolve living in
-/// `feed_containers`, `feed_char` read a lock set that was about to be cleared *later in the same
-/// frame*, pushed `locked: true`, and then never ran again — leaving a bank bag button greyed
-/// until the window was reopened.
+/// Slots whose lock cleared this frame, from any clear; `feed_containers` drains it and fires
+/// `ITEM_LOCK_CHANGED`. `ui_items::feed::resolve_item_locks` must run ahead of every feed, since
+/// `feed_char` runs before `feed_containers` and would push a lock cleared later that frame.
 #[derive(Resource, Default)]
 pub(crate) struct LockTransitions(pub Vec<(i64, u32)>);
 
@@ -223,8 +170,7 @@ mod tests {
             .is_empty());
         assert!(p.contains(0, 1) && p.contains(0, 5));
 
-        // The destination's guid now differs (the swap/split landed) — the WHOLE entry clears,
-        // both slots unlock together even though the source's baseline didn't move this check.
+        // The destination changed: both slots unlock together.
         let unlocked = p.resolve(|bag, slot| {
             if (bag, slot) == (0, 1) {
                 (100, 5)
@@ -236,15 +182,10 @@ mod tests {
         assert!(!p.contains(0, 1) && !p.contains(0, 5));
     }
 
-    /// The gap guid-only tracking would miss (the module doc): a partial split-merge leaves BOTH
-    /// ends' guids unchanged — only their stack counts move. Count must join guid in the baseline
-    /// or this op would stay locked forever.
     #[test]
     fn resolve_catches_a_same_guid_stack_count_change() {
         let mut p = PendingItemOps::default();
-        // Source: item 100, was a 5-stack; destination: item 200 (same item id, different guid —
-        // impossible in the real client, but the bookkeeping only ever compares within one slot),
-        // was a 3-stack. A partial split-merge leaves both guids exactly where they were.
+        // Source item 100 was a 5-stack, destination item 200 a 3-stack.
         p.add([(0, 1, 100, 5), (0, 7, 200, 3)]);
         assert!(p
             .resolve(|bag, slot| if (bag, slot) == (0, 1) {
@@ -254,8 +195,7 @@ mod tests {
             })
             .is_empty());
 
-        // The merge landed: source dropped to a 2-stack (guid unchanged), destination rose to 6
-        // (guid unchanged) — a guid-only comparison would see no change at all.
+        // The merge landed: 2 and 6, both guids unchanged.
         let unlocked = p.resolve(|bag, slot| {
             if (bag, slot) == (0, 1) {
                 (100, 2)
@@ -278,8 +218,6 @@ mod tests {
         assert!(p.contains(1, 3), "op B untouched — a different guid");
     }
 
-    /// Unlike the failure clear, the guid clear has no clear-all fallback: an unmatched or zero
-    /// guid (a corpse's release) must leave every other lock standing.
     #[test]
     fn clear_by_guid_clears_only_the_named_item() {
         let mut p = PendingItemOps::default();
diff --git a/crates/benilla-app/src/perf/blend_check.rs b/crates/benilla-app/src/perf/blend_check.rs
index 1209661a..f685d3f1 100644
--- a/crates/benilla-app/src/perf/blend_check.rs
+++ b/crates/benilla-app/src/perf/blend_check.rs
@@ -1,24 +1,16 @@
-//! **The additive blend-state check** — does every transparent draw bind the blend state its
+//! The additive blend-state check: does every transparent draw bind the blend state its
 //! material asked for?
 //!
-//! An additive glow card's look is two halves that must agree: the material's marker word
-//! (`clutter_fade.z` bit 2) tells `wow_model.wgsl` to fold the radial alpha into the colour,
-//! and the SAME marker, through `WowModelExt::specialize`, gives the pipeline its pure
-//! `(ONE, ONE)` add. A draw that pairs the folded colour with an alpha-blend pipeline draws a
-//! dim skirt; one that pairs an unfolded colour with the pure add draws the texture unweighted
-//! — a hard, saturated disc where a soft halo should be. Decision 0071 measured that class on
-//! macOS/Metal with the extra UI camera on the window (some draws intermittently bound a
-//! blend-enabled pipeline) and immunised *opaque* batches with an alpha pin; glow cards were
-//! left alone. The director's strong-halo report reads a correct main-world material on a
-//! card whose draw is wrong, which is exactly the half this check reads.
+//! An additive glow card needs two halves to agree: the material's marker (`clutter_fade.z`
+//! bit 2) makes `wow_model.wgsl` fold the radial alpha into the colour, and the same marker,
+//! through `WowModelExt::specialize`, gives the pipeline its pure `(ONE, ONE)` add. A folded
+//! colour on an alpha-blend pipeline draws a dim skirt; an unfolded colour on the pure add draws
+//! a hard, saturated disc.
 //!
-//! Render world, `Cleanup`, every frame, whatever the env: for each `Transparent3d` item whose
-//! entity binds one of our materials, compare the pipeline descriptor's colour blend against
-//! the material's additive marker. Mismatches are counted into a main-world-readable atomic
-//! (the perf pill prints them red the frame they happen, so the director sees the count beside
-//! the halo), and the first few of each second are logged with the entity, the material and
-//! the blend state actually bound — the number and the names the fix will be judged against.
-//! Cost: one hash probe and one descriptor read per transparent item, a few hundred a frame.
+//! Render world, `Cleanup`, every frame: each `Transparent3d` item bound to one of our materials
+//! has its pipeline's colour blend compared with the material's marker. Mismatches are counted
+//! into an atomic the pill prints red, and runs that outlast the specialization tick are logged
+//! with the entity, the material and the blend state bound.
 
 use std::collections::{HashMap, HashSet};
 use std::sync::atomic::{AtomicU64, Ordering};
@@ -35,45 +27,38 @@ use bevy::render::{Render, RenderApp, RenderSystems};
 
 use benilla_assets::materials::WowModelMaterial;
 
-/// The realized materials whose marker word says ADDITIVE, by asset id — what a draw of theirs
-/// must bind `(ONE, ONE)` for. Maintained from the asset events in the main world (a realized
-/// material is Added, an edited one Modified), extracted as an `Arc` clone each frame.
+/// The realized materials whose marker says additive, so their draws must bind `(ONE, ONE)`;
+/// kept from the main world's asset events and extracted as an `Arc` clone each frame.
 #[derive(Resource, Clone, Default, ExtractResource)]
 pub(crate) struct AdditiveMaterials(pub(crate) Arc<HashSet<AssetId<WowModelMaterial>>>);
 
 /// Draws this frame whose bound blend state contradicted their material's additive marker.
-/// Written by the render world's [`check_blend_states`], read by the pill and the probe.
 #[derive(Resource, Clone)]
 pub(crate) struct BlendMismatchShared(pub(crate) Arc<AtomicU64>);
 
-/// How many consecutive frames a mismatch must last before it is worth a warning — one frame is
-/// the pipeline specialization catching up with a material swap, which a 2026-09-06 login
-/// confirmed by ending four such runs at exactly one frame.
+/// Consecutive frames a mismatch must last to warn: a one-frame run is the pipeline
+/// specialization catching up with a material swap.
 const REPORT_AFTER_FRAMES: u32 = 2;
 
-/// One mismatching draw, tracked across frames so a transient (one frame after a material
-/// swap, the specialization tick catching up) reads differently from a PERSISTING one — the
-/// director's strong halo holds until a relog, and that difference is the finding.
+/// One mismatching draw, tracked across frames so a transient reads differently from a
+/// persisting one.
 pub(crate) struct Mismatch {
     pub(crate) material: AssetId<WowModelMaterial>,
-    /// Whether the bound pipeline was the pure add (so the material was NOT additive), or the
-    /// reverse.
+    /// Whether the bound pipeline was the pure add (so the material was not additive).
     pub(crate) bound_add: bool,
     /// Consecutive frames this entity has mismatched.
     pub(crate) frames: u32,
-    /// The `frames` count the main world last reported at, so each entry logs on its first
-    /// frame and then once every couple of seconds while it persists.
+    /// The `frames` count the main world last reported at.
     pub(crate) reported: u32,
-    /// The draw has left the transparent phase — the run is over, and its LENGTH is the fact the
-    /// log could not previously state. Kept one more pass so the main world can narrate the end
-    /// before the entry is dropped.
+    /// The draw has left the transparent phase; kept one more pass so the main world can report
+    /// the run's length.
     pub(crate) ended: bool,
-    /// …and narrated exactly once.
+    /// The end has been reported.
     pub(crate) end_reported: bool,
 }
 
-/// The live mismatch table, by main-world entity — kept by the render world, read and
-/// narrated by [`report_blend_mismatches`] with the names only the main world knows.
+/// The live mismatch table by main-world entity, kept by the render world and reported by
+/// [`report_blend_mismatches`] with the names only the main world knows.
 #[derive(Resource, Clone, Default)]
 pub(crate) struct BlendMismatchLive(pub(crate) Arc<Mutex<HashMap<Entity, Mismatch>>>);
 
@@ -110,7 +95,7 @@ fn track_additive_materials(
     }
 }
 
-/// Render world, `Cleanup`: the check itself (module docs).
+/// Render world, `Cleanup`: the check itself.
 fn check_blend_states(
     additive: Res<AdditiveMaterials>,
     shared: Res<BlendMismatchShared>,
@@ -129,7 +114,7 @@ fn check_blend_states(
                     continue;
                 };
                 let Ok(id) = inst.asset_id.try_typed::<WowModelMaterial>() else {
-                    continue; // not one of ours (the sky dome's StandardMaterial, …)
+                    continue; // not one of ours (the sky dome's StandardMaterial)
                 };
                 let expect_add = additive.0.contains(&id);
                 let blend = pipeline_cache
@@ -159,24 +144,19 @@ fn check_blend_states(
                     e.material = id;
                     e.bound_add = is_add;
                     e.frames += 1;
-                    e.ended = false; // back in the phase — the run is still running
+                    e.ended = false; // back in the phase: the run continues
                 }
             }
         }
     }
-    // **A run's end is reported, not dropped.** This used to be a bare `retain`, so an entry
-    // vanished the moment its entity left the transparent phase — despawned, culled, hidden, or
-    // genuinely fixed — and the run's LENGTH went with it. That was half of why a mismatch line
-    // was unanswerable: every run of 1..119 frames prints "1 frame(s)" (the report fires on
-    // frame 1 and then only on multiples of 120), so a two-second visible defect and a
-    // single-frame specialization hiccup were the same text. Entries are held one extra pass
-    // marked `ended`, which is what lets the main world state the length it actually ran.
+    // An entry that left the phase is held one extra pass marked `ended`, so its run's length
+    // can be reported.
     table.retain(|e, m| {
         if seen.contains(e) {
             return true;
         }
         if m.ended {
-            return false; // its end has been narrated — now it can go
+            return false; // its end has been reported
         }
         m.ended = true;
         true
@@ -184,10 +164,9 @@ fn check_blend_states(
     shared.0.store(mismatches, Ordering::Relaxed);
 }
 
-/// Main world, `PostUpdate`: narrate the live table with the names the render world lacks —
-/// the object the entity is a part of, and the texture the material binds — on an entry's
-/// first frame and then every two seconds while it persists. A one-frame entry is the
-/// specialization tick catching up with a material swap; a persisting one is the defect.
+/// Main world, `PostUpdate`: report the live table with the object and texture names the render
+/// world lacks, once a run reaches [`REPORT_AFTER_FRAMES`], every 120 frames after, and at its
+/// end.
 fn report_blend_mismatches(
     live: Res<BlendMismatchLive>,
     objects: Query<&benilla_world::interact::WorldObject>,
@@ -196,12 +175,7 @@ fn report_blend_mismatches(
 ) {
     let mut table = live.0.lock().unwrap();
     for (entity, m) in table.iter_mut() {
-        // **A one-frame run is the specialization tick, and is no longer shouted about.** The
-        // module always said so; it warned on frame 1 anyway, because nothing could tell a
-        // one-frame run from a 119-frame one. Now something can, and a real login settled it:
-        // four entries reported "1 frame(s) so far" and "ran 1 frame(s), now clear" 26 ms later
-        // (2026-09-06). So the warn waits for a run to SURVIVE the tick, and a run that does not
-        // is recorded at debug rather than as a warning about a defect nobody has.
+        // A run that ends without surviving the specialization tick logs at debug, not warn.
         let ending = m.ended && !m.end_reported;
         if ending {
             m.end_reported = true;
@@ -243,16 +217,11 @@ fn report_blend_mismatches(
             } else {
                 "alpha-blend"
             },
-            // "1 frame(s)" was printed for every run from 1 to 119 frames long, so the line could
-            // not distinguish a specialization hiccup from a two-second visible defect. An ended
-            // run now states the length it actually ran.
             if ending {
                 format!("ran {} frame(s), now clear", m.frames)
             } else {
                 format!("{} frame(s) so far", m.frames)
             },
-            // Only a run still going can be persisting; an ended one has already said how long
-            // it lasted, and "now clear PERSISTING" is a contradiction.
             if !ending && m.frames > 1 {
                 " PERSISTING"
             } else {
@@ -269,11 +238,9 @@ pub(crate) fn plugin(app: &mut App) {
         .insert_resource(BlendMismatchShared(shared.clone()))
         .insert_resource(live.clone())
         .add_plugins(ExtractResourcePlugin::<AdditiveMaterials>::default())
-        // After the asset event flush, like bevy's own `check_entities_needing_specialization`:
-        // a material realized this frame is extracted, prepared and drawn this frame, and a
-        // tracker that reads its `Added` a frame late reports every first draw of an additive
-        // material as a mismatch — the rig's whole first harvest (glue sword glows, weapon
-        // sheens, the lamppost card), all one frame, all false.
+        // After the asset event flush, like bevy's `check_entities_needing_specialization`: a
+        // material realized this frame is drawn this frame, and a late `Added` read reports
+        // its first draw as a false mismatch.
         .add_systems(
             PostUpdate,
             (
diff --git a/crates/benilla-app/src/perf/census.rs b/crates/benilla-app/src/perf/census.rs
index f1ffc3c0..667218de 100644
--- a/crates/benilla-app/src/perf/census.rs
+++ b/crates/benilla-app/src/perf/census.rs
@@ -1,28 +1,11 @@
-//! Env-gated one-shot and per-second counters: the premise-checkers a sizing question needs before
-//! anyone designs a fix for it.
+//! Env-gated one-shot and per-second counters that check a performance premise before a fix.
 
 use bevy::prelude::*;
 
-/// `WOW_CPU_CENSUS=<at>:<secs>` — the per-thread CPU census (macOS): where does the pill's
-/// cpu-ms actually go, thread by thread, summing **exactly** to the process total?
-///
-/// Two snapshots bracket a window: at each, `getrusage(RUSAGE_SELF)` (the pill's own clock,
-/// [`super::clock::process_cpu_secs`]) and then every live thread's cumulative CPU via
-/// `proc_pidinfo(PROC_PIDLISTTHREADS / PROC_PIDTHREADINFO)`. The report prints each thread's
-/// delta over the window in ms/frame, then the **residual** = process delta − Σ live-thread
-/// deltas, which is exactly the CPU of threads that exited inside the window (plus the
-/// inter-read skew of the sweep itself). Nothing is modeled: every row is a measured delta and
-/// the rows plus the residual reproduce the process total by construction.
-///
-/// Facts this rests on, pinned empirically on this machine (2026-08-20, threadcpu.c probe)
-/// before this was written:
-/// - `pth_user_time`/`pth_system_time` are **nanoseconds** (a 200 ms calibrated burn read
-///   196.6 ms; the mach-timebase interpretation read 31.8× over) — *not* mach ticks, unlike
-///   `rusage_info`'s `ri_user_time`.
-/// - live-thread sums + exited-thread time = `getrusage` total to 0.05 ms over a ~1 s burn
-///   (a thread that burned 250 ms and exited was absent from the list and present in the
-///   residual at exactly 250.0 ms).
-/// - `PROC_PIDLISTTHREADS = 6` (verified in the SDK's `sys/proc_info.h`; libc lacks the const).
+/// `WOW_CPU_CENSUS=<at>:<secs>`: the pill's cpu-ms over a window, thread by thread (macOS). Two
+/// snapshots of the process clock and every live thread's CPU bracket the window; the residual,
+/// process delta minus the live-thread deltas, is the CPU of threads that exited in the window.
+/// `pth_user_time`/`pth_system_time` are nanoseconds, not mach ticks.
 #[cfg(target_os = "macos")]
 pub(super) mod cpu_census {
     use std::collections::HashMap;
@@ -32,13 +15,11 @@ pub(super) mod cpu_census {
 
     use crate::perf::clock::process_cpu_secs;
 
-    /// `sys/proc_info.h`; not in the libc crate (its sibling `PROC_PIDTHREADINFO = 5` is).
+    /// `sys/proc_info.h`; not in the libc crate.
     const PROC_PIDLISTTHREADS: libc::c_int = 6;
 
-    /// One cumulative reading per live thread: `tid → (name, user_ns, system_ns)`. User and
-    /// system are kept apart on purpose: real work is user time, while a thread whose CPU is
-    /// mostly *system* time is burning it in the kernel — park/wake churn, semaphores, mach
-    /// calls — which points at the scheduler/driver seam rather than at any system's body.
+    /// One cumulative reading per live thread: `tid → (name, user_ns, system_ns)`; mostly-system
+    /// time points at kernel churn (park/wake, semaphores) rather than a system's body.
     fn thread_snapshot() -> HashMap<u64, (String, u64, u64)> {
         let pid = std::process::id() as libc::c_int;
         let mut tids = [0u64; 512];
@@ -93,8 +74,7 @@ pub(super) mod cpu_census {
         threads: HashMap<u64, (String, u64, u64)>,
     }
 
-    /// Armed from the env at plugin build (on the main thread — which is how `main_tid` is
-    /// known without pinning the census system itself).
+    /// Armed from the env at plugin build, on the main thread, which is how `main_tid` is known.
     #[derive(Resource)]
     pub(in crate::perf) struct CpuCensus {
         at: f32,
@@ -102,9 +82,8 @@ pub(super) mod cpu_census {
         main_tid: u64,
         frames: u64,
         start: Option<Snap>,
-        /// Every thread seen by the once-a-second sweeps inside the window, with its **latest**
-        /// cumulative reading — so a thread that dies mid-window can still be *named* in the
-        /// residual report (its last reading is a lower bound on what it contributed).
+        /// Every thread the once-a-second sweeps saw in the window, with its latest reading, so
+        /// a thread that dies mid-window can be named in the residual.
         seen: HashMap<u64, (String, u64, u64)>,
         next_sweep: f32,
         done: bool,
@@ -116,7 +95,7 @@ pub(super) mod cpu_census {
             let v = std::env::var("WOW_CPU_CENSUS").ok()?;
             let (at, window) = v.split_once(':')?;
             let mut main_tid = 0u64;
-            // SAFETY: null pthread = the calling thread; writes one u64.
+            // SAFETY: a null pthread means the calling thread; writes one u64.
             unsafe { libc::pthread_threadid_np(0, &mut main_tid) };
             Some(Self {
                 at: at.parse().ok()?,
@@ -165,8 +144,7 @@ pub(super) mod cpu_census {
         let process_ms = (end_process - start.process_secs) * 1000.0;
         let per_frame = |ms: f64| ms / frames as f64;
 
-        // Per-thread deltas over the window. A thread born inside the window has no start
-        // reading — its full cumulative time is its delta (it was zero at birth).
+        // A thread born inside the window has no start reading; its whole time is its delta.
         let mut rows: Vec<(f64, f64, String)> = Vec::new(); // (user_ms, sys_ms, label)
         let mut live_sum_ms = 0.0f64;
         for (tid, (name, end_u, end_s)) in &end_threads {
@@ -200,7 +178,7 @@ pub(super) mod cpu_census {
         for (u, s, label) in &rows {
             let ms = u + s;
             if per_frame(ms) < 0.0005 {
-                continue; // folded into the "under" line below — still in the printed sum
+                continue; // folded into the "under" line below, still in the printed sum
             }
             eprintln!(
                 "[cpu-census] {:>9.4}  {:>8.4}  {:>8.4}  {:>5.1}%  {label}",
@@ -231,10 +209,8 @@ pub(super) mod cpu_census {
             per_frame(residual_ms),
             residual_ms / process_ms * 100.0
         );
-        // Name the churn: threads the per-second sweeps saw that are gone by the end snapshot.
-        // Their last cumulative reading minus their start reading (0 if born in-window) is a
-        // LOWER bound on what they contributed to the residual — they kept burning after the
-        // sweep that last saw them.
+        // Threads the sweeps saw that are gone by the end: their last reading is a lower bound
+        // on their share of the residual.
         let mut churned: HashMap<String, (usize, f64)> = HashMap::new();
         for (tid, (name, last_u, last_s)) in &census.seen {
             if end_threads.contains_key(tid) {
@@ -261,9 +237,7 @@ pub(super) mod cpu_census {
     }
 }
 
-/// `WOW_MESH_EVENTS=1`: per-second Mesh asset-event counts (see the plugin registration). The
-/// `sample` list names a few mutated asset ids so the writer can be found by grepping who holds
-/// that handle.
+/// `WOW_MESH_EVENTS=1`: per-second Mesh asset-event counts, with a few Modified ids.
 pub(super) fn count_mesh_events(
     mut events: MessageReader<bevy::asset::AssetEvent<Mesh>>,
     time: Res<Time>,
@@ -295,11 +269,9 @@ pub(super) fn count_mesh_events(
     }
 }
 
-/// `WOW_PART_CHURN=1`: per-second M2-part churn. `rm_frames` is the count of frames with ≥1
-/// `MeshMaterial3d<WowModelMaterial>` removal — exactly the predicate that promotes
-/// `classify_water_side` to its full walk (0930's twin-GC mark), so a regime reading ~60 here
-/// full-walks every frame. `mat_mod` counts `WowModelMaterial` asset Modified events — the
-/// global asset-changed tick that wakes every `AssetChanged` scan.
+/// `WOW_PART_CHURN=1`: per-second M2-part churn. `rm_frames` counts frames with a
+/// `MeshMaterial3d<WowModelMaterial>` removal, the predicate that sends `classify_water_side` to
+/// its full walk; `mat_mod` counts the material Modified events that wake `AssetChanged` scans.
 pub(super) fn count_part_churn(
     added: Query<(), Added<MeshMaterial3d<benilla_assets::materials::WowModelMaterial>>>,
     mut removed: RemovedComponents<MeshMaterial3d<benilla_assets::materials::WowModelMaterial>>,
@@ -329,10 +301,8 @@ pub(super) fn count_part_churn(
     }
 }
 
-/// `WOW_MESH_HOLDERS=1`: once a second, the set of mesh asset ids Modified in the last second
-/// and the component signature of every entity holding one — [`count_mesh_events`] counts and
-/// samples the ids, this names the writer by its holder's archetype (an id alone says nothing).
-/// Exclusive, like [`arch_census`], for the same reason: the signature needs the live archetype.
+/// `WOW_MESH_HOLDERS=1`: once a second, the archetype of each entity holding a mesh Modified in
+/// that second. Exclusive, since the signature needs the live archetype.
 pub(super) fn mesh_holders(
     world: &mut World,
     mut cursor: Local<Option<bevy::ecs::message::MessageCursor<bevy::asset::AssetEvent<Mesh>>>>,
@@ -390,13 +360,12 @@ pub(super) fn mesh_holders(
     ids.clear();
 }
 
-/// When the one-shot archetype census fires (seconds of `Time` elapsed; `f32::MAX` = spent).
+/// When the one-shot archetype census fires, in seconds of `Time`; `f32::MAX` once spent.
 #[derive(Resource)]
 pub(super) struct ArchCensusAt(pub(super) f32);
 
-/// The census itself (`WOW_ARCH_CENSUS`): exclusive, so it sees every archetype of the live
-/// world in one stop. Component paths are trimmed to their last two segments — the census reads
-/// as lanes, not as imports.
+/// `WOW_ARCH_CENSUS`: the entity total, then the 60 largest archetypes' entity counts and
+/// component sets.
 pub(super) fn arch_census(world: &mut World) {
     let due = world.resource::<ArchCensusAt>().0;
     if world.resource::<bevy::time::Time>().elapsed_secs() < due {
@@ -436,7 +405,7 @@ pub(super) fn arch_census(world: &mut World) {
 }
 
 /// `WOW_CAM_CHANGED=1`: per-second count of frames whose world-camera `Transform` /
-/// `GlobalTransform` registered as changed (see the plugin registration).
+/// `GlobalTransform` registered as changed.
 pub(super) fn count_camera_changes(
     t_changed: Query<(), (With<benilla_world::view::WorldCamera>, Changed<Transform>)>,
     g_changed: Query<
@@ -460,18 +429,7 @@ pub(super) fn count_camera_changes(
     }
 }
 
-/// `WOW_ROW_BLOAT=<n>` — the consolidation question's premise counter (the drastic-options
-/// census, 2026-08-17): once the world holds a real static model row, spawn `n` inert CLONES of
-/// it — same mesh handle, same material handle, same component shape — parked 10,000 yd
-/// underground so the frustum culls every one. The per-frame walks that scale with TOTAL rows
-/// (the visibility reset/sweep pair, the `AssetChanged` tick scans, `PreviousGlobalTransform`,
-/// `mark_dirty_trees`) pay for these rows exactly as for real ones, while the O(visible) half
-/// (specialize/queue/encode) never sees them — so an interleaved leg A/B (bloat off vs on) reads
-/// **d(cpu_ms)/d(rows)** directly. That derivative × the rows a mega-merge would delete is the
-/// honest ceiling of the consolidation option, measured before anyone builds it.
-/// (Measured the same night it was built: +30k rows = +1.33 cpu_ms at LBRS, ~44 ns/row/frame.)
-///
-/// `BloatSource` is one live static row's clonable component set, named for the lint.
+/// One live static row's clonable component set.
 type BloatSource<'w, 's> = Query<
     'w,
     's,
@@ -485,12 +443,15 @@ type BloatSource<'w, 's> = Query<
     Without<benilla_world::rig_palette::RigPart>,
 >;
 
+/// `WOW_ROW_BLOAT=<n>`: once a static model row exists, spawn `n` inert clones of it parked
+/// 10,000 yd underground, so the walks that scale with total rows pay for them and the
+/// per-visible work never sees them; a leg A/B reads d(cpu_ms)/d(rows).
 pub(super) fn row_bloat(mut commands: Commands, mut done: Local<bool>, source: BloatSource) {
     if *done {
         return;
     }
     let Some((mesh, mat, part, tag, aabb)) = source.iter().next() else {
-        return; // no static row streamed yet — try again next frame
+        return; // no static row streamed yet
     };
     let n: usize = std::env::var("WOW_ROW_BLOAT")
         .ok()
@@ -513,19 +474,10 @@ pub(super) fn row_bloat(mut commands: Commands, mut done: Local<bool>, source: B
     *done = true;
 }
 
-/// `WOW_MESH_TOUCH=<secs>` — from `secs` onward, mark ONE scratch [`Mesh`] asset modified every
-/// frame, and nothing else.
-///
-/// **The tax meter for [`bevy::asset::AssetChanged`].** Bevy 0.18's `AssetChanged<Mesh3d>` fast
-/// path is all-or-nothing: one `Assets<Mesh>` modification — of *any* mesh, including a `Mesh2d`
-/// UI batch no 3D row will ever reference — arms `mark_3d_meshes_as_changed_if_their_assets_changed`
-/// plus one `check_entities_needing_specialization::<M>` walk per registered material type, each
-/// over every `Mesh3d` row in the scene. 1361's per-slot skip gate and 1463's pan gate both exist
-/// to keep that disarmed, and both are gates on the *UI's* writes; this measures the price of a
-/// single arming with the UI's own work subtracted out, which no gate-side experiment can.
-///
-/// One run, two regimes, so the reading is a WITHIN-run paired delta: run-to-run cpu variance on
-/// this machine is ±1 ms (1157), which is the size of the thing being measured.
+/// `WOW_MESH_TOUCH=<secs>`: from `secs` on, mark one scratch [`Mesh`] modified every frame and
+/// nothing else, pricing one arming of [`bevy::asset::AssetChanged`] as a within-run delta. Any
+/// `Assets<Mesh>` modification, even a 2D UI mesh, arms a walk of every `Mesh3d` row per
+/// registered material type.
 pub(super) fn mesh_touch(
     mut meshes: ResMut<Assets<Mesh>>,
     time: Res<bevy::time::Time<bevy::time::Real>>,
@@ -541,8 +493,7 @@ pub(super) fn mesh_touch(
             bevy::asset::RenderAssetUsages::default(),
         ))
     });
-    // `get_mut` is the whole point: it writes `AssetEvent::Modified` for this id, which bumps the
-    // global changed tick every `AssetChanged` filter reads. The mesh itself stays empty.
+    // `get_mut` writes `AssetEvent::Modified`, bumping the tick every `AssetChanged` filter reads.
     let _ = meshes.get_mut(&*handle);
 }
 
@@ -550,23 +501,10 @@ pub(super) fn mesh_touch(
 #[derive(Resource)]
 pub(super) struct MeshTouchAt(pub f32);
 
-/// `WOW_RES_CENSUS=<at>:<secs>` — the resource change census: over a window opening at `at`
-/// seconds and `secs` long, on how many of its frames each resource read as CHANGED, printed
-/// once at the window's end, noisiest first.
-///
-/// The premise-checker behind every still-frame gate, generalised from 1982's five hand-picked
-/// `noisy=` counters to every registered resource. Bevy marks a resource changed on every `&mut`
-/// borrow, not on every write: one system that takes `ResMut<T>` — or `as_deref_mut()`s an
-/// `Option<ResMut<T>>` — each frame to *test* something makes `T.is_changed()` true on every
-/// frame of every run, and silently disarms every gate that asks it. 1982 found `DebugState`
-/// that way (299 of 300 frames); 1697's item 1 (`Creatures`, every frame, the equipment gate)
-/// sat unfound for a fortnight after being named because nothing walked the rest. On a parked
-/// leg the honest list is short — the clocks, the input state, the probe's own bookkeeping —
-/// and anything else near 100 % is a writer to find with `grep -rn 'ResMut<Name>'`.
-///
-/// Exclusive (`&mut World`) in `Last`; dev-only and env-gated, so it costs nothing unarmed and
-/// a few microseconds a frame armed. `NonSend` resources (the UI script VM) are not walked: the
-/// world exposes no iterator over that storage.
+/// `WOW_RES_CENSUS=<at>:<secs>`: on how many of the window's frames each resource read as
+/// changed, noisiest first. Bevy marks a resource changed on every `&mut` borrow, not every
+/// write, so one per-frame `ResMut<T>` disarms every gate on `T.is_changed()`. `NonSend`
+/// resources are not walked: the world has no iterator over them.
 pub(super) mod res_census {
     use std::collections::HashMap;
 
@@ -579,8 +517,7 @@ pub(super) mod res_census {
     pub(in crate::perf) struct ResCensus {
         at: f32,
         window: f32,
-        /// The world tick this census last counted at — `is_changed(last_run, this_run)`'s
-        /// "when the system last ran", so a touch counts once per frame, never twice.
+        /// The tick this census last counted at, so a touch counts once per frame.
         last_run: Option<Tick>,
         frames: u32,
         counts: HashMap<ComponentId, u32>,
@@ -653,9 +590,8 @@ pub(super) mod res_census {
         rows.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| a.1.cmp(&b.1)));
         let frames = census.frames.max(1);
         let hot = |n: u32| n * 10 >= frames * 9;
-        // bevy's own asset stores are `ResMut` in its per-frame asset systems by design (that is
-        // why `AssetChanged` exists) — every `Assets<T>` reads hot on every run, so they are one
-        // count here and never a row, or they would bury the app's own writers.
+        // Bevy's own asset stores read hot every frame by design, so they are one count, not
+        // rows.
         let bevy_store =
             |name: &str| name.starts_with("Assets<") || name.starts_with("AssetChanges<");
         let every_frame = rows.iter().filter(|(n, _)| hot(*n)).count();
@@ -667,8 +603,7 @@ pub(super) mod res_census {
             "RES_CENSUS frames={frames} resources={total} touched={} at_90pct_or_more={every_frame} (of which bevy asset stores: {bevy_hot})\n",
             rows.len()
         );
-        // Every row at half the window or more: the whole list is the point (the first run
-        // printed 48 of 302 and stopped in the B's).
+        // Every row at half the window or more, unabridged.
         for (n, name) in rows
             .iter()
             .filter(|(n, name)| *n * 2 >= frames && !bevy_store(name))
diff --git a/crates/benilla-app/src/perf/clock.rs b/crates/benilla-app/src/perf/clock.rs
index 7a8ebe53..47226718 100644
--- a/crates/benilla-app/src/perf/clock.rs
+++ b/crates/benilla-app/src/perf/clock.rs
@@ -1,28 +1,12 @@
-//! The CPU clocks the instruments are denominated in — process, main thread, and machine.
-//!
-//! Three different questions, three different calls. [`process_cpu_secs`] is the campaign's
-//! currency (decisions 0711/0736/0717): *work per frame*, immune to the present grant.
-//! [`main_thread_cpu_secs`] narrows that to the serialized half — the part a hitch is actually made
-//! of. [`system_cpu_ticks`] says how loaded the machine was while we measured, so two legs can be
-//! told apart from two moods of the same leg (1157).
+//! The CPU clocks the instruments are denominated in: process, main thread, and machine.
 
-/// Whole-process CPU seconds consumed so far — **user + system, summed across every thread**
-/// (`getrusage(RUSAGE_SELF)`).
-///
-/// The perf probes report wall-clock frame time, which on this machine is not a usable regression
-/// instrument: parallel builds share the same cores, and two identical probe runs
-/// of the same pin came back 49.6 ms and 28.6 ms apart purely on machine load. CPU-per-frame moves
-/// with the work we actually do, not with who else is compiling — and it is the metric the Mac
-/// report is written in ("250 % CPU at 59 fps" against 1.12.1's "100 % at 160"), so a probe that
-/// prints it can be compared against a reporter's number directly.
-///
-/// Unix answers through `getrusage`, Windows through `GetProcessTimes` (decision 2219);
-/// elsewhere `None`: the probes print the field only where the platform answers.
+/// Whole-process CPU seconds so far, user + system across every thread: work per frame, which
+/// other load on the machine barely moves, unlike wall frame time. `None` off Unix and Windows.
 pub(crate) fn process_cpu_secs() -> Option<f64> {
     #[cfg(unix)]
     {
-        // SAFETY: `getrusage` writes a fully-initialized `rusage` into the out-param and reads
-        // nothing from it; zeroed is a valid starting value for a C struct of plain integers.
+        // SAFETY: `getrusage` fully writes the out-param and reads nothing from it; zeroed is
+        // valid for a struct of plain integers.
         unsafe {
             let mut ru: libc::rusage = std::mem::zeroed();
             if libc::getrusage(libc::RUSAGE_SELF, &mut ru) != 0 {
@@ -35,9 +19,8 @@ pub(crate) fn process_cpu_secs() -> Option<f64> {
     #[cfg(windows)]
     {
         use windows_sys::Win32::System::Threading::{GetCurrentProcess, GetProcessTimes};
-        // SAFETY: `GetProcessTimes` writes four fully-initialised `FILETIME`s into its out-params
-        // and reads nothing from them; zeroed is a valid starting value for two plain integers,
-        // and the pseudo-handle `GetCurrentProcess` returns is never closed.
+        // SAFETY: `GetProcessTimes` fully writes four plain-integer `FILETIME`s and reads none;
+        // the `GetCurrentProcess` pseudo-handle is never closed.
         unsafe {
             let mut creation = std::mem::zeroed();
             let mut exit = std::mem::zeroed();
@@ -62,8 +45,7 @@ pub(crate) fn process_cpu_secs() -> Option<f64> {
     }
 }
 
-/// A `FILETIME` — 100-nanosecond ticks — as an integer, for the differences and sums the
-/// Windows arms take before converting.
+/// A `FILETIME` as an integer of 100-nanosecond ticks.
 #[cfg(windows)]
 fn filetime_ticks(t: windows_sys::Win32::Foundation::FILETIME) -> u64 {
     (u64::from(t.dwHighDateTime) << 32) | u64::from(t.dwLowDateTime)
@@ -75,15 +57,12 @@ fn filetime_secs(t: windows_sys::Win32::Foundation::FILETIME) -> f64 {
     filetime_ticks(t) as f64 * 1e-7
 }
 
-/// The process's page-fault counters so far — `(minor, major)` from `getrusage`. A minor fault
-/// is a page the kernel had to map or zero-fill on first touch: memory the allocator handed back
-/// to the OS and then asked for again. It is CPU time the process pays in the kernel with no
-/// syscall in any user stack — invisible to a sampler, visible to [`thread_cpu_table`]'s `sys`
-/// column. Per frame, it is the number that says whether that column is allocator churn.
+/// The process's `(minor, major)` page faults so far. Minor faults are kernel time no user-mode
+/// sampler sees; per frame they say whether [`thread_cpu_table`]'s `sys` is allocator churn.
 pub(crate) fn process_faults() -> Option<(u64, u64)> {
     #[cfg(unix)]
     {
-        // SAFETY: as in `process_cpu_secs` — `getrusage` fills the out-param completely.
+        // SAFETY: as in `process_cpu_secs`: `getrusage` fills the out-param completely.
         unsafe {
             let mut ru: libc::rusage = std::mem::zeroed();
             if libc::getrusage(libc::RUSAGE_SELF, &mut ru) != 0 {
@@ -98,27 +77,14 @@ pub(crate) fn process_faults() -> Option<(u64, u64)> {
     }
 }
 
-/// CPU seconds consumed by **the calling thread** (`CLOCK_THREAD_CPUTIME_ID`).
-///
-/// The twin [`process_cpu_secs`] cannot answer the question a hitch actually poses. It sums every
-/// thread, so a frame in which an asset worker spent 12 ms decompressing reads identically to a
-/// frame in which the main thread blocked for 12 ms — the first costs nothing the player can see,
-/// the second *is* the stutter. Narrowing to one thread separates them.
-///
-/// **Only meaningful when called from the thread you mean.** Bevy's executor runs systems across
-/// the task pool, so a caller that wants the *main* thread's number must pin itself there with a
-/// [`NonSendMarker`](bevy::ecs::system::NonSendMarker) param; without it the reading silently
-/// becomes "whichever worker happened to run this system", which is noise shaped like a
-/// measurement.
-///
-/// Unix answers through `clock_gettime`, Windows through `GetThreadTimes` on the calling
-/// thread's pseudo-handle — the same "whichever thread calls" contract (decision 2219);
-/// elsewhere `None`, like its twin.
+/// CPU seconds consumed by the calling thread. A caller that wants the main thread's must pin
+/// itself there with a [`NonSendMarker`](bevy::ecs::system::NonSendMarker) param, or it reads
+/// whichever worker ran the system. `None` off Unix and Windows.
 pub(crate) fn main_thread_cpu_secs() -> Option<f64> {
     #[cfg(unix)]
     {
-        // SAFETY: `clock_gettime` writes a fully-initialized `timespec` into the out-param and
-        // reads nothing from it; zeroed is a valid starting value for two plain integers.
+        // SAFETY: `clock_gettime` fully writes the out-param and reads nothing from it; zeroed is
+        // valid for two plain integers.
         unsafe {
             let mut ts: libc::timespec = std::mem::zeroed();
             if libc::clock_gettime(libc::CLOCK_THREAD_CPUTIME_ID, &mut ts) != 0 {
@@ -130,8 +96,8 @@ pub(crate) fn main_thread_cpu_secs() -> Option<f64> {
     #[cfg(windows)]
     {
         use windows_sys::Win32::System::Threading::{GetCurrentThread, GetThreadTimes};
-        // SAFETY: as in `process_cpu_secs` — four out-params fully written, nothing read, and
-        // `GetCurrentThread` is a pseudo-handle valid on the thread that asked for it.
+        // SAFETY: as in `process_cpu_secs`; `GetCurrentThread` is a pseudo-handle valid on the
+        // thread that asked for it.
         unsafe {
             let mut creation = std::mem::zeroed();
             let mut exit = std::mem::zeroed();
@@ -156,46 +122,20 @@ pub(crate) fn main_thread_cpu_secs() -> Option<f64> {
     }
 }
 
-/// Cumulative **machine-wide** CPU ticks as `(busy, total)` — every core, every process, us
-/// included (`host_statistics64(HOST_CPU_LOAD_INFO)`). Diff two samples and `busy/total` is the
-/// fraction of all cores that were doing work between them.
+/// Cumulative machine-wide CPU ticks as `(busy, total)`, every core and process; diff two samples
+/// for the busy fraction. Machine load inflates `cpu_ms` too (cache and memory-bandwidth
+/// contention), so a leg stamps this and only legs at similar load compare. Load average is no
+/// substitute: a 1-minute decaying mean lags a build burst. `None` off macOS and Windows.
 ///
-/// Why the probes need it, when [`process_cpu_secs`] above already promises load-independence:
-/// that promise is **weaker than it reads**, and 1157 caught it. `cpu_ms` is per-frame work rather
-/// than wall time, so it shrugs off the scheduling delay that makes frame time useless under load
-/// — but it is not immune. The same LBRS pin leg, same binary, same day, read **25.93** while two
-/// other slots ran `cargo test --workspace` (load 20-32 on 14 cores) and **18.80-20.12** on a quiet
-/// machine: a ~35 % inflation, far outside the ±0.4 band the campaign reasons in (0736). Cache and
-/// memory-bandwidth contention is work we genuinely do; `getrusage` counts it and cannot tell us
-/// it was someone else's fault.
-///
-/// So the leg has to say how loaded the machine was, and the reader compares. Deliberately a
-/// **stamp, not a gate** (the director's call): no threshold is invented here. Two legs at similar
-/// `sys_busy_pct` are comparable; two legs far apart are not, whatever their `cpu_ms` says. That
-/// is a relative rule, which is the only kind the four calibration points behind 1157 support.
-///
-/// **Do not reach for `uptime` instead.** Load average is a 1-minute *decaying* mean and lags
-/// badly: a leg stamped 99 % here was taken at load 5.55, seconds after a build burst the average
-/// had not caught up with. Cross-checked against an independent out-of-process sampler over the
-/// same window — 44 % vs 44.5 % — so where the two disagree, this is the one that is right.
-///
-/// macOS answers through `host_statistics64`, Windows through `GetSystemTimes` (decision 2219
-/// — its kernel time INCLUDES idle, so busy is kernel − idle + user); elsewhere `None`: the
-/// probes print the field only where the platform answers.
-///
-/// The `deprecated` allow is `libc::mach_host_self`, whose deprecation note says "use the `mach2`
-/// crate instead". Checked, and it does not apply here: `mach2` 0.5.0 carries `mach_host_self` and
-/// **nothing else this call needs** — no `host_statistics64`, no `host_cpu_load_info`, no
-/// `HOST_CPU_LOAD_INFO`. Taking the advice would split one call across two crates and add a direct
-/// dependency to get the *port* while `libc` still supplies the call it is passed to. Revisit if
-/// `mach2` ever grows the host-statistics surface.
+/// The `deprecated` allow is `libc::mach_host_self`: `mach2` has the port but not
+/// `host_statistics64` or its types, so `libc` stays the one source for the call.
 #[allow(deprecated)]
 pub(crate) fn system_cpu_ticks() -> Option<(u64, u64)> {
     #[cfg(target_os = "macos")]
     {
-        // SAFETY: `host_statistics64` fills at most `count` u32s into the out-param and reads
-        // nothing from it; `host_cpu_load_info` is plain integers, so zeroed is a valid starting
-        // value. `mach_host_self` returns the global host port — no send right to deallocate.
+        // SAFETY: `host_statistics64` fills at most `count` u32s and reads nothing; the struct is
+        // plain integers, so zeroed is valid. `mach_host_self` is the global host port, with no
+        // send right to deallocate.
         unsafe {
             let mut info: libc::host_cpu_load_info = std::mem::zeroed();
             let mut count = libc::HOST_CPU_LOAD_INFO_COUNT;
@@ -235,22 +175,12 @@ pub(crate) fn system_cpu_ticks() -> Option<(u64, u64)> {
     }
 }
 
-/// CPU seconds consumed so far by **every thread of this process, by name** — the split of
-/// [`process_cpu_secs`] that says *which* thread a tax landed on. A frame's `cpu_ms` rose by
-/// ~1.8 ms under vsync with no system growing on a sampled profile and no thread spinning
-/// (decision 1947): the number that resolves that is per-thread CPU across a window, which
-/// no sampler reports and this call does.
-///
-/// macOS only (`task_threads` + `thread_info(THREAD_BASIC_INFO)`, names through
-/// `pthread_getname_np`); elsewhere `None`, like the twins above. Threads are keyed by their
-/// pthread identity so two snapshots subtract, user and system time apart — the vsync tax
-/// turned out to be the main thread's kernel time, which a user-mode sampler never sees; a
-/// thread without a name reports as `"?"`.
-/// Cost: one kernel round-trip per thread — tens of microseconds, taken twice per probe
-/// window, never per frame.
+/// CPU seconds so far per thread of this process, as `(pthread id, name, user, system)`, keyed so
+/// two snapshots subtract; an unnamed thread reads `"?"`. macOS only; one kernel round-trip per
+/// thread, so taken per probe window, never per frame.
 pub(crate) fn thread_cpu_table() -> Option<Vec<(usize, String, f64, f64)>> {
-    // `libc` deprecates its mach port bindings in favour of a crate this module does not need
-    // for two symbols; both are libSystem's, the import every mach caller links.
+    // Declared here rather than taken from `libc`'s deprecated mach bindings; both are
+    // libSystem's.
     #[cfg(target_os = "macos")]
     extern "C" {
         static mach_task_self_: libc::mach_port_t;
@@ -263,9 +193,9 @@ pub(crate) fn thread_cpu_table() -> Option<Vec<(usize, String, f64, f64)>> {
     {
         use std::ffi::CStr;
         let mut out = Vec::new();
-        // SAFETY: mach's own out-param protocol — `task_threads` hands back a kernel-allocated
-        // array of thread ports and its count, each port is inspected with a stack-allocated,
-        // count-checked `thread_basic_info`, and every port and the array are released after.
+        // SAFETY: `task_threads` returns a kernel-allocated array of thread ports and its count;
+        // each port is read into a count-checked `thread_basic_info`, and every port and the
+        // array are released after.
         unsafe {
             let task = mach_task_self_;
             let mut list: libc::thread_act_array_t = std::ptr::null_mut();
diff --git a/crates/benilla-app/src/perf/crash_inject.rs b/crates/benilla-app/src/perf/crash_inject.rs
index eb9647ea..76e7223a 100644
--- a/crates/benilla-app/src/perf/crash_inject.rs
+++ b/crates/benilla-app/src/perf/crash_inject.rs
@@ -1,15 +1,9 @@
-//! `WOW_CRASH_INJECT=<at_secs>` — one deliberate main-thread panic, mid-run: the crash reporter's
-//! standing test affordance (`crate::crash`, decision 2266 §B2), in the shape of the stall
-//! sampler's own injectors. The end-to-end falsifier is a run with it set: the process must die
-//! with a `crash-<unix>.txt` whose log tail ends in the `crash-inject` line below.
+//! `WOW_CRASH_INJECT=<at_secs>`: one deliberate main-thread panic mid-run, the test affordance
+//! for the crash reporter (`crate::crash`); a run with it set must die with a `crash-<unix>.txt`
+//! whose log tail ends in the `crash-inject` line.
 //!
-//! **Why it lives here and not in `crash.rs`, and not in `stall.rs`.** An instrument's home is a
-//! dev root (`run_mode::the_dev_plane_has_exactly_one_door`, 1176): the reporter ships to
-//! players and knows nothing of the `dev` seam, so its injector cannot sit beside it under a
-//! `cfg`. And it was first armed from inside the stall sampler, which is macOS-only
-//! (`/usr/bin/sample`) — so on Linux and Windows the injector was dead code, `-D warnings` made
-//! that a red cross-platform compile on both, and the macOS gates stayed green for six days. An
-//! instrument's cfg is `dev`, never a platform's; `PerfPlugin` arms this on every platform.
+//! It lives in the dev plane, not beside the reporter, which ships to players, and is armed on
+//! every platform: an instrument's cfg is `dev`, never a platform's.
 
 use bevy::prelude::*;
 
diff --git a/crates/benilla-app/src/perf/gpu.rs b/crates/benilla-app/src/perf/gpu.rs
index 1dc3f5a2..75ec832a 100644
--- a/crates/benilla-app/src/perf/gpu.rs
+++ b/crates/benilla-app/src/perf/gpu.rs
@@ -1,31 +1,13 @@
-//! **`WOW_GPU_MS=1` — the whole-frame GPU meter** (1389's scoped follow-on, built 2026-08-18;
-//! the drastic-options census' unknown #2 was "GPU frame time and VRAM headroom — no instrument
-//! exists").
+//! `WOW_GPU_MS=1`: the whole-frame GPU meter. Two sentinel render passes bracket the camera
+//! driver and write a timestamp pair at their pass boundaries, which Apple GPUs can sample where
+//! bevy's in-pass diagnostics cannot.
 //!
-//! Two plain render-graph nodes bracket the camera driver — `begin` writes timestamp 0 into a
-//! two-slot query set from its command encoder, `end` writes timestamp 1 — legal on this machine
-//! because we hold `TIMESTAMP_QUERY_INSIDE_ENCODERS` (Apple Silicon samples at stage boundaries;
-//! bevy's own `RenderDiagnosticsPlugin` needs INSIDE_PASSES and reads zero GPU spans here — the
-//! `perf` module header's ⚠ note, measured in 1389).
-//!
-//! **The resolve rides the NEXT frame's command buffer, ahead of that frame's own stamps.**
-//! 1389's recorded trap: resolving the query set in the SAME command buffer as the timed work
-//! returns zeros on Metal (5 of 6 reads; the 6th a plausible-looking near-miss) — resolve on a
-//! later submission. The first build of this meter did that with a submission of its own: a
-//! fresh encoder, a second `queue.submit` and an explicit `device.poll` in `Cleanup`, every
-//! frame — a per-frame poll that traced at 1.8 ms on Intel's DX12 driver (2236) and priced
-//! untraced in 2254. So the query set holds TWO stamp pairs and the frames alternate between
-//! them ([`pairs`]): the `begin` node first resolves the pair the previous frame wrote — a later
-//! submission, 1389's rule kept — and copies it into a free slot of a small ring of MAP_READ
-//! buffers, on the graph's own shared encoder; then it writes this frame's pair. `Cleanup` only
-//! kicks the map on the slot the graph just filled, and that map lands inside the NEXT frame's
-//! own `queue.submit`, which runs wgpu's device maintenance as part of every submit
-//! (`wgpu_core::device::queue::Queue::submit` ends in `Device::maintain(Poll)`) — the shape of
-//! bevy's own `DiagnosticsRecorder`, and no submission or poll of the meter's own. The
-//! published number is the freshest mapped delta, nanoseconds in one `AtomicU64` shared with
-//! the main world — `FPS_PROBE` samples it per frame under the same env and prints its own
-//! percentiles, so a leg gets `gpu_p50/gpu_p99` beside `cpu_ms` with zero cost when the env is
-//! off (nothing registers).
+//! Resolving the query set in the same command buffer as the timed work reads zeros on Metal, so
+//! the query set holds two pairs that alternate by frame ([`pairs`]): the `begin` node resolves
+//! the pair the previous frame wrote into a ring of `MAP_READ` buffers on the graph's own encoder,
+//! then writes this frame's. `Cleanup` only starts the map, which lands in the next frame's
+//! `queue.submit` (every submit maintains the device), so the meter adds no submission or poll.
+//! The freshest delta is published in nanoseconds through one shared `AtomicU64`.
 
 use std::sync::atomic::{AtomicU64, AtomicU8, Ordering};
 use std::sync::Arc;
@@ -45,25 +27,20 @@ use bevy::render::{Render, RenderApp, RenderSystems};
 use bevy::ui_render::TransparentUi;
 use wgpu::{QuerySet, QuerySetDescriptor, QueryType};
 
-/// Is the meter armed? One read; everything registers behind it.
+/// Whether the meter is armed, read once.
 pub(crate) fn enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var("WOW_GPU_MS").as_deref() == Ok("1"))
 }
 
-/// The freshest whole-frame GPU duration, nanoseconds. Written by the render app's readback,
-/// read by `FPS_PROBE`/whoever in the main world. 0 = no reading yet.
+/// The freshest whole-frame GPU duration in nanoseconds, written by the render app's readback;
+/// 0 until the first reading.
 #[derive(Resource, Clone)]
 pub(crate) struct GpuMsShared(pub Arc<AtomicU64>);
 
-/// **The wgpu resource census** — live buffers, textures and bind groups, off wgpu-core's own
-/// registry report, refreshed once a frame by the render app and read by `FPS_PROBE` under the
-/// same env (`wgpu_bufs=… wgpu_texs=… wgpu_bgs=…`). It is on the GPU meter because it prices
-/// the GPU *lane's* CPU: every render pass wgpu encodes allocates and clears usage trackers
-/// sized to the device's live buffer and texture counts (`wgpu_core::track::UsageScope`), so a
-/// scene's pass-encode CPU carries a term that scales with residency, not with what is drawn —
-/// a sampled profile of the crowd rig (1929's follow-on) put that term at roughly half of
-/// `encode_render_pass`. The count is the number that lever moves.
+/// The wgpu resource census: live buffers, textures and bind groups from wgpu-core's registry
+/// report, refreshed once a frame. Every pass wgpu encodes sizes its usage trackers to these
+/// counts, so pass-encode CPU scales with residency as well as with what is drawn.
 #[derive(Resource, Clone)]
 pub(crate) struct WgpuCensusShared(pub Arc<WgpuCensus>);
 
@@ -72,15 +49,14 @@ pub(crate) struct WgpuCensus {
     pub buffers: AtomicU64,
     pub textures: AtomicU64,
     pub bind_groups: AtomicU64,
-    /// Draw calls the render phases will issue this frame, per family — see [`count_draws`].
+    /// Draw calls the render phases issue this frame, per family ([`count_draws`]).
     pub draws_opaque: AtomicU64,
     pub draws_transparent: AtomicU64,
     pub draws_shadow: AtomicU64,
     pub draws_ui: AtomicU64,
 }
 
-/// Render world, `Cleanup`: refresh the census. wgpu-core's report takes each registry's read
-/// lock and counts live ids — microseconds, and only under the meter's env.
+/// Render world, `Cleanup`: refresh the census from wgpu-core's report.
 fn census(instance: Res<bevy::render::renderer::RenderInstance>, shared: Res<WgpuCensusShared>) {
     let Some(report) = instance.generate_report() else {
         return;
@@ -95,13 +71,9 @@ fn census(instance: Res<bevy::render::renderer::RenderInstance>, shared: Res<Wgp
         .store(hub.bind_groups.num_allocated as u64, Ordering::Relaxed);
 }
 
-/// Render world, `Cleanup`: the frame's draw-call count per phase family, off the phases bevy
-/// just rendered — the number the pass-encode CPU on the render thread scales with (wgpu-core
-/// validates and wgpu-hal encodes per draw, and on Metal a draw is also what the driver's
-/// kernel-side work is measured in). A binned phase issues one draw per bin (Metal has no
-/// multi-draw indirect, so a multidrawable batch set still draws bin by bin) plus one per
-/// unbatchable entity and per non-mesh item; a sorted phase issues one per item whose batch
-/// range survived batching (a merged item's range is emptied into its predecessor's).
+/// Render world, `Cleanup`: the frame's draw calls per phase family. A binned phase draws once
+/// per bin (Metal has no multi-draw indirect) plus once per unbatchable entity and non-mesh item;
+/// a sorted phase draws once per item whose batch range survived batching.
 #[allow(clippy::type_complexity)]
 fn count_draws(
     shared: Res<WgpuCensusShared>,
@@ -169,49 +141,38 @@ fn count_draws(
 
 const RING: usize = 4;
 
-/// Ring-slot states: a copy may only target a FREE slot — submitting into a mapped (or
-/// map-pending) buffer is a wgpu validation error, which the first live run demonstrated.
+/// Ring-slot states: a copy may only target a `FREE` slot, since submitting into a mapped or
+/// map-pending buffer is a wgpu validation error.
 const FREE: u8 = 0;
 const PENDING: u8 = 1;
 const MAPPED: u8 = 2;
 
-/// Which stamp pair a graph run writes and which it resolves, for the [`GpuStamp::frame`] it
-/// runs under: the two pairs alternate, and a run resolves the pair the run before it wrote —
-/// a later submission than the timed work (1389's rule), and one whose queries the previous
-/// command buffer reset before writing (a resolve of a never-reset query is 2211's hang). Pair
-/// `p` is queries `2p` (begin) and `2p + 1` (end).
+/// `(write, resolve)` pairs for a [`GpuStamp::frame`]: a run resolves the pair the run before
+/// it wrote, a later submission whose queries were reset by being written. Pair `p` is queries
+/// `2p` (begin) and `2p + 1` (end).
 fn pairs(frame: usize) -> (u32, u32) {
     #[allow(clippy::cast_possible_truncation)]
     let write = (frame % 2) as u32;
     (write, 1 - write)
 }
 
-/// Render-world state: the query set (two stamp pairs, alternating by frame), the resolve
-/// buffer, and the mapping ring.
+/// Render-world state: the query set (two alternating stamp pairs), the resolve buffer, and the
+/// mapping ring.
 #[derive(Resource)]
 struct GpuStamp {
     query_set: QuerySet,
-    /// A 1×1 target the sentinel passes clear — real (if trivial) work, because an EMPTY pass
-    /// never reaches the Metal encoder and samples nothing (this meter's second zero-read).
+    /// A 1×1 target the sentinel passes clear: an empty pass never reaches the Metal encoder and
+    /// samples nothing.
     sentinel_view: wgpu::TextureView,
     resolve: Buffer,
     ring: Vec<(Buffer, Arc<AtomicU8>)>,
-    /// `Cleanup`s this resource has seen, counting the one that created it; the graph run that
-    /// follows each writes pair `frame % 2` and resolves the other ([`pairs`]). **The creation
-    /// `Cleanup` precedes the first stamped frame**: `init_stamp` inserts the resource in
-    /// `Cleanup`, the scheduler's sync point applies it before `readback` runs in the same set,
-    /// and the sentinel nodes that write — and, in wgpu, reset — the queries only run in the
-    /// NEXT frame's graph. A resolve on that first run would read a query pool no command has
-    /// ever reset, which Vulkan forbids (`VUID-vkCmdCopyQueryPoolResults-None-09402`) and
-    /// answers, on NVIDIA's driver, by waiting on it forever — a GPU hang, the TDR, and the
-    /// lost device 2205 met at the swapchain acquire. Metal hands back zeros for the same read,
-    /// which is why the meter's first live runs (1389) saw "zeros" and never a hang. Decision
-    /// 2211. So the first run is armed with no [`Self::slot`] and resolves nothing.
+    /// `Cleanup`s seen, counting the creating one; the graph run after each writes pair
+    /// `frame % 2` and resolves the other ([`pairs`]). The first run is armed with no
+    /// [`Self::slot`]: no command has reset its query pool yet, and resolving one is forbidden
+    /// on Vulkan (`VUID-vkCmdCopyQueryPoolResults-None-09402`), a GPU hang on NVIDIA.
     frame: usize,
-    /// The ring slot the NEXT graph run copies the previous run's stamps into: chosen in
-    /// `Cleanup` from the FREE slots — `None` while no run has written a pair yet, or while the
-    /// ring is full (that sample is skipped; the meter is a meter). The `begin` node reads it,
-    /// the `Cleanup` after that run maps it.
+    /// The `FREE` ring slot the next graph run copies the previous run's stamps into; `None`
+    /// before any pair is written or while the ring is full, and that sample is skipped.
     slot: Option<usize>,
     period: f32,
     shared: Arc<AtomicU64>,
@@ -237,9 +198,7 @@ impl Node for GpuStampNode {
             let (write, resolve) = pairs(stamp.frame);
             if self.index == 0 {
                 if let Some(slot) = stamp.slot {
-                    // The previous run's pair, resolved and copied out on the graph's own
-                    // encoder: a later submission than the stamps it reads (1389), and none of
-                    // the meter's own.
+                    // A later submission than the stamps it reads, on the graph's own encoder.
                     let encoder = render_context.command_encoder();
                     encoder.resolve_query_set(
                         &stamp.query_set,
@@ -250,10 +209,8 @@ impl Node for GpuStampNode {
                     encoder.copy_buffer_to_buffer(&stamp.resolve, 0, &stamp.ring[slot].0, 0, 16);
                 }
             }
-            // A SENTINEL PASS, not a bare `write_timestamp`: Apple Silicon samples counters only
-            // at stage boundaries, and an encoder-level stamp with no stages around it resolves
-            // to zero (measured on this meter's first live run — 1389's "two sentinel nodes"
-            // meant exactly this). An empty compute pass is the cheapest stage boundary there is.
+            // A sentinel pass, not a bare `write_timestamp`: Apple GPUs sample counters only at
+            // stage boundaries, and an encoder-level stamp resolves to zero.
             let (begin, end) = if self.index == 0 {
                 (Some(write * 2), None)
             } else {
@@ -285,9 +242,8 @@ impl Node for GpuStampNode {
     }
 }
 
-/// Build [`GpuStamp`] on the first render frame — the device does not exist yet at plugin
-/// build time (`RenderPlugin` creates it in `finish`), which a startup-eager version learned
-/// as a `RenderDevice does not exist` panic on its first live run.
+/// Build [`GpuStamp`] on the first render frame: `RenderPlugin` creates the device in `finish`,
+/// after plugin build.
 fn init_stamp(
     mut commands: Commands,
     stamp: Option<Res<GpuStamp>>,
@@ -353,16 +309,11 @@ fn init_stamp(
     });
 }
 
-/// `Cleanup`, after the graph's own submission: kick the map on the slot the graph just filled,
-/// publish every landed mapping, and arm a slot for the next run. No encoder, no submit and no
-/// poll of the meter's own — the map lands in the next frame's `queue.submit`, which maintains
-/// the device (the module header).
+/// `Cleanup`, after the graph's submission: start the map on the slot the graph just filled,
+/// publish every landed mapping, and arm a slot for the next run.
 fn readback(stamp: Option<ResMut<GpuStamp>>) {
     let Some(mut stamp) = stamp else { return };
-    // The slot the graph run just copied into: FREE when armed, so that submission is the only
-    // one in flight on it, and it is out of the arming below until the mapping is read and
-    // released — submitting into a mapped or map-pending buffer is a wgpu validation error,
-    // which the first live run demonstrated.
+    // The slot stays out of the arming below until its mapping is read and released.
     if let Some(i) = stamp.slot.take() {
         let flag = stamp.ring[i].1.clone();
         flag.store(PENDING, Ordering::Relaxed);
@@ -389,8 +340,7 @@ fn readback(stamp: Option<ResMut<GpuStamp>>) {
             }
         }
     }
-    // Arm the next run — which resolves the pair the run that just finished wrote — unless no
-    // run has written one yet (the creation `Cleanup`; see `frame`). None FREE → no sample.
+    // Not on the creation `Cleanup`, before any pair is written; no `FREE` slot, no sample.
     if stamp.frame >= 1 {
         stamp.slot = (0..RING).find(|&i| stamp.ring[i].1.load(Ordering::Relaxed) == FREE);
     }
@@ -427,8 +377,6 @@ pub(crate) fn plugin(app: &mut App) {
 mod tests {
     use super::pairs;
 
-    /// The ordering law the Vulkan hang (2211) and the Metal zeros (1389) both hang on: a run
-    /// never resolves the pair it writes, and always resolves the one the run before it wrote.
     #[test]
     fn a_run_resolves_the_pair_the_run_before_it_wrote() {
         for frame in 1..12 {
diff --git a/crates/benilla-app/src/perf/hud.rs b/crates/benilla-app/src/perf/hud.rs
index 5ec91e3d..ec59c09b 100644
--- a/crates/benilla-app/src/perf/hud.rs
+++ b/crates/benilla-app/src/perf/hud.rs
@@ -1,29 +1,11 @@
 //! The standing dev HUD: the cost pill, and nothing else.
 //!
-//! **The pill is two small numbers** (1448 pared it back; 1454 made it the whole HUD; 1455
-//! dropped the spike arrow). fps dim — the familiar anchor, and by construction the number that
-//! cannot see cost (0717) — then process-CPU cost per frame, the meter vsync cannot rail; both
-//! under-size, because the pill sits over the game all session. Anything deeper is an
-//! instrument's job, not a panel's: the journal (`WOW_FPS_JOURNAL`), the probes, Tracy, the
-//! `frame hitch` log line and the stall self-sampler. The expanded egui readout that used to
-//! live behind a click is gone (1454) — it duplicated the instruments at a standing cost — and
-//! the spike-latch arrow went the same way (1455, the director's call).
+//! The pill is fps (dim) and CPU cost per frame, drawn from a 4 Hz snapshot of the meters, which
+//! keep sampling every frame. It is laid onto the player-UI quad pass, never egui: drawing
+//! through egui wakes its whole per-frame pipeline and a full-screen compositing camera.
 //!
-//! **Drawn from a 4 Hz snapshot, not the live meters.** The pill renders from [`PerfHud::snap`];
-//! the meters keep sampling every frame — only the *view* is quantized, and 250 ms is inside a
-//! human read of a number.
-//!
-//! **The pill does not touch egui at all** (1453). Drawing anything through egui wakes the whole
-//! lane — bevy_egui's per-frame pipeline plus a full-screen compositing camera — which the
-//! director's live toggle priced at ~1 ms for a 20-glyph pill. So [`pill_quads`] lays the pill
-//! onto the player-UI quad pass, whose append lane is rebuilt every frame anyway; since 1454 the
-//! HUD has no egui surface left and [`crate::debug_panel`]'s 1445 gate no longer consults it.
-//!
-//! **The HUD does not own settings.** It briefly carried a VSync checkbox and an MSAA readout;
-//! VSync is a player video option now ([`crate::video`], the Graphics page's `gxVSync` row) and
-//! MSAA is a startup knob (`$WOW_MSAA`). An instrument reports — it does not double as the control
-//! panel, and this one is `#[cfg(feature = "dev")]`, so anything a player must reach cannot live
-//! here at all. The measurement knob the checkbox actually existed for is `$WOW_NOVSYNC=1`.
+//! The HUD owns no settings: it is `#[cfg(feature = "dev")]`, so nothing a player must reach can
+//! live here. `$WOW_NOVSYNC=1` is the measurement knob for vsync.
 
 use benilla_ui::script::{JustifyH, JustifyV, Outline, UiScript};
 use bevy::prelude::*;
@@ -34,58 +16,37 @@ use super::stats::FrameStats;
 use crate::ui_pass::{UiQuad, UiQuads};
 use crate::ui_text::{layout_text_quads, FontSpec, Justify, UiFontAtlas};
 
-// ---- The quad pill (1453): the standing readout, drawn on the player-UI pass. --------------
-// The old egui overlay palette, restated as client-space sRGB floats for [`UiQuad::color`]
-// (black alpha 224 fill; gray 235 text; gray 180 dim).
+// ---- The quad pill, drawn on the player-UI pass. ---------------------------------------------
+// Client-space sRGB for [`UiQuad::color`]: black alpha 224 fill, gray 235 text, gray 180 dim.
 const Q_FILL: [f32; 4] = [0.0, 0.0, 0.0, 224.0 / 255.0];
 const Q_TEXT: [f32; 4] = [0.92, 0.92, 0.92, 1.0];
 /// `|cAARRGGBB` markup for the dim fps run (gray 180).
 const Q_DIM_MARKUP: &str = "|cffb4b4b4";
-/// Paint order: the pill background one under the glyphs, both above every packed WoW z_key
-/// (frame tuples never fill the top bits).
+/// Paint order: the background under the glyphs, both above every packed WoW z_key, whose frame
+/// tuples never fill the top bits.
 const Z_PILL_BG: u64 = u64::MAX - 1;
 const Z_PILL: u64 = u64::MAX;
 /// The quad pill's font height (logical px) and box padding.
 const PILL_QUAD_PX: f32 = 12.0;
 const PILL_PAD: Vec2 = Vec2::new(9.0, 4.0);
-/// Top-center offset — where the pill sits when nothing else claims that band.
+/// Top-centre offset, where the pill sits when nothing else claims that band.
 const PILL_TOP: f32 = 8.0;
 /// The gap the pill leaves under whatever game UI it is stepping below.
 const PILL_YIELD_GAP: f32 = 4.0;
 
-/// How often the drawn snapshot advances. Fast enough that the numbers read as live and a latched
-/// badge appears within a perceptual beat; slow enough that between refreshes the pill's cached
-/// quads are reused byte-identical (see [`pill_quads`]).
+/// How often the drawn snapshot advances; between refreshes [`pill_quads`] reuses its cache.
 const HUD_REFRESH_SECS: f32 = 0.25;
 
-/// HUD state. The **dev chord + `P`** (Ctrl+Shift+P) toggles `visible`, and it starts **hidden**
-/// — the director's call, 2026-09-08: the pill sits over the game for the whole session and the
-/// game is what a dev build is for looking at. It is an instrument you reach for, not furniture.
-/// `visible` is `pub(crate)` so the capture harness ([`crate::capture`]) can force the overlay off
-/// for pristine, UI-free screenshots.
-///
-/// **`WOW_PERF_HUD=1` starts it shown**, which is how the HUD gets priced — the knob kept its
-/// meaning in both spellings when the default flipped, so `0` and unset are both hidden. 1370
-/// records the open gap: every campaign anchor was measured on a binary that draws this overlay,
-/// at a cost booked as "est 0.4–1.2 ms CPU + unquantified GPU" — an estimate, never a measurement,
-/// because nothing could turn the fixture off without also changing the binary. One env var makes
-/// it an interleaved A/B on *one* binary instead (a leg runner), so the constant baked into
-/// every anchor becomes a number. The meters keep sampling either way: only the drawing stops,
-/// which is the half being priced — and with the default flipped, the *unmeasured* leg is now the
-/// one nobody is running.
+/// HUD state. The dev chord + `P` (Ctrl+Shift+P) toggles `visible`; it starts hidden unless
+/// `WOW_PERF_HUD=1`. The capture harness ([`crate::capture`]) forces it off for UI-free shots.
 #[derive(Resource)]
 pub(crate) struct PerfHud {
     pub(crate) visible: bool,
-    /// The snapshot the pill draws from — a copy of the meters taken every [`HUD_REFRESH_SECS`],
-    /// so the strings it formats hold still between refreshes (the module doc's cost argument).
-    /// The live [`FrameStats`] keeps sampling every frame; this is only the view.
+    /// The meters as of the last [`HUD_REFRESH_SECS`] tick, the view the pill draws.
     snap: FrameStats,
-    /// The clock `snap` was taken at. Spike ages are computed against this, not the live clock,
-    /// so they hold still with the rest of the view — and it doubles as the refresh timer.
+    /// The clock `snap` was taken at, which is also the refresh timer.
     snap_at: f32,
-    /// How far down the screen the top-centre band is already spoken for (window logical px from
-    /// the top edge, `0.0` when it is clear) — see [`top_centre_claimed`]. The pill seats itself
-    /// below this.
+    /// How far down the top-centre band the game UI reaches ([`top_centre_claimed`]).
     top_claimed: f32,
 }
 
@@ -94,7 +55,7 @@ impl Default for PerfHud {
         Self {
             visible: std::env::var("WOW_PERF_HUD").as_deref() == Ok("1"),
             snap: FrameStats::default(),
-            // −∞, so the very first frame refreshes rather than drawing an empty snapshot.
+            // So the first frame refreshes rather than drawing an empty snapshot.
             snap_at: f32::NEG_INFINITY,
             top_claimed: 0.0,
         }
@@ -102,8 +63,7 @@ impl Default for PerfHud {
 }
 
 impl PerfHud {
-    /// Advance the snapshot if the current one is older than [`HUD_REFRESH_SECS`]; `true` when it
-    /// did (the caller's gate for the rest of the refresh — see [`refresh_hud_snapshot`]).
+    /// Advance the snapshot if it is older than [`HUD_REFRESH_SECS`]; `true` when it did.
     fn maybe_refresh(&mut self, stats: &FrameStats, now: f32) -> bool {
         if now - self.snap_at < HUD_REFRESH_SECS {
             return false;
@@ -113,26 +73,22 @@ impl PerfHud {
         true
     }
 
-    /// Where the pill's top edge goes: its usual seat, pushed below anything already occupying the
-    /// top-centre band.
+    /// The pill's top edge: its usual seat, pushed below anything claiming the band.
     fn pill_top(&self) -> f32 {
         PILL_TOP.max(self.top_claimed + PILL_YIELD_GAP)
     }
 }
 
 pub(super) fn toggle_hud(keys: Res<ButtonInput<KeyCode>>, mut hud: ResMut<PerfHud>) {
-    // The dev chord + `P`, not a bare `p` — `P` is the reference's TOGGLESPELLBOOK, and a dev
-    // doesn't get to squat on a game binding (decision 0585). The chord can't be mistaken for typed
-    // text, so unlike the old bare key it needs no chat-bar/EditBox gate.
+    // The dev chord, not a bare `P`, which is the reference's TOGGLESPELLBOOK; a chord cannot be
+    // typed text, so it needs no EditBox gate.
     if benilla_world::modkeys::dev_chord(&keys, KeyCode::KeyP) {
         hud.visible = !hud.visible;
     }
 }
 
-/// Advance the HUD's 4 Hz snapshot — its own system (1453), kept separate so the sampling cadence
-/// never depends on whether anything drew this frame. It also re-asks who else is using the pill's
-/// band ([`top_centre_claimed`]), on the same cadence and for the same reason: once per view, not
-/// once per frame.
+/// Advance the HUD's 4 Hz snapshot, independent of whether anything drew, and re-ask
+/// [`top_centre_claimed`] on the same cadence.
 pub(super) fn refresh_hud_snapshot(
     mut hud: ResMut<PerfHud>,
     stats: Res<FrameStats>,
@@ -153,41 +109,16 @@ pub(super) fn refresh_hud_snapshot(
     };
 }
 
-/// How far down the top-centre band the **game UI** already reaches, in window logical px from the
-/// top edge (`0.0` = clear).
+/// How far down the top-centre band the game UI reaches, in window logical px (`0.0` when
+/// clear). The always-up world-state readout (`WorldStateAlwaysUpFrame`, stock
+/// `WorldStateFrame.xml`) shares the band, and the dev pill is the one that yields.
 ///
-/// The pill has sat at the top centre since 1453 because that band was empty. It is not empty
-/// everywhere: the always-up world-state readout (`WorldStateAlwaysUpFrame` — the tower counters
-/// and battleground scores, decision 1590) is anchored to the top centre too, and in Eastern
-/// Plaguelands or a battleground the two drew straight through each other. **The dev instrument is
-/// the one that yields** — the readout is the game, the pill is scaffolding — and it yields by
-/// stepping below it rather than by moving house, because a 1.12 UI has no corner a standing
-/// overlay can claim outright (player/target frames own the top left, buffs and the minimap the top
-/// right, the action bar the bottom, the chat dock the bottom left).
-///
-/// **Asked of the frame, not recomputed from its numbers.** Its row pitch and anchor live in
-/// the stock `WorldStateFrame.xml` (1972); mirroring them here would be two copies to keep in step, so
-/// this reads the resolved edge the layout actually produced (`GetBottom`, y-up). One tiny chunk
-/// at 4 Hz, only while the HUD is drawing — the same shape as [`crate::hover_log`]'s tooltip
-/// probe.
-///
-/// **Two coordinate spaces meet here, and mixing them is the whole trap.** The layout answers in
-/// WoW UI units — a screen that is always `768/uiScale` units tall whatever the window is
-/// (decision 0582's seam) — while the pill lays itself out in window px. Subtracting one from the
-/// other is right only in the single case where the seam scale happens to be 1 (a 768 px-tall
-/// window at uiScale 1) and wrong by `windowH − 768` everywhere else — which on the director's
-/// window seated the pill back on top of the readout's third row while every test at 768 passed.
-/// So the chunk answers a **fraction of the screen**, which belongs to neither space, and the
-/// caller multiplies by the window height it actually draws in.
-///
-/// **Its own cost, stated (1370's rule for this overlay):** an edge read settles the layout, so on
-/// a frame where something has written anchors since the last resolve this pays one graph solve
-/// (~47 µs on a 200-frame tree — `layout_methods::settle`'s own measurement), four times a second.
-/// Every other frame it is a chunk load and a table lookup.
+/// The layout answers in UI units, a screen `768/uiScale` units tall whatever the window, while
+/// the pill draws in window px, so the chunk returns a fraction of the screen and the caller
+/// scales it by the window height. Reading an edge settles the layout, one graph solve at most.
 pub(crate) fn top_centre_claimed(script: &UiScript, win_h: f32) -> f32 {
-    // The stock `WorldStateAlwaysUpFrame` is a permanently shown container (1972); what the
-    // readout actually occupies is its ROWS — `AlwaysUpFrame<n>`, built on demand and hidden when
-    // the scope admits nothing — so the claim is the lowest shown row's bottom, or nothing.
+    // `WorldStateAlwaysUpFrame` is always shown; the readout occupies its `AlwaysUpFrame<n>` rows,
+    // built on demand and hidden when empty, so the claim is the lowest shown row's bottom.
     const CHUNK: &str = r#"
         local f = WorldStateAlwaysUpFrame
         if not (f and f:IsVisible()) then return -1 end
@@ -212,10 +143,8 @@ pub(crate) fn top_centre_claimed(script: &UiScript, win_h: f32) -> f32 {
     frac * win_h
 }
 
-/// The pill as ~20 quads on the player-UI pass (decision 1453). The append lane is rebuilt every
-/// frame anyway, so the marginal cost is the clone of a cached Vec — where the old egui pill woke
-/// bevy_egui's whole pipeline plus a full-screen compositing camera (~1 ms on the director's live
-/// toggle). Glyphs are laid out only when the snapshot ticks or the window resizes.
+/// The pill as ~20 quads on the player-UI pass, a cached Vec clone per frame; glyphs are laid
+/// out again only when the snapshot ticks, the window resizes or the seat moves.
 pub(super) fn pill_quads(
     hud: Res<PerfHud>,
     atlas: Option<Res<UiFontAtlas>>,
@@ -228,13 +157,12 @@ pub(super) fn pill_quads(
         return;
     }
     let (Some(atlas), Ok(win)) = (atlas, windows.single()) else {
-        return; // headless: nothing draws, nothing to price
+        return; // headless
     };
     let win_w = win.width();
     let top = hud.pill_top();
-    // Draws this frame that bound a blend state contradicting their material (the additive
-    // check, `perf::blend_check`): shown red the frame it happens, so a wrong halo on screen
-    // and a non-zero count here are seen together.
+    // Draws that bound a blend state contradicting their material (`perf::blend_check`), shown
+    // red the frame it happens.
     let mismatch = mismatch.map_or(0, |m| m.0.load(std::sync::atomic::Ordering::Relaxed));
     let stale = !matches!(
         &*cache,
@@ -244,11 +172,8 @@ pub(super) fn pill_quads(
         let cpu = hud.snap.cpu.mean();
         let main = hud.snap.main.mean();
         let fps = hud.snap.fps();
-        // One string, the dim runs via markup: "59 fps  7.0 ms  17.3 cpu" — fps dim, the MAIN
-        // thread's ms in full text (the part of the frame the player feels), and the process-wide
-        // sum dim at the end (every thread, the number a CPU % agrees with — decision 1954: a
-        // raid read 17 on it at a solid 60 with the main thread at 7, and the sum was taken for
-        // a frame time by everyone who looked at it).
+        // "59 fps  7.0 ms  17.3 cpu": fps dim, the main thread's ms in full, and the all-thread
+        // sum dim, so the sum is not read as a frame time.
         let mut text = match (main, cpu) {
             (Some(main), Some(cpu)) => {
                 format!("{Q_DIM_MARKUP}{fps:.0} fps|r  {main:.1} ms  {Q_DIM_MARKUP}{cpu:.1} cpu|r")
@@ -318,8 +243,7 @@ pub(super) fn pill_quads(
     quads.overlays.extend(c.quads.iter().cloned());
 }
 
-/// [`pill_quads`]' cache: the laid-out pill, valid for one snapshot tick at one window width and
-/// one seat (the seat moves when the game UI takes the band — [`top_centre_claimed`]).
+/// [`pill_quads`]' cache: the laid-out pill, valid for one snapshot tick, window width and seat.
 pub(super) struct PillCache {
     snap_at: f32,
     win_w: f32,
@@ -336,29 +260,12 @@ mod tests {
 
     use crate::ui_script::world_state_tests::{harness, push, row};
 
-    /// The readout and the dev cost pill both want the top centre, and before this they drew straight
-    /// through each other (the pill is anchored 8 px down; the readout's first row starts at 15). The
-    /// pill asks the frame itself how far down the band is spoken for ([`top_centre_claimed`]) and
-    /// seats itself below that — so this pins the probe against the shipped XML: nothing claimed while
-    /// the readout is empty, and the readout's real resolved bottom once it is up.
-    ///
-    /// **Why it lives here and not beside the frame it drives.** It was written in
-    /// `ui_script/world_state_tests.rs`, next to the readout — but `perf` is compiled out of a player
-    /// build, so the `player-tests` gate (`--no-default-features --lib`, decision 1175) could not
-    /// compile that file, and gating the one test with `#[cfg(feature = "dev")]` trips `run_mode`'s
-    /// dev-plane enforcer (1179: seam knowledge has exactly three addresses, and a gameplay module is
-    /// not one of them). Both laws point the same way — a test of a dev instrument belongs in a dev
-    /// root. It borrows the readout's own `#[cfg(test)]` helpers rather than copying them, so the XML
-    /// it drives stays the shipped one.
+    /// Pins [`top_centre_claimed`] against the stock XML. It lives here, not beside the readout,
+    /// because a test of a dev instrument belongs in a dev root.
     #[test]
     fn the_readout_tells_the_dev_pill_how_much_of_the_top_it_uses() {
         benilla_formats::wow_data_or_skip!();
-        // NOT 768. The layout answers in WoW UI units — a screen that is always 768 units tall
-        // whatever the window is (decision 0582) — and the pill draws in window px, so a probe that
-        // subtracts one from the other is right only when the two happen to coincide. Feeding a
-        // window height that is NOT the virtual one is the whole point of this test: it is what the
-        // director's client does, and the first version of this probe put the pill back on top of the
-        // readout's third row there while passing every test at 768.
+        // Not 768: a window height other than the UI's virtual one catches mixed units.
         const SCREEN_H: f32 = 900.0;
         let mut s = harness();
         s.fire_event("PLAYER_ENTERING_WORLD", vec![ScriptValue::Str("".into())]);
@@ -390,8 +297,7 @@ mod tests {
             claimed > 8.0,
             "two rows reach past the pill's own seat, so the pill must move: {claimed}"
         );
-        // The frame's own geometry, read back the way the probe reads it: the second (lowest)
-        // row's resolved bottom. Asserted against the stock XML rather than restated as constants.
+        // The second (lowest) row's resolved bottom, read from the stock layout.
         let expected: f32 = s
             .eval::<f64>(
                 "return (GetScreenHeight() - AlwaysUpFrame2:GetBottom()) / GetScreenHeight()",
@@ -412,9 +318,6 @@ mod tests {
         );
     }
 
-    /// The view the HUD draws only advances on the refresh interval — between ticks it holds
-    /// still, which is the entire cost argument (identical snapshots are what the quad cache can
-    /// reuse) — and a refresh adopts the live meters wholesale.
     #[test]
     fn the_snapshot_advances_on_the_interval_not_per_frame() {
         let mut live = FrameStats::default();
@@ -449,9 +352,6 @@ mod tests {
         );
     }
 
-    /// The pill's seat: its usual place while the top-centre band is clear, and below the game UI
-    /// the moment something claims it — the always-up world-state readout is the one frame that
-    /// shares this band (decision 1590), and before this the two drew through each other.
     #[test]
     fn the_pill_steps_below_whatever_claims_the_top_centre() {
         let mut hud = PerfHud::default();
diff --git a/crates/benilla-app/src/perf/journal.rs b/crates/benilla-app/src/perf/journal.rs
index 8763453e..5d3c0ba2 100644
--- a/crates/benilla-app/src/perf/journal.rs
+++ b/crates/benilla-app/src/perf/journal.rs
@@ -1,41 +1,13 @@
-//! The FPS JOURNAL — `/console fpsJournal 1` in any build, or `WOW_FPS_JOURNAL=<csv path>` on a
-//! harness run: once a second, append one row of where the player is, what the frame cost on
-//! the wall, on the CPU and on the GPU, and **what is resident** (see [`JOURNAL_HEADER`] for the
-//! column order, written into every fresh file) — the "where does it dip" instrument for a
-//! director-driven run, and since decision 2008 the instrument a PLAYER on hardware we do not
-//! own can run for us. They play normally; the journal turns "it drops in the Dwarven District"
-//! into coordinates a headless probe can tele straight back to, and its GPU columns turn a Steam
-//! Deck's "GPU 94 % busy" into which pass is eating it. Negligible cost: one line of IO a second,
-//! samples reused from the frame meters.
+//! The FPS journal (`/console fpsJournal 1` in any build, or `WOW_FPS_JOURNAL=<csv path>`): once
+//! a second, one row of where the player is, what the frame cost on the wall, the CPU and the
+//! GPU, and what is resident ([`JOURNAL_HEADER`]). It ships in the player build so a player on any
+//! hardware can record a run; the file is `benilla-config/Diagnostics/fps-journal.csv`, opened
+//! with a `#` line naming the adapter, the backend and whether the device can time passes.
 //!
-//! **Player-facing, so it lives outside the `dev` seam** (2008, on 1495's precedent): the people
-//! whose frames we need to read run the player build, which compiles every other instrument out
-//! (1173). The CVar's knob is [`FpsJournalSetting`]; the file is
-//! `benilla-config/Diagnostics/fps-journal.csv` ([`crate::local_state::fps_journal_path`]), the
-//! thing a reporter attaches. `WOW_FPS_JOURNAL` names another path and turns the journal on for
-//! the run regardless of the CVar — the harness lever it always was. A fresh file opens with one
-//! `#` line naming the adapter, the backend and whether the device can time passes, so a journal
-//! from a machine we have never seen says what it was read on.
-//!
-//! **The GPU columns read bevy's render diagnostics** (`RenderDiagnosticsPlugin`, registered here
-//! so it is present in every build): one timestamp pair per render pass, resolved a few frames
-//! later into `render/<pass>/elapsed_gpu` measurements. Those exist where the device offers
-//! `TIMESTAMP_QUERY_INSIDE_PASSES` — Vulkan and DX12, so the Linux and Windows builds — and never
-//! on an Apple GPU, which samples counters only at stage boundaries (the `perf` module header);
-//! there the columns stay EMPTY rather than zero, so "no reading" cannot be mistaken for "free".
-//! Our own passes (`static_gx`, the `ffx_glow` chain, `ui_gamma_decode`) open spans of their own,
-//! because a city's biggest draw must not land in `gpu_other`. The buckets are [`gpu_bucket`]; a
-//! pass this file does not name is still counted, under `gpu_other`, and `gpu_ms` is the sum of
-//! every pass — the GPU's busy time inside passes, which is what "GPU-bound" reads against the
-//! wall `mean_ms` beside it.
-//!
-//! The residency columns make it the **leak curve** instrument too (B131): `FPS_PROBE`'s residency
-//! meter samples once per run, which can only compare two runs at one point each — it cannot tell
-//! "grows with distance streamed" from "grows with time elapsed", and cannot show *where* on a
-//! route the cost arrives. A per-second row of `cpu_ms` beside `mats/images/uv/tint` plots the
-//! per-frame cost directly against residency along one continuous leg, on the same time axis as
-//! the position — so a same-map traverse (no `MapChange`, so no map-scoped eviction) shows its
-//! accumulation as a slope instead of a before/after pair.
+//! The GPU columns read bevy's per-pass render diagnostics, which exist only where the device
+//! has `TIMESTAMP_QUERY_INSIDE_PASSES` (Vulkan and DX12, never an Apple GPU); elsewhere the cells
+//! stay empty, not zero. `gpu_ms` is the sum of every pass, and an unnamed pass lands in
+//! `gpu_other`.
 
 use std::path::PathBuf;
 use std::time::Instant;
@@ -50,23 +22,19 @@ use super::clock::{main_thread_cpu_secs, process_cpu_secs};
 
 pub(crate) struct FpsJournalPlugin;
 
-/// The `fpsJournal` CVar's knob (2008): on, the journal appends to the player's
-/// `Diagnostics/fps-journal.csv` from the next second on; off, it stops mid-run and the file
-/// keeps what it has. `/console fpsJournal 1` is the whole recipe a reporter needs.
+/// The `fpsJournal` CVar: on, the journal appends from the next second; off, it stops and the
+/// file keeps what it has.
 #[derive(Resource, Default)]
 pub(crate) struct FpsJournalSetting(pub(crate) bool);
 
-/// The journal's column order, written as the first line of a fresh file (after the `#` adapter
-/// line). Appended-to files keep whatever header they were created with — the columns only ever
-/// grow at the end, so an older journal still parses against its own header.
+/// The column order, written once into a fresh file after the `#` adapter line. Columns only
+/// ever grow at the end, so an older journal still parses against its own header.
 const JOURNAL_HEADER: &str = "t,x,y,z,mean_ms,p95_ms,streamed,entities,cpu_ms,mats,meshes,images,\
                               m2,uv,tint,pmat,emat,skin,cmat,tex,cgeo,evicted,fx,fy,fz,main_ms,\
                               gpu_ms,gpu_opaque,gpu_static,gpu_transp,gpu_glow,gpu_post,gpu_ui,\
                               gpu_other\n";
 
-/// The FPS journal switch's change callback (2008, 2303): a flag, the client's int-parse +
-/// `!= 0`. The journal system reads the knob every frame, so the file opens on the next second
-/// and closes the second it is turned off.
+/// The `fpsJournal` change callback: a flag, int-parsed and `!= 0`.
 pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut journal: ResMut<FpsJournalSetting>) {
     if ev.is("fpsJournal") {
         journal.0 = ev.flag();
@@ -75,10 +43,8 @@ pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut journal: ResMut<Fps
 
 impl Plugin for FpsJournalPlugin {
     fn build(&self, app: &mut App) {
-        // bevy's per-pass render diagnostics — the source of the GPU columns, and (under the
-        // `tracy` feature) the hook Tracy's GPU zones ride. Present in every build: its per-frame
-        // cost is one query resolve and one buffer map on the render thread, and a player's
-        // journal is exactly the build that has to carry it (2008).
+        // Bevy's per-pass render diagnostics, the source of the GPU columns and of Tracy's GPU
+        // zones, registered in every build.
         app.add_plugins(RenderDiagnosticsPlugin)
             .init_resource::<FpsJournalSetting>()
             .add_observer(on_cvar)
@@ -102,18 +68,15 @@ impl Plugin for FpsJournalPlugin {
 struct FpsJournal {
     /// `WOW_FPS_JOURNAL`: a fixed path, on for the whole run whatever the CVar says.
     env_path: Option<PathBuf>,
-    /// Where rows go while the journal is on; `None` = off, or nowhere to write (a hermetic
-    /// run has no state folder, and the CVar has no other place to point).
+    /// Where rows go while the journal is on; `None` when off, or on a hermetic run with no
+    /// state folder.
     path: Option<PathBuf>,
     window: Vec<f32>,
     last_flush: f32,
-    /// Process CPU seconds at the previous flush — the row's `cpu_ms` is this second's CPU cost
-    /// per frame, the load-robust half of the measurement.
+    /// Process CPU seconds at the previous flush, for the row's per-frame `cpu_ms`.
     cpu_at_flush: Option<f64>,
-    /// Main-thread CPU seconds at the previous flush, for the row's `main_ms`. Exactly parallel to
-    /// `cpu_at_flush`, so the two columns are the same measurement at two scopes: `cpu_ms` is every
-    /// thread's work, `main_ms` the serialized part of it. A leg where they diverge is a leg whose
-    /// cost moved off (or onto) the critical path — which the all-threads column alone cannot say.
+    /// Main-thread CPU seconds at the previous flush, for the row's `main_ms`: `cpu_at_flush`'s
+    /// measurement narrowed to the serialized part.
     main_at_flush: Option<f64>,
     /// This second's GPU spans, folded per frame from the diagnostics store.
     gpu: GpuAccum,
@@ -122,29 +85,28 @@ struct FpsJournal {
 /// The GPU columns after `gpu_ms`, in header order.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 enum GpuBucket {
-    /// bevy's `main_opaque_pass_3d` — terrain, the model lane's opaque parts, the sky shells.
+    /// Bevy's `main_opaque_pass_3d`: terrain, opaque model parts, the sky shells.
     Opaque = 0,
-    /// Our retained static pass (`static_gx`): the WMOs and the doodads, the city's own draw.
+    /// Our retained static pass (`static_gx`): the WMOs and the doodads.
     Static,
-    /// bevy's transparent (and transmissive) 3D passes — water, glow cards, particles.
+    /// Bevy's transparent and transmissive 3D passes: water, glow cards, particles.
     Transparent,
-    /// The `ffx_glow` chain: the quarter-res downsample, the two Gauss taps — and a bake's
-    /// combine. The world's combine is the first draw of the UI camera's main pass since 2234,
-    /// inside `main_transparent_pass_2d`'s own span (it has none of its own — 2258), so it lands
-    /// in [`Self::Ui`] with that pass.
+    /// The `ffx_glow` chain: the quarter-res downsample, the two Gauss taps and a bake's combine.
+    /// The world's combine draws inside `main_transparent_pass_2d`'s span, so it lands in
+    /// [`Self::Ui`].
     Glow,
     /// The full-screen tail on every camera: tonemapping, upscaling, the MSAA writeback.
     Post,
     /// The 2D camera's passes, bevy UI, and our `ui_gamma_decode`.
     Ui,
-    /// Every span this file does not name — counted, never dropped.
+    /// Every span this file does not name, counted, never dropped.
     Other,
 }
 
 const GPU_BUCKETS: usize = 7;
 
-/// Which column a diagnostics path lands in. `None` = not a top-level GPU span: a CPU span, a
-/// non-render diagnostic, or a span nested under another (its parent already carries it).
+/// Which column a diagnostics path lands in; `None` for anything but a top-level GPU span (a
+/// nested span's parent already carries it).
 fn gpu_bucket(path: &str) -> Option<GpuBucket> {
     let pass = path.strip_prefix("render/")?.strip_suffix("/elapsed_gpu")?;
     if pass.contains('/') {
@@ -163,21 +125,17 @@ fn gpu_bucket(path: &str) -> Option<GpuBucket> {
     })
 }
 
-/// One second's GPU spans: summed per bucket, divided at the flush by the number of frames
-/// whose readback landed — not by the wall window's frame count, because bevy's diagnostics
-/// mutex hands the store at most one frame per sync and drops the rest when readbacks bunch up,
-/// so the honest divisor is the frames actually read.
+/// One second's GPU spans, summed per bucket and divided by the frames whose readback landed:
+/// bevy hands the store at most one frame per sync and drops the rest when readbacks bunch up.
 #[derive(Default)]
 struct GpuAccum {
     sum: [f64; GPU_BUCKETS],
     frames: u32,
-    /// The newest measurement time consumed, so each fold reads only what arrived since. All
-    /// measurements of one sync share one `Instant`, which is what makes "a frame" countable.
+    /// The newest measurement time consumed; all measurements of one sync share one `Instant`,
+    /// which is what makes a frame countable.
     seen: Option<Instant>,
-    /// `WOW_GPU_PASSES=1` — the same sums per PASS, printed beside each row as a `GPU_PASSES`
-    /// line: the journal's buckets fold both 2D passes, the UI pass and the gamma decode into
-    /// one `gpu_ui`, and a pass-level question (an empty pass encoded every frame; one filter
-    /// pass of a chain) needs the raw split. Empty and unread unless armed.
+    /// `WOW_GPU_PASSES=1`: the same sums per pass, printed beside each row as a `GPU_PASSES`
+    /// line; empty unless armed.
     passes: std::collections::BTreeMap<String, f64>,
 }
 
@@ -220,9 +178,8 @@ impl GpuAccum {
         self.seen = newest;
     }
 
-    /// The row's GPU cells — `,gpu_ms,<one per bucket>` — and the reset. All empty when no
-    /// frame was read this second: the platform has no in-pass timestamps, and an empty cell
-    /// says so where a zero would lie.
+    /// The row's GPU cells, `,gpu_ms,<one per bucket>`, and the reset; all empty when no frame
+    /// was read this second.
     fn columns(&mut self) -> String {
         let mut s = String::new();
         if self.frames == 0 {
@@ -235,7 +192,7 @@ impl GpuAccum {
                 s.push_str(&format!(",{:.2}", bucket / n));
             }
             if passes_armed() {
-                // Costliest first, ms per read frame — the raw split the buckets fold.
+                // Costliest first, ms per read frame.
                 let mut rows: Vec<(&String, &f64)> = self.passes.iter().collect();
                 rows.sort_by(|a, b| b.1.total_cmp(a.1));
                 let line: Vec<String> = rows
@@ -252,9 +209,7 @@ impl GpuAccum {
     }
 }
 
-/// The `#` line a fresh file opens with: what the rows were read on, and whether the GPU
-/// columns can ever fill (the device's in-pass timestamp feature, the one bevy's pass spans
-/// need). Everything a reader needs to know before comparing two journals.
+/// The `#` line a fresh file opens with: the adapter, and whether the GPU columns can ever fill.
 fn preamble(adapter: Option<&RenderAdapterInfo>, device: Option<&RenderDevice>) -> String {
     let (gpu, backend, driver) = adapter.map_or_else(
         || ("?".to_string(), "?".to_string(), "?".to_string()),
@@ -263,7 +218,7 @@ fn preamble(adapter: Option<&RenderAdapterInfo>, device: Option<&RenderDevice>)
             (
                 a.name.clone(),
                 format!("{:?}", a.backend),
-                // Metal reports no driver string at all; a `?` reads better than a blank.
+                // Metal reports no driver string.
                 if driver.is_empty() {
                     "?".to_string()
                 } else {
@@ -285,14 +240,9 @@ fn preamble(adapter: Option<&RenderAdapterInfo>, device: Option<&RenderDevice>)
     format!("# benilla fps journal | gpu {gpu} | backend {backend} | driver {driver} | gpu_spans {spans}\n")
 }
 
-/// The journal's residency columns, grouped because `journal_fps` is near Bevy's system-param
-/// arity limit.
-///
-/// The `Assets<T>` counts are the totals — what the process holds. The [`ArtCensus`] half is the
-/// same population **broken down by the cache that holds it** (decision 0793), which is what turns
-/// "materials are growing" into a named holder in one row instead of a run-length probe. `evicted`
-/// is the running total dropped by distance: on a same-map traverse it was structurally zero before
-/// 0793, because nothing but a `MapChange` evicted anything (0729).
+/// The journal's residency columns, grouped for Bevy's system-param arity limit. The
+/// `Assets<T>` counts are totals; the [`ArtCensus`] half breaks the same population down by the
+/// cache that holds it, and `evicted` is the running total dropped by distance.
 ///
 /// [`ArtCensus`]: benilla_world::art_scope::ArtCensus
 #[derive(bevy::ecs::system::SystemParam)]
@@ -304,16 +254,12 @@ struct JournalResidency<'w> {
     uv_reg: Res<'w, benilla_world::doodad_anim::UvAnimMaterials>,
     tint_reg: Res<'w, benilla_world::doodad_anim::TintAnimMaterials>,
     art: Res<'w, benilla_world::art_scope::ArtCensus>,
-    /// The **view focus** — where art is actually being asked for. Distinct from the row's `x,y,z`,
-    /// which is the avatar: through a detached free-fly the body stands still while the camera covers
-    /// kilometres, so on that leg the position columns describe nothing that is happening. The
-    /// director's first run was exactly that leg, and reading it needed this column.
+    /// The view focus, where art is asked for; it leaves the avatar's `x,y,z` in a detached
+    /// free-fly.
     scope: Res<'w, benilla_world::art_scope::ArtScopeState>,
 }
 
-/// The GPU side: the diagnostics store the render spans sync into, and the two facts the
-/// preamble names. All optional — a headless app without a renderer has none of them, and the
-/// journal then writes its CPU columns and leaves the GPU cells empty.
+/// The diagnostics store and the preamble's adapter and device; all absent without a renderer.
 #[derive(bevy::ecs::system::SystemParam)]
 struct JournalGpu<'w> {
     store: Option<Res<'w, DiagnosticsStore>>,
@@ -321,9 +267,7 @@ struct JournalGpu<'w> {
     device: Option<Res<'w, RenderDevice>>,
 }
 
-/// `NonSendMarker` pins this to the main thread, which the `main_ms` column requires:
-/// [`main_thread_cpu_secs`] reports *the calling thread*, so on a worker it would silently log
-/// whichever pool thread ran the flush.
+/// Pinned to the main thread: [`main_thread_cpu_secs`] reads the calling thread's clock.
 fn journal_fps(
     _pin_to_main_thread: bevy::ecs::system::NonSendMarker,
     mut journal: ResMut<FpsJournal>,
@@ -336,8 +280,8 @@ fn journal_fps(
     gpu: JournalGpu,
 ) {
     let now = time.elapsed_secs();
-    // The switch, read every frame: the env lever or the CVar. Turning on opens (or creates) the
-    // file and restarts every per-second baseline; turning off drops the half-second in hand.
+    // Read every frame: turning on opens the file and restarts every baseline; turning off
+    // drops the partial second.
     let wanted = journal.env_path.is_some() || setting.0;
     match (wanted, journal.path.is_some()) {
         (false, false) => return,
@@ -354,10 +298,9 @@ fn journal_fps(
                 .clone()
                 .or_else(crate::local_state::fps_journal_path)
             else {
-                return; // hermetic: no state folder, and nothing else to write into
+                return; // hermetic: no state folder
             };
-            // The header goes in exactly once, at creation: the rows are appended for the life
-            // of the run (and across runs, deliberately — a journal accumulates legs).
+            // The header goes in once, at creation; rows append across runs.
             if !path.exists() {
                 let head = format!(
                     "{}{JOURNAL_HEADER}",
@@ -401,8 +344,6 @@ fn journal_fps(
         .filter(|p| p.active)
         .map(|p| benilla_assets::coords::bevy_to_wow(p.pos))
         .unwrap_or([0.0; 3]);
-    // CPU per frame over this second — the number the reporter's "CPU %" compares against, and
-    // the one that does not move with whatever else is compiling on this machine.
     let cpu_now = process_cpu_secs();
     let cpu_ms = match (journal.cpu_at_flush, cpu_now) {
         (Some(t0), Some(t1)) => format!("{:.2}", (t1 - t0) * 1000.0 / v.len() as f64),
@@ -423,7 +364,7 @@ fn journal_fps(
         residency.uv_reg.0.len(),
         residency.tint_reg.0.len(),
     );
-    // The per-cache breakdown, in `ArtSlot::ALL` order — which IS the header's column order.
+    // `ArtSlot::ALL` order is the header's column order.
     for slot in benilla_world::art_scope::ArtSlot::ALL {
         line.push_str(&format!(",{}", residency.art.live(slot)));
     }
@@ -432,8 +373,7 @@ fn journal_fps(
         Some(f) => line.push_str(&format!(",{:.1},{:.1},{:.1}", f[0], f[1], f[2])),
         None => line.push_str(",,,"),
     }
-    // Appended at the end, per this file's own rule: the columns only ever grow there, so an
-    // existing journal keeps parsing against the header it was created with.
+    // New columns only ever append at the end of the row.
     let main_now = main_thread_cpu_secs();
     match (journal.main_at_flush, main_now) {
         (Some(t0), Some(t1)) => {
@@ -442,7 +382,6 @@ fn journal_fps(
         _ => line.push(','),
     }
     journal.main_at_flush = main_now;
-    // The GPU cells (2008), last of all.
     let gpu_cells = journal.gpu.columns();
     line.push_str(&gpu_cells);
     line.push('\n');
@@ -482,7 +421,6 @@ mod tests {
         assert_eq!(b("render/ui/elapsed_gpu"), Some(Ui));
         assert_eq!(b("render/ui_gamma_decode/elapsed_gpu"), Some(Ui));
         assert_eq!(b("render/main_transparent_pass_2d/elapsed_gpu"), Some(Ui));
-        // Unnamed passes are counted, not dropped.
         assert_eq!(
             b("render/early_mesh_preprocessing/elapsed_gpu"),
             Some(Other)
diff --git a/crates/benilla-app/src/perf/main_split.rs b/crates/benilla-app/src/perf/main_split.rs
index af5eead9..7e87c8a2 100644
--- a/crates/benilla-app/src/perf/main_split.rs
+++ b/crates/benilla-app/src/perf/main_split.rs
@@ -1,10 +1,6 @@
-//! **The main thread's CPU, inside the app's frame** — `First` to `Last`, per frame, so the
-//! probe can subtract it from the thread's whole-frame CPU (`thr=[main:…]`) and name what is
-//! left: the event loop, AppKit's redraw path, the pipelined-render handshake. The vsync tax
-//! (decision 1947/1949) is +1.2 ms of main-thread user time per frame that no system grew and
-//! no sampler placed; whether it is spent inside the schedules or around them is this split.
-//!
-//! Two pinned systems, one `clock_gettime` each — nothing a frame can feel.
+//! The main thread's CPU inside the app's frame (`First` to `Last`), so the probe can subtract it
+//! from the thread's whole-frame CPU (`thr=[main:…]`) and attribute the rest to the event loop,
+//! the windowing system's redraw path and the pipelined-render handshake.
 
 use bevy::prelude::*;
 
diff --git a/crates/benilla-app/src/perf/mod.rs b/crates/benilla-app/src/perf/mod.rs
index 4345ad72..2f4dd206 100644
--- a/crates/benilla-app/src/perf/mod.rs
+++ b/crates/benilla-app/src/perf/mod.rs
@@ -1,54 +1,24 @@
-//! `perf` — performance instrumentation + the standing dev HUD ([`PerfPlugin`]), and the one
-//! instrument that ships to players: the FPS journal ([`FpsJournalPlugin`], decision 2008).
+//! Performance instrumentation and the standing dev HUD ([`PerfPlugin`]), plus the one
+//! instrument that ships to players, the FPS journal ([`FpsJournalPlugin`]).
 //!
-//! Owns the **frame-cost measurement layer** that every future subsystem is measured against (the
-//! standard), and draws the always-on cost pill (top-center) — the whole HUD since 1454; anything
-//! deeper is an instrument's job (the journal, the probes, Tracy). The **dev chord + `P`** toggles
-//! it (`Ctrl+Shift+P` — decisions 0585/0867/0870).
+//! The HUD is the always-on cost pill (top-center), toggled by the dev chord + `P`. While synced,
+//! wall frame time measures the display's present grant, not our cost, so the pill's headline is
+//! CPU ms and fps is drawn dim.
 //!
-//! The concerns, one file each:
-//! - [`clock`] — the three CPU clocks (process, main thread, machine) every number is denominated in,
-//! - [`stats`] — the rolling windows the pill reads,
-//! - [`hud`] — the standing cost pill,
-//! - [`trace`] / [`journal`] — the two CSV instruments (`WOW_STREAM_TRACE`, `WOW_FPS_JOURNAL`);
-//!   the journal also answers the `fpsJournal` CVar, in every build (2008),
-//! - [`stall`] — the stuck-main-thread self-sampler (macOS),
-//! - [`census`] — the env-gated premise counters.
+//! - [`clock`]: the CPU clocks (process, main thread, machine) every number is denominated in,
+//! - [`stats`]: the rolling windows the pill reads,
+//! - [`hud`]: the cost pill,
+//! - [`trace`] / [`journal`]: the CSV instruments (`WOW_STREAM_TRACE`, `WOW_FPS_JOURNAL`); the
+//!   journal also answers the `fpsJournal` CVar, in every build,
+//! - [`stall`]: the stuck-main-thread self-sampler (macOS),
+//! - [`census`]: the env-gated premise counters.
 //!
-//! **The dev seam runs through this module.** 1173 named `perf` dev wholesale; 2008 carved the
-//! journal, and the clocks it reads, out to the player side: `clock` and `journal` compile in the
-//! player build, everything else — the HUD, the meters, the census counters, [`PerfPlugin`]
-//! itself — is `#[cfg(feature = "dev")]`. The rule is unchanged (`dev.rs`): dev may see anything;
-//! nothing may depend on dev. The journal depends on nothing on the dev side.
+//! `clock` and `journal` compile in the player build; everything else is
+//! `#[cfg(feature = "dev")]`, and the journal depends on nothing on the dev side.
 //!
-//! **The law the whole surface obeys (0717): while synced, wall frame time measures the display's
-//! present grant, not our cost.** Only the CPU series measure work. That is why the pill's headline
-//! is `cpu ms` and not fps — on a 120 Hz-adaptive panel, cost can double with the granted interval
-//! unchanged and framerate unmoved, and the pill's old red threshold (fps < 58) sat ~5.7× above a
-//! healthy frame. fps stays on the pill — dim and small, the familiar anchor, never the thing
-//! being watched (1448).
-//!
-//! The budget is a **60 fps floor = 16.7 ms; no frame should exceed it** — but note that the
-//! *missed-interval* threshold is derived from the interval we actually observe, not from this
-//! constant (see [`stats::DROPPED_FACTOR`]). Deep per-system attribution is via Tracy
-//! (`cargo run --features tracy`) — the `info_span!` markers on the hot systems feed it.
-//!
-//! ⚠️ **macOS/Metal — GPU timing.** We have `Features::TIMESTAMP_QUERY` on this machine, but
-//! **`TIMESTAMP_QUERY_INSIDE_PASSES` is `false`**: Apple GPUs sample counters only at stage
-//! boundaries (`MTLCounterSamplingPoint::AtStageBoundary`). Bevy's `RenderDiagnosticsPlugin`
-//! (registered by the journal, so present in every build) writes its timestamps *inside* passes,
-//! so on Apple Silicon every span falls through to the CPU-only branch and the store carries
-//! **zero** `elapsed_gpu` paths — verified on a live run: 14 diagnostic paths, all `elapsed_cpu`.
-//! (bevy_render's own "Vulkan and DX12 only" comment is stale as a statement about the
-//! *platform* — an Intel Mac would report `INSIDE_PASSES` and emit GPU spans.) Where the feature
-//! IS present — Vulkan and DX12, so the Linux and Windows builds — those spans are the journal's
-//! `gpu_*` columns (2008), which is how a Steam Deck's frame gets read without a Deck here.
-//! Pass-boundary `timestamp_writes` **does** work on Apple and is the route to whole-frame
-//! GPU-ms — built as [`gpu`] (`WOW_GPU_MS=1`): two sentinel render-graph nodes at ~0.03 ms/frame,
-//! the query set resolved in a *different* command buffer than the timed pass or Metal returns
-//! zeros (1389). Per-pass on Apple remains unbuilt: a GPU-bound frame here is identified rather
-//! than timed — the one that runs long while the CPU meters stay flat, read side by side in the
-//! journal or a probe line.
+//! Apple GPUs lack `TIMESTAMP_QUERY_INSIDE_PASSES`, so bevy's render diagnostics carry CPU spans
+//! only there; on Vulkan and DX12 their GPU spans are the journal's `gpu_*` columns. Whole-frame
+//! GPU ms on Apple comes from pass-boundary timestamps, [`gpu`] (`WOW_GPU_MS=1`).
 
 #[cfg(feature = "dev")]
 mod blend_check;
@@ -93,15 +63,14 @@ pub(crate) use main_split::MainThreadSplit;
 /// The frame budget: a 60 fps floor. No frame should exceed this.
 pub const FRAME_BUDGET_MS: f32 = 1000.0 / 60.0;
 
-/// The dev-side instruments, as one plugin — everything in this module but the journal (2008).
+/// The dev-side instruments as one plugin: everything in this module but the journal.
 #[cfg(feature = "dev")]
 pub struct PerfPlugin;
 
 #[cfg(feature = "dev")]
 impl Plugin for PerfPlugin {
     fn build(&self, app: &mut App) {
-        // (bevy's render-pass diagnostics — the CPU spans here, the GPU spans on Vulkan/DX12, and
-        // the hook Tracy's GPU zones ride — are registered by `FpsJournalPlugin`, in every build.)
+        // Bevy's render-pass diagnostics are registered by `FpsJournalPlugin`, in every build.
         main_split::plugin(app);
         app.init_resource::<stats::FrameStats>()
             .init_resource::<PerfHud>()
@@ -114,50 +83,30 @@ impl Plugin for PerfPlugin {
             })
             .add_systems(
                 Update,
-                // `toggle_hud` needs no ordering against the UI keyboard feed any more: its dev
-                // chord can't be typed text, so there's no `UiKeyboardCapture` to read (decision 0585).
+                // `toggle_hud` needs no ordering against the UI keyboard feed: its dev chord
+                // cannot be typed text.
                 (
                     hud::toggle_hud,
                     hud::refresh_hud_snapshot,
                     stats::sample_frame_time,
                 ),
             )
-            // The pill rides the player-UI quad pass (1453): appended with the other overlay
-            // producers, so the HUD costs a Vec clone and never touches the egui lane (1454).
             .add_systems(Update, hud::pill_quads.in_set(crate::ui_pass::UiQuadAppend))
-            // `Last`, so a row carries everything this frame's Stream chain did — and the reset runs
-            // whether or not anything is tracing, or the counters would accumulate forever.
+            // `Last`, so a row carries all of this frame's Stream chain; it runs untraced too, to
+            // reset the per-frame counters.
             .add_systems(Last, trace::trace_stream);
-        // `WOW_MESH_EVENTS=1` — who churns Mesh assets per frame? The premise counter behind
-        // the Stormwind trace's `allocate_and_free_meshes` row (0.86 ms/frame at a PARKED pin):
-        // the allocator answers every Modified with a free+realloc, so a steady scene should
-        // show ~zero here. Printed once a second with the top mutated ids' first sighting.
         if std::env::var_os("WOW_MESH_EVENTS").is_some() {
             app.add_systems(Update, census::count_mesh_events);
         }
-        // `WOW_PART_CHURN=1` — the moving-regime premise counters (1461): how many frames per
-        // second despawn an M2 part (= `classify_water_side` full-walk promotions), and how
-        // often model materials fire Modified (= the `AssetChanged` scan wake-ups).
         if std::env::var_os("WOW_PART_CHURN").is_some() {
             app.add_systems(Update, census::count_part_churn);
         }
-        // `WOW_MESH_HOLDERS=1` — who OWNS the meshes `WOW_MESH_EVENTS` counts? Prints each
-        // holder's archetype signature once a second (1461's writer hunt).
         if std::env::var_os("WOW_MESH_HOLDERS").is_some() {
             app.add_systems(Last, census::mesh_holders);
         }
-        // `WOW_CAM_CHANGED=1` — is the world camera's transform bit-stable at a parked pin?
-        // The premise counter for gating the per-submesh visibility sweep on frame-stable
-        // camera inputs: if the controller rewrites an equal transform every frame, change
-        // detection fires anyway and the gate can never hold — the controller's no-op write
-        // is then the first fix, not the sweep's.
         if std::env::var_os("WOW_CAM_CHANGED").is_some() {
             app.add_systems(bevy::app::PostUpdate, census::count_camera_changes);
         }
-        // `WOW_ARCH_CENSUS=<secs>` — one archetype census at t=secs: every non-empty
-        // archetype's entity count beside its component set, largest first. The exact by-lane
-        // entity picture (1354's anchor census generalized to every lane at once), for sizing
-        // which populations are worth collapsing before designing any collapse.
         if let Some(at) = std::env::var("WOW_ARCH_CENSUS")
             .ok()
             .and_then(|v| v.parse::<f32>().ok())
@@ -165,8 +114,6 @@ impl Plugin for PerfPlugin {
             app.insert_resource(census::ArchCensusAt(at));
             app.add_systems(Last, census::arch_census);
         }
-        // `WOW_ROW_BLOAT=<n>` — spawn n inert clones of a live static row (see the system doc):
-        // the d(cpu_ms)/d(rows) instrument the consolidation option divides by.
         if std::env::var("WOW_ROW_BLOAT")
             .ok()
             .and_then(|v| v.parse::<usize>().ok())
@@ -174,9 +121,6 @@ impl Plugin for PerfPlugin {
         {
             app.add_systems(Update, census::row_bloat);
         }
-        // `WOW_MESH_TOUCH=<secs>` — the `AssetChanged` tax meter (see the system's doc): from
-        // `secs` onward, one scratch `Assets<Mesh>` modification per frame and nothing else, so
-        // the arming's price is read as a within-run paired delta with the UI's own work removed.
         if let Some(at) = std::env::var("WOW_MESH_TOUCH")
             .ok()
             .and_then(|v| v.parse::<f32>().ok())
@@ -184,31 +128,20 @@ impl Plugin for PerfPlugin {
             app.insert_resource(census::MeshTouchAt(at));
             app.add_systems(Update, census::mesh_touch);
         }
-        // `WOW_CPU_CENSUS=<at>:<secs>` — the per-thread CPU census (see its module doc): where
-        // the pill's cpu-ms goes, thread by thread, summing exactly to the process total.
         #[cfg(target_os = "macos")]
         if let Some(c) = census::cpu_census::CpuCensus::from_env() {
             app.insert_resource(c);
             app.add_systems(Update, census::cpu_census::cpu_census);
         }
-        // `WOW_RES_CENSUS=<at>:<secs>` — the resource change census (see its module doc): on how
-        // many of the window's frames each resource read as changed, noisiest first — the
-        // finder for the dead-gate class 1982's `noisy=` counted five of by hand.
         if let Some(c) = census::res_census::ResCensus::from_env() {
             app.insert_resource(c);
             app.add_systems(Last, census::res_census::res_census);
         }
-        // `WOW_CRASH_INJECT=<at>` — the crash reporter's standing injector (its module doc says
-        // why it lives here): armed on every platform, and ahead of the stall sampler's own
-        // off-switch for the same reason the sampler arms its injectors first.
+        // `WOW_CRASH_INJECT=<at>`: armed here, on every platform, not in the macOS-only sampler.
         crash_inject::arm(app);
         #[cfg(target_os = "macos")]
         stall::plugin(app);
-        // `WOW_FRAME_PHASES=<ms>` — which PHASE of a slow frame spent it (see the module doc).
         phases::plugin(app);
-        // `WOW_GPU_MS=1` — the whole-frame GPU meter (its module doc owns the design and the
-        // 1389 resolve-on-a-later-submission trap). Registers nothing when off, so campaign
-        // anchors never carry its ~0.03 ms sentinel cost uninvited.
         gpu::plugin(app);
         blend_check::plugin(app);
     }
diff --git a/crates/benilla-app/src/perf/phases.rs b/crates/benilla-app/src/perf/phases.rs
index 1a748519..55e1ac86 100644
--- a/crates/benilla-app/src/perf/phases.rs
+++ b/crates/benilla-app/src/perf/phases.rs
@@ -1,40 +1,21 @@
-//! The FRAME-PHASE breakdown (`WOW_FRAME_PHASES=<ms>`) — *which phase* of a slow frame spent it.
+//! The frame-phase breakdown (`WOW_FRAME_PHASES=<ms>`): which phase of a slow frame spent it.
 //!
-//! The instruments we had bracket this question from both sides and answer neither half of it.
-//! `WOW_STREAM_TRACE` says a frame cost 411 ms and how many tiles/meshes/pipelines it touched;
-//! the stall sampler (0713) shells `/usr/bin/sample` at a *600 ms* main-thread stall and hands
-//! back a stack. Between them sits the whole class this project actually reports — the
-//! 40–500 ms world-entry and teleport hitches (0962, 1116, 1345) — where the diagnosis has each
-//! time been *"guess the suspect, then time it by hand"*. 1345 named that cost outright: the
-//! FrameXML burst was found by reading a log's wall-clock stamps and subtracting.
+//! - Between the main schedules the stamps are marker schedules spliced into
+//!   [`bevy::app::MainScheduleOrder`], so each stamp is a schedule boundary, a hard sync point.
+//! - Inside `Update` the stamps are exclusive systems around the four [`WorldStage`] sets. That
+//!   perturbs `Update`'s parallelism, which is why the instrument is opt-in.
 //!
-//! So: stamp the frame at boundaries that are **exact by construction**, and print the
-//! breakdown for any frame over the threshold.
-//!
-//! - **Between the main schedules** the stamps are their own *marker schedules*, spliced into
-//!   [`bevy::app::MainScheduleOrder`]. A schedule boundary is a hard sync point, so the stamp is
-//!   the boundary — no ordering constraint to get wrong, no executor freedom to float in.
-//! - **Inside `Update`** the stamps ride the four [`WorldStage`] sets the frame contract already
-//!   defines (0737's Net → Input → Stream → Present chain), as **exclusive** systems so each one
-//!   is a sync point too. That is a real perturbation of `Update`'s parallelism — which is why it
-//!   is opt-in, and why the printed line carries `total=` measured across the whole frame rather
-//!   than summed from the parts.
-//!
-//! **The residue is the point, not an afterthought.** A frame is `Main` *plus* the render
-//! sub-app — extract, prepare, queue, render, present — and on macOS every first-sight pipeline
-//! variant is compiled with `block_on` **inline on the render thread** (`pipe_warm`'s header),
-//! which is invisible to every stamp inside `Main`. So the total is measured frame-start to
-//! frame-start and the unaccounted remainder is printed as its own span, `render+present`. The
-//! first cut of this instrument closed the tape at the end of `Last` and silently reported a
-//! 506 ms frame as fitting inside 20 ms of `Main`.
+//! The total runs frame start to frame start, and the remainder after `Last` prints as
+//! `render+present`: the render sub-app, including pipelines compiled inline on the render
+//! thread, is invisible to every stamp inside `Main`.
 //!
 //! One line per slow frame, spans in the order they closed:
 //!
 //! ```text
-//! [phase] frame 1972 total=60.5ms  First=0.2 PreUpdate=1.1 StateTransition=8.9 … render+present=31.2
+//! [phase] frame 812 total=60.5ms  PreUpdate=1.1 StateTransition=8.9 … render+present=31.2
 //! ```
 //!
-//! Off unless `WOW_FRAME_PHASES` is set; `WOW_FRAME_PHASES=0` prints every frame.
+//! `WOW_FRAME_PHASES=0` prints every frame.
 
 use std::time::Instant;
 
@@ -44,15 +25,13 @@ use bevy::prelude::*;
 
 use benilla_world::schedule::WorldStage;
 
-/// The marker schedules spliced between the main ones. A tuple label rather than seven unit
-/// structs: the index IS the position, so the splice table below reads as the frame's shape.
+/// The marker schedules spliced between the main ones; the index is the position.
 #[derive(ScheduleLabel, Clone, Copy, Debug, PartialEq, Eq, Hash)]
 struct PhaseMark(u8);
 
-/// Where each mark is spliced, and what the *preceding* span is called. `None` = the frame's
-/// opening stamp (spliced before `First`), which names no span of its own.
+/// Each mark and the name of the span it closes; mark 0, before `First`, is the frame's t0.
 const MARKS: &[(u8, &str)] = &[
-    (0, ""), // before First — the frame's t0
+    (0, ""), // before First: the frame's t0
     (1, "First"),
     (2, "PreUpdate"),
     (3, "StateTransition"),
@@ -61,18 +40,18 @@ const MARKS: &[(u8, &str)] = &[
     (6, "Last"),
 ];
 
-/// The per-frame stamp tape. Read (and reported) at the NEXT frame's opening mark, so the
-/// render sub-app's share of this frame is inside the window — see the module doc.
+/// The per-frame stamp tape, reported at the next frame's opening mark so the render sub-app's
+/// share falls inside the window.
 #[derive(Resource)]
 struct Phases {
     /// Print a frame whose total exceeds this (ms).
     threshold_ms: f32,
-    /// `(span name, instant at its END)`, in frame order; the first entry is the frame's t0.
+    /// `(span name, instant at its end)`, in frame order; the first entry is the frame's t0.
     marks: Vec<(&'static str, Instant)>,
     frame: u64,
 }
 
-/// Is the instrument armed, and at what threshold? (Read once.)
+/// The armed threshold, read once.
 fn threshold() -> Option<f32> {
     static T: std::sync::OnceLock<Option<f32>> = std::sync::OnceLock::new();
     *T.get_or_init(|| {
@@ -93,9 +72,8 @@ pub(super) fn plugin(app: &mut App) {
         frame: 0,
     });
 
-    // Splice the marker schedules. `insert_before(First, …)` opens the frame; every other mark
-    // closes the schedule it is inserted after. `StateTransition` is inserted by `StatesPlugin`
-    // after `PreUpdate`, so it is in the list by the time this plugin builds.
+    // Mark 0 opens the frame; every other mark closes the schedule it follows. `StatesPlugin`
+    // has inserted `StateTransition` after `PreUpdate` by the time this plugin builds.
     {
         let mut order = app.world_mut().resource_mut::<MainScheduleOrder>();
         order.insert_before(First, PhaseMark(0));
@@ -110,8 +88,8 @@ pub(super) fn plugin(app: &mut App) {
         let (i, name) = (*i, *name);
         app.add_systems(PhaseMark(i), move |mut p: ResMut<Phases>| {
             if i == 0 {
-                // The previous frame closes HERE, not at the end of `Last`: everything between
-                // `Last` and this stamp is the render sub-app and the present.
+                // The previous frame closes here, not at the end of `Last`, so the render
+                // sub-app and the present fall inside it.
                 report(&mut p);
                 p.frame += 1;
                 p.marks.clear();
@@ -120,8 +98,7 @@ pub(super) fn plugin(app: &mut App) {
         });
     }
 
-    // The four `Update` stages, stamped as EXCLUSIVE systems so each stamp is a sync point and
-    // the span either side of it is the stage's own (see the module doc's perturbation note).
+    // Exclusive systems, so each stamp is a sync point and each span is its stage's own.
     app.add_systems(
         Update,
         (
@@ -149,10 +126,8 @@ fn stamp(name: &'static str) -> impl IntoSystem<(), (), ()> {
     })
 }
 
-/// Print the previous frame's tape if it was slow. Spans print in the order they closed, with
-/// the `Update` stages folded in where they fell — the marker-schedule `Update` entry then
-/// reports only what ran after `WorldStage::Present` — and the remainder between the end of
-/// `Last` and this call as `render+present`.
+/// Print the previous frame's tape if it was slow. The `Update` stages fold in where they fell,
+/// so the marker `Update` span is only what ran after `WorldStage::Present`.
 fn report(p: &mut Phases) {
     let Some((_, t0)) = p.marks.first().copied() else {
         return;
diff --git a/crates/benilla-app/src/perf/stall.rs b/crates/benilla-app/src/perf/stall.rs
index 756d02a8..8803d7dd 100644
--- a/crates/benilla-app/src/perf/stall.rs
+++ b/crates/benilla-app/src/perf/stall.rs
@@ -1,35 +1,20 @@
-//! The stuck-main-thread self-sampler (`WOW_STALL_SAMPLE=0` to disable; macOS only): a watchdog
-//! thread notices the main-thread heartbeat has gone stale and shells the stock profiler
-//! (`/usr/bin/sample`) at our own PID, so an intermittent stall or teardown hang **diagnoses
-//! itself the next time it happens** — on anyone's run, no reproduction needed. **Except while
-//! an audio device is open** (decision 1857): `sample` suspends every thread of the task,
-//! CoreAudio's realtime IO thread included, and each suspended cycle is a crackle — the one
-//! the director heard on every desktop switch and world entry, because those are exactly the
-//! ≥600 ms main-thread stalls this watchdog fires on. In-frame sampling now waits for a run
-//! nobody is listening to; `WOW_STALL_SAMPLE=force` opts a sounding run back in, knowingly. Two bugs that
-//! each lost their reproduction motivated it (decision 0713): the ~1 s silent frame stalls at
-//! the BWL pin, and the on-close beachball the director had to force-quit — where even the probe
-//! backstop's `process::exit(0)` can wedge, because libc `exit(3)` runs the same atexit teardown
-//! the hang may own. Samples land in `benilla-config/Diagnostics/` and the path prints on stderr
-//! (the tracing subscriber may already be gone during teardown).
+//! The stuck-main-thread self-sampler (macOS only; `WOW_STALL_SAMPLE=0` disables it): a watchdog
+//! thread sees the main-thread heartbeat go stale and runs `/usr/bin/sample` on our own PID, so a
+//! stall or teardown hang diagnoses itself on any run. Samples land in
+//! `benilla-config/Diagnostics/` and the path prints on stderr, since the tracing subscriber may
+//! be gone during teardown.
 //!
-//! After a teardown sample, an [`EXIT_KILL_MS`] backstop `_exit` ends the wedged process —
-//! diagnosis first, then the force-quit the director would otherwise perform by hand.
-//! `libc::_exit`, never `process::exit`: it skips the atexit handlers. It exits with the code
-//! [`AppExit`] asked for, not a blanket 0 — a capture that already failed its own deadline must
-//! not be laundered into a success by the thing that unwedges it.
+//! In-frame sampling is skipped while an audio device is open: `sample` suspends every thread,
+//! the audio IO thread included, and each suspension is a crackle. `WOW_STALL_SAMPLE=force`
+//! samples anyway.
 //!
-//! **The backstop is not a diagnostic, and it runs where the samples cannot.** A hermetic capture
-//! run has no `benilla-config/` to write into ([`crate::local_state::home`] returns `None` under
-//! `$WOW_CAPTURE`), and for one day in 1631 that turned the whole plugin off for exactly the runs
-//! that most need a liveness guarantee — an agent-driven run with nobody watching it. So the split
-//! is by concern, not by run: the watchdog thread and its `_exit` always run; the sample *file* is
-//! written only where there is a folder that may hold one. Decision 1637.
+//! After a teardown sample, an [`EXIT_KILL_MS`] backstop `libc::_exit`s the wedged process with
+//! the code [`AppExit`] asked for; `_exit` skips the atexit teardown the hang may own. The
+//! watchdog and its backstop always run; the sample file is written only where
+//! `benilla-config/` exists, never under `$WOW_CAPTURE`.
 //!
-//! Verification is end-to-end via two injectors (used by the 0713 probe rounds, kept as standing
-//! test affordances): `WOW_STALL_INJECT=<at_secs>:<ms>` sleeps the main thread mid-run, and
-//! `WOW_TEARDOWN_INJECT=<ms>` wedges World drop via a resource whose `Drop` sleeps — the
-//! director's beachball, synthetically.
+//! Two injectors test it end to end: `WOW_STALL_INJECT=<at_secs>:<ms>` sleeps the main thread
+//! mid-run, and `WOW_TEARDOWN_INJECT=<ms>` wedges World drop.
 
 use std::sync::atomic::{AtomicBool, AtomicU64, AtomicU8, Ordering};
 use std::sync::OnceLock;
@@ -38,32 +23,26 @@ use std::time::{Duration, Instant};
 use bevy::prelude::*;
 use bevy::time::Real;
 
-/// The monotonic epoch every heartbeat is measured against. `Instant`, not `SystemTime`:
-/// a wall-clock step (NTP) must not fake a stall — an instrument that lies once is poison.
+/// The monotonic epoch of every heartbeat, so a wall-clock step cannot fake a stall.
 static START: OnceLock<Instant> = OnceLock::new();
-/// Last main-thread heartbeat, ms since [`START`]. 0 = no full frame yet, watchdog stays
-/// quiet — startup (shader compiles, first loads) never false-positives.
+/// Last main-thread heartbeat, ms since [`START`]; 0 until the first full frame, and the
+/// watchdog stays quiet until then.
 static HEARTBEAT_MS: AtomicU64 = AtomicU64::new(0);
 /// Latched the frame `AppExit` is written: switches the watchdog to the teardown threshold
 /// and arms the post-sample `_exit` backstop.
 static EXITING: AtomicBool = AtomicBool::new(false);
-/// The status `AppExit` asked to exit with, latched alongside [`EXITING`] so the backstop can
-/// honour it. A wedged teardown must not turn a failed run into a passing one — which is exactly
-/// what a blanket `_exit(0)` would do to the capture deadline (`capture::deadline`).
+/// The status `AppExit` asked for, so the backstop never turns a failed run into a passing one.
 static EXIT_CODE: AtomicU8 = AtomicU8::new(0);
 
-/// In-frame staleness that means a real stall (ms) — above the ~250 ms loading-screen
-/// hitches, below the ~1030 ms stall class it exists to catch.
+/// In-frame staleness that means a real stall (ms), above the ~250 ms loading-screen hitches.
 const STALL_MS: u64 = 600;
-/// In-frame sampling stays disarmed this long after launch: startup/login legitimately
-/// stalls past [`STALL_MS`] (a 683 ms hitch at 1.7 s uptime, caught by the 0713 pristine-run
-/// gate), and the classes this instrument hunts are steady-state. Teardown is unaffected.
+/// In-frame sampling stays disarmed this long after launch, since startup legitimately stalls
+/// past [`STALL_MS`]; teardown is unaffected.
 const STARTUP_GRACE_MS: u64 = 15_000;
-/// Post-`AppExit` staleness that means teardown is wedged, not merely slow (ms). A clean
-/// teardown is sub-second (26/26 measured exit cycles); the probe hard-exit backstop sits
-/// at 5 s, so a 2.5 s trigger + 2 s capture completes before it.
+/// Post-`AppExit` staleness that means teardown is wedged (ms); with a 2 s sample it finishes
+/// inside the probe's 5 s hard-exit backstop.
 const EXIT_STALL_MS: u64 = 2_500;
-/// Teardown backstop: still alive this long after `AppExit` (sample already taken) → `_exit`.
+/// Teardown backstop: still alive this long after `AppExit`, the process `_exit`s.
 const EXIT_KILL_MS: u64 = 8_000;
 /// Rate limit: at most this many samples per run, at least [`SAMPLE_GAP_MS`] apart.
 const SAMPLE_CAP: u32 = 5;
@@ -73,8 +52,7 @@ fn since_start_ms() -> u64 {
     START.get().map_or(0, |s| s.elapsed().as_millis() as u64)
 }
 
-/// `Last`-schedule heartbeat: stamp the clock; latch [`EXITING`] the frame the app decides
-/// to quit (no later frame will run to unlatch anything).
+/// `Last`-schedule heartbeat; latches [`EXITING`] the frame the app decides to quit.
 fn beat(mut exits: MessageReader<AppExit>) {
     if let Some(exit) = exits.read().next() {
         if let AppExit::Error(code) = exit {
@@ -86,24 +64,13 @@ fn beat(mut exits: MessageReader<AppExit>) {
 }
 
 pub(super) fn plugin(app: &mut App) {
-    // The injectors are armed FIRST, deliberately: they are how the wedge is reproduced, and the
-    // one A/B this instrument exists to support is "same wedge, watchdog off — does the process
-    // still hang?". Registered after the `WOW_STALL_SAMPLE=0` gate, as they were until 1637, that
-    // control silently disarms the wedge too and comes back a clean exit 0, which reads as "the
-    // watchdog was never load-bearing" — the exact wrong conclusion. Arming a deliberate hang is
-    // never something the sampler's off-switch should be able to veto.
+    // Armed before the off-switch, so "same wedge, watchdog off" still wedges.
     arm_injectors(app);
     if std::env::var("WOW_STALL_SAMPLE").is_ok_and(|v| v == "0") {
         return;
     }
-    // Through `local_state`, never a hand-built path — the one-folder rule. This used to read
-    // `$HOME` and write `~/Library/Logs/benilla/`; see `local_state::diagnostics_dir`. `None` is a
-    // hermetic capture run, which gets **no sample file and the watchdog anyway** — see the header:
-    // 1631 returned here instead and cost every capture its teardown backstop.
-    //
-    // The folder is NOT created here: an empty `Diagnostics/` on every single run would be this
-    // instrument advertising itself in the player's folder for the ~always-case where nothing ever
-    // stalls. The watchdog creates it at the moment it actually has a sample to write.
+    // `None` on a hermetic capture, which still gets the watchdog. The folder is created only
+    // when there is a sample to write.
     let dir = crate::local_state::diagnostics_dir();
     START
         .set(Instant::now())
@@ -115,8 +82,7 @@ pub(super) fn plugin(app: &mut App) {
         .expect("spawn stall-sample watchdog");
 }
 
-/// The injectors (module doc): a mid-run main-thread sleep, and a wedged World drop. Both are
-/// standing test affordances, not diagnostics — see why they are armed ahead of the off-switch.
+/// The injectors: a mid-run main-thread sleep, and a wedged World drop.
 fn arm_injectors(app: &mut App) {
     if let Some((at, ms)) = std::env::var("WOW_STALL_INJECT")
         .ok()
@@ -135,9 +101,7 @@ fn arm_injectors(app: &mut App) {
             app.insert_resource(TeardownWedge(ms));
         }
     }
-    // The third standing injector — `crash::arm_injector`, a deliberate main-thread panic — is
-    // armed by `PerfPlugin` itself, beside this plugin's registration, not from here: this
-    // module is macOS-only and the crash injector is not (its doc has the cross-platform incident).
+    // The crash injector is armed by `PerfPlugin`, not here: this module is macOS-only.
 }
 
 fn watchdog(dir: Option<std::path::PathBuf>) {
@@ -166,35 +130,25 @@ fn watchdog(dir: Option<std::path::PathBuf>) {
             );
             use std::io::Write;
             let _ = std::io::stdout().flush();
-            // SAFETY: terminates the process immediately; no locks, no atexit — the whole
-            // point, since the wedge may own both.
+            // SAFETY: terminates the process at once, taking no locks and running no atexit
+            // handlers, which the wedge may own.
             unsafe { libc::_exit(code as i32) };
         }
         let age = now.saturating_sub(hb);
         if !exiting && now < STARTUP_GRACE_MS {
             continue;
         }
-        // `dir` is `None` on a hermetic capture: everything above still runs (the backstop is this
-        // thread's other, unconditional job), there is just nowhere to put a sample.
+        // On a hermetic capture the backstop above still runs; there is nowhere to put a sample.
         let Some(dir) = dir.as_deref() else { continue };
         let threshold = if exiting { EXIT_STALL_MS } else { STALL_MS };
         if age > threshold
             && taken < SAMPLE_CAP
-            // The gap gates *between* samples only — gating the first one against
-            // `last_sample_ms = 0` would silently forbid any sample in the first
-            // [`SAMPLE_GAP_MS`] of process uptime (caught by the 0713 injector runs).
+            // The gap gates between samples only, or no sample could land in the first
+            // `SAMPLE_GAP_MS` of uptime.
             && (taken == 0 || now.saturating_sub(last_sample_ms) > SAMPLE_GAP_MS)
         {
-            // **Never while the speakers are live** (decision 1857). `sample` suspends the whole
-            // task for each of its ~1000 snapshots — the CoreAudio IO thread and our realtime
-            // render thread included — and coreaudiod times the client out: every stall this
-            // watchdog sampled in a run with a device open was also a crackle ("client timeout"
-            // × 4 per manual sample, zero overloads across 25 hitches with the sampler off).
-            // 1232 cleared the sampler on a quiet-machine measurement of the hole; under real
-            // load the hole is the sample. The instrument keeps its whole job on the runs that
-            // cannot be heard (captures, probes, `WOW_NOSOUND` — no device is open there) and
-            // at teardown, where the wedge outranks the last half-second of sound.
-            // `WOW_STALL_SAMPLE=force` overrides for a deliberate diagnostic run with sound.
+            // Not while an audio device is open: `sample` suspends the audio IO thread and the
+            // sound server times the client out, a crackle. Teardown samples regardless.
             if !exiting && crate::sound::output::device_open() && !force {
                 if !declined {
                     eprintln!(
@@ -223,8 +177,8 @@ fn watchdog(dir: Option<std::path::PathBuf>) {
                 if exiting { " (teardown)" } else { "" },
                 file.display()
             );
-            // 1 s in-frame so the stall dominates its own capture (a ~1 s stall in a 2 s
-            // window is half idle); 2 s for teardown, where the wedge holds the whole time.
+            // 1 s in-frame so the stall dominates the capture; 2 s at teardown, where the wedge
+            // holds throughout.
             let _ = std::process::Command::new("/usr/bin/sample")
                 .arg(&pid)
                 .arg(if exiting { "2" } else { "1" })
@@ -235,7 +189,7 @@ fn watchdog(dir: Option<std::path::PathBuf>) {
     }
 }
 
-/// `WOW_STALL_INJECT=<at_secs>:<ms>` — one deliberate main-thread sleep, mid-run.
+/// `WOW_STALL_INJECT=<at_secs>:<ms>`: one deliberate main-thread sleep, mid-run.
 #[derive(Resource)]
 struct StallInject {
     at: f32,
@@ -251,8 +205,8 @@ fn stall_inject(mut inject: ResMut<StallInject>, time: Res<Time<Real>>) {
     }
 }
 
-/// `WOW_TEARDOWN_INJECT=<ms>` — wedge World drop: this resource's `Drop` runs on the main
-/// thread during `App` teardown and sleeps there, reproducing the beachball synthetically.
+/// `WOW_TEARDOWN_INJECT=<ms>`: this resource's `Drop` sleeps on the main thread during `App`
+/// teardown, wedging World drop.
 #[derive(Resource)]
 struct TeardownWedge(u64);
 
diff --git a/crates/benilla-app/src/perf/stats.rs b/crates/benilla-app/src/perf/stats.rs
index 6041e462..9c9ef971 100644
--- a/crates/benilla-app/src/perf/stats.rs
+++ b/crates/benilla-app/src/perf/stats.rs
@@ -1,15 +1,7 @@
 //! The frame-cost meters the pill reads: a rolling window each of wall frame time and process
 //! CPU per frame.
-//!
-//! **The law (0717): while synced, wall frame time measures the display's present grant, not our
-//! cost.** Only the CPU series measures work — it is the pill's headline. `wall` exists for the
-//! dim fps anchor and the hitch log below, nothing else.
-//!
-//! This file used to carry a per-series spike latch (0610's burst detector) and the
-//! median baselines it tested against; both left with their last surface — the pill's arrow
-//! (1455, after 1454 removed the expanded panel). The standing stall record is the
-//! `frame hitch` warn below plus the self-sampler ([`super::stall`]); burst-shaped analysis
-//! belongs to the instruments (the journal, the probes, Tracy).
+//! While synced, wall frame time measures the display's present grant, not our cost, so the CPU
+//! series is the pill's headline and `wall` only feeds the dim fps and the hitch log.
 
 use std::collections::VecDeque;
 
@@ -21,8 +13,7 @@ use super::clock::{main_thread_cpu_secs, process_cpu_secs};
 /// Recent frames kept for the pill's windowed means (~5 s at 60 fps, ~2.5 s at 120).
 pub(super) const SAMPLE_WINDOW: usize = 300;
 
-/// Frame duration above which a frame is logged as a hitch (a stall the player feels). Far above
-/// any present interval so it only fires on real stalls (load bursts), not normal jitter.
+/// Frame duration above which a frame is logged as a hitch, far above any present interval.
 const HITCH_LOG_MS: f32 = 250.0;
 
 /// A rolling window of one cost series, in milliseconds, capped at its own length.
@@ -51,27 +42,22 @@ impl Series {
         self.samples.len()
     }
 
-    /// Windowed mean. `None` on an empty window, so a caller can tell "no data" from "zero cost".
+    /// Windowed mean; `None` on an empty window tells "no data" from "zero cost".
     pub(super) fn mean(&self) -> Option<f32> {
         (!self.samples.is_empty())
             .then(|| self.samples.iter().sum::<f32>() / self.samples.len() as f32)
     }
 }
 
-/// The per-frame cost meters.
-///
-/// `Clone` is for the HUD's 4 Hz snapshot (`PerfHud::maybe_refresh`) — a few hundred floats,
-/// four times a second.
+/// The per-frame cost meters; `Clone` is for the HUD's 4 Hz snapshot.
 #[derive(Resource, Clone)]
 pub(super) struct FrameStats {
-    /// Wall frame interval. The grant while synced; our real cost only when uncapped.
+    /// Wall frame interval: the present grant while synced, our cost only when uncapped.
     pub(super) wall: Series,
-    /// Process CPU per frame, user+system across every thread (`getrusage`) — the campaign's
-    /// currency (0736) and the meter the rail cannot fool (0717).
+    /// Process CPU per frame, user+system across every thread (`getrusage`).
     pub(super) cpu: Series,
     prev_cpu_secs: Option<f64>,
-    /// The MAIN thread's CPU per frame — the part of the frame the player can feel: the wall
-    /// the schedule runs on. Sampled pinned (`sample_frame_time`'s `NonSendMarker`).
+    /// The main thread's CPU per frame, sampled pinned to that thread.
     pub(super) main: Series,
     prev_main_secs: Option<f64>,
 }
@@ -89,9 +75,7 @@ impl Default for FrameStats {
 }
 
 impl FrameStats {
-    /// Windowed mean frames per second. A mean, and labelled as one — it is the number that
-    /// cannot see cost (0717), which is why the pill draws it dim and small, never as the
-    /// headline.
+    /// Windowed mean frames per second; it cannot see cost, so the pill draws it dim.
     pub(super) fn fps(&self) -> f32 {
         match self.wall.mean() {
             Some(mean) if mean > 0.0 => 1000.0 / mean,
@@ -99,17 +83,15 @@ impl FrameStats {
         }
     }
 
-    /// Drive the meters from a sibling module's test, on the same path [`sample_frame_time`]
-    /// takes minus the clocks. Each frame is `(wall_ms, cpu_ms)`; returns the clock it left off
-    /// at. `hud`'s snapshot test needs a realistically-populated `FrameStats`.
+    /// Feed `(wall_ms, cpu_ms)` frames without the clocks, for tests; returns the clock it left
+    /// off at.
     #[cfg(test)]
     pub(super) fn feed_frames(&mut self, frames: &[(f32, f32)], start_t: f32, dt: f32) -> f32 {
         let mut t = start_t;
         for &(wall, cpu) in frames {
             self.wall.push(wall);
             self.cpu.push(cpu);
-            // The fixture's main-thread share: a fixed fraction of the sum, so a test can tell
-            // the two apart without a second column.
+            // A fixed main-thread share, so a test can tell the two series apart.
             self.main.push(cpu * 0.5);
             t += dt;
         }
@@ -119,7 +101,7 @@ impl FrameStats {
 
 /// Sample both meters for this frame.
 pub(super) fn sample_frame_time(
-    // Pinned to the main thread: `main_thread_cpu_secs` reads the CALLING thread's clock.
+    // Pinned to the main thread: `main_thread_cpu_secs` reads the calling thread's clock.
     _pin: bevy::ecs::system::NonSendMarker,
     time: Res<Time<Real>>,
     mut stats: ResMut<FrameStats>,
@@ -138,8 +120,7 @@ pub(super) fn sample_frame_time(
     }
     stats.prev_main_secs = main;
 
-    // Log hard hitches so a load freeze is attributable from the log alone (one big stall vs many
-    // medium ones, and roughly when). The first frame's delta is the startup gap, not a hitch.
+    // The first frame's delta is the startup gap, not a hitch.
     if wall_ms > HITCH_LOG_MS && stats.wall.len() > 1 {
         warn!("frame hitch: {wall_ms:.0} ms (main thread blocked this long)");
     }
@@ -149,8 +130,6 @@ pub(super) fn sample_frame_time(
 mod tests {
     use super::*;
 
-    /// The window is capped and the means are windowed: 300 quiet frames after 100 loud ones
-    /// must read quiet, and fps must be the reciprocal of the windowed wall mean.
     #[test]
     fn the_windows_roll_and_the_means_are_windowed() {
         let mut s = FrameStats::default();
@@ -173,7 +152,6 @@ mod tests {
         );
     }
 
-    /// An empty cpu window is "no data", not "zero cost" — the pill prints `--` for it.
     #[test]
     fn no_data_is_not_zero_cost() {
         let s = FrameStats::default();
diff --git a/crates/benilla-app/src/perf/trace.rs b/crates/benilla-app/src/perf/trace.rs
index 7d16a7fd..bd9fc29f 100644
--- a/crates/benilla-app/src/perf/trace.rs
+++ b/crates/benilla-app/src/perf/trace.rs
@@ -1,35 +1,30 @@
-//! The STREAM TRACE (`WOW_STREAM_TRACE=<csv path>`) — B181's instrument.
+//! The stream trace (`WOW_STREAM_TRACE=<csv path>`): a CSV row per frame of terrain streaming.
 
 use bevy::prelude::*;
 use bevy::time::Real;
 
 use super::clock::process_cpu_secs;
 
-/// A frame past this is logged even with no streamer activity — catches a spike whose cost lands
-/// outside the Stream chain (command application, render extraction, asset frees frames later).
+/// A frame past this is logged even with no streamer activity, for a cost that lands outside
+/// the Stream chain (command application, render extraction, later asset frees).
 const TRACE_FRAME_MS: f32 = 25.0;
-/// Frames still logged after the last streamer event: the despawn commands apply after the system,
-/// the asset frees land when the last handle drops, and the render world reacts a frame later —
-/// the tail is where the cost shows, so the window must outlive the event.
+/// Frames still logged after the last streamer event: despawns, asset frees and the render
+/// world's reaction all land after the event itself.
 const TRACE_TAIL_FRAMES: u64 = 10;
 
-/// One row per frame in which the terrain streamer did anything (plus a [`TRACE_TAIL_FRAMES`]
-/// tail, plus any frame over [`TRACE_FRAME_MS`]): what was dropped/requested/spawned, the Stream
-/// chain's own self-times, and the frame's wall delta beside it. **The off-by-one to remember
-/// reading it: `delta_ms` on a row is the interval that *ended* at this frame's start, so frame N's
-/// cost appears in row N+1.**
+/// One row per frame in which the terrain streamer did anything, plus a [`TRACE_TAIL_FRAMES`]
+/// tail and any frame over [`TRACE_FRAME_MS`]. A row's `delta_ms` is the interval that ended at
+/// this frame's start, so frame N's cost appears in row N+1.
 #[derive(Resource)]
 pub(super) struct StreamTrace {
     pub(super) path: String,
     pub(super) frame: u64,
     pub(super) log_until: u64,
-    /// [`process_cpu_secs`] at the previous frame — the row's `cpu_ms` is this frame's process-CPU
-    /// delta (user+system, all threads): the load-robust cost meter beside the wall delta, because
-    /// on this machine wall frame time moves with whoever else is compiling (0711; a parallel
-    /// build polluted this instrument's first A/B).
+    /// [`process_cpu_secs`] at the previous frame; `cpu_ms` is the process-CPU delta (user+system,
+    /// all threads), a cost meter that other load on the machine does not move.
     pub(super) prev_cpu_secs: Option<f64>,
-    /// `PipeWatch::created` at the previous frame, so `pipes_new` is per-frame like every other
-    /// counter (the render world bumps the shared atomic; ±1 frame skew is inherent and fine).
+    /// `PipeWatch::created` at the previous frame, so `pipes_new` is per-frame (±1 frame skew,
+    /// since the render world bumps the shared atomic).
     pub(super) prev_pipes_created: usize,
 }
 
@@ -49,7 +44,7 @@ pub(super) fn trace_stream(
     mut image_events: MessageReader<bevy::asset::AssetEvent<bevy::image::Image>>,
     pipes: Res<crate::pipe_warm::PipeWatch>,
 ) {
-    // Taken every frame — the counters are per-frame by contract, tracing or not.
+    // Taken every frame, tracing or not: the counters are per-frame by contract.
     let a = std::mem::take(&mut *activity);
     let pipes_created = pipes.0.created.load(std::sync::atomic::Ordering::Relaxed);
     let pipes_settled = pipes.0.settled.load(std::sync::atomic::Ordering::Relaxed);
@@ -66,15 +61,9 @@ pub(super) fn trace_stream(
         _ => String::new(),
     };
     trace.prev_cpu_secs = cpu_now;
-    // One pass per reader: `Added` beside `Unused` — B181's recurring spike was the free wave's
-    // family, but the first-contact head frame is the ADD wave (a landed tile's cell meshes +
-    // texture arrays hitting the render world's prepare at once), invisible until counted.
-    //
-    // The freed columns count `Unused` (last strong handle dropped), not `Removed`: a
-    // `RENDER_WORLD`-only asset (chunk-cell meshes, the tile arrays — decision 0832) leaves the
-    // main store at *extract* via the untracked path, so `Removed` never fires for it; `Unused`
-    // is the release signal both usage kinds emit exactly once, and it is what actually frees
-    // the GPU copy.
+    // The freed columns count `Unused`, not `Removed`: a `RENDER_WORLD`-only asset leaves the
+    // main store at extract untracked, so `Removed` never fires for it, while `Unused` fires once
+    // for both usage kinds and is what frees the GPU copy.
     fn count_events<A: bevy::asset::Asset>(
         events: &mut MessageReader<bevy::asset::AssetEvent<A>>,
     ) -> (u32, u32) {
diff --git a/crates/benilla-app/src/pipe_warm/menagerie.rs b/crates/benilla-app/src/pipe_warm/menagerie.rs
index 3af254a1..40a9e4ec 100644
--- a/crates/benilla-app/src/pipe_warm/menagerie.rs
+++ b/crates/benilla-app/src/pipe_warm/menagerie.rs
@@ -1,9 +1,5 @@
-//! The menagerie — `pipe_warm`'s warm-set builder: one tiny rig per reachable pipeline variant,
-//! spawned behind the entry cover by [`super::run_warm_pass`]. The watch/tripwire half (and the
-//! why of the whole pass) lives in the parent module; this file owns WHAT gets warmed — the
-//! model lane and its derived keys, the sky/water lanes, the plain-`StandardMaterial` lanes,
-//! and the portrait-booth samples=1 twins — plus the lane-coverage gate test that keeps a new
-//! material lane from shipping unwarmed (decisions 0837 / 0937 / 0938).
+//! The menagerie, `pipe_warm`'s warm set: one tiny rig per reachable pipeline variant, and the
+//! lane-coverage tests that keep a new lane from shipping unwarmed.
 
 use benilla_formats::{FogPolicy, ModelBlend, RenderSubmesh};
 use bevy::asset::RenderAssetUsages;
@@ -24,27 +20,14 @@ use benilla_world::sun::{CelestialMaterial, StarMaterial};
 use super::WarmRig;
 
 // --------------------------------------------------------------------------------------------
-// The warm pass — the fix half of 0837, widened by 0937.
-//
-// The 0837 inventory (pipes1.log) showed the model lane's REACHABLE pipeline space is small once
-// the batch-order axis left the key: 4 vertex layouts × the blend/depth-flag families, ~28
-// observed in a wilderness-to-Stormwind leg. 0937 added the spaces 0837 left out — the
-// shard-rung buckets and far-side-of-water twins of that same model lane, and the sky/water
-// lanes (celestial discs/glares, stars, cloud dome, gradient dome, WMO skybox, liquid), each of
-// which had fired the tripwire as a director-felt live stall. The menagerie below compiles the
-// whole space behind the entry loading cover — one 1 cm rig per variant, parented to the world
-// camera (the camera renders under the cover, 0540, so every rig's draw queues its pipeline
-// through the production specialize path), the cover held (via `WarmPass::satisfied` in the
-// loading screen's clear condition) until the cache drains, then the rigs despawn. A variant
-// this misses shows up as the tripwire's "compiled LIVE" warn — extend the loops, don't guess.
+// The warm set: the model lane (4 vertex layouts by the blend and depth-flag families), its
+// shard-rung and far-side-of-water twins, and the sky and water lanes. Each rig is 1 cm on a
+// camera that renders under the cover, so its draw queues its pipeline through the production
+// specialize path. A variant this misses shows as the tripwire's "compiled LIVE" warn.
 
-/// The sky/water lanes' material stores, grouped so [`run_warm_pass`] stays under Bevy's
-/// system-param arity. Every store here is populated at `Startup` by its own subsystem (the
-/// celestial rig, the star dome, the cloud dome, the gradient dome, the liquid frame sets), so
-/// by the time the menagerie spawns behind the entry cover, iterating the store IS the complete
-/// reachable set — warming can never drift from what's spawned. The one exception is the WMO
-/// skybox, whose materials are built on first need; since decision 1264 it is not a lane of its own
-/// at all but a cross of `WowModelMaterial` keys, warmed with the model cross below.
+/// The lanes' material stores, bundled for [`run_warm_pass`]'s arity. The sky and water stores
+/// are complete at `Startup`, so iterating them is the reachable set; the WMO skybox is a cross of
+/// `WowModelMaterial` keys, warmed with the model cross.
 #[derive(SystemParam)]
 pub(super) struct WarmLanes<'w> {
     celestial: ResMut<'w, Assets<CelestialMaterial>>,
@@ -52,31 +35,20 @@ pub(super) struct WarmLanes<'w> {
     clouds: ResMut<'w, Assets<CloudMaterial>>,
     sky: ResMut<'w, Assets<SkyMaterial>>,
     liquid: ResMut<'w, Assets<LiquidMaterial>>,
-    /// The plain-`StandardMaterial` lanes (0938): representatives for the on-demand nameplate
-    /// and raid-mark materials go through this store the way their builders do.
+    /// For representatives of the on-demand nameplate and raid-mark materials.
     standard: ResMut<'w, Assets<StandardMaterial>>,
-    /// The fallback cube (0938): production mesh + materials, drawn while a model streams.
+    /// The fallback cube: production mesh + materials, drawn while a model streams.
     cubes: Option<Res<'w, crate::entities::CubeAssets>>,
-    /// The image store (0958): the twin booth's render target and the effect-lane warm's
-    /// stand-in texture are created here for the life of the pass.
+    /// For the twin booth's render target and the stand-in textures.
     pub(super) images: ResMut<'w, Assets<Image>>,
-    /// The UI quad store (2262): the minimap interior composite's tile material is built here
-    /// through its own production builder, for the tile-quad warm rig below.
+    /// For the minimap interior composite's tile material, through its production builder.
     ui_quads: ResMut<'w, Assets<crate::ui_pass::UiQuadMaterial>>,
 }
 
-/// One portrait/paperdoll booth camera + its layer ([`crate::portrait`], 0938): the booths run
-/// `Msaa::Off`, so every model-lane pipeline has a samples=1 twin that otherwise compiles live
-/// on the first in-world portrait (the first click-target). The booth cameras exist from
-/// `Startup` and render during the warm window (the demand gate counts the pass as demand), so
-/// menagerie rigs duplicated onto ONE booth's layer compile that twin space behind the cover —
-/// the view shape (HDR, no tonemap, the glow node) is otherwise the world camera's, leaving TWO
-/// twin axes: samples, and the projection CLASS (0958). A real booth carries the Perspective
-/// placeholder until its first bake installs `Projection::custom(WowPortraitProjection)` — a
-/// distinct bevy_pbr view key — so the rigs are ALSO duplicated onto the pass's own twin booth
-/// ([`crate::portrait::spawn_warm_booth`]), which is that custom-projection space; 0938 warmed
-/// only the placeholder class, and the whole samples=1 space compiled again, live, on the first
-/// target portrait.
+/// A portrait booth camera and its layer. Booths run `Msaa::Off`, so each model pipeline has a
+/// samples=1 twin per projection class: a real booth's Perspective placeholder, and the custom
+/// projection its first bake installs, which the twin booth
+/// ([`crate::portrait::spawn_warm_booth`]) carries.
 pub(super) type BoothCamQuery<'w, 's> = Query<
     'w,
     's,
@@ -84,14 +56,9 @@ pub(super) type BoothCamQuery<'w, 's> = Query<
     With<crate::portrait::BoothCam>,
 >;
 
-/// Spawn one tiny quad per reachable pipeline variant — the model lane, its shard-rung and
-/// far-side-of-water twins, and the sky/water lanes (decision 0945 widened 0837's model-only
-/// scope) — parented to the world camera. Materials come from the PRODUCTION builders
-/// (`model_material` / `zfill_material` / `far_twin_of`) or the PRODUCTION live asset stores
-/// (celestial, stars, clouds, gradient dome, liquid — all populated at `Startup`), so the
-/// variant encoding can never drift from the real spawn paths; meshes from the production
-/// submesh builders (or their attribute-exact stand-ins) so the vertex layouts can't either.
-/// Returns the entity count.
+/// Spawn one tiny quad per reachable pipeline variant and return the count. Materials come from
+/// the production builders or live stores and meshes from the production builders, so neither
+/// can drift from the real spawn paths.
 pub(super) fn spawn_menagerie(
     commands: &mut Commands,
     cam: Entity,
@@ -104,10 +71,8 @@ pub(super) fn spawn_menagerie(
     cache: &mut MaterialCache,
     light: &Buffer,
 ) -> usize {
-    // The four vertex layouts the model lane ships (0837 dump: strides 32/48/56/72): static ×
-    // {plain, vertex-colours} and their skinned twins. Statics are RENDER_WORLD-only, so their
-    // Aabb is computed here and inserted explicitly (0832's rule); skinned twins keep main-world
-    // data and `calculate_bounds` covers them.
+    // The model lane's four layouts (strides 32/48/56/72): static and skinned, plain and
+    // vertex-coloured. Statics are render-world-only, so their Aabb is inserted explicitly.
     let mut layouts: Vec<(Handle<Mesh>, Option<bevy::camera::primitives::Aabb>, bool)> = Vec::new();
     for colors in [false, true] {
         let stat = benilla_assets::submesh_to_static_mesh(&warm_quad(colors, false));
@@ -117,14 +82,10 @@ pub(super) fn spawn_menagerie(
         layouts.push((meshes.add(skin), None, true));
     }
 
-    // The material families. The full cross is deliberate: every branch here is authorable in an
-    // M2/WMO (blends, the 0x10/0x08 depth flags, sidedness), and an over-warmed variant costs
-    // milliseconds behind a loading bar once per run, while a missed one is a director-felt live
-    // stall. The observed set (28) is the floor, not the target.
+    // The full cross is deliberate: every branch is authorable in an M2 or WMO (blends, the
+    // 0x10/0x08 depth flags, sidedness).
     let mut mats: Vec<Handle<WowModelMaterial>> = Vec::new();
-    // The sky lane is kept apart from `mats`: it rides the STATIC layout only and is never
-    // far-twinned (a camera-anchored backdrop has no side of the water plane —
-    // `model_render::classify_water_side` skips it) nor booth-duplicated (no portrait sees a sky).
+    // The sky lane stays apart: static layout only, never far-twinned or on a booth.
     let mut sky_mats: Vec<Handle<WowModelMaterial>> = Vec::new();
     for two_sided in [false, true] {
         for blend in [
@@ -150,8 +111,7 @@ pub(super) fn spawn_menagerie(
                         no_depth_write,
                         no_depth_test,
                         FogPolicy::Scene,
-                        // Not a `WowModelKey` axis (it swaps a sampled UV, not pipeline state), so
-                        // warming one side warms both.
+                        // Not a `WowModelKey` axis: it swaps a sampled UV, not pipeline state.
                         false,
                         ShadeSel::Lit,
                         0,
@@ -160,22 +120,17 @@ pub(super) fn spawn_menagerie(
                         None,
                         None,
                         false,
-                        false, // warms the WORLD lane; the sky lane warms with its own model
+                        false, // the world lane
                         light,
-                        // The pipeline menagerie warms the SHARED batch material; the
-                        // per-placement lane (1408) builds an identical pipeline, so a clone
-                        // needs no row of its own here.
+                        // The shared batch material; a per-placement clone has the same
+                        // pipeline.
                         None,
                     ));
                 }
             }
         }
-        // The additive glow-card blend state (specialize's pure ONE/ONE add) and the
-        // doodad/entity distance-fade blend twin, each over the FULL depth-flag cross: the
-        // production builders forward the source batch's 0x10/0x08 flags verbatim into both
-        // (`assemble.rs` / `display.rs` / `particles/model.rs`), so every combination is
-        // authorable — 0938 pinned the additive rows' depth-test and the fade row's both flags
-        // false, and the sweep behind 0958 found the pinned keys reachable.
+        // The additive glow-card blend and the distance-fade blend, each over the full
+        // depth-flag cross: the builders forward the batch's 0x10/0x08 flags into both.
         for additive_not_fade in [true, false] {
             for no_depth_write in [false, true] {
                 for no_depth_test in [false, true] {
@@ -193,8 +148,7 @@ pub(super) fn spawn_menagerie(
                         no_depth_write,
                         no_depth_test,
                         FogPolicy::Scene,
-                        // Not a `WowModelKey` axis (it swaps a sampled UV, not pipeline state), so
-                        // warming one side warms both.
+                        // Not a `WowModelKey` axis: it swaps a sampled UV, not pipeline state.
                         false,
                         ShadeSel::Lit,
                         0,
@@ -203,11 +157,8 @@ pub(super) fn spawn_menagerie(
                         None,
                         None,
                         false,
-                        false, // warms the WORLD lane; the sky lane warms with its own model
+                        false, // the world lane
                         light,
-                        // The pipeline menagerie warms the SHARED batch material; the
-                        // per-placement lane (1408) builds an identical pipeline, so a clone
-                        // needs no row of its own here.
                         None,
                     ));
                 }
@@ -219,14 +170,9 @@ pub(super) fn spawn_menagerie(
                 cache, materials, None, two_sided, cutout, light,
             ));
         }
-        // The **WMO-skybox lane** (decision 1264): `sky_depth` is a `WowModelKey` axis — it
-        // compiles the shader's forced-far-depth branch — so every skybox batch is a pipeline the
-        // world cross above does not cover, however identical the rest of its key. Built exactly
-        // the way `M2BatchMaterials::skybox` builds them: depth-write pinned off, depth-test
-        // pinned on, the batch's own blend and sidedness. `CavernsOfTimeSky.m2` authors Opaque,
-        // AlphaTest, Blend and additive-Blend across both sidednesses; Mod/Mod2x are warmed too
-        // because nothing stops a skybox authoring them. Unwarmed, walking into the Caverns of
-        // Time crater is 21 live compiles in the frame the sky appears.
+        // The WMO-skybox lane: `sky_depth` is a `WowModelKey` axis (the forced-far-depth branch).
+        // Built as `M2BatchMaterials::skybox` builds it: depth-write off, depth-test on, every
+        // blend and sidedness.
         for blend in [
             ModelBlend::Opaque,
             ModelBlend::AlphaTest,
@@ -243,11 +189,11 @@ pub(super) fn spawn_menagerie(
                     two_sided,
                     false,
                     false,
-                    true, // every skybox batch the chain ships authors UNLIT
+                    true, // every shipped skybox batch is unlit
                     additive,
                     false,
-                    true,  // …depth-write off
-                    false, // …depth-test on
+                    true,  // depth-write off
+                    false, // depth-test on
                     FogPolicy::Off,
                     false,
                     ShadeSel::Lit,
@@ -259,20 +205,14 @@ pub(super) fn spawn_menagerie(
                     false,
                     true, // the sky lane
                     light,
-                    None, // the shared lane — see the note above
+                    None, // the shared lane
                 ));
             }
         }
     }
-    // The ground-clutter lane (specialize's over-blend), both sidednesses — the first
-    // verification leg caught the two-sided one compiling live. Its material is built by
-    // `WorldAssets::model_material` (image machinery this pass doesn't need) — the pipeline only
-    // sees the KEY bits, so arm `clutter_fade` on a COPY of the plain material (a fresh asset;
-    // the dedup cache's own entry stays untouched). ALL THREE alpha modes the clutter builder
-    // maps to (Opaque / Mask / Blend — Mod/Mod2x fold to Blend there), not just Mask: a detail
-    // doodad's trunk batch is Opaque, its canopy Blend, and the builder's untextured fallback is
-    // Opaque + back-cull with the fade still armed — each its own key (0958's sweep; 0938 warmed
-    // Mask only).
+    // The ground-clutter lane, both sidednesses and all three alpha modes its builder maps to
+    // (Opaque, Mask, Blend). The pipeline sees only key bits, so `clutter_fade` is armed on a
+    // copy of the plain material, leaving the dedup cache's entry untouched.
     for two_sided in [false, true] {
         for blend in [ModelBlend::Opaque, ModelBlend::AlphaTest, ModelBlend::Blend] {
             let plain = model_material(
@@ -289,8 +229,7 @@ pub(super) fn spawn_menagerie(
                 false,
                 false,
                 FogPolicy::Scene,
-                // Not a `WowModelKey` axis (it swaps a sampled UV, not pipeline state), so
-                // warming one side warms both.
+                // Not a `WowModelKey` axis: it swaps a sampled UV, not pipeline state.
                 false,
                 ShadeSel::Lit,
                 0,
@@ -299,12 +238,11 @@ pub(super) fn spawn_menagerie(
                 None,
                 None,
                 false,
-                false, // warms the WORLD lane; the sky lane warms with its own model
+                false, // the world lane
                 light,
-                None, // the shared lane — see the note above
+                None, // the shared lane
             );
-            // The warmer reads what it builds (`model_render::lazy` parks a built material
-            // until something visible binds it; the warmer's entities bind next frame).
+            // `model_render::lazy` parks a built material until something binds it.
             benilla_world::model_render::lazy::realize_all(materials);
             if let Some(m) = materials.get(&plain) {
                 let mut m = m.clone();
@@ -315,13 +253,10 @@ pub(super) fn spawn_menagerie(
         }
     }
 
-    // The shard-rung rows (decision 0945). A 3-D model particle's instance material carries its
-    // owner-last rung in `depth_bias`, which is ALSO a pipeline-key axis (0837's law) — so the
-    // runtime stamps only the closed bucket set (`owner_last_rung_bucket`), and this table
-    // compiles that set. Families are the corpus census's floor plus the depth-write axis
-    // (`benilla-extract shardcensus`: every 1.12.1 shard batch is Blend, ± two-sided,
-    // ± additive, all no-depth-write — over-warming the write axis costs milliseconds). Built as
-    // bias-stamped COPIES exactly like the runtime does it, so the dedup cache stays untouched.
+    // The shard-rung rows: a model particle's `depth_bias` carries its owner-last rung, a key
+    // axis, so the runtime stamps only the closed bucket set and this compiles it. Every 1.12.1
+    // shard batch is Blend, either sidedness, either additive, no depth write (`benilla-extract
+    // shardcensus`); built as bias-stamped copies as the runtime does.
     let mut shard_mats: Vec<Handle<WowModelMaterial>> = Vec::new();
     for &bucket in benilla_formats::OWNER_RUNG_BUCKETS.iter() {
         for two_sided in [false, true] {
@@ -341,8 +276,7 @@ pub(super) fn spawn_menagerie(
                         no_depth_write,
                         false,
                         FogPolicy::Scene,
-                        // Not a `WowModelKey` axis (it swaps a sampled UV, not pipeline state), so
-                        // warming one side warms both.
+                        // Not a `WowModelKey` axis: it swaps a sampled UV, not pipeline state.
                         false,
                         ShadeSel::Lit,
                         0,
@@ -351,9 +285,9 @@ pub(super) fn spawn_menagerie(
                         None,
                         None,
                         false,
-                        false, // warms the WORLD lane; the sky lane warms with its own model
+                        false, // the world lane
                         light,
-                        None, // the shared lane — see the note above
+                        None, // the shared lane
                     );
                     benilla_world::model_render::lazy::realize_all(materials);
                     if let Some(m) = materials.get(&h) {
@@ -366,34 +300,16 @@ pub(super) fn spawn_menagerie(
         }
     }
 
-    // The far-side-of-water twins (decision 0945). `classify_water_side` swaps every transparent
-    // model material for its `far_twin_of` — a DISTINCT pipeline key (the far marker bit + the
-    // shifted bias integer) that the cache never dedups against the near one even though
-    // `specialize` makes the descriptors byte-identical. Unwarmed, the first eye-and-model
-    // straddle of a water plane is a live compile. Twin everything transparent above, through the
-    // swap's own builder, with the swap's own predicate.
+    // The far-side-of-water twins: `classify_water_side` swaps a transparent material for its
+    // `far_twin_of`, a distinct pipeline key the cache never dedups against the near one.
     let far_mats = far_twins_of(materials, &mats);
     let far_shard_mats = far_twins_of(materials, &shard_mats);
 
     let mut count = 0;
-    // The main cross and its far twins ride every layout (any family can appear static or
-    // skinned, plain or vertex-coloured — a submerged character's skinned gear classifies far
-    // too); the shard rows and their far twins ride the static layouts only (shard geometry
-    // models are static meshes by construction — `particles::model`). Every main-cross rig is
-    // ALSO duplicated onto one portrait booth's layer (0938) AND the twin booth's (0958): the
-    // booths render at `Msaa::Off`, so each model pipeline has a samples=1 twin per projection
-    // CLASS — the real booth's Perspective placeholder and the twin booth's custom projection
-    // (the class real bakes install) — that otherwise compiles live on the first in-world
-    // portrait. A unit's gear (any family, any layout, far-swapped included when submerged)
-    // can reach a booth pane. Shard rows can't (particle instances never ride booth layers).
-    //
-    // …and onto the ORTHOGRAPHIC twin (2262), the third projection class: the UI model tile
-    // atlas's camera. Its rigs are built by `ui_models` through `portrait::material_variant`,
-    // which clones the world material and swaps only the light buffer — the same pipeline key,
-    // under a class nothing warmed. **Minus the far twins**, which the booths do take: a far
-    // twin is `model_render::classify_water_side` swapping a material for an eye-and-model
-    // straddle of a water plane, and a tile is a `<Model>` widget's own file on its own stage —
-    // there is no water plane in a tile and no classify pass runs over one.
+    // The main cross and its far twins ride every layout, on the world camera, one real booth and
+    // the twin booth; the orthographic twin (the UI model tile camera) takes the main cross only,
+    // as no water classify runs over a tile. Shard rows ride the static layouts on the world
+    // camera only: shard models are static and never on a booth.
     for (mesh, aabb, skinned) in &layouts {
         for mat in mats.iter().chain(far_mats.iter()) {
             spawn_model_rig(commands, cam, None, mesh, aabb, *skinned, mat);
@@ -441,14 +357,10 @@ pub(super) fn spawn_menagerie(
         }
     }
 
-    // The MERGED-BLOB layouts (`WOW_STATIC_MERGE`, 1417–1420): the static layouts plus the baked
-    // per-vertex fade sphere, and plus the interior-prop probe slot — four more strides
-    // (48/52, and their vertex-coloured 64/68), each a distinct pipeline family via the
-    // `WOW_MERGED_FADE`/`WOW_MERGED_SLOT` shader defs `specialize` keys on the layout. Built
-    // through the REAL blob mesh builder (`merged_static_mesh_faded`) so the warm layout can't
-    // drift from production. World camera only: a blob never reaches a portrait booth and never
-    // far-twins (no `DoodadFade`, so `classify_water_side` never swaps it). Missing these was a
-    // live compile — a director-felt stall — on the first blob of each family to enter view.
+    // The merged-blob layouts (`WOW_STATIC_MERGE`): the static layouts plus the baked fade
+    // sphere and the interior-prop probe slot, strides 48/52 and 64/68, keyed by the
+    // `WOW_MERGED_FADE`/`WOW_MERGED_SLOT` defs. World camera only: a blob never far-twins or
+    // reaches a booth.
     for colors in [false, true] {
         for slot in [false, true] {
             let part = std::sync::Arc::new(warm_quad(colors, false));
@@ -466,10 +378,8 @@ pub(super) fn spawn_menagerie(
         }
     }
 
-    // The WMO-skybox rows (decision 1264): the STATIC PLAIN layout only, and only on the world
-    // camera. `skybox::build_skybox` inserts POSITION + NORMAL + UV_0 — `layouts[0]` exactly — a
-    // skybox is never skinned (the asteroid belts' bones are a deferral, not a shipped lane), never
-    // vertex-coloured (M2 carries no MOCV), never far-twinned, and never reaches a portrait booth.
+    // The WMO-skybox rows: `skybox::build_skybox` inserts POSITION + NORMAL + UV_0, exactly
+    // `layouts[0]`, on the world camera only.
     {
         let (plain_mesh, plain_aabb, _) = &layouts[0];
         for mat in &sky_mats {
@@ -478,18 +388,14 @@ pub(super) fn spawn_menagerie(
         }
     }
 
-    // The sky and water lanes (decision 0945 — 0837's scope was model-lane-only, and every hole
-    // was a director-felt stall: the sun disc first drawn on stepping outdoors, the first water
-    // in view, a spell's shards mid-cast). Every material that EXISTS in these Startup-populated
-    // stores gets a rig with its production mesh layout — iterating the store can't drift from
-    // what's spawned. Layout indices: the loop above pushed [static plain, skinned plain,
-    // static colours, skinned colours].
+    // The sky and water lanes: every material in these stores gets a rig with its production
+    // layout. `layouts` is [static plain, skinned plain, static colours, skinned colours].
     let (plain_mesh, plain_aabb, _) = layouts[0].clone();
     let (colours_mesh, colours_aabb, _) = layouts[2].clone();
     let posuv = meshes.add(warm_pos_uv_mesh());
     let liquid_mesh = meshes.add(warm_liquid_mesh(false));
     let liquid_color_mesh = meshes.add(warm_liquid_mesh(true));
-    // Celestial discs + glares (`sun::setup` quads: position+normal+UV).
+    // Celestial discs and glares (`sun::setup` quads: position, normal, UV).
     for mat in lane_handles(&mut lanes.celestial) {
         spawn_lane_rig(
             commands,
@@ -501,8 +407,7 @@ pub(super) fn spawn_menagerie(
             &mut count,
         );
     }
-    // Stars: the real `Stars.m2` patches carry position+UV only; the assetless fallback dome
-    // carries normals too — two distinct pipeline keys, warm both.
+    // Stars: `Stars.m2` patches carry position and UV; the assetless fallback adds normals.
     for mat in lane_handles(&mut lanes.stars) {
         spawn_lane_rig(commands, cam, None, &posuv, None, mat.clone(), &mut count);
         spawn_lane_rig(
@@ -515,7 +420,7 @@ pub(super) fn spawn_menagerie(
             &mut count,
         );
     }
-    // The cloud dome (position+normal+UV+colour) and the gradient dome (position+normal+UV).
+    // The cloud dome (position, normal, UV, colour) and the gradient dome (without colour).
     for mat in lane_handles(&mut lanes.clouds) {
         spawn_lane_rig(
             commands,
@@ -538,14 +443,9 @@ pub(super) fn spawn_menagerie(
             &mut count,
         );
     }
-    // Liquid: every kind × fog-block material `setup_liquid` built, on BOTH of the liquid grid's
-    // layouts. An **interior** WMO pool bakes its `MOMT.diffColor` into a fifth attribute —
-    // `ATTRIBUTE_COLOR`, `liquid::surface::liquid_bevy_mesh` — which `liquid.wgsl:275` reads behind
-    // `#ifdef VERTEX_COLORS`: a different shader-def set AND a different vertex buffer, so a
-    // different pipeline, exactly the way the minimap composite's quad was (2262). The ADT and
-    // WMO-exterior lanes pass `None` and take the shader's `#else` white. Warming only the
-    // four-attribute form left the first indoor water pool — a cave, a dungeon, an inn's basin —
-    // compiling live on the frame it came into view.
+    // Liquid: every material on both grid layouts. An interior WMO pool bakes `MOMT.diffColor`
+    // into `ATTRIBUTE_COLOR`, read behind `#ifdef VERTEX_COLORS` (`liquid.wgsl:275`), a separate
+    // pipeline.
     for mat in lane_handles(&mut lanes.liquid) {
         spawn_lane_rig(
             commands,
@@ -566,15 +466,9 @@ pub(super) fn spawn_menagerie(
             &mut count,
         );
     }
-    // The plain-`StandardMaterial` lanes (0938 — the director's evening log). The fallback cube
-    // (`entities::CubeAssets`, drawn while any entity's model streams) uses the production mesh
-    // + materials, on the world camera AND a booth layer (a cube-bodied target can reach a
-    // portrait pane) — but NOT the orthographic twin (2262): `ui_models` has no cube fallback at
-    // all, a tile's root simply stays bare until its M2 is resident, so no cube ever draws
-    // through the tile camera. The nameplate and raid-mark materials are built on first need, so the lane
-    // warms REPRESENTATIVES with the builders' exact key fields (`nameplates::spawn_nameplates`,
-    // `raid_marks::place_marks` — texture presence is not a key axis); the plate/mark quads
-    // share the static-plain attribute set.
+    // The plain-`StandardMaterial` lanes. The fallback cube, drawn while a model streams, goes on
+    // the world camera and the booths but not the tile camera, as `ui_models` has no cube. The
+    // nameplate and raid-mark materials are representatives with their builders' key fields.
     if let Some(cubes) = lanes.cubes.as_ref() {
         let (cube_mesh, cube_mats) = cubes.warm_parts();
         for mat in cube_mats {
@@ -641,23 +535,13 @@ pub(super) fn spawn_menagerie(
         &mut count,
     );
 
-    // The **minimap interior composite's tile quad** (1466, warmed by 2262). A `Material2d`
-    // pipeline is keyed on `(view key, MESH LAYOUT)`, and `UiQuadMaterial` therefore has TWO
-    // pipelines, not the one `warm_ui_quad_lane`'s doc claimed: the HUD's batch mesh is
-    // POSITION+UV_0+COLOR, the composite's tile is `Rectangle` — POSITION+NORMAL+UV_0. The
-    // composite's own camera cannot be warmed through (it is `is_active: false` until the player
-    // is inside a baked WMO interior, and an inactive camera is not extracted at all, so there is
-    // no view to specialise against) — but it does not need to be: the two cameras' VIEW keys are
-    // byte-identical (both `Msaa::Off`, neither HDR, same tonemap defs — confirmed by diffing the
-    // two variants in a `WOW_PIPE_TRACE` inventory, which differ in nothing but the vertex defs
-    // and buffer layout). So drawing the composite's mesh + its production material through the
-    // player-UI camera mints exactly the composite's pipeline, under the cover.
+    // The minimap interior composite's tile quad: a `Material2d` pipeline is keyed on the mesh
+    // layout too, and its `Rectangle` differs from the HUD batch mesh. The composite's camera is
+    // inactive outside a WMO interior, but its view key equals the player-UI camera's, so this
+    // draws through that one.
     //
-    // The texture is a real 1×1 stand-in rather than a default handle, so the material's
-    // `AsBindGroup` cannot land on the retry path: a `#[texture]` binding whose `Some(handle)`
-    // does not resolve returns `RetryNextUpdate`, and a warm rig that never prepares is a warm
-    // rig that draws nothing and warms nothing, silently. `warm_effect_lane` binds a stand-in
-    // for the same reason.
+    // A real stand-in texture: an unresolved `#[texture]` handle returns `RetryNextUpdate`, and a
+    // rig that never prepares warms nothing.
     let tile_tex = lanes.images.add(Image::default());
     commands.spawn((
         Mesh2d(meshes.add(crate::ui_pass::tile_quad_mesh())),
@@ -669,8 +553,7 @@ pub(super) fn spawn_menagerie(
                     crate::minimap::INTERIOR_TILE_ALPHA_REF,
                 )),
         ),
-        // Visible — unlike the model rigs, which the pacing reveals a slice at a time. It is one
-        // pipeline, drawn once at a scale that covers no pixel worth speaking of.
+        // Visible, unlike the paced model rigs: one pipeline, drawn at a negligible scale.
         Transform::from_xyz(0.0, 0.0, 0.0).with_scale(Vec3::splat(0.001)),
         crate::ui_pass::ui_render_layers(),
         WarmRig,
@@ -680,8 +563,8 @@ pub(super) fn spawn_menagerie(
     count
 }
 
-/// The far twins of every TRANSPARENT material in `src` — the same `alpha_mode == Blend`
-/// predicate `classify_water_side` swaps on, through the swap's own `far_twin_of` builder.
+/// The far twins of every transparent material in `src`, by `classify_water_side`'s own
+/// predicate and builder.
 fn far_twins_of(
     materials: &mut Assets<WowModelMaterial>,
     src: &[Handle<WowModelMaterial>],
@@ -696,8 +579,7 @@ fn far_twins_of(
     twins.into_iter().map(|m| materials.add(m)).collect()
 }
 
-/// Strong handles to every material currently in a lane's store (the iterate-the-store warm:
-/// what exists is what gets compiled).
+/// Strong handles to every material in a lane's store.
 fn lane_handles<M: Material>(assets: &mut Assets<M>) -> Vec<Handle<M>> {
     let ids: Vec<AssetId<M>> = assets.iter().map(|(id, _)| id).collect();
     ids.into_iter()
@@ -705,8 +587,7 @@ fn lane_handles<M: Material>(assets: &mut Assets<M>) -> Vec<Handle<M>> {
         .collect()
 }
 
-/// One model-lane menagerie entity: a 1 cm rig in front of the camera (world or booth — `layers`
-/// puts the rig on the booth camera's layer for the samples=1 twin space), drawn under the cover.
+/// One model-lane rig, 1 cm in front of `cam`; `layers` puts it on a booth camera's layer.
 fn spawn_model_rig(
     commands: &mut Commands,
     cam: Entity,
@@ -727,9 +608,7 @@ fn spawn_model_rig(
         Transform::from_xyz(0.0, 0.0, -0.5).with_scale(Vec3::splat(0.01)),
         tag,
         WarmRig,
-        // Hidden at spawn: a hidden rig is never extracted, so it queues no pipeline. The pass
-        // reveals rigs a slice at a time (`super::reveal_slice`) — that is what paces the
-        // compile burst instead of paying all 1480 in one blocking frame (decision 1116).
+        // Hidden at spawn, so it queues no pipeline until `super::reveal_slice` reveals it.
         Visibility::Hidden,
         ChildOf(cam),
     ));
@@ -741,8 +620,7 @@ fn spawn_model_rig(
     }
 }
 
-/// One sky/water/standard-lane menagerie entity — same rig, no `MeshTag` (those lanes don't
-/// carry one in production, and the tag is instance data, never a pipeline axis).
+/// One sky, water or standard-lane rig: the same rig without a `MeshTag`, as in production.
 fn spawn_lane_rig<M: Material>(
     commands: &mut Commands,
     cam: Entity,
@@ -757,7 +635,7 @@ fn spawn_lane_rig<M: Material>(
         MeshMaterial3d(mat),
         Transform::from_xyz(0.0, 0.0, -0.5).with_scale(Vec3::splat(0.01)),
         WarmRig,
-        // Hidden at spawn — revealed a slice at a time; see `spawn_model_rig`.
+        // Hidden at spawn, revealed a slice at a time.
         Visibility::Hidden,
         ChildOf(cam),
     ));
@@ -770,11 +648,8 @@ fn spawn_lane_rig<M: Material>(
     *count += 1;
 }
 
-/// A tiny triangle carrying POSITION + UV_0 only — the layout the real `Stars.m2` patches ship
-/// (`sun::setup` inserts exactly these two attributes). The WMO skybox used to share it; since
-/// decision 1264 it draws on the model lane and carries that lane's NORMAL too, so it rides
-/// `layouts[0]` instead. Main-world-resident (`RenderAssetUsages::default()`), so `calculate_bounds`
-/// covers it — no explicit Aabb needed.
+/// A tiny triangle with POSITION + UV_0 only, the `Stars.m2` layout. Main-world-resident, so
+/// `calculate_bounds` covers it.
 fn warm_pos_uv_mesh() -> Mesh {
     let mut m = Mesh::new(
         PrimitiveTopology::TriangleList,
@@ -792,15 +667,9 @@ fn warm_pos_uv_mesh() -> Mesh {
     m
 }
 
-/// A tiny quad in the liquid grid's layout — POSITION + NORMAL + UV_0 + UV_1, plus
-/// `ATTRIBUTE_COLOR` when `body_color` is set.
-///
-/// **Both forms are real** (2262's lesson, found by the sweep after it): `liquid_bevy_mesh` takes
-/// an `Option<[f32; 3]>` body colour and inserts the fifth attribute only for an INTERIOR WMO
-/// pool that is not fullbright — the ADT and WMO-exterior lanes pass `None`. `liquid.wgsl:275`
-/// reads it behind `#ifdef VERTEX_COLORS`, so the two are separate pipelines. This doc used to
-/// claim `liquid::surface` "inserts exactly these four attributes", which is what kept the second
-/// one out of the menagerie.
+/// A tiny quad in the liquid grid's layout: POSITION + NORMAL + UV_0 + UV_1, plus
+/// `ATTRIBUTE_COLOR` when `body_color` is set, as `liquid_bevy_mesh` does for a non-fullbright
+/// interior WMO pool.
 fn warm_liquid_mesh(body_color: bool) -> Mesh {
     let mut m = Mesh::new(
         PrimitiveTopology::TriangleList,
@@ -820,16 +689,15 @@ fn warm_liquid_mesh(body_color: bool) -> Mesh {
     m.insert_attribute(Mesh::ATTRIBUTE_UV_0, uvs.clone());
     m.insert_attribute(Mesh::ATTRIBUTE_UV_1, uvs);
     if body_color {
-        // The production insert's shape exactly (`liquid_bevy_mesh`): one RGBA per vertex, alpha 1.
+        // As `liquid_bevy_mesh` inserts it: one RGBA per vertex, alpha 1.
         m.insert_attribute(Mesh::ATTRIBUTE_COLOR, vec![[1.0, 1.0, 1.0, 1.0]; 4]);
     }
     m.insert_indices(Indices::U32(vec![0, 1, 2, 0, 2, 3]));
     m
 }
 
-/// A unit quad in each attribute combination the model lane ships. Every `RenderSubmesh` field
-/// is spelled out on purpose: a new field breaks THIS build, which is the drift alarm that keeps
-/// the menagerie honest against the format.
+/// A unit quad in each attribute combination the model lane ships. Every `RenderSubmesh` field is
+/// spelled out so a new field breaks this build.
 fn warm_quad(colors: bool, skinned: bool) -> RenderSubmesh {
     let n = 4usize;
     RenderSubmesh {
@@ -887,27 +755,16 @@ fn warm_quad(colors: bool, skinned: bool) -> RenderSubmesh {
 
 #[cfg(test)]
 mod tests {
-    /// The gate's second half (decision 0958): a lane can also be a hand-rolled
-    /// `SpecializedRenderPipeline`/`SpecializedMeshPipeline`/`SpecializedComputePipeline` impl —
-    /// invisible to the `MaterialPlugin` scan below, which is exactly how the `wow_effect` lane
-    /// (particles, decals, the selection ring) shipped unwarmed and the ring's first-target
-    /// compile stalled live twice (0837's inventory missed it too). Every such impl's TYPE must
-    /// be named in the pipe_warm module, or this red-bars the build.
+    /// Every hand-rolled `Specialized*Pipeline` impl's type must be named in the pipe_warm
+    /// module, comments included.
     #[test]
     fn every_custom_pipeline_lane_has_a_warm_contributor() {
-        // Lanes whose one pipeline compiles covered BY CONSTRUCTION, each with the reason:
-        // - UiGammaPipeline (`ui_gamma`, decision 2206): one variant, keyed on the swapchain's
-        //   view format, specialised in the first frame's prepare — pre-world, so covered
-        //   (`publish_cover`: `state != InWorld`) — and the surface's format never changes
-        //   after, so no later variant exists. Not a timing race like `UiQuadMaterial`'s: the
-        //   view exists from frame one, and the pipeline is what bevy's own output blit was.
-        //   (Its world-lane twin, benilla-world's `FfxCombinePipeline`, is outside this scan
-        //   and compiles under the same cover: the player-UI camera's backdrop pair is keyed on
-        //   that camera's own main texture and specialised on its first frame, pre-world, and a
-        //   bake's pair on the bake image's fixed format. That list was one short — a world view
-        //   also has its OWN pair, for the frames nothing claims it, and 2262 found it compiling
-        //   live at app exit. `prepare_textures` now specialises that pair on every frame rather
-        //   than only on the frame it first needs it.)
+        // Lanes whose one pipeline compiles covered by construction:
+        // - UiGammaPipeline (`ui_gamma`): one variant keyed on the swapchain format, specialised
+        //   on the first frame, pre-world, and the format never changes.
+        // `FfxCombinePipeline` compiles covered the same way (first frame, pre-world, a bake's
+        // fixed format; a world view's pair every frame in `prepare_textures`); this mention of
+        // its name is what passes it here.
         let exempt = ["UiGammaPipeline"];
         let own_src = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
         let warm_src = std::fs::read_to_string(own_src.join("pipe_warm/mod.rs")).unwrap()
@@ -943,20 +800,10 @@ mod tests {
         );
     }
 
-    /// **The scan root: every crate in the workspace, not just this one.**
-    ///
-    /// Both lane-coverage scans below used to walk `CARGO_MANIFEST_DIR/src` — which is
-    /// `crates/benilla-app/src`, and every lane either scan exists to catch lives in
-    /// **`benilla-world`**: all eight 3-D `MaterialPlugin` registrations, and both real hand-rolled
-    /// pipelines (`FfxCombinePipeline`, `EffectPipeline`). The only `Specialized*Pipeline` impl in
-    /// benilla-app is `UiGammaPipeline`, which the test then exempts — so the custom-lane assertion
-    /// could not fail, ever, and the material assertion could only ever see the two 2-D/UI
-    /// families. Both tests were green because they were looking at an empty room; the exempt list
-    /// even named `TerrainMaterial`/`WdlMaterial`, types the walk could never reach. Found by the
-    /// sweep after 2262, which is the third time in this file's history that a lane shipped
-    /// unwarmed because the instrument could not see it.
+    /// The scan roots: every crate's `src` in the workspace, since most lanes live in
+    /// `benilla-world`.
     fn workspace_src_roots() -> Vec<std::path::PathBuf> {
-        // `crates/benilla-app` → `crates`, then every crate's `src` under it.
+        // `crates/benilla-app` -> `crates`, then every crate's `src` under it.
         let crates = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
             .parent()
             .expect("CARGO_MANIFEST_DIR always has a parent")
@@ -978,7 +825,7 @@ mod tests {
         roots
     }
 
-    /// Every `.rs` file under `src`, read — shared by both lane-coverage scans.
+    /// Every `.rs` file under `src`, read.
     fn walk_rs(src_root: &std::path::Path) -> Vec<(std::path::PathBuf, String)> {
         let mut out = Vec::new();
         let mut stack = vec![src_root.to_path_buf()];
@@ -999,31 +846,20 @@ mod tests {
         out
     }
 
-    /// The lane-coverage gate (decision 0938, widened by 0958): every material lane registered
-    /// anywhere in this crate — 3-D (`MaterialPlugin::<X>`), 2-D (`Material2dPlugin::<X>`), and
-    /// UI (`UiMaterialPlugin::<X>`) — must be NAMED in this file. The warm pass is the one place
-    /// that compiles a lane's pipelines behind the loading cover, so a lane nobody considered
-    /// for warming is a future director-felt live stall on its first sight. 0938 exempted the
-    /// 2-D/UI families wholesale ("pre-world counts as covered"), which was wrong for
-    /// `UiQuadMaterial` — its quads only exist in-world, so its one pipeline's compile time was
-    /// a race with the cover lift (0958's sweep). Exemptions carry their reason beside them;
-    /// anything else red-bars the build. The runtime half of the contract stays
-    /// `watch_pipelines`' "compiled LIVE" tripwire, which catches per-VARIANT drift inside a
-    /// covered lane; this test catches whole lanes.
+    /// Every registered 3-D, 2-D and UI material lane must be named in the pipe_warm module or
+    /// exempt with a reason; `watch_pipelines` catches per-variant drift inside a lane.
     #[test]
     fn every_material_lane_has_a_warm_contributor() {
-        // Lanes that never need the menagerie, each with the reason it is safe:
-        // - TerrainMaterial / WdlMaterial: the ground the player spawns on and its horizon
-        //   ring — always drawn under the entry cover by construction, no per-variant key axis.
-        // - AddUiMaterial: drawn only by the glue screens, and every pre-world frame counts
-        //   as covered (`publish_cover`: `state != InWorld`).
+        // Lanes that never need the menagerie:
+        // - TerrainMaterial / WdlMaterial: always drawn under the entry cover, no variant axis.
+        // - AddUiMaterial: glue screens only, and every pre-world frame counts as covered.
         let families: [(&str, &[&str]); 3] = [
             ("MaterialPlugin::<", &["TerrainMaterial", "WdlMaterial"]),
             ("Material2dPlugin::<", &[]),
             ("UiMaterialPlugin::<", &["AddUiMaterial"]),
         ];
         let own_src = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
-        // "Named in this file" = anywhere in the pipe_warm module folder.
+        // Anywhere in the pipe_warm module folder.
         let warm_src = std::fs::read_to_string(own_src.join("pipe_warm/mod.rs")).unwrap()
             + &std::fs::read_to_string(own_src.join("pipe_warm/menagerie.rs")).unwrap();
         let mut missing = Vec::new();
@@ -1034,9 +870,8 @@ mod tests {
         for (path, text) in files {
             for (needle, exempt) in families {
                 for (i, _) in text.match_indices(needle) {
-                    // A preceding ident char means this match is really a longer family's name
-                    // (`Material2dPlugin::<` contains no bare `MaterialPlugin::<`, but
-                    // `UiMaterialPlugin::<` does) — that family gets its own row above.
+                    // A preceding ident char means a longer family's name, such as
+                    // `UiMaterialPlugin`, which has its own row.
                     if i > 0 && (text.as_bytes()[i - 1].is_ascii_alphanumeric()) {
                         continue;
                     }
diff --git a/crates/benilla-app/src/pipe_warm/mod.rs b/crates/benilla-app/src/pipe_warm/mod.rs
index 526bc00e..1a1a7a78 100644
--- a/crates/benilla-app/src/pipe_warm/mod.rs
+++ b/crates/benilla-app/src/pipe_warm/mod.rs
@@ -1,50 +1,15 @@
-//! The pipeline warm pass + its instrument — decision 0837 (the B181 city-approach stall).
+//! The pipeline warm pass and its instrument. On macOS Bevy compiles every pipeline synchronously
+//! on the render thread, so a variant first drawn live is a frame-long stall; the pass compiles
+//! every reachable variant behind the loading cover instead.
 //!
-//! **Why this exists:** on macOS, Bevy compiles every GPU pipeline **synchronously on the render
-//! thread** — `bevy_render`'s `create_pipeline_task` has a `target_os = "macos"` carve-out (0.18
-//! and 0.19 both) that `block_on`s the build regardless of `synchronous_pipeline_compilation`,
-//! and the Metal half of that build runs out-of-process in `MTLCompilerService` (near-zero
-//! process CPU while the frame is blocked). So any pipeline variant first drawn *live* is a
-//! frame-long stall the app cannot pace; the only fix is compiling everything where a stall is
-//! invisible — behind the loading cover, where 0540 put the warm-up. (The worst offender — the
-//! per-batch-index depth bias that made every WMO batch its own pipeline, ~3000 variants at
-//! Stormwind — left the pipeline key in this same decision: the nudge now rides `sun_scale.y`
-//! into `wow_model.wgsl`'s vertex stage as uniform data.)
-//!
-//! The pieces:
-//!
-//! **The burst is paced** (decision 1116). Compiling behind the cover fixed *where* the stall
-//! lands, not its shape: all ~1480 variants became drawable in one frame, so one frame blocked
-//! 1.0–2.3 s — the cover frozen solid, and CoreAudio missing a device cycle inside it (the
-//! crackle of 1114/1115). Rigs now spawn hidden and are revealed [`WARM_REVEAL_PER_FRAME`] at a
-//! time, each hidden again the frame after (its pipeline is compiled by then), so every frame's
-//! synchronous batch is bounded and the machine gets gaps. Same pipelines, same order of
-//! magnitude of work — verified byte-identical inventories via `WOW_PIPE_TRACE`.
-//!
-//! - [`WarmPass`] + `spawn_menagerie` — the warm pass: one tiny rig per reachable pipeline
-//!   variant — the model lane with its shard-rung and far-side twins, and the sky/water lanes
-//!   (celestial, stars, clouds, gradient dome, WMO skybox, liquid; decision 0945 widened 0837's
-//!   model-only scope) — parented to the world camera, spawned a few frames AFTER the entry
-//!   cover rises (so the cover is on the glass before the burst, not racing it — 0962); the
-//!   loading screen's clear condition holds on [`WarmPass::satisfied`] until the pipeline cache
-//!   drains (10 s backstop, 0737's rule), then the menagerie despawns (roots only — recursion
-//!   takes the twin booth's children, 0962). Captures skip it.
-//!   Booth twins ride a real booth's layer (samples=1, 0938) AND the pass's own twin booth
-//!   ([`crate::portrait::spawn_warm_booth`] — the custom-projection view key real bakes install;
-//!   decision 0958), and [`warm_effect_lane`] pushes the `wow_effect` lane's whole key cross
-//!   through the production stream each warm frame (the ring's first-target stall, 0958).
-//! - [`PipeWatch`] — an `Arc` shared by the main and render worlds: how many pipelines the cache
-//!   has ever queued, how many have settled (Ok/Err), and whether a cover currently hides the
-//!   frame (loading screen up, or not in world — the glue scene is its own cover, 0540).
-//! - [`watch_pipelines`] (render world, after the cache's own process step): maintains the
-//!   counters and — the permanent tripwire — logs a `warn!` for every pipeline compiled while
-//!   **uncovered**. That line firing in a session log IS the regression signal: it means the
-//!   menagerie has a coverage hole (extend its loops, don't guess).
-//! - `WOW_PIPE_TRACE=<path>` — the inventory dump: one line per pipeline creation (covered or
-//!   not) with the full variant identity (shaders, defs, depth bias, blend, write mask, vertex
-//!   buffers, cull), the ground truth the menagerie was built from.
-//! - Two stream-trace columns (`pipes_new`, `pipes_pending` — see `perf::trace_stream`) so a
-//!   compile burst is attributable on the same row as the frame that paid for it.
+//! - [`WarmPass`] and `spawn_menagerie`: one tiny rig per reachable variant, spawned once the
+//!   entry cover is on screen and revealed [`WARM_REVEAL_PER_FRAME`] at a time so each frame's
+//!   compile batch is bounded; the cover holds on [`WarmPass::satisfied`] until the cache drains.
+//! - [`PipeWatch`]: counters shared by the main and render worlds, and whether a cover hides the
+//!   frame.
+//! - [`watch_pipelines`]: the tripwire, a `warn!` for every pipeline compiled uncovered, which
+//!   means the menagerie has a coverage hole.
+//! - `WOW_PIPE_TRACE=<path>`: one line per pipeline created, with its full variant identity.
 
 use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
 use std::sync::Arc;
@@ -64,38 +29,25 @@ use benilla_world::particles::buffer::{
 mod menagerie;
 use menagerie::{spawn_menagerie, BoothCamQuery, WarmLanes};
 
-/// The cross-world channel: cloned into the render app at plugin build. Frame alignment between
-/// the two worlds is ±1 frame under pipelined rendering — fine for counters and a tripwire.
+/// The channel between the main and render worlds, aligned to within one frame.
 #[derive(Resource, Clone)]
 pub(crate) struct PipeWatch(pub(crate) Arc<PipeShared>);
 
 pub(crate) struct PipeShared {
     /// Pipelines the cache has ever queued (its vec only grows; ids are indices).
     pub(crate) created: AtomicUsize,
-    /// Of those, how many have settled — `Ok` or a non-retryable `Err`. A retryable error
-    /// (shader not loaded yet) flips back to `Queued` and correctly reads as pending.
+    /// Of those, how many are `Ok` or a non-retryable `Err`; a retryable one reads as pending.
     pub(crate) settled: AtomicUsize,
-    /// Main-world truth: an opaque cover hides the frame (loading screen, or not `InWorld`).
+    /// An opaque cover hides the frame: the loading screen, or not `InWorld`.
     pub(crate) covered: AtomicBool,
 }
 
 impl PipeWatch {
-    /// **Is a pipeline still being built?** — i.e. is there a variant the render world would
-    /// silently DROP the draw for right now.
+    /// Whether a pipeline is still building. Off macOS the build is async, and until it settles
+    /// `SetItemPipeline` skips the batch, so a one-shot bake taken now would miss it.
     ///
-    /// Off macOS, `create_pipeline_task` spawns the build on the async pool
-    /// (`bevy_render` 0.18.1 `pipeline_cache.rs:855`; the `block_on` arm is `cfg`'d to
-    /// wasm/macOS/single-threaded), and until it settles `PipelineCache::get_render_pipeline`
-    /// returns `None` — at which point `SetItemPipeline` returns
-    /// [`RenderCommandResult::Skip`](bevy::render::render_phase::RenderCommandResult::Skip)
-    /// (`render_phase/mod.rs:1745`) and that batch simply **does not draw this frame**. A live
-    /// view redraws it the moment the pipeline lands; a one-shot bake that has already gone to
-    /// sleep keeps the hole forever (report B331 — see [`crate::portrait`]'s pipeline settle).
-    ///
-    /// Reading `settled` first is deliberate: the pair is published unsynchronised, so the only
-    /// skew this ordering can produce is a stale-low `settled` against a fresh `created` — a
-    /// spurious `true`, which costs one extra rendered frame. The other order could produce a
-    /// spurious `false`, which is a wrong still.
+    /// `settled` is read first: the pair is unsynchronised, and this order can only err towards a
+    /// spurious `true` (one extra frame), never a spurious `false` (a wrong still).
     pub(crate) fn compiling(&self) -> bool {
         let settled = self.0.settled.load(Ordering::Relaxed);
         self.0.created.load(Ordering::Relaxed) > settled
@@ -119,14 +71,12 @@ pub(crate) fn plugin(app: &mut App) {
             census_view_classes,
         ),
     );
-    // Before the Present stage so the loading screen reads this frame's gate, not last frame's.
+    // Before Present, so the loading screen reads this frame's gate.
     app.add_systems(
         Update,
         run_warm_pass.before(benilla_world::schedule::WorldStage::Present),
     );
-    // The effect-lane warm writer rides the production stream, which is cleared at the top of
-    // PostUpdate's effect set — so it writes after the clear, like every family writer. The
-    // HUD-quad warm rides the UI append lane the same way (cleared at the top of its own set).
+    // Both warm writers push into streams cleared at the top of their sets, so they run after.
     app.add_systems(PostUpdate, warm_effect_lane.after(begin_effect_frame));
     app.add_systems(
         Update,
@@ -139,15 +89,13 @@ pub(crate) fn plugin(app: &mut App) {
     render_app.add_systems(Render, watch_pipelines.in_set(RenderSystems::Cleanup));
 }
 
-/// Main world → render thread: the render thread is about to spend this window blocked inside
-/// Metal pipeline compilation with nothing but a still cover on screen, so it drops out of the
-/// frame-critical QoS band for the duration (decision 1117; the band itself is `thread_qos`).
+/// Tell the render thread a compile burst is on, so it leaves the frame-critical QoS band.
 fn publish_compile_burst(warm: Res<WarmPass>) {
     let bursting = warm.spawned_at.is_some() && !warm.done;
     benilla_world::thread_qos::COMPILE_BURST.store(bursting, Ordering::Relaxed);
 }
 
-/// Main world → render world: is the frame covered right now?
+/// Publish whether the frame is covered to the render world.
 fn publish_cover(
     watch: Res<PipeWatch>,
     loading: Res<LoadingScreen>,
@@ -157,9 +105,8 @@ fn publish_cover(
     watch.0.covered.store(covered, Ordering::Relaxed);
 }
 
-/// Render world, after `PipelineCache::process_pipeline_queue_system` has merged this frame's new
-/// pipelines and started (= on macOS: finished) their builds. `seen` is how many cache entries the
-/// previous frame had — everything past it is new this frame.
+/// Count the cache's pipelines after it queues this frame's builds, and warn on any new one
+/// compiled uncovered. `seen` is the previous frame's count.
 fn watch_pipelines(
     cache: Res<PipelineCache>,
     watch: Res<PipeWatch>,
@@ -167,11 +114,8 @@ fn watch_pipelines(
     mut settled_seen: Local<usize>,
 ) {
     let covered = watch.0.covered.load(Ordering::Relaxed);
-    // O(1) early-out for the steady state: nothing new since last look AND everything had already
-    // settled then, so the walk below could only re-derive last frame's counts. `size_hint().0`
-    // because the opaque `impl Iterator` hides the backing slice's `.len()`; for a slice iterator
-    // the lower bound is exact. The settled conjunct is load-bearing: Queued/Creating pipelines
-    // settle on later frames without `total` moving.
+    // Early-out when nothing is new and everything had settled; queued pipelines settle later
+    // without `total` moving. `size_hint().0` is exact for the slice iterator behind it.
     let total = cache.pipelines().size_hint().0;
     if total == *seen && *settled_seen == total {
         return;
@@ -191,8 +135,7 @@ fn watch_pipelines(
             if covered {
                 debug!("pipeline compiled (covered) [{id}] {line}");
             } else {
-                // THE TRIPWIRE: after 0837, a live compile is a stall the director can feel —
-                // this line in a session log means the warm pass has a coverage hole.
+                // The tripwire: a live compile is a visible stall, and a warm pass coverage hole.
                 warn!("pipeline compiled LIVE [{id}] {line}");
             }
             if let Ok(path) = std::env::var("WOW_PIPE_TRACE") {
@@ -214,8 +157,7 @@ fn watch_pipelines(
     watch.0.settled.store(settled, Ordering::Relaxed);
 }
 
-/// One line of variant identity: everything that distinguishes this pipeline from its neighbours
-/// (label + shaders + defs + the raster/depth/blend states), compact enough to grep and diff.
+/// One greppable line of a pipeline's variant identity.
 fn describe(desc: &PipelineDescriptor) -> String {
     fn defs(d: &[bevy::shader::ShaderDefVal]) -> String {
         let mut v: Vec<String> = d
@@ -298,48 +240,31 @@ fn describe(desc: &PipelineDescriptor) -> String {
 #[derive(Component)]
 struct WarmRig;
 
-/// Marker on the menagerie's twin booth camera ([`crate::portrait::spawn_warm_booth`] — the
-/// custom-projection view key space, decision 0958), so [`warm_effect_lane`] can address its
-/// view. It also carries [`WarmRig`], which despawns it with the rest of the pass.
+/// Marker on the menagerie's twin booth camera, for [`warm_effect_lane`]; it is also a
+/// [`WarmRig`].
 #[derive(Component)]
 struct WarmBoothCam;
 
-/// Main-world warm-pass state. The loading screen folds [`Self::satisfied`] into its clear
-/// condition, so the cover holds while menagerie pipelines are still compiling.
+/// Warm-pass state; the loading screen holds its cover on [`Self::satisfied`].
 #[derive(Resource, Default)]
 pub(crate) struct WarmPass {
-    /// `Time<Real>::elapsed_secs` when the menagerie spawned under the current cover; `None` =
-    /// idle (no cover, or the pass already finished for this cover). **Real, not virtual**: the
-    /// pass's whole subject is a burst that stalls frames, and `Time<Virtual>` clamps its delta
-    /// at 250 ms — so on the virtual clock this pass measured its own 1.3–2.3 s burst as
-    /// "0.27 s" and its 10 s backstop was 10 *virtual* seconds (decision 1116).
+    /// `Time<Real>` when the menagerie spawned under this cover, `None` when idle. Real, because
+    /// `Time<Virtual>` clamps its delta at 250 ms and would shrink the stalls being timed.
     spawned_at: Option<f32>,
     /// This cover's warm work is done (drained, timed out, or not applicable).
     done: bool,
-    /// The 1×1 stand-in texture [`warm_effect_lane`]'s draws bind while the pass runs (a strong
-    /// handle so the asset lives exactly as long as the pass; `None` = the lane isn't warming).
+    /// The 1x1 stand-in texture [`warm_effect_lane`] binds, held strong for the pass's life.
     effect_tex: Option<Handle<Image>>,
-    /// **The menagerie has drained cleanly once in this process.** The warm set is a fixed
-    /// variant cross built from `Startup`-populated stores (see `menagerie`) — not the resident
-    /// map's art — and `PipelineCache` is process-global and never evicts, so a second pass
-    /// compiles nothing. Re-running it under every later cover was pure cost, and *visible*
-    /// cost: it holds the cover (`satisfied`) for the whole paced reveal, which measured 3.8 s
-    /// on a mid-session teleport whose world was resident in 0.7 s. Later covers therefore skip
-    /// the pass. If that is ever wrong the tripwire says so out loud — `PipeWatch`'s "compiled
-    /// LIVE" warn is exactly the instrument for it — which is why this can be a latch and not a
-    /// guess. A timeout does NOT latch it: something was still pending.
+    /// The menagerie drained cleanly once. The warm set does not depend on the map and the
+    /// pipeline cache never evicts, so later covers skip the pass; a timeout does not latch this.
     warmed_once: bool,
-    /// **The cameras the menagerie parents rigs to** — the world camera, one real portrait booth,
-    /// the twin booth and the orthographic twin. Recorded as entities at spawn so
-    /// [`record_warmed_views`] can read their LIVE view key each frame instead of restating what
-    /// the spawn code meant (2264).
+    /// The cameras the menagerie parents rigs to, whose live view keys [`record_warmed_views`]
+    /// reads.
     anchors: Vec<Entity>,
-    /// **The view keys those anchors actually carried while the pass ran** — the census's only
-    /// notion of "warm". Never a rule, never an inference: if a rig did not render through it,
-    /// it is not in here.
+    /// The view keys those anchors carried while the pass ran: the census's only notion of warm.
     warmed_views: Vec<ViewClass>,
-    /// Pacing state (1116): rigs warmed so far, when the last slice went out, how many frames
-    /// the reveal spanned, and the slice currently on screen (hidden again next frame).
+    /// Pacing state: rigs warmed so far, when the last slice went out, frames the reveal spanned,
+    /// and the slice on screen now (hidden again next frame).
     revealed: usize,
     last_reveal: f32,
     reveal_frames: u32,
@@ -353,25 +278,12 @@ impl WarmPass {
     }
 }
 
-/// The last revealed slice must have been extracted + drawn + its pipelines queued before
-/// `pending == 0` means anything (the counters cross worlds ±1 frame) — anchored to the last
-/// reveal, not to the spawn, now that the reveal is paced.
+/// How long after the last reveal `pending == 0` means drained: the counters cross worlds a frame
+/// apart.
 const WARM_SETTLE_SECS: f32 = 0.25;
-/// Rigs revealed per frame — the pacing slice (decision 1116).
-///
-/// On macOS Bevy compiles every pipeline with `block_on` **inline on the render thread**, and
-/// `PipelineCache::process_queue` drains the whole backlog in one frame with no budget
-/// (bevy_render 0.18.1 `pipeline_cache.rs:869` and `:697`; `synchronous_pipeline_compilation`
-/// is `cfg`'d out of existence here). So the burst's shape is set entirely by how many variants
-/// we make *drawable* per frame. Revealing all ~1480 at once bought one unbroken 1.3 s (warm
-/// shader cache) to 2.3 s (cold) frame — the loading screen frozen solid, and CoreAudio's IO
-/// cycle missing its hardware deadline inside it (1114/1115). A slice this size keeps each
-/// frame's compile batch inside one 43 ms device cycle, so the audio HAL always gets its turn
-/// and the cover animates instead of freezing.
-///
-/// Override with `$WOW_WARM_SLICE` for A/B work; **0 means unpaced** (the pre-1116 behaviour,
-/// kept as the baseline arm — the honest way to re-measure the burst this const exists to
-/// break up).
+/// Rigs revealed per frame. On macOS the pipeline cache drains its whole backlog in one frame,
+/// inline, so this bounds each frame's compile batch to within one 43 ms audio device cycle.
+/// `$WOW_WARM_SLICE` overrides it; 0 means unpaced.
 const WARM_REVEAL_PER_FRAME: usize = 24;
 
 /// The pacing slice actually in force, `$WOW_WARM_SLICE` applied once.
@@ -392,16 +304,12 @@ fn reveal_slice() -> usize {
     })
 }
 
-/// Marker: this rig has had its one visible frame, so its pipeline is compiled and it is hidden
-/// again. Without it a slice stays drawable for the rest of the pass and every later frame
-/// redraws the whole warmed set, so the pass's per-frame cost climbs as it runs. (Measured: it
-/// does *not* move the pass's total wall time — the per-frame floor is elsewhere — it keeps the
-/// per-frame cost flat, which is what pacing is trying to buy.)
+/// Marker: this rig has had its one visible frame and is hidden again, which keeps the pass's
+/// per-frame cost flat.
 #[derive(Component)]
 struct Warmed;
 
-/// The pacing query: every rig but the twin booth CAMERA, which is a view, not a variant —
-/// hiding it would take the booth-layer rigs' camera away mid-pass.
+/// The pacing query: every rig but the twin booth camera, whose rigs need it visible.
 type WarmRigVis<'w, 's> = Query<
     'w,
     's,
@@ -409,8 +317,8 @@ type WarmRigVis<'w, 's> = Query<
     (With<WarmRig>, Without<WarmBoothCam>),
 >;
 
-/// 0737's rule: never hold a cover unbounded. A timeout fires the tripwire-adjacent warn and
-/// releases; the remaining compiles land live (the pre-0837 world, once, with a named cause).
+/// Never hold a cover unbounded: on timeout the pass warns and releases, and what remains
+/// compiles live.
 const WARM_TIMEOUT_SECS: f32 = 10.0;
 fn run_warm_pass(
     mut commands: Commands,
@@ -429,11 +337,8 @@ fn run_warm_pass(
     mut cache: Local<MaterialCache>,
     shared_light: Option<Res<benilla_world::lighting::SharedLightBuffer>>,
 ) {
-    // `EntryCover` already IS "a loading cover is up and we are in world", counted once for the
-    // whole client (see its doc); this used to spell the pair out for itself.
     if !cover.covering() {
-        // No world cover → nothing to hold; a leftover menagerie (timeout, teleport race)
-        // despawns. `done` stays true so the gate never blocks an uncovered frame.
+        // No cover: a leftover menagerie despawns, and `done` keeps the gate open.
         warm.done = true;
         warm.spawned_at = None;
         warm.effect_tex = None;
@@ -441,23 +346,20 @@ fn run_warm_pass(
         despawn_rigs(&mut commands, &rigs);
         return;
     }
-    // Captures boot straight in-world, deterministic by construction — no menagerie in a shot.
+    // No menagerie in a capture.
     if benilla_world::dev_state::deterministic_run() {
         warm.done = true;
         return;
     }
     let now = time.elapsed_secs();
-    // Already warmed in this process: nothing to compile, so nothing to hold the cover for.
+    // Already warmed in this process: nothing to compile.
     if warm.warmed_once {
         warm.done = true;
         return;
     }
     let Some(spawned) = warm.spawned_at else {
-        // The cover just rose (or the world just became live under one): raise the gate and
-        // spawn the menagerie once the camera + shared light exist (both are entry-frame-early;
-        // until they do, the gate holds the cover, which is exactly right) — and once the cover
-        // has actually reached the glass ([`EntryCover`]), so the burst is hidden rather than
-        // holding the frozen character screen (0962).
+        // A new cover: close the gate, and spawn once the camera and shared light exist and the
+        // cover is on screen ([`EntryCover`]), so the burst is hidden behind it.
         warm.done = false;
         let Ok(cam) = camera.single() else { return };
         let Some(light) = shared_light.as_ref() else {
@@ -470,21 +372,18 @@ fn run_warm_pass(
         warm.last_reveal = now;
         warm.revealed = 0;
         warm.reveal_frames = 0;
-        // The twin booth (0958): the custom-projection view key space real bakes use — the real
-        // booths warm the placeholder-Perspective class, this camera the NONSTANDARD one. It is
-        // a WarmRig, so every despawn path below cleans it up with the rigs.
+        // The twin booth warms the custom-projection view key real bakes install; the real
+        // booths warm the Perspective one.
         let warm_booth = crate::portrait::spawn_warm_booth(&mut commands, &mut lanes.images);
         commands
             .entity(warm_booth.0)
             .insert((WarmRig, WarmBoothCam));
-        // The orthographic twin (2262): the THIRD projection class, the one the UI model tile
-        // atlas draws through. Same deal — a WarmRig, so the despawn paths take it too.
+        // The orthographic twin, the projection class the UI model tile atlas draws through.
         let warm_ortho = crate::ui_models::spawn_warm_tile_cam(&mut commands, &mut lanes.images);
         commands.entity(warm_ortho.0).insert(WarmRig);
-        // The effect lane's stand-in texture — held for the life of the pass.
+        // The effect lane's stand-in texture, held for the life of the pass.
         warm.effect_tex = Some(lanes.images.add(Image::default()));
-        // The anchors the census measures "warm" from (2264): every camera the menagerie actually
-        // hangs rigs on. Recorded as entities, not as remembered shapes.
+        // Every camera the menagerie hangs rigs on, for the census.
         warm.anchors = vec![cam, warm_booth.0, warm_ortho.0];
         warm.anchors.extend(booth.iter().next().map(|(e, _)| e));
         warm.warmed_views.clear();
@@ -506,26 +405,16 @@ fn run_warm_pass(
     if warm.done {
         return;
     }
-    // The gizmo-line lane (0938): gizmos are immediate-mode, so the warm draw happens per frame
-    // while the pass runs — one tiny line through the DEFAULT config group, exactly the config
-    // the bowstring draws with, compiles the `LineGizmo` pipeline that otherwise waits for the
-    // first bow-wielder in view.
+    // Gizmos are immediate-mode, so each frame draws one tiny line in the default config group,
+    // the bowstring's, to compile the `LineGizmo` pipeline.
     gizmos.line(
         Vec3::new(0.0, 0.0, -0.5),
         Vec3::new(0.001, 0.0, -0.5),
         Color::WHITE,
     );
-    // The pacing slice (1116). Two moves per frame, in this order:
-    //
-    // 1. Hide the slice revealed LAST frame. Its rigs were extracted and drawn by that frame's
-    //    render, which is where the (synchronous) compile happened — they have nothing left to
-    //    contribute, and leaving them visible makes every later frame redraw the whole warmed
-    //    set. Hiding is safe precisely because extraction for the frame that revealed them has
-    //    already run: this system is in `Update`, an extract behind.
-    // 2. Reveal the next slice, bounding this frame's compile batch.
-    //
-    // A frame that reveals nothing means the menagerie is fully warmed, and only then can
-    // `pending == 0` mean "drained".
+    // The pacing slice, in this order: hide last frame's slice (already extracted and drawn,
+    // as this runs in `Update`, an extract behind), then reveal the next. A frame that reveals
+    // nothing means every rig is warmed, and only then does `pending == 0` mean drained.
     for e in std::mem::take(&mut warm.showing) {
         if let Ok((_, mut vis, _)) = rig_vis.get_mut(e) {
             *vis = Visibility::Hidden;
@@ -575,30 +464,10 @@ fn run_warm_pass(
     }
 }
 
-/// **The view-class census** (2262, rebuilt by 2264) — 0958's claim, turned from a sentence into
-/// an instrument that can actually fire.
-///
-/// 0958 verified that "the whole 3-D view space is `(samples, projection class)`, and both classes
-/// of both sample counts are now warm". True the day it was written; false a month later, when
-/// 2013 gave the UI model tile atlas an orthographic camera — a third class, warmed by nothing,
-/// whose first tile compiled its whole batch set live. Neither lane-coverage gate test can see a
-/// *camera*, so nothing caught it.
-///
-/// **2262's first attempt at this census could not fire.** It decided what was warm from a rule it
-/// held in its own head — "samples=1 is warm in all three classes, and the world camera's own pair
-/// is warm" — and then skipped every camera matching it. But `gxMultisample` registers `"1"`
-/// (`cvars.rs`), `MsaaSetting::default()` is 1, and **only the world camera ever reads it**
-/// (`player/setup.rs:99`, `:118`); every other 3-D camera hard-codes `Msaa::Off` through
-/// `booth_view_shape()`. So `samples == 1` covered the entire population and the loop body was
-/// unreachable — including for the very camera 2013 added. An instrument that restates what the
-/// author believed is not an instrument.
-///
-/// So it no longer believes anything. [`WarmPass::warmed_views`] records the view key of each
-/// camera the menagerie **actually parented rigs to**, read off those cameras live while the pass
-/// runs; the census compares every `Camera3d` against that recorded set and nothing else. It also
-/// runs for the whole session rather than once at drain, warning once per distinct unwarmed key,
-/// because the class a booth is warm in is one it installs *at runtime* on its first bake — which
-/// a single read at drain is too early to see.
+/// The view-class census: warn once per `Camera3d` view key that no rig rendered through, since
+/// its whole model-pipeline space would compile live. It compares only against the recorded
+/// [`WarmPass::warmed_views`], and runs all session because a booth installs its projection on
+/// its first bake.
 fn census_view_classes(
     warm: Res<WarmPass>,
     mut reported: Local<Vec<ViewClass>>,
@@ -628,8 +497,7 @@ fn census_view_classes(
     }
 }
 
-/// Every 3-D camera in the world, for [`census_view_classes`]: the name it reports itself by, and
-/// the three components that decide its mesh-pipeline view key.
+/// Every 3-D camera, with its name and the three components that decide its view key.
 type ViewCamQuery<'w, 's> = Query<
     'w,
     's,
@@ -642,15 +510,9 @@ type ViewCamQuery<'w, 's> = Query<
     With<Camera3d>,
 >;
 
-/// The key a 3-D view contributes to `MeshPipelineKey`, as [`census_view_classes`] compares them.
-///
-/// `hdr` is here because it is a key bit in its own right AND the gate on two more: bevy admits
-/// `TONEMAP_IN_SHADER` and `DEBAND_DITHER` into the key only when the view is **not** HDR
-/// (`bevy_pbr-0.18.1` `render/mesh.rs:418`), and `Camera3d`'s required components hand a camera
-/// both by default. 0958's "every 3-D camera is HDR so tonemap/dither are dead axes" is true of
-/// every camera we spawn today and is exactly the kind of sentence this census exists to stop
-/// trusting: a new 3-D camera that forgets `Hdr` flips three key bits at once, and 2262's version
-/// did not look at it.
+/// The key a 3-D view contributes to `MeshPipelineKey`. `hdr` is a key bit and gates two more:
+/// bevy keys `TONEMAP_IN_SHADER` and `DEBAND_DITHER` only on a non-HDR view
+/// (`bevy_pbr-0.18.1` `render/mesh.rs:418`).
 #[derive(PartialEq, Eq, Clone, Copy, Debug)]
 pub(crate) struct ViewClass {
     projection: &'static str,
@@ -671,10 +533,8 @@ impl ViewClass {
 
 fn view_class(projection: Option<&Projection>, msaa: Option<&Msaa>, hdr: bool) -> ViewClass {
     ViewClass {
-        // bevy_pbr folds exactly these three into `MeshPipelineKey` (`bevy_pbr-0.18.1`
-        // `render/mesh.rs:397`); the match is exhaustive so a fourth variant upstream stops the
-        // build here rather than opening a silent hole. A view with no `Projection` at all sets
-        // no bits, which is the NONSTANDARD pattern — the same class as Custom.
+        // bevy_pbr keys these three (`bevy_pbr-0.18.1` `render/mesh.rs:397`); exhaustive so a
+        // new variant stops the build. No `Projection` sets no bits, the same class as Custom.
         projection: match projection {
             Some(Projection::Perspective(_)) => "Perspective",
             Some(Projection::Orthographic(_)) => "Orthographic",
@@ -685,8 +545,7 @@ fn view_class(projection: Option<&Projection>, msaa: Option<&Msaa>, hdr: bool) -
     }
 }
 
-/// The menagerie's anchor cameras, read for their LIVE view key by [`record_warmed_views`] —
-/// entity first, so the recorder can match against [`WarmPass::anchors`].
+/// The 3-D cameras by entity, for [`record_warmed_views`] to match against the anchors.
 type AnchorViewQuery<'w, 's> = Query<
     'w,
     's,
@@ -699,9 +558,7 @@ type AnchorViewQuery<'w, 's> = Query<
     With<Camera3d>,
 >;
 
-/// Record the view key of every camera the menagerie actually parents rigs to, while the pass is
-/// running. Read off the live cameras rather than restated from what the spawn code intended —
-/// that restatement is what made 2262's census unable to fire.
+/// Record the live view key of every anchor camera while the pass runs.
 fn record_warmed_views(mut warm: ResMut<WarmPass>, cams: AnchorViewQuery) {
     if warm.spawned_at.is_none() || warm.done {
         return;
@@ -718,11 +575,8 @@ fn record_warmed_views(mut warm: ResMut<WarmPass>, cams: AnchorViewQuery) {
     }
 }
 
-/// Tear the pass down by despawning only its ROOT entities. `despawn` is recursive, and the twin
-/// booth's rigs are *children* of the twin booth camera — itself a `WarmRig` — so despawning
-/// every query row queues the children twice (once explicitly, once via the parent's recursion):
-/// a warn per child on the teardown frame (0962). Children of a live camera (the world camera,
-/// a real booth) still get their explicit despawn.
+/// Despawn the pass's root rigs only: `despawn` is recursive, and the twin booth camera is itself
+/// a rig, so its children would be despawned twice.
 fn despawn_rigs(commands: &mut Commands, rigs: &Query<(Entity, Option<&ChildOf>), With<WarmRig>>) {
     for (e, child_of) in rigs {
         if child_of.is_some_and(|c| rigs.contains(c.parent())) {
@@ -732,29 +586,8 @@ fn despawn_rigs(commands: &mut Commands, rigs: &Query<(Entity, Option<&ChildOf>)
     }
 }
 
-/// The **effect-lane** warm writer (decision 0958 — the 07:45 log's [831], the selection ring's
-/// first-target stall). `wow_effect` is a custom `SpecializedRenderPipeline` lane, not a
-/// `MaterialPlugin` one, so no menagerie *entity* can reach it: its pipelines exist only when a
-/// draw record sits in the shared stream at queue time. So while the pass runs, this pushes one
-/// degenerate draw per reachable [`EffectPipelineKey`] — the full blend × raster-bias cross
-/// ({Add, Alpha, Opaque, AlphaKey, Multiply, Mod2x} × {0, ground-decal, blob-shadow}; the key's own doc
-/// pins the closed bias set) — through the PRODUCTION stream (`EffectQuads` → extract → queue →
-/// specialize), once per view class: the world camera (samples=N) and the twin booth (samples=1).
-/// The queue path specializes per matching view regardless of coverage, so a 4-vertex sliver at
-/// the origin compiles the whole space behind the cover; the stand-in texture keeps the prepare
-/// half exercised too. Per-frame like the gizmo line: the stream clears every frame.
-///
-/// [`EffectPipelineKey`]: benilla_world::particles::render::EffectPipelineKey
-/// The HUD-substrate warm (0958's sweep, residual): on a normal entry the HUD's first quad batch
-/// lands under the cover — but nothing structural holds that timing (a slow Interface load would
-/// land it after the lift). One invisible overlay quad per warm frame pins the compile inside the
-/// cover window; the append lane clears itself every frame, so nothing lingers.
-///
-/// This warms the HUD's **batch mesh** layout (POSITION + UV_0 + COLOR) only. 0958 read
-/// `UiQuadMaterial` as "exactly ONE pipeline"; it is two, because a `Material2d` pipeline is
-/// keyed on the mesh layout as well as the view, and the minimap interior composite draws the
-/// same material on a `Rectangle` (POSITION + NORMAL + UV_0). That second one is warmed as a rig
-/// in [`menagerie`], not here — this lane's stream only ever builds the batch layout (2262).
+/// One invisible HUD quad per warm frame, so its batch-mesh pipeline (POSITION + UV_0 + COLOR)
+/// compiles under the cover. The minimap composite's `Rectangle` layout is a rig in [`menagerie`].
 fn warm_ui_quad_lane(warm: Res<WarmPass>, mut quads: ResMut<crate::ui_pass::UiQuads>) {
     if warm.spawned_at.is_none() || warm.done {
         return;
@@ -766,6 +599,11 @@ fn warm_ui_quad_lane(warm: Res<WarmPass>, mut quads: ResMut<crate::ui_pass::UiQu
     });
 }
 
+/// Push one degenerate draw per reachable [`EffectPipelineKey`] through the production stream,
+/// per warm view: `wow_effect` is a specialized lane whose pipelines exist only when a draw is
+/// queued, so no menagerie entity reaches it. Per frame, as the stream clears every frame.
+///
+/// [`EffectPipelineKey`]: benilla_world::particles::render::EffectPipelineKey
 fn warm_effect_lane(
     warm: Res<WarmPass>,
     mut quads: ResMut<EffectQuads>,
@@ -787,11 +625,8 @@ fn warm_effect_lane(
             EffectBlend::Multiply,
             EffectBlend::Mod2x,
         ] {
-            // The rasterizer settle is a PAIR — constant and slope-scale — and both halves are
-            // pipeline-key axes, so they are warmed as the pairs that actually ship, not as a
-            // cross product: every ground decal shares `Rung::DECAL_RASTER` (1817) and the foam
-            // takes its own, much smaller one. A hole here is a live compile the first time anyone
-            // wades or drops a shadow.
+            // The rasterizer settle's constant and slope are both key axes, warmed as the pairs
+            // that ship: every ground decal's, and the foam's.
             for (raster_bias, raster_slope) in [
                 (0, 0.0),
                 (benilla_world::sky_order::Rung::DECAL_RASTER, 0.0),
@@ -800,11 +635,8 @@ fn warm_effect_lane(
                     benilla_world::sky_order::Rung::FOAM_RASTER_SLOPE,
                 ),
             ] {
-                // `lit` is a pipeline-key axis (a shader def), so BOTH arms are warmed — a hole
-                // here is a first-lit-emitter compile mid-play, which is the whole failure this
-                // module exists to prevent (0937's holes, 0958's blind lanes). The lit arm is
-                // rare content (400 of 7792 emitters) which is exactly why it would otherwise
-                // never be warm when it finally shows up.
+                // Lighting is a key axis (a shader def), so both arms are warmed; lit emitters
+                // are rare.
                 for lighting in [
                     benilla_world::particles::buffer::EffectLighting::None,
                     benilla_world::particles::buffer::EffectLighting::Scene,
@@ -839,12 +671,8 @@ fn warm_effect_lane(
                 }
             }
         }
-        // The depth-test-off arm (2076), warmed as the ONE combination that ships rather than as
-        // another factor of the cross product above — the weapon swing trail is its only producer
-        // and it always draws alpha-blended, unlit, with no rasterizer settle. A hole here is a
-        // live compile on the first Heroic Strike anyone lands, which is the whole failure this
-        // module exists to prevent; a doubled cross product would be 36 more warm draws per camera
-        // for pipelines nothing will ever ask for.
+        // Depth-test off, warmed as the one combination that ships: the weapon swing trail,
+        // alpha-blended, unlit, no rasterizer settle.
         let start = quads.begin();
         for (u, v) in [(0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)] {
             quads.verts.push(EffectVertex {
@@ -889,9 +717,8 @@ mod census_tests {
         Projection::Orthographic(OrthographicProjection::default_3d())
     }
 
-    /// The warm set as it stood the day 2013 landed: the world camera's Perspective and the two
-    /// `Msaa::Off` booth classes. No orthographic arm — because there was no orthographic camera
-    /// when 0958 wrote the census down.
+    /// A warm set with no orthographic arm: the world camera's Perspective and the two
+    /// `Msaa::Off` booth classes.
     fn warm_set_before_2262() -> Vec<ViewClass> {
         vec![
             view_class(Some(&perspective()), Some(&Msaa::Off), true),
@@ -900,12 +727,8 @@ mod census_tests {
         ]
     }
 
-    /// **The census must fire for decision 2013's tile camera.** This is the case 2262's first
-    /// version could not report: that camera is `Msaa::Off` like every other booth, and 2262
-    /// skipped `samples == 1` outright, so the loop body was unreachable for it — and for every
-    /// other camera the client spawns, since `gxMultisample` defaults to 1 and only the world
-    /// camera ever reads it. The census now compares against the keys rigs actually rendered
-    /// through, so a class nothing warmed is a class it names.
+    /// The tile camera is `Msaa::Off` like every booth, so a census keyed on sample count alone
+    /// would miss it.
     #[test]
     fn the_census_fires_for_an_unwarmed_orthographic_camera() {
         let warm = warm_set_before_2262();
@@ -915,15 +738,12 @@ mod census_tests {
             "the ui_models tile camera's view key must read as unwarmed against a warm set that \
              has no orthographic arm — this is the report 2262 was written to produce"
         );
-        // And the rule 2262 actually shipped would have swallowed it.
         assert_eq!(
             tile_cam.samples, 1,
             "the tile camera is Msaa::Off, like every booth"
         );
     }
 
-    /// The other half: a class the menagerie DID render through is silent, so the census cannot
-    /// cry wolf on the cameras it is meant to bless.
     #[test]
     fn the_census_is_silent_for_every_warmed_class() {
         let warm = warm_set_before_2262();
@@ -938,8 +758,7 @@ mod census_tests {
         );
     }
 
-    /// `Hdr` is a key bit and the gate on two more (tonemap, deband — `bevy_pbr` `mesh.rs:418`).
-    /// 2262's census did not read it, so a 3-D camera that forgot `Hdr` was invisible to it.
+    /// `Hdr` is a key bit and gates two more (`bevy_pbr` `mesh.rs:418`).
     #[test]
     fn dropping_hdr_is_a_different_view_key() {
         let with = view_class(Some(&perspective()), Some(&Msaa::Off), true);
diff --git a/crates/benilla-app/src/poi_marker.rs b/crates/benilla-app/src/poi_marker.rs
index 5e1d4b5f..52d1b55d 100644
--- a/crates/benilla-app/src/poi_marker.rs
+++ b/crates/benilla-app/src/poi_marker.rs
@@ -1,36 +1,24 @@
-//! **The guard's directions** — the marker `SMSG_GOSSIP_POI` drops on the minimap and the world
-//! map when you ask a city guard where the warrior trainer is (or the bank, or the inn).
+//! The guard's directions: the marker `SMSG_GOSSIP_POI` drops on the minimap and world map.
 //!
-//! The wire is volunteered, never requested: a gossip option carrying an `action_poi_id` makes the
-//! server send `{flags, x, y, icon, data, name}` (vmangos `Player::OnGossipSelect` →
-//! `PlayerMenu::SendPointOfInterest`, `GossipDef.cpp:253`). Every 5875-era row ships
-//! `icon = 6` (`ICON_POI_REDFLAG` — the red flag with the yellow `!`) and `flags = 99`.
+//! The server volunteers `{flags, x, y, icon, data, name}` for a gossip option with an
+//! `action_poi_id` (vmangos `PlayerMenu::SendPointOfInterest`, `GossipDef.cpp:253`); every
+//! 5875-era row ships `icon = 6` (`ICON_POI_REDFLAG`) and `flags = 99`.
 //!
-//! **The reference does NOT give this its own drawing code.** It builds a synthetic `AreaPOI`
-//! record out of the packet and appends it to the minimap's landmark candidate list — one fixed
-//! static slot, so a new marker overwrites the old. Byte law and packet→record map (1516): handler
-//! `0x4e2840`, `set_blip 0x6dac10` writing static slot **1** at `0xcea7d4`, and the minimap's
-//! candidate array, which appends the static slots *unconditionally* (`0x6d8fa8`), bypassing
-//! the DBC scan's `ContinentID`/`Flags & 1` gate. So it is a landmark
-//! in every way that follows — the 0.8 in/out split, the `POIIcons` cell picked by `Icon`, the rim
-//! arrow, the nearest-3 `Importance` rank, the 694.444-yd rank cut (the marker gets **no**
-//! exemption from it — that belongs to the corpse slot `0xcea848`), the hover tooltip on both the
-//! icon and the arrow. This module holds only what is *specific* to the marker: the record, and
-//! its lifetime. The drawing is [`crate::minimap::blips`] and the world map's POI pool.
+//! The reference draws it as a landmark: the handler (`0x4e2840`) builds a synthetic `AreaPOI`
+//! record in static slot 1 at `0xcea7d4` (`set_blip` `0x6dac10`), which the minimap's candidate
+//! list appends unconditionally (`0x6d8fa8`), past the DBC scan's `ContinentID`/`Flags & 1` gate.
+//! Every landmark rule then applies, including the 694.444 yd rank cut (only the corpse slot
+//! `0xcea848` is exempt). This module holds the record and its lifetime; the drawing is
+//! [`crate::minimap::blips`] and the world map's POI pool.
 //!
-//! **The lifetime is four ways to lose it, whichever comes first**:
-//! - **8 minutes.** `set_blip` stamps a deadline of `time() + 480` — *seconds*, not the
-//!   milliseconds a `GetTickCount` reading would suggest (`0x429580` is a cached `time()`; the
-//!   tick count is only its 500 ms cache check).
-//! - **Arriving.** `minimap_update 0x6d93a0` clears it once `(player − marker)² < 100`
-//!   (`0x806b10`) — strictly inside 10 yards, the boundary excluded.
-//! - **A replacing packet.** One slot; the next set of directions overwrites this one.
-//! - **World entry.** The world-enter path runs `zone_rebuild`, which stamps the slot clear. Ours
-//!   maps that to a worldport and to logging out — the two ways a benilla session re-enters.
+//! The marker clears on whichever comes first:
+//! - 480 seconds after `set_blip` (`0x429580` is a cached `time()`, in seconds);
+//! - arriving strictly inside 10 yd (`minimap_update` `0x6d93a0`, `(player - marker)^2 < 100`);
+//! - the next set of directions, which overwrites the one slot;
+//! - world entry (`zone_rebuild`), here a worldport or a logout.
 //!
-//! The record keeps the map it was given on, because the wire has no map field and the world map
-//! must project the marker through *some* map's rect. The reference re-derives the same thing from
-//! its live current-map global at `set_blip` time (`+0x1c ContinentID ← [0x86f694]`).
+//! The wire has no map; the record takes the current map, as the reference does at `set_blip`
+//! (`+0x1c ContinentID <- [0x86f694]`).
 
 use benilla_formats::AreaPoi;
 use bevy::prelude::*;
@@ -41,33 +29,23 @@ use benilla_assets::coords::bevy_to_wow;
 use crate::net::{LoggedOutMessage, WorldportMessage};
 use crate::player::Player;
 
-/// The arrival clear's radius, squared, in yards² — `0x806b10` = 100 = (10 yd)², VERIFIED, and the
-/// compare is strict (`<`), so a marker exactly 10 yd away survives.
+/// The arrival radius squared, `0x806b10` = 100 yd^2, compared strictly.
 const ARRIVE_CLEAR_YD_SQ: f32 = 100.0;
-/// How long a set of directions lasts before it drops itself: `time() + 480` **seconds**
-/// (`set_blip 0x6dac10`'s deadline stamp; 480 ms would be a marker you could never walk to).
+/// The marker's lifetime, `time() + 480` seconds (`set_blip` `0x6dac10`).
 const MARKER_TTL_SECS: f64 = 480.0;
 
-/// The one point of interest a guard's directions left on the map — a synthetic `AreaPOI` record,
-/// exactly as the reference builds it, or `None` when no directions are live.
-///
-/// Read by the minimap's landmark pass ([`crate::minimap::blips`]) and the world map's feed
-/// ([`crate::ui_world_map`]); written only by the `SMSG_GOSSIP_POI` arm and the clears below.
+/// The live directions as the reference's synthetic `AreaPOI` record, read by
+/// [`crate::minimap::blips`] and [`crate::ui_world_map`].
 #[derive(Resource, Default)]
 pub(crate) struct PoiMarker {
-    /// The record. Its `continent_id` is the map the directions were given on, and its `pos` z is
-    /// `0.0`: the wire carries x/y only, and every law that reads it measures a 2-D distance (the
-    /// reference leaves `+0x18 Z` unwritten for the same reason).
+    /// Its z is 0: the wire carries x/y only, and the reference leaves `+0x18 Z` unwritten.
     pub(crate) poi: Option<AreaPoi>,
-    /// `Time<Real>` seconds at which the marker expires — meaningless while `poi` is `None`. Real,
-    /// not virtual: this is a wall-clock span like the corpse reclaim delay (decision 0846).
+    /// `Time<Real>` seconds at which the marker expires.
     expires_at: f64,
 }
 
 impl PoiMarker {
-    /// Take the guard's directions: replace whatever marker was live (the reference's single
-    /// slot), and start its 8-minute clock. `map_id` is the map the player is standing on — the
-    /// wire has no map field, and the reference reads its own current-map global here.
+    /// Replaces the live marker and starts its 8-minute clock; `map_id` is the player's map.
     pub(crate) fn set(
         &mut self,
         wire: &benilla_protocol::messages::GossipPoi,
@@ -76,11 +54,8 @@ impl PoiMarker {
     ) {
         self.expires_at = now_secs + MARKER_TTL_SECS;
         self.poi = Some(AreaPoi {
-            // The nearest-3 rim rank key is the packet's own `data` field, verbatim (`0x6dac4e`
-            // writes it to `+0x04 Importance` — 1516's correction; we had guessed a constant `0`).
-            // Shipped server data sends `0` in every row, which lands the marker in the
-            // first rank band: it out-ranks 28 of Kalimdor's 29 possible competitors outright and
-            // ties Eastern Kingdoms' Importance-0 landmarks, winning those on distance.
+            // The rank key is the packet's `data` (`0x6dac4e` writes `+0x04 Importance`); shipped
+            // rows send 0, the first rank band.
             importance: wire.data,
             icon: wire.icon,
             faction_id: 0,
@@ -89,22 +64,19 @@ impl PoiMarker {
             flags: wire.flags,
             area_id: 0,
             name: wire.name.clone(),
-            // Never written by the handler — and the reference's `GetMapLandmarkInfo` returns nil
-            // for this landmark's description because of it.
+            // Never written, so `GetMapLandmarkInfo` returns a nil description.
             description: String::new(),
             world_state_id: 0,
         });
     }
 
-    /// The marker, if it is on `map_id` — the one form both draws want.
+    /// The marker, if it is on `map_id`.
     pub(crate) fn on_map(&self, map_id: u32) -> Option<&AreaPoi> {
         self.poi.as_ref().filter(|p| p.continent_id == map_id)
     }
 }
 
-/// The two clocks that end a marker on their own: **arriving** (strictly inside 10 yd) and the
-/// **8-minute deadline**. Both are the reference's, and both are checked where it checks them —
-/// once a frame, in the minimap driver's place.
+/// Clears the marker on arrival or at its deadline, once a frame as the minimap driver does.
 fn expire_marker(mut marker: ResMut<PoiMarker>, player: Res<Player>, time: Res<Time<Real>>) {
     let Some(poi) = &marker.poi else {
         return;
@@ -122,10 +94,7 @@ fn expire_marker(mut marker: ResMut<PoiMarker>, player: Res<Player>, time: Res<T
     }
 }
 
-/// **World entry clears it** — the reference's fourth exit, whose path stamps the slot clear
-/// through `zone_rebuild`. Benilla re-enters the world in two ways: a worldport (the cross-map
-/// teleport that IS a new world entry) and a logout, after which the next login is somebody else's
-/// session.
+/// World entry clears the slot (`zone_rebuild`): a worldport or a logout.
 fn clear_on_world_entry(
     mut marker: ResMut<PoiMarker>,
     mut worldports: MessageReader<WorldportMessage>,
@@ -136,8 +105,6 @@ fn clear_on_world_entry(
     }
 }
 
-/// The marker's packet handler (in the net handler table since 2318, moved out of the drain's npc
-/// arm file) — registered from [`PoiMarkerPlugin`].
 fn on_gossip_poi(
     In(ev): In<benilla_protocol::SessionEvent>,
     mut marker: ResMut<PoiMarker>,
@@ -154,16 +121,8 @@ fn on_gossip_poi(
     }
 }
 
-/// The guard's directions (`SMSG_GOSSIP_POI`): drop the marker at that spot. Volunteered by the
-/// server for a gossip option carrying an `action_poi_id` — it answers nothing we asked for, and
-/// it does **not** end the gossip session on its own (vmangos `Player::OnGossipSelect`'s
-/// `GOSSIP_OPTION_GOSSIP` arm sends the POI *before* it decides whether to move the menu on, leave
-/// it, or close it).
-///
-/// `map_id` is the map the player is standing on, which is the only place the marker can mean
-/// anything — the wire carries no map field, and the reference reads its own current-map global at
-/// exactly this point. `now_secs` starts the marker's 8-minute clock (this module); it
-/// is the same real clock the corpse reclaim delay is stamped against (decision 0846).
+/// `SMSG_GOSSIP_POI`: drops the marker. It does not end the gossip session: vmangos
+/// `Player::OnGossipSelect` sends it before deciding what the menu does next.
 fn gossip_poi(
     poi: &benilla_protocol::messages::GossipPoi,
     marker: &mut PoiMarker,
@@ -177,7 +136,6 @@ fn gossip_poi(
     marker.set(poi, map_id, now_secs);
 }
 
-/// The guard's directions marker — see the module doc.
 pub(crate) struct PoiMarkerPlugin;
 
 impl Plugin for PoiMarkerPlugin {
@@ -197,13 +155,7 @@ mod tests {
     use super::*;
     use benilla_protocol::messages::GossipPoi;
 
-    /// The `POIIcons.blp` cell every 5875-era `points_of_interest` row ships: `ICON_POI_REDFLAG`,
-    /// which vmangos names "red flag w/ yellow !" (`GossipDef.h:113`) — and the real atlas agrees,
-    /// measured rather than taken on the enum's word: decoded off the install's own 128² DXT3
-    /// `POIIcons.blp`, cell 6's lit pixels mean **RGB (140, 38, 17)**, against the corpse skull's
-    /// (98, 70, 67) in cell 7 and the grey AV mine's (115, 113, 115) in cell 0 as controls.
-    /// Nothing hardcodes the number — the packet's own `icon` is what draws — so it lives here,
-    /// naming what the data actually sends.
+    /// The `POIIcons.blp` cell every 5875-era row ships, the red flag (`GossipDef.h:113`).
     const ICON_POI_REDFLAG: u32 = 6;
 
     fn wire(name: &str, x: f32, y: f32) -> GossipPoi {
@@ -216,9 +168,6 @@ mod tests {
         }
     }
 
-    /// The packet becomes the synthetic AreaPOI record the landmark pipeline reads: the wire's
-    /// own `flags`/`icon` (the two columns the draw laws consult), `data` as the rim rank key,
-    /// z zeroed, the map stamped.
     #[test]
     fn the_wire_becomes_a_landmark_record() {
         let mut m = PoiMarker::default();
@@ -236,7 +185,6 @@ mod tests {
         assert_eq!(poi.continent_id, 0, "the map it was given on");
     }
 
-    /// The rim rank key is the packet's `data`, verbatim — not a constant of ours (`0x6dac4e`).
     #[test]
     fn the_rank_key_is_the_packets_data_field() {
         let mut w = wire("The Bank", -8900.0, 600.0);
@@ -246,8 +194,6 @@ mod tests {
         assert_eq!(m.poi.as_ref().unwrap().importance, 7);
     }
 
-    /// One slot: the next set of directions replaces the last, it never stacks — and restarts the
-    /// 8-minute clock.
     #[test]
     fn a_second_set_of_directions_replaces_the_first() {
         let mut m = PoiMarker::default();
@@ -259,8 +205,6 @@ mod tests {
         assert_eq!(m.expires_at, 100.0 + MARKER_TTL_SECS);
     }
 
-    /// The deadline is 480 **seconds**, not milliseconds (`0x429580` is a cached `time()`) — long
-    /// enough to walk across a capital.
     #[test]
     fn the_deadline_is_eight_minutes_from_when_it_was_given() {
         let mut m = PoiMarker::default();
@@ -268,7 +212,6 @@ mod tests {
         assert_eq!(m.expires_at, 492.5);
     }
 
-    /// The marker is drawn only on the map it was given on.
     #[test]
     fn a_marker_is_off_the_map_it_was_not_given_on() {
         let mut m = PoiMarker::default();
diff --git a/crates/benilla-app/src/preflight.rs b/crates/benilla-app/src/preflight.rs
index 3b94e6c0..b1be8d1d 100644
--- a/crates/benilla-app/src/preflight.rs
+++ b/crates/benilla-app/src/preflight.rs
@@ -1,57 +1,22 @@
-//! The session preflight (decision 0649) — one always-on banner naming **what body we just logged
-//! into**, plus loud warnings for the avatar states that silently invalidate a session's work.
+//! The session preflight: an always-on banner naming the body just logged into, and warnings for
+//! the states that silently invalidate a run's readings.
 //!
-//! This is instrumentation for the *reader of the log*, not a game system. It exists because three
-//! things cost a session ten minutes each and none of them announces itself:
+//! 1. Dead or a ghost: nothing can be interacted with, the world renders through the death filter
+//!    and movement is rooted or ghost-speed.
+//! 2. GM mode on: vmangos's `Player::SetGameMaster` re-templates the player to faction template 35
+//!    (FactionTemplate.dbc: faction 31, group and enemy masks 0) and freezes the mirror timers, so
+//!    nothing is hostile, nothing aggros, environmental damage is skipped and breath never ticks.
+//!    It also keeps outdoor-only auras on indoors (`Player.cpp:6284` is `!IsGameMaster()`-gated),
+//!    so a GM stays mounted inside. It is on by default for a probe body; [`crate::probe_shield`]
+//!    makes dropping it safe.
+//! 3. Movement server-blocked: rooted, stunned, confused, fleeing or on a taxi.
+//! 4. No server at all ([`offline_notice`]): a capture run spawns no IO thread, so nothing on the
+//!    packet path executes and a clean exit proves nothing about it. This fires at startup, since
+//!    the banner itself waits on [`EnteredWorldMessage`].
+//! 5. Two `Camera2d`s on one target with different MSAA ([`camera_2d_msaa_agrees`]), fatal the
+//!    frame it happens with an error that names no camera.
 //!
-//! 1. **The character is dead or a ghost**, left that way by an earlier session. Nothing can be
-//!    interacted with, attacked, looted or talked to; the world renders through the death filter;
-//!    movement is rooted (unreleased) or ghost-speed (released). Every symptom reads like a client
-//!    bug, and the client is fine.
-//! 2. **GM mode is on** — which every probe character used to carry by default, as the only guard
-//!    against unattended aggro killing it. vmangos's `Player::SetGameMaster` re-templates the player
-//!    to **faction template 35** and freezes the mirror timers, so nothing is hostile, nothing
-//!    aggros, fall/environmental damage is skipped and breath/fatigue never tick.
-//!    FactionTemplate.dbc row 35 (VERIFIED from the extracted DBC): faction 31 "Friendly", own group
-//!    mask 0, enemy mask 0 — it is hostile to nothing and nothing is hostile to it. Any hostility,
-//!    reaction-colour, nameplate, aggro, threat, damage or drowning measurement taken with GM on is
-//!    simply wrong, quietly. It also silently suspends the **indoor dismount**: the outdoor-only
-//!    aura sweep is `!IsGameMaster()`-gated, so a GM rides into the Goldshire inn and stays mounted
-//!    (decision 0934). It is now **off** by default: [`crate::probe_shield`] keeps the body
-//!    alive without poisoning any of that (decision 0677), and this banner reports which it is.
-//! 3. **Movement is server-blocked** — rooted, stunned, confused, fleeing, or mid-taxi-flight. The
-//!    controller ignores input and the honest report is "the mover is broken".
-//! 4. **The run has no server at all** ([`offline_notice`], decision 0728). Capture mode passes
-//!    `NetPlugin { connect: false }`, so no IO thread is spawned and the drain receives nothing —
-//!    the whole packet path (`net::apply`, the movement wire, every `MSG_MOVE_*`) simply does not
-//!    execute. This one is the mirror image of the other three: they make a healthy client *look*
-//!    broken, while this makes an untested change *look proven*. A capture run over a change to the
-//!    packet path exits clean no matter what that change does, and "clean run" then lands in a
-//!    commit message as evidence it never was (twice in one day — decisions 0725 and 0726, both
-//!    pure wire work, both reported with a capture run behind them). The banner above cannot catch
-//!    it: that one waits on [`EnteredWorldMessage`], which needs a server. So this notice fires at
-//!    **startup**, before anything can be concluded from the run.
-//!
-//! 5. **Two `Camera2d`s on one target disagree about MSAA** ([`camera_2d_msaa_agrees`], decision
-//!    1659). Not an avatar state, but the same shape as the four above: it is invisible until it
-//!    kills the frame, and when it does, wgpu's `Attachments have differing sample counts` names
-//!    two numbers and no camera. One scan on the frame the cameras spawn turns that into a line
-//!    that names them.
-//!
-//! The banner is **not env-gated**: a warning nobody knows to switch on is not a warning. It costs
-//! one line per world entry when everything is fine, and it re-fires on every re-entry (a relog, a
-//! `.character race` forced logout, a reconnect) because the state can have changed.
-//!
-//! The same audience — the reader of the log — is why [`benilla_world::build_id::banner`] exists.
-//! It is **not** registered here any more (decision 1179): this module is dev-only since 1174, and
-//! "which build produced this log" is the first thing a report from *someone else's machine* has to
-//! establish — which is precisely the player build. The banner now registers beside the stamp
-//! itself, in `lib::run`, where it is always compiled.
-//!
-//! The other half of decision 0649 — the pre-connect **account guard**, which keeps a scripted
-//! run from logging in as an account its checkout did not declare — lives in
-//! [`crate::run_mode`] now, not here: it is consulted by the login policy, and 1174's seam does not
-//! let gameplay call an instrument. Its reasoning went with it.
+//! The banner is not env-gated and re-fires on every world entry, since the state can change.
 
 use std::collections::HashMap;
 
@@ -66,21 +31,14 @@ use crate::net::{DisconnectedMessage, EnteredWorldMessage, ObjectStore, SelfGuid
 use crate::probe_shield::{ProbeShield, ShieldReport};
 use benilla_world::world_map::CurrentMap;
 
-/// `PLAYER_FLAGS_GM` (vmangos `Player.h`) — set by `SetGameMaster(true)` alongside the faction-35
-/// re-template. PUBLIC, so it rides our own descriptor like any other player flag.
+/// `PLAYER_FLAGS_GM` (vmangos `Player.h`), set by `SetGameMaster(true)` with the faction-35
+/// re-template; a public flag on our own descriptor.
 const PLAYER_FLAGS_GM: u32 = 0x0000_0008;
 
-/// The `UNIT_FIELD_FLAGS` bits that mean "the server is driving, or refusing to let you drive"
-/// (vmangos `UnitDefines.h`) — each is a distinct reason the **mover** looks broken.
-///
-/// **PACIFIED and DISARMED used to sit in here and do not belong** (decision 1903): neither
-/// touches movement, and a banner telling a session "movement is server-blocked" because the
-/// character is disarmed sends someone hunting a mover bug that is not there. They moved to
-/// [`ABILITY_BLOCKERS`]. What is left is movement — and note they are **not one gate**: STUNNED
-/// is the only bit that reaches the local input tick (`0x5145b0` → `0x514755`, killing the turn
-/// and pitch emitters), CONFUSED and FLEEING act through the `IsSelfControlled` predicate
-/// `0x5fa550` (mask `0xc00004`, which STUNNED is *not* in), POSSESSED does not refuse at all but
-/// redirects to the charmer (`0x5fa582`), and the taxi bit shares no gate with any of them.
+/// The `UNIT_FIELD_FLAGS` bits (vmangos `UnitDefines.h`) that block or drive the mover, each
+/// through its own gate: STUNNED alone reaches the input tick (`0x5145b0` → `0x514755`, no turn or
+/// pitch), CONFUSED and FLEEING act through `0x5fa550` (mask `0xc00004`), POSSESSED redirects to
+/// the charmer (`0x5fa582`), and the taxi bit shares no gate.
 const MOVE_BLOCKERS: &[(u32, &str)] = &[
     (0x0004_0000, "STUNNED (no turning, no pitch)"),
     (
@@ -92,9 +50,7 @@ const MOVE_BLOCKERS: &[(u32, &str)] = &[
     (0x0100_0000, "POSSESSED (another unit holds the reins)"),
 ];
 
-/// The `UNIT_FIELD_FLAGS` bits that leave the mover alone and take **abilities** away instead —
-/// the other half of the split above. A session that reads "movement is server-blocked" and finds
-/// the character walking fine has been misdirected; these say what is actually gone.
+/// The `UNIT_FIELD_FLAGS` bits that leave the mover alone and take abilities away.
 const ABILITY_BLOCKERS: &[(u32, &str)] = &[
     (0x0002_0000, "PACIFIED (no melee, no pacify-blocked casts)"),
     (
@@ -105,39 +61,25 @@ const ABILITY_BLOCKERS: &[(u32, &str)] = &[
     ),
 ];
 
-/// Worth naming on entry: an unattended probe that logs in already fighting is the exact shape of
-/// the accident the unattended-combat ban exists for (docs/METHOD.md). The bit itself is declared once
-/// ([`crate::player`]).
+/// Named on entry: an unattended run must not be left fighting (`docs/METHOD.md`).
 use crate::player::UNIT_FLAG_IN_COMBAT;
 
-/// `UNIT_FLAG_SILENCED` — the client's OWN local refusal, not just the server's: the CC validator
-/// `0x6094f0` (reached from `TryCast 0x6e4b60`, bailing at `0x6e4f42`) refuses before any packet
-/// goes out. But it is **per spell** — the arm runs only where `Spell.dbc PreventionType` (column
-/// 165) is `1`, so a silence stops the ~4800 rows that declare it and nothing else (decision
-/// 1903). The banner said "spell casts will refuse" flat, which is wrong for every other row.
+/// `UNIT_FLAG_SILENCED`: the 1.12 client refuses locally (`0x6094f0`, from `0x6e4b60`), but only
+/// spells whose `Spell.dbc` `PreventionType` (column 165) is 1.
 const UNIT_FLAG_SILENCED: u32 = 0x0000_2000;
 
-/// The GM faction template vmangos swaps in with GM mode (`SetFactionTemplateId(35)`).
+/// The faction template vmangos swaps in with GM mode (`SetFactionTemplateId(35)`).
 const GM_FACTION_TEMPLATE: u32 = 35;
 
-/// How long after world entry we keep waiting for the zone name before reporting without it. The
-/// descriptor lands in a few hundred ms but the area id only resolves once the tile under us has
-/// streamed (~2 s), and "Eastern Plaguelands" is the line's whole orienting value — a raw map id
-/// and a coordinate triple do not tell a reader at a glance that this character is nowhere useful.
+/// How long after world entry to wait for the zone name, which resolves only once the tile under
+/// us has streamed (~2 s).
 const ZONE_WAIT_SECS: f32 = 4.0;
 
-/// How long we let an in-flight `.gm off` settle before banner-ing the GM flag anyway.
-///
-/// `WOW_GM=off` is a **round trip** and it loses the race with the descriptor: the shield sends
-/// `.gm off` at world entry and the server's answer lands ~0.9 s later, while the self descriptor
-/// is here in ~0.3 s. Without this grace the banner shouts "GM MODE IS ON — any damage or drowning
-/// reading taken now is wrong" at precisely the run that asked for GM off, which reads as *discard
-/// this measurement* and is exactly backwards (a 2026-08-13 lava probe hit it). Wait, then report
-/// what actually held — a `.gm off` that never lands is still warned about, one grace later.
+/// How long an in-flight `.gm off` gets to land before the GM flag is reported: its answer takes
+/// ~0.9 s, the self descriptor ~0.3 s.
 const GM_OFF_WAIT_SECS: f32 = 3.0;
 
-/// The hard backstop: report whatever we have this long after world entry. Only reached when
-/// something is badly wrong with the stream, and reporting late beats never reporting.
+/// The backstop: report whatever there is this long after world entry.
 const DESCRIPTOR_WAIT_SECS: f32 = 8.0;
 
 pub(crate) struct PreflightPlugin;
@@ -154,13 +96,7 @@ impl Plugin for PreflightPlugin {
     }
 }
 
-/// Say out loud, once at startup, that this run has **no server** — so nobody reads its clean exit
-/// as evidence about code that never ran (module header §4, decision 0728).
-///
-/// Deliberately a `warn!` rather than an `info!`. A netless run is completely normal and completely
-/// fine — it is what every visual capture wants — so this is not a complaint about the run. It is
-/// aimed at the *reader*, who is usually a session skimming for the word "error" before pasting
-/// "clean run" into a commit message, and `warn` is the lowest level that survives that skim.
+/// Warn once at startup that this run has no server; a `warn!` so a skim of the log sees it.
 fn offline_notice(net: Option<Res<crate::net::NetOffline>>) {
     if net.is_none() {
         return;
@@ -173,31 +109,10 @@ fn offline_notice(net: Option<Res<crate::net::NetOffline>>) {
     );
 }
 
-/// **Every `Camera2d` sharing a render target must carry the same `Msaa`** — checked out loud on
-/// the frame they spawn, because the failure is fatal, immediate, and names nobody (decision 1659).
-///
-/// Bevy's two prepare passes disagree about whether the sample count is part of a texture's
-/// identity. `view::prepare_view_targets` keys the **colour** target on `(target, usage, hdr,
-/// msaa)`, so every camera gets an attachment at its own count. `core_2d::
-/// prepare_core_2d_depth_textures` keys the **depth** texture on `camera.target` *alone* and stamps
-/// it with whichever camera the hash map reaches first — `core_3d`'s equivalent keys on `(target,
-/// msaa)`, so the asymmetry is 2D-only and there is nothing here for `Camera3d`. Two `Camera2d`s on
-/// one window at different counts therefore share one depth texture, and the one that did not
-/// create it opens its pass with mismatched attachments: `Attachments have differing sample
-/// counts: the depth attachment's texture view has count N but ... count M`. Two numbers, no
-/// camera, no system, no frame — a panic in `render_system` on a thread called `Compute Task Pool`.
-///
-/// It costs a session an afternoon of source archaeology, and it is one query to catch. The trap
-/// that produces it is silence: `Camera` requires `Msaa` and `Msaa::default()` is `Sample4`, so a
-/// camera that never mentions multisampling does not get none, it gets four (1628 found that
-/// costing a full-window 4× texture on the player-UI camera; 1659 found the same silence on the
-/// egui overlay camera crashing the debug panel outright, one commit after 1628 broke the tie that
-/// had been hiding it). So the error below says *which* camera and *what* count, and names the
-/// likely cause.
-///
-/// Gated on `Added<Camera2d>` rather than run once at `PostStartup`: our three 2D cameras all spawn
-/// in `Startup` today, but a fourth added later must be checked too, and the guard makes the
-/// steady-state cost one empty query.
+/// Every `Camera2d` on one render target must carry the same `Msaa`: Bevy keys the 2D depth
+/// texture on the target alone (`core_2d::prepare_core_2d_depth_textures`) but the colour target
+/// on the sample count too, so a mismatch panics in `render_system` naming no camera. A camera
+/// that never names an `Msaa` gets `Sample4`. Checked whenever a `Camera2d` is added.
 fn camera_2d_msaa_agrees(
     added: Query<(), (With<Camera2d>, Added<Camera2d>)>,
     cams: Query<(Entity, &RenderTarget, &Msaa, Option<&Name>), With<Camera2d>>,
@@ -209,7 +124,7 @@ fn camera_2d_msaa_agrees(
     let primary = primary.single().ok();
     let mut first: HashMap<NormalizedRenderTarget, (Entity, Option<String>, u32)> = HashMap::new();
     for (entity, target, msaa, name) in &cams {
-        // A target that will not normalize has no swapchain yet and no depth texture either.
+        // A target that will not normalize has no depth texture yet.
         let Some(key) = target.normalize(primary) else {
             continue;
         };
@@ -239,10 +154,10 @@ fn camera_2d_msaa_agrees(
 }
 
 /// The banner's once-per-entry latch: armed by [`EnteredWorldMessage`], disarmed when the report
-/// goes out, when the wait expires, or when the session that armed it ends.
+/// goes out, the wait expires or the session ends.
 #[derive(Resource, Default)]
 struct Preflight {
-    /// `Time::elapsed_secs` at the world entry we still owe a report for; `None` = nothing pending.
+    /// `Time::elapsed_secs` at the world entry still owed a report.
     armed_at: Option<f32>,
 }
 
@@ -263,13 +178,8 @@ fn report_session(
     if entered.read().next().is_some() {
         state.armed_at = Some(time.elapsed_secs());
     }
-    // **A session that ended disarms the wait** — after the arm, so the entry-and-death-in-one-drain
-    // race (decision 1262) resolves the way it does everywhere else: the dead session is the last
-    // word. Without this the latch outlives the session that armed it and the banner fires from the
-    // glue screen, telling a future reader that "the avatar never streamed in" when the truth is
-    // that nobody ever entered a world for it to stream into. A refused character login makes that
-    // reachable on purpose (`SMSG_CHARACTER_LOGIN_FAILED` revokes an entry already announced); a
-    // socket that dies mid-entry always could.
+    // An ended session disarms the wait, after the arm, so an entry and a disconnect in one drain
+    // leave it disarmed (`SMSG_CHARACTER_LOGIN_FAILED` revokes an announced entry).
     if ended.read().next().is_some() {
         state.armed_at = None;
     }
@@ -284,13 +194,11 @@ fn report_session(
         }
         return;
     };
-    // MAXHEALTH is always in the login snapshot; an empty store means the create block hasn't been
-    // applied yet, and reading it would report a level-0 dead corpse of no race.
+    // MAXHEALTH is always in the login snapshot; without it the create block is not applied yet.
     if store.0.unit_max_health().unwrap_or(0) == 0 && !expired {
         return;
     }
-    // `CurrentArea` is the FINEST area under us ("Darrowshire"), which on its own can be unplaceable;
-    // the parent zone ("Eastern Plaguelands") is what orients a reader, so print zone / subzone.
+    // The area is the finest one under us, so print zone / subzone.
     let zone = world
         .area()
         .zip(area_table.as_deref())
@@ -305,10 +213,9 @@ fn report_session(
         })
         .filter(|z| !z.is_empty());
     if zone.is_none() && time.elapsed_secs() - armed_at < ZONE_WAIT_SECS {
-        return; // the tile under us hasn't streamed yet — give the zone name its grace
+        return; // the tile under us has not streamed yet
     }
-    // The other in-flight state the banner would otherwise misreport: a requested `.gm off` that
-    // the server has not answered yet (see [`GM_OFF_WAIT_SECS`]).
+    // A requested `.gm off` the server has not answered yet.
     if hold_for_gm_off(
         store.0.player_flags() & PLAYER_FLAGS_GM != 0,
         crate::probe_shield::wants_gm_off(),
@@ -334,8 +241,7 @@ fn report_session(
         .and_then(|c| crate::ui_unit::class_names(c).map(|(d, _)| d))
         .unwrap_or("?");
     let zone = zone.unwrap_or_default();
-    // Printed as the raw WoW triple, which is what `.go xyz <x> <y> <z> <map>` takes — the whole
-    // point of putting the position in the banner is that it can be pasted back.
+    // The raw WoW triple, as `.go xyz <x> <y> <z> <map>` takes it.
     let [wx, wy, wz] = benilla_assets::coords::bevy_to_wow(transform.translation);
     info!(
         "preflight: {name} — level {lvl} {race} {class}, {hp}/{maxhp} hp, map {map}{zone} @ [{wx:.1}, {wy:.1}, {wz:.1}], faction template {faction}{shielded}",
@@ -344,9 +250,7 @@ fn report_session(
         maxhp = store.0.unit_max_health().unwrap_or(0),
         map = map.map_or(-1, |m| m.0 as i64),
         faction = store.0.unit_faction_template().unwrap_or(0),
-        // A shielded body is good news, so it rides the banner rather than the warning ladder —
-        // but it is still *stated*, because "can this thing die?" is the first question an
-        // unattended run needs answered (decision 0677).
+        // A shielded body rides the banner, not the warnings.
         shielded = match shield.report() {
             ShieldReport::Armed => ", SHIELDED (cannot die)",
             ShieldReport::Arming => ", shield arming",
@@ -359,13 +263,8 @@ fn report_session(
     }
 }
 
-/// Whether to hold the banner for a `.gm off` that has gone out but not been answered
-/// ([`GM_OFF_WAIT_SECS`] is the why). Pure, so the race it guards is testable without an app.
-///
-/// All four clauses matter. Only a run that *asked* for GM off waits; only a body the shield
-/// actually commands (`probe<N>`) can have a `.gm off` in flight at all — on the director's own
-/// account `WOW_GM` is inert (0677), so waiting there would just delay a true warning; and the
-/// grace expires, so a `.gm off` that never lands is still reported, one grace later.
+/// Whether to hold the banner for a `.gm off` sent but not answered: only a run that asked for it,
+/// only on a body the shield commands, and only until [`GM_OFF_WAIT_SECS`].
 fn hold_for_gm_off(gm_flag_set: bool, wants_off: bool, shield: ShieldReport, waited: f32) -> bool {
     gm_flag_set
         && wants_off
@@ -373,9 +272,7 @@ fn hold_for_gm_off(gm_flag_set: bool, wants_off: bool, shield: ShieldReport, wai
         && waited < GM_OFF_WAIT_SECS
 }
 
-/// Everything about this avatar that will quietly invalidate a session's work, worst first. Pure
-/// over the descriptor (plus the one piece of state that rides no descriptor field — the probe
-/// shield, decision 0677) so the whole ladder is unit-testable.
+/// Everything about this avatar that will quietly invalidate a run's readings, worst first.
 fn findings(
     fields: &benilla_protocol::messages::ObjectFields,
     shield: ShieldReport,
@@ -383,8 +280,7 @@ fn findings(
     let mut out = Vec::new();
     let unit_flags = fields.unit_flags();
 
-    // Dead and ghost are mutually exclusive on the wire (a released ghost's health is 1, decision
-    // 0308 §1) — report whichever holds, never both.
+    // Dead and ghost are exclusive on the wire: a released ghost's health is 1.
     if fields.unit_is_dead() {
         out.push(
             "THE CHARACTER IS DEAD (health 0, corpse not released) — the mover is server-rooted \
@@ -401,7 +297,7 @@ fn findings(
         );
     }
 
-    // The shield's bad states are findings; being armed is good news and rides the banner line.
+    // Being armed rides the banner line; only the bad states are findings.
     match shield {
         ShieldReport::Disabled => out.push(
             "THE PROBE SHIELD IS OFF (WOW_GOD=off) — this character CAN die, so an unattended run \
@@ -427,17 +323,12 @@ fn findings(
              `CheckAreaExploreAndOutdoor` drops outdoor-only auras only `if (… && \
              !IsGameMaster())`, so a GM rides into a building and stays mounted (decision 0934). {}",
             match shield {
-                // GM mode is the DEFAULT (0679) — it is what stops a parked body being mobbed, and
-                // the shield is what makes dropping it safe. So this warning is expected on most
-                // runs, and its job is to make sure nobody measures hostility through faction 35.
+                // The default on a probe body, so this warning shows on most runs.
                 ShieldReport::Arming | ShieldReport::Armed =>
                     "This is the default. Re-run with WOW_GM=off for those readings — safe, \
                      because the probe shield (decision 0677) keeps the body alive without it.",
-                // Not a probe body — a player's account, or a plain test account. `WOW_GM` would be
-                // inert here (the shield only ever commands `probe<N>`, 0677), and saying otherwise
-                // sends the reader after a switch that does nothing. The state is also PERSISTED:
-                // vmangos saves it in `characters.extra_flags` bit 0 and `GM.LoginState = 2`
-                // restores it, so it stays on across logins until somebody turns it off.
+                // `WOW_GM` does not reach a non-probe body, and vmangos persists GM mode in
+                // `characters.extra_flags` bit 0, restored at login by `GM.LoginState = 2`.
                 ShieldReport::NotOurs =>
                     "WOW_GM does not reach this body — the shield only ever commands probe accounts \
                      (0677) — so the way out is typing `.gm off` yourself. It persists across \
@@ -495,8 +386,7 @@ mod tests {
     use super::*;
     use benilla_protocol::messages::ObjectFields;
 
-    /// Build a player descriptor from `(field index, value)` pairs — the wire indices the
-    /// accessors read.
+    /// Build a player descriptor from `(field index, value)` pairs.
     fn player(fields: &[(u16, u32)]) -> ObjectFields {
         ObjectFields::from_pairs(fields)
     }
@@ -506,16 +396,14 @@ mod tests {
     const UNIT_FLAGS: u16 = 46;
     const PLAYER_FLAGS: u16 = 190;
 
-    /// The banner must not accuse a `WOW_GM=off` run of measuring through GM mode while the
-    /// `.gm off` it just sent is still in flight — the race [`GM_OFF_WAIT_SECS`] exists for, and
-    /// the one a lava probe walked into on 2026-08-13.
+    /// A `WOW_GM=off` run is not warned about GM mode while its `.gm off` is in flight.
     #[test]
     fn the_banner_waits_out_a_gm_off_round_trip_but_not_forever() {
-        // The race itself: flag still set, we asked for off, shield is ours, answer not back yet.
+        // Flag still set, off asked for, shield ours, answer not back yet.
         assert!(hold_for_gm_off(true, true, ShieldReport::Arming, 0.4));
         assert!(hold_for_gm_off(true, true, ShieldReport::Armed, 0.4));
 
-        // …but the grace expires, so a `.gm off` that never lands is still reported.
+        // A `.gm off` that never lands is still reported.
         assert!(!hold_for_gm_off(
             true,
             true,
@@ -523,14 +411,12 @@ mod tests {
             GM_OFF_WAIT_SECS + 0.1
         ));
 
-        // Nothing else ever waits. GM mode is the DEFAULT (0679): a run that did not ask for it off
-        // must be warned immediately, not three seconds late…
+        // Nothing else waits: not a run that did not ask for off,
         assert!(!hold_for_gm_off(true, false, ShieldReport::Armed, 0.4));
-        // …a body the shield does not command (the director's own account) can have no `.gm off`
-        // in flight at all, so waiting there would only delay a true warning (0677)…
+        // not a body the shield does not command,
         assert!(!hold_for_gm_off(true, true, ShieldReport::NotOurs, 0.4));
         assert!(!hold_for_gm_off(true, true, ShieldReport::Disabled, 0.4));
-        // …and with the flag already clear there is nothing to wait for.
+        // and not a clear flag.
         assert!(!hold_for_gm_off(false, true, ShieldReport::Armed, 0.4));
     }
 
@@ -546,7 +432,7 @@ mod tests {
         let dead = findings(&player(&[(MAXHEALTH, 60)]), ShieldReport::Armed);
         assert_eq!(dead.len(), 1);
         assert!(dead[0].contains("IS DEAD"));
-        // Ghost: health 1 and PLAYER_FLAGS_GHOST — the wire never shows both (decision 0308 §1).
+        // Ghost: health 1 and PLAYER_FLAGS_GHOST.
         let ghost = findings(
             &player(&[(HEALTH, 1), (MAXHEALTH, 60), (PLAYER_FLAGS, 0x10)]),
             ShieldReport::Armed,
@@ -570,8 +456,6 @@ mod tests {
     #[test]
     fn a_shielded_body_says_nothing_but_an_unshielded_one_does() {
         let healthy = player(&[(HEALTH, 60), (MAXHEALTH, 60)]);
-        // Armed is good news: it rides the banner line, never the warning ladder. Neither does a
-        // body the shield has no opinion about (the director's own account).
         for quiet in [
             ShieldReport::Armed,
             ShieldReport::Arming,
@@ -579,7 +463,7 @@ mod tests {
         ] {
             assert!(findings(&healthy, quiet).is_empty(), "{quiet:?}");
         }
-        // Both failure shapes are findings, because both mean "this body can die".
+        // Both failure shapes mean the body can die.
         let off = findings(&healthy, ShieldReport::Disabled);
         assert_eq!(off.len(), 1);
         assert!(off[0].contains("SHIELD IS OFF") && off[0].contains("WOW_GOD"));
@@ -590,10 +474,8 @@ mod tests {
 
     #[test]
     fn the_gm_warning_always_names_the_way_out() {
-        // GM mode is the default (0679), so this warning fires on nearly every probe run. Its whole
-        // job is that nobody measures hostility through faction 35 without being told how to stop —
-        // and the old advice ("put it back on when you are done") must not come back, because a
-        // session that complies re-poisons every faction reading (0657).
+        // The way out is always named, and never "put it back on", which re-poisons every
+        // faction reading.
         let gm = player(&[
             (HEALTH, 60),
             (MAXHEALTH, 60),
@@ -610,9 +492,7 @@ mod tests {
             assert!(line.contains("WOW_GM=off"), "{report:?}: {line}");
             assert!(!line.contains("put it back on"), "{report:?}: {line}");
         }
-        // …but the way out has to be one that WORKS on this body. `WOW_GM` only ever commands a
-        // probe account (0677), so on anyone else's — the director's own, which is exactly who
-        // rides into an inn and asks why they are still mounted — the switch is `.gm off`, typed.
+        // On a non-probe body `WOW_GM` does nothing; the way out is typing `.gm off`.
         let not_ours = findings(&gm, ShieldReport::NotOurs);
         let line = not_ours
             .iter()
@@ -626,9 +506,7 @@ mod tests {
 
     #[test]
     fn the_gm_warning_names_the_indoor_dismount() {
-        // The consequence that cost a session (decision 0934): the outdoor-only aura sweep is
-        // `!IsGameMaster()`-gated server-side, so a GM never dismounts riding into a building — and
-        // the client, whose mount lane is nothing but the MOUNTDISPLAYID watcher, has no say in it.
+        // The server's outdoor-only aura sweep skips a GM, so a GM stays mounted indoors.
         let gm = player(&[
             (HEALTH, 60),
             (MAXHEALTH, 60),
@@ -650,10 +528,7 @@ mod tests {
         assert!(out[0].contains("STUNNED") && out[0].contains("TAXI FLIGHT"));
     }
 
-    /// **The two tables are separate lines, and neither claims the other's symptom** (decision
-    /// 1903). PACIFIED and DISARMED touch no movement gate — sending a session to hunt a mover
-    /// bug is the whole cost of filing them under one banner, and this is what makes that
-    /// regression loud.
+    /// PACIFIED and DISARMED touch no movement gate, so they never report as a movement block.
     #[test]
     fn ability_blockers_are_their_own_line_and_never_say_movement() {
         let disarmed = player(&[(HEALTH, 60), (MAXHEALTH, 60), (UNIT_FLAGS, 0x0020_0000)]);
@@ -667,7 +542,7 @@ mod tests {
             out[0]
         );
 
-        // Both halves at once: two lines, each naming only its own flags.
+        // Both at once: two lines, each naming only its own flags.
         let both = player(&[
             (HEALTH, 60),
             (MAXHEALTH, 60),
diff --git a/crates/benilla-app/src/probe_shield.rs b/crates/benilla-app/src/probe_shield.rs
index a61392f7..7e8a499e 100644
--- a/crates/benilla-app/src/probe_shield.rs
+++ b/crates/benilla-app/src/probe_shield.rs
@@ -1,74 +1,23 @@
-//! The probe shield (decision 0677) — **a probe body cannot die, and does not need GM mode to stay
-//! alive.**
+//! The probe shield: a probe body cannot die, and does not need GM mode to stay alive.
 //!
-//! ## The failure it removes
+//! GM mode (`Player::SetGameMaster`) re-templates the player to faction 35 ("Friendly", enemy
+//! mask 0) and freezes the mirror timers, so nothing hostility-, damage- or breath-related can be
+//! measured with it on. `.cheat god` (`Player::SetCheatGod` → `SetInvincibilityHpThreshold(1)`)
+//! instead makes `Unit::DealDamage` stop at 1 hp, environmental damage included, and changes
+//! nothing a client can see. The shield is always armed; GM mode also stays on by default, since
+//! the shield does not stop aggro, and `WOW_GM=off` drops it safely when a run needs faithful
+//! factions. A shielded body with GM off in a hostile camp survives pinned at 1 hp.
 //!
-//! Probe characters kept dying, and the reason was structural: the only protection we had was **GM
-//! mode**, and GM mode is exactly what a session has to switch off to measure anything real.
-//! `Player::SetGameMaster(true)` re-templates the player to faction 35 ("Friendly", enemy mask 0)
-//! and freezes the mirror timers, so with it on nothing is hostile, nothing aggros, environmental
-//! damage is skipped and breath/fatigue never tick (0649, 0657). Every session doing hostility,
-//! reaction-colour, nameplate, threat, damage or drowning work therefore sends `.gm off` — and the
-//! moment it does, the body is a level-1 standing wherever the last session parked it. Measured on
-//! this project's own transcripts: `.gm off` **257×**, `.revive` **121×** (0651). Measured live
-//! while writing this: `.gm off` on a probe parked in Valley of Spears killed it in **~2 seconds**,
-//! inside the gap between two probe-chat lines.
+//! - Not persisted: the threshold is a runtime `Unit` member, so it is re-sent on every world
+//!   entry, and a body parked somewhere hostile is unshielded for the few hundred ms before the
+//!   first line goes out. GM mode on by default keeps it from being whittled down there.
+//! - Target-sensitive: `.cheat god on` acts on the current selection and answers "Player not
+//!   found!" for a creature, so the command always names the character.
+//! - `.die` clears it silently (`HandleDieHelper` calls `SetCheatGod(false)`), so a death re-arms
+//!   it.
 //!
-//! Telling sessions to "put GM mode back when you are done" was the old advice and it cannot work:
-//! it asks every session to remember a manual step at the exact moment it is thinking about
-//! something else, and it trades one silent wrongness (a dead probe) for another (faction 35).
-//!
-//! ## What it does instead
-//!
-//! vmangos has a second, *invisible* protection: **`.cheat god`**
-//! (`Player::SetCheatGod` → `SetInvincibilityHpThreshold(1)`). `Unit::DealDamage` then clamps every
-//! hit at 1 hp instead of calling `Kill` — and `Player::EnvironmentalDamage` (fall, lava, slime,
-//! drowning, fatigue) routes through the same `DealDamage`, so it is covered too. Unlike GM mode it
-//! touches **nothing** a client can see: no `UNIT_FIELD_FLAGS` bit, no `PLAYER_FLAGS` bit, no
-//! faction re-template, no frozen timers. Damage still lands, combat still happens, hostility is
-//! still faithful — the body simply cannot reach 0.
-//!
-//! **The shield is therefore always on** — and, since it does not stop *aggro*, GM mode **stays on
-//! by default too** (decision 0679). The two do different jobs: GM mode stops the town attacking a
-//! parked body, the shield stops anything killing it. Without the shield, `.gm off` was a two-second
-//! death sentence; with it, `.gm off` (`WOW_GM=off`) is a free, safe switch a session flips whenever
-//! it needs faithful factions. That — making the drop safe, not making it the default — is the whole
-//! win. A shielded body with GM off in a hostile camp survives, but survives *pinned*: 1 hp, stunned,
-//! permanently in combat, never regenerating, which is its own kind of useless.
-//!
-//! ## The three things about it that are not obvious
-//!
-//! 1. **It is not persisted**, and that leaves a window nothing here can close.
-//!    `m_invincibilityHpThreshold` is a runtime `Unit` member, zeroed in the constructor and never
-//!    saved, so it must be re-sent on **every world entry** — which is why this is a client module
-//!    and not a one-off DB fix. But a command cannot be sent before we are *in* the world, so a body
-//!    parked somewhere hostile is unshielded for the few hundred ms it takes to get the first line
-//!    out. MEASURED: a probe left at 1 hp in a centaur camp entered the world at `29.41`, had the
-//!    shield confirmed at `29.75` (+337 ms) and was already **dead** when the banner printed at
-//!    `29.97`. This is the "it was alive at 1 hp when I closed the window, it was dead next login"
-//!    report, and it is why **GM mode stays on by default** (0679): the fix is to never let the body
-//!    be whittled down and mobbed in the first place, not to arm faster.
-//! 2. **It is target-sensitive.** `.cheat god on` re-targets to the current selection
-//!    (`ChatHandler::GetSelectedPlayer` → `sObjectMgr.GetPlayer(guid)`), which is `nullptr` for a
-//!    creature — the server answers *"Player not found!"* and the body is left mortal. VERIFIED
-//!    live: with a centaur Tab-selected the bare form was refused, and the same command with the
-//!    name appended succeeded before and after. So we **always name the character**.
-//! 3. **`.die` clears it silently.** `HandleDieHelper` calls `SetCheatGod(false)` with
-//!    `notify = false` before killing, so deliberate death-testing still works out of the box —
-//!    but the shield is down afterwards and nothing says so. Hence the death watch below.
-//!
-//! ## What it never touches
-//!
-//! Only a body on a **probe account** (`probe<N>`). The director's own account is never given a
-//! command it did not ask for, whether they typed the login or an env var did.
-//!
-//! ## Knobs
-//!
-//! - `WOW_GM=off` — drop GM mode, for anything about hostility, reaction colour, nameplates,
-//!   threat, aggro, damage or breath/fatigue. Safe now, which is the point. `WOW_RIG="… gm:off"` is
-//!   honoured the same way, so the rig's explicit token wins over the default.
-//! - `WOW_GOD=off` — run unshielded (a death-arc test that wants a real corpse). Reported as a
-//!   `WARN` finding on the preflight banner, because the body can now die.
+//! Only a probe account (`probe<N>`) is ever sent anything. `WOW_GM=off` (or `gm:off` in
+//! `WOW_RIG`) drops GM mode; `WOW_GOD=off` runs unshielded, reported on the preflight banner.
 
 use bevy::prelude::*;
 
@@ -76,22 +25,19 @@ use crate::login::LoginIntent;
 use crate::names::NameCache;
 use crate::net::{EnteredWorldMessage, ObjectStore, SelfGuid, SelfPlayer, ServerSaidMessage};
 
-/// `PLAYER_FLAGS_GM` — the bit that says the body is carrying the faction-35 re-template.
+/// `PLAYER_FLAGS_GM`: the body carries the faction-35 re-template.
 const PLAYER_FLAGS_GM: u32 = 0x0000_0008;
 
-/// Spacing between the shield's lines. Two server-side flips inside one net drain merge to a no-op
-/// (0441's lesson, which the rig also spaces for), and `.gm off` must land *after* the shield is up
-/// — never before, or the body is naked for exactly as long as the gap.
+/// Spacing between the shield's lines: two server-side flips inside one net drain merge to a
+/// no-op, and `.gm off` must land after the shield is up.
 const STEP_SECS: f32 = 0.8;
 
-/// How long we wait for our own name to resolve before arming anyway. The name makes the command
-/// selection-proof (§2 above), so it is worth a short wait; going without it is still better than
-/// leaving the body mortal.
+/// How long to wait for our own name, which makes the command selection-proof, before arming
+/// without it.
 const NAME_WAIT_SECS: f32 = 3.0;
 
-/// How long the server gets to confirm before we stop claiming the body is shielded. The live
-/// round trip measured ~100–150 ms; this is a wide margin whose only job is to stop a silent
-/// refusal from reading as success (0651's lesson).
+/// How long the server gets to confirm before the body is reported unshielded; the round trip is
+/// ~100-150 ms.
 const CONFIRM_SECS: f32 = 5.0;
 
 pub(crate) struct ProbeShieldPlugin;
@@ -105,37 +51,35 @@ impl Plugin for ProbeShieldPlugin {
     }
 }
 
-/// What the preflight banner says about the shield. Copy and tiny on purpose: the banner is the
-/// reader's one orienting line and it must not have to reason about the state machine.
+/// What the preflight banner says about the shield.
 #[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
 pub(crate) enum ShieldReport {
-    /// Not a probe account — the shield has no opinion about this body and never sends anything.
+    /// Not a probe account: the shield never sends anything.
     #[default]
     NotOurs,
     /// `WOW_GOD=off`: deliberately unshielded. This body CAN die.
     Disabled,
     /// The command is out, the server has not answered yet.
     Arming,
-    /// The server confirmed it. This body cannot die.
+    /// The server confirmed it; this body cannot die.
     Armed,
-    /// The server did not confirm inside [`CONFIRM_SECS`], or refused. Treat the body as mortal.
+    /// The server refused or did not confirm inside [`CONFIRM_SECS`]; the body is mortal.
     Unconfirmed,
 }
 
 /// The shield's state for this session.
 #[derive(Resource)]
 pub(crate) struct ProbeShield {
-    /// What the banner reports.
     report: ShieldReport,
-    /// Queued lines and when the next one may go out — the rig's cadence, for the rig's reason.
+    /// Queued lines and when the next one may go out.
     steps: Vec<String>,
     next_at: f32,
     /// `Time::elapsed_secs` after which an unanswered `.cheat god on` is called unconfirmed.
     confirm_by: f32,
-    /// Set at world entry, cleared once the batch is built — the "we owe this body a shield" latch.
+    /// Set at world entry, cleared once the batch is built.
     arm_wanted: Option<f32>,
-    /// Our own death state last frame, so a death *edge* is distinguishable from arriving dead.
-    /// `None` until the first descriptor read of this world entry.
+    /// Our own death state last frame, so a death edge differs from arriving dead; `None` until
+    /// the first descriptor read of this world entry.
     was_dead: Option<bool>,
 }
 
@@ -153,17 +97,16 @@ impl Default for ProbeShield {
 }
 
 impl ProbeShield {
-    /// What the preflight banner should say ([`crate::preflight`]).
+    /// What the preflight banner should say.
     pub(crate) fn report(&self) -> ShieldReport {
         self.report
     }
 }
 
-/// Whether `user` is a probe account — `probe` followed by digits, the identity every unattended
-/// run logs in with (`docs/CONTRIBUTING.md`, "Running it unattended"). Nothing else is ours to
-/// modify: a player's account is theirs, and a plain test account is not a probe.
+/// Whether `user` is a probe account, `probe` followed by digits: the identity an unattended run
+/// logs in with (`docs/CONTRIBUTING.md`, "Running it unattended"). No other account is touched.
 fn is_probe_account(user: &str) -> bool {
-    // Byte-wise (a &str slice at 5 would panic mid-char on non-ASCII input; bytes can't).
+    // Byte-wise: a `&str` slice at 5 would panic mid-char on non-ASCII input.
     let Some((prefix, digits)) = user.as_bytes().split_at_checked(5) else {
         return false;
     };
@@ -172,22 +115,15 @@ fn is_probe_account(user: &str) -> bool {
         && digits.iter().all(u8::is_ascii_digit)
 }
 
-/// Whether this run wants GM mode **off** — `WOW_GM=off`, or an explicit `gm:off` in `WOW_RIG`.
-/// The default is on (decision 0679), so this is the flag a session sets when it needs faithful
-/// factions, hostility, colours, threat, damage or timers. An explicit ask always beats the
-/// default, and the rig's token is an explicit ask: two modules must not send `.gm` at each other,
-/// so the one with the spec in front of it wins (0651's rig owns its own `gm:` step).
-///
-/// [`crate::preflight`] reads it too — the banner has to know a `.gm off` is on its way out before
-/// it accuses the run of measuring through GM mode.
+/// Whether this run wants GM mode off: `WOW_GM=off`, or `gm:off` in `WOW_RIG`, so the shield
+/// never sends `.gm` against the rig's own step. The preflight banner reads it too.
 pub(crate) fn wants_gm_off() -> bool {
     std::env::var("WOW_GM").is_ok_and(|v| v.eq_ignore_ascii_case("off"))
         || std::env::var("WOW_RIG").is_ok_and(|spec| rig_asks_for_gm_off(&spec))
 }
 
-/// Whether a `WOW_RIG` spec carries an explicit `gm:off` — the rig's own token
-/// ([`crate::capture::probe_rig`]), matched the way the rig matches it (case-insensitive key,
-/// anything but `on`/`1` falsy).
+/// Whether a `WOW_RIG` spec carries `gm:off`, matched as [`crate::capture::probe_rig`] matches
+/// it: case-insensitive key, anything but `on`/`1` false.
 fn rig_asks_for_gm_off(spec: &str) -> bool {
     spec.split_whitespace().any(|tok| {
         matches!(
@@ -197,8 +133,7 @@ fn rig_asks_for_gm_off(spec: &str) -> bool {
     })
 }
 
-/// Whether `WOW_GOD=off` asked for an unshielded run — a launch-time knob, read once (the shield
-/// drive asks every frame).
+/// Whether `WOW_GOD=off` asked for an unshielded run, read once.
 fn disabled_by_env() -> bool {
     static OFF: std::sync::LazyLock<bool> = std::sync::LazyLock::new(|| {
         std::env::var("WOW_GOD").is_ok_and(|v| v.eq_ignore_ascii_case("off"))
@@ -206,12 +141,9 @@ fn disabled_by_env() -> bool {
     *OFF
 }
 
-/// Classify one `CHAT_MSG_SYSTEM` line as an answer about god mode. `None` = not about it.
-///
-/// The strings are vmangos `mangos_string` 368/369 (`LANG_YOU_SET_GOD`, `LANG_YOUR_GOD_SET`) — the
-/// only ones that reach us as *chat*. `LANG_CHEAT_GOD_ON/OFF` (349/350) travel as
-/// `SMSG_NOTIFICATION` instead and never appear here, which is why matching on "GOD mode is ON"
-/// would silently never fire.
+/// Classify one `CHAT_MSG_SYSTEM` line as an answer about god mode. The chat strings are
+/// `mangos_string` 368/369 (`LANG_YOU_SET_GOD`, `LANG_YOUR_GOD_SET`); `LANG_CHEAT_GOD_ON/OFF`
+/// (349/350) arrive as `SMSG_NOTIFICATION` and never reach here.
 fn god_verdict(text: &str) -> Option<bool> {
     let lower = text.to_ascii_lowercase();
     if !lower.contains("god mode") {
@@ -265,7 +197,7 @@ fn drive_shield(
         shield.report = ShieldReport::Arming;
     }
 
-    // The server's verdict — the only ground truth about a flag that rides no descriptor field.
+    // The server's answer is the only evidence: the flag rides no descriptor field.
     for msg in said.read() {
         match god_verdict(&msg.text) {
             Some(true) => {
@@ -291,9 +223,7 @@ fn drive_shield(
         }
     }
 
-    // A death is proof the shield was down, whatever we believed. `.die` is the usual cause: it
-    // clears god mode silently (`notify = false`) before killing, by design, so this is the normal
-    // path for a session that wanted a corpse — not necessarily a fault.
+    // A death proves the shield was down; `.die` clears it silently before killing.
     if let Ok(store) = self_q.single() {
         let dead = store.0.unit_is_dead() || store.0.player_is_ghost();
         match shield.was_dead {
@@ -311,13 +241,13 @@ fn drive_shield(
         }
     }
 
-    // Build the batch once the body — and ideally our own name — is there to address.
+    // Build the batch once the body, and ideally our own name, is there to address.
     if let Some(wanted_at) = shield.arm_wanted {
         let Ok(store) = self_q.single() else { return };
         let name = self_guid.0.and_then(|g| names.peek(g));
         let waited = time.elapsed_secs() - wanted_at;
         if name.is_none() && waited < NAME_WAIT_SECS {
-            return; // the name makes the command selection-proof — it is worth a short wait
+            return;
         }
         if name.is_none() {
             warn!(
@@ -331,8 +261,7 @@ fn drive_shield(
         shield.confirm_by = time.elapsed_secs() + CONFIRM_SECS;
         let gm_is_on = store.0.player_flags() & PLAYER_FLAGS_GM != 0;
         match (gm_is_on, wants_gm_off()) {
-            // The default (decision 0679): GM mode stays on, so nothing aggros a parked body. The
-            // shield is what makes it SAFE to drop, not a reason to drop it by default.
+            // The default: GM mode stays on, so nothing aggros a parked body.
             (false, false) => {
                 info!(
                     "probe-shield: GM mode is off — turning it back ON, so a parked body is not \
@@ -354,7 +283,7 @@ fn drive_shield(
         shield.next_at = time.elapsed_secs();
     }
 
-    // Send the queued lines, one per STEP_SECS — god first, always.
+    // Send the queued lines, one per `STEP_SECS`, god first.
     if !shield.steps.is_empty() {
         let Some(mut script) = script else { return };
         while !shield.steps.is_empty() && time.elapsed_secs() >= shield.next_at {
@@ -378,8 +307,7 @@ fn drive_shield(
     }
 }
 
-/// The command, always naming the character when we know it — `.cheat god` re-targets to the
-/// current selection, and a creature selection makes the bare form fail.
+/// The command, naming the character when known: the bare form acts on the current selection.
 fn god_line(name: Option<&str>) -> String {
     match name {
         Some(n) => format!(".cheat god on {n}"),
@@ -405,7 +333,6 @@ mod tests {
         for user in ["probe0", "probe7", "PROBE12"] {
             assert!(is_probe_account(user), "{user} is a probe account");
         }
-        // A player's account, and plain test accounts: never touched.
         for user in ["one", "two", "probe", "probeone", "aprobe1", "probe1x"] {
             assert!(!is_probe_account(user), "{user} is NOT a probe account");
         }
@@ -413,7 +340,7 @@ mod tests {
 
     #[test]
     fn the_servers_own_words_are_what_confirm_it() {
-        // vmangos 368, what `.cheat god on <name>` actually answers (captured live).
+        // vmangos 368, the answer to `.cheat god on <name>`.
         assert_eq!(
             god_verdict("You set god mode to on for |cffffffff|Hplayer:Probetwo|h[Probetwo]|h|r."),
             Some(true)
@@ -427,7 +354,6 @@ mod tests {
             god_verdict("Your god mode has been turned off by [Someone]."),
             Some(false)
         );
-        // Everything else on the same channel is not an answer about the shield.
         for other in [
             "Player not found!",
             "GM mode is OFF",
@@ -440,11 +366,8 @@ mod tests {
 
     #[test]
     fn the_rigs_own_gm_token_wins_over_the_default() {
-        // GM mode is ON by default (0679), so the rig's token only matters when it asks for OFF —
-        // and then the shield must not fight it back on.
         assert!(rig_asks_for_gm_off("gnome mage 39 gm:off"));
         assert!(rig_asks_for_gm_off("GM:0"));
-        // An explicit gm:on, and every spec that says nothing, leave the default alone.
         for spec in [
             "tauren druid 60 gm:on at:ThunderBluff",
             "GM:1",
@@ -457,8 +380,6 @@ mod tests {
 
     #[test]
     fn the_command_always_names_its_target() {
-        // The bare form re-targets to the selection and is refused with a creature targeted
-        // (verified live), so the name is the whole point.
         assert_eq!(god_line(Some("Probetwo")), ".cheat god on Probetwo");
         assert_eq!(god_line(None), ".cheat god on");
     }
diff --git a/crates/benilla-app/src/query_cache.rs b/crates/benilla-app/src/query_cache.rs
index 8143705e..3b5a333e 100644
--- a/crates/benilla-app/src/query_cache.rs
+++ b/crates/benilla-app/src/query_cache.rs
@@ -1,24 +1,11 @@
-//! **`QueryCache<K, V>` — the one ask-once cache** (decision 2288; 2265 §A4).
+//! `QueryCache<K, V>`, the ask-once cache: the reference's `DBCache<T>` (vtable `0x80912c`). A
+//! miss sends the query once, a second lookup of a pending key does not re-send, the response
+//! lands the record, and eviction is explicit only.
 //!
-//! The reference has one `DBCache<T>` (vtable `0x80912c`): a consumer's miss
-//! sends the query and queues a callback; a second lookup of a pending key appends a callback
-//! instead of re-sending; the response handler writes the record and fires the callbacks;
-//! eviction is explicit only. benilla had that machine hand-copied across eight modules under
-//! three names for the in-flight set (`pending`, `querying`, `queried`), the miss and the
-//! landing bodies pasted ("the exact twin of `NameCache`"), and the release that keeps an ask
-//! sent before the writer thread exists from latching its key for the process lifetime written
-//! for two of the eight.
+//! The read that asks takes `&self` (the in-flight set is behind a lock), so read-only systems
+//! share the owning resource and its change detection means an answer landed.
 //!
-//! **The read that asks takes `&self`.** A miss marks itself in a lock-guarded set and sends
-//! its query; the answered map does not move. That is the reason for a type over the copies: a
-//! system that only *reads* a name or a template holds the owning resource shared, so two such
-//! systems no longer conflict over it — 2287's "pure cache" class measured 556 such undeclared
-//! orders — and Bevy's change detection on the owner means "an answer landed" again instead of
-//! "someone looked" (the two hand-rolled epochs in `items.rs` were written because it did not).
-//!
-//! A negative answer is cached as `None` (the server's high-bit miss), so a dead key is never
-//! re-asked; [`QueryCache::answered_unknown`] is for the consumer that waits (the cast-fail
-//! redisplay, decision 0552) to know when to stop.
+//! A negative answer (the server's high-bit miss) is cached as `None` and never re-asked.
 
 use std::collections::{HashMap, HashSet};
 use std::hash::Hash;
@@ -31,12 +18,10 @@ use crate::net::EnteredWorldMessage;
 
 pub(crate) struct QueryCache<K, V> {
     answered: HashMap<K, Option<V>>,
-    /// The keys in flight. Behind a lock so the read that asks is `&self`; uncontended by
-    /// construction (every holder runs on the main thread under the single-threaded executor,
-    /// and a miss is the rare path).
+    /// The keys in flight, locked so the read that asks is `&self`; uncontended on the main
+    /// thread.
     pending: Mutex<HashSet<K>>,
-    /// Bumped by every landing, positive or negative — the broadcast a consumer that caches a
-    /// view derived from an answer keys on (the reference's `DBCACHECALLBACK` redisplay, 0660).
+    /// Bumped by every landing or eviction, the reference's `DBCACHECALLBACK` redisplay.
     generation: u64,
 }
 
@@ -51,8 +36,8 @@ impl<K: Copy + Eq + Hash, V> Default for QueryCache<K, V> {
 }
 
 impl<K: Copy + Eq + Hash, V> QueryCache<K, V> {
-    /// The answer for `key` if the server has given one. `None` for a miss — which runs `ask`
-    /// once per key per connection — and for a cached negative alike.
+    /// The answer for `key`; a miss runs `ask` once per key per connection. `None` for a miss
+    /// and a cached negative alike.
     pub(crate) fn get_or_ask(&self, key: K, ask: impl FnOnce()) -> Option<&V> {
         match self.answered.get(&key) {
             Some(answer) => answer.as_ref(),
@@ -65,35 +50,33 @@ impl<K: Copy + Eq + Hash, V> QueryCache<K, V> {
         }
     }
 
-    /// The read-only twin: the answer if it is already here, and never an ask.
+    /// The answer if it is already here, never asking.
     pub(crate) fn get(&self, key: K) -> Option<&V> {
         self.answered.get(&key)?.as_ref()
     }
 
-    /// The answer for `key`, mutably — for a record the wire patches in place after it landed
-    /// (a guild's rank rename, a petition's new title). Never an ask.
+    /// The answer, mutably, for a record the wire patches in place; never asking.
     pub(crate) fn get_mut(&mut self, key: K) -> Option<&mut V> {
         self.answered.get_mut(&key)?.as_mut()
     }
 
-    /// Has the server answered `key` at all — with a record or with "unknown"?
+    /// Whether the server answered `key`, with a record or "unknown".
     pub(crate) fn answered(&self, key: K) -> bool {
         self.answered.contains_key(&key)
     }
 
-    /// Has the server answered `key` with "unknown"? Distinct from a still-pending ask, which
-    /// reads `None` from [`Self::get_or_ask`] too.
+    /// Whether the server answered "unknown", as opposed to a still-pending ask.
     pub(crate) fn answered_unknown(&self, key: K) -> bool {
         self.answered.get(&key).is_some_and(Option::is_none)
     }
 
     #[cfg(test)]
-    /// Is an ask for `key` in flight?
+    /// Whether an ask for `key` is in flight.
     pub(crate) fn is_pending(&self, key: K) -> bool {
         self.pending.lock_recover().contains(&key)
     }
 
-    /// Land an answer; `None` is the server's negative.
+    /// Lands an answer; `None` is the server's negative.
     pub(crate) fn insert(&mut self, key: K, answer: Option<V>) {
         self.pending
             .get_mut()
@@ -104,7 +87,7 @@ impl<K: Copy + Eq + Hash, V> QueryCache<K, V> {
     }
 
     /// The reference's explicit eviction (a high-bit key, `SMSG_INVALIDATE_PLAYER`): the next
-    /// read anywhere re-asks. Returns whether there was anything to evict.
+    /// read re-asks. Returns whether there was anything to evict.
     pub(crate) fn evict(&mut self, key: K) -> bool {
         self.pending
             .get_mut()
@@ -117,9 +100,8 @@ impl<K: Copy + Eq + Hash, V> QueryCache<K, V> {
         was
     }
 
-    /// Forget the in-flight asks — a disconnect may have dropped them on the writer floor, and
-    /// an ask sent before the writer existed never left at all. [`register`] runs this on every
-    /// world entry for every cache that registers.
+    /// Forgets the in-flight asks, which a disconnect or a send before the writer existed may
+    /// have dropped; [`register`] runs it on every world entry.
     pub(crate) fn clear_pending(&mut self) {
         self.pending
             .get_mut()
@@ -127,18 +109,17 @@ impl<K: Copy + Eq + Hash, V> QueryCache<K, V> {
             .clear();
     }
 
-    /// Drop everything, answers included (a session-scoped cache on disconnect).
+    /// Drops everything, answers included (a session-scoped cache on disconnect).
     pub(crate) fn clear(&mut self) {
         self.answered.clear();
         self.clear_pending();
     }
 
-    /// The landing counter — see the field.
     pub(crate) fn generation(&self) -> u64 {
         self.generation
     }
 
-    /// Every answered key with its answer (a persisted cache's save walks this).
+    /// Every answered key with its answer, for a persisted cache's save.
     pub(crate) fn iter(&self) -> impl Iterator<Item = (&K, &Option<V>)> {
         self.answered.iter()
     }
@@ -158,12 +139,8 @@ pub(crate) trait AskOnce: Resource {
     fn clear_pending(&mut self);
 }
 
-/// **The one release-on-enter.** Every cache owner registers here at build; the system runs on
-/// the world-enter message and clears the in-flight sets, so a key asked before the io writer
-/// existed — or across a disconnect — is asked again. Before 2288 this was written for two of
-/// the eight owners (`net::release_ask_once_latches_on_enter`, after the mail send tab's
-/// stationery list went missing for a whole session in silence), and the other six were the
-/// same dead-feature class, still armed.
+/// Registers a cache owner to clear its in-flight asks on world entry, so a key asked before the
+/// writer existed, or across a disconnect, is asked again.
 pub(crate) fn register<T: AskOnce>(app: &mut App) {
     app.add_systems(
         Update,
diff --git a/crates/benilla-app/src/raid_marks.rs b/crates/benilla-app/src/raid_marks.rs
index d998dc35..fee68919 100644
--- a/crates/benilla-app/src/raid_marks.rs
+++ b/crates/benilla-app/src/raid_marks.rs
@@ -1,26 +1,19 @@
-//! Raid-target marker **overhead billboards** — the name render's marker leg `0x6c709a`: for
-//! each unit holding a mark on the 8-slot board (decision 0434 §6,
-//! `GroupState::raid_targets`) and NOT carrying a live V-nameplate (the `[CGUnit+0xe60]==0`
-//! mutual exclusion — the plate shows its own raid-icon child instead, `vplates`), the client
-//! draws a separate world billboard: the anchor unit-quad LUT `(−.5,1,0),(.5,1,0),(.5,0,0),
-//! (−.5,0,0)` (bottom-anchored, h-centered), the 4-column `UI-RaidTargetingIcons` atlas cell
-//! (`col = idx&3`, `row = idx>>2`, cell 0.25), index list `{0,1,3,3,1,2}`.
+//! Raid-target marker overhead billboards, the name render's marker leg (`0x6c709a`): each unit
+//! holding a mark on the 8-slot board (`GroupState::raid_targets`) and without a live V-nameplate
+//! (`[CGUnit+0xe60] == 0`; the plate shows its own raid icon) gets a world billboard, the unit
+//! quad LUT `(-.5,1,0),(.5,1,0),(.5,0,0),(-.5,0,0)` over the 4-column `UI-RaidTargetingIcons`
+//! atlas (`col = idx&3`, `row = idx>>2`, cell 0.25), indices `{0,1,3,3,1,2}`.
 //!
-//! Seat (`0x6c70d8`): if the unit's overhead NAME shows this frame, the marker's bottom sits
-//! **one line-pitch above the top of the name block** — world Z = `anchor + (lineCount + 1)·scale`;
-//! with no name it sits at the bare anchor. Camera-facing, world-scaled by the shared name
-//! height-scale law ([`crate::nameplates::height_scale`]) — same world-pass unlit/Blend state
-//! as the names (walls occlude; the skipped depth-write is the shared named divergence).
+//! Seat (`0x6c70d8`): with the unit's name shown, the bottom sits at
+//! `anchor + (lineCount + 1) * scale`, one line pitch above the name block; else at the anchor.
+//! `scale` is the names' height law ([`crate::nameplates::height_scale`]).
 //!
-//! Size (`0x6c7200`): the marker is a
-//! **fixed unit (1×1) world billboard** — `scale` feeds only the seat (the z-raise), NEVER the
-//! quad geometry. The ref builds the quad by a verbatim vertex copy of the unit LUT (no `fmul`
-//! on position) and billboards it through a world-matrix-cancellation chain (`0x7bca80…`) that
-//! re-normalizes the basis to unit length, so the on-screen size is a world/view-transform
-//! quantity independent of the name `scale`. (The earlier "one pitch square = `scale`·1" was
-//! REFUTED — that under-sized the marker ~5× for a small unit.) Drawn here at [`MARK_WORLD_SIZE`],
-//! a fixed world unit, camera-facing; the absolute pixel projection is the render boundary (a
-//! director look-call). The ref's third gate (`0x605f30()==0`) is unresolved and not reproduced.
+//! Size (`0x6c7200`): a fixed one-unit world quad; `scale` never enters its geometry, and the
+//! billboard chain (`0x7bca80`) renormalizes the basis to unit length.
+//!
+//! Drawn in the names' world pass, unlit and blended. Deviation: no depth write, as for the names,
+//! because blended sorting looks the same.
+//! The reference's third gate (`0x605f30() == 0`) is untraced and not applied.
 
 use bevy::prelude::*;
 
@@ -31,25 +24,20 @@ use crate::ui_party::GroupState;
 use crate::vplates::VPlates;
 use benilla_world::view::WorldCamera;
 
-/// The mark atlas (4×2 icons in a 4-column grid, cell 0.25) — the same art the popup's submenu
-/// rows and the plate child slice.
+/// The mark atlas: 4x2 icons in a 4-column grid, cell 0.25.
 const MARK_TEXTURE: &str = "mpq://interface/targetingframe/ui-raidtargetingicons.blp";
 
-/// The marker's world size (`0x6c7200`): a **fixed** world unit,
-/// independent of the name `scale`. The ref's quad is the bare unit LUT billboarded by a
-/// world-matrix-cancellation chain that leaves a unit-length basis; the pixel projection is the
-/// render boundary (a director look-call — adjust here if it reads too big/small).
+/// The marker's world size (`0x6c7200`): one unit, independent of the name `scale`.
 const MARK_WORLD_SIZE: f32 = 1.0;
 
-/// One live marker: the billboard entity, the unit it rides, and its wire icon slot.
+/// One live marker: the billboard entity and the unit it rides.
 #[derive(Clone, Copy)]
 struct LiveMark {
     marker: Entity,
     unit: Entity,
 }
 
-/// The marker caches: the shared material, one tiny quad mesh per icon (lazy), and the live
-/// marker per board slot (wire icon 0..7).
+/// The shared material, one lazy quad mesh per icon, and the live marker per board slot.
 #[derive(Resource, Default)]
 pub(crate) struct RaidMarks {
     material: Option<Handle<StandardMaterial>>,
@@ -57,12 +45,11 @@ pub(crate) struct RaidMarks {
     live: [Option<LiveMark>; 8],
 }
 
-/// Marker component on a mark billboard entity (root-level, following its unit).
+/// A root-level mark billboard, following its unit.
 #[derive(Component)]
 struct RaidMarkBillboard;
 
-/// The marker quad (`0x6c709a`) for one wire icon: the LUT positions (local X ∈ [−.5, .5],
-/// Y ∈ [0, 1], bottom anchored), the atlas cell UVs, the ref's own index list.
+/// The marker quad (`0x6c709a`) for one wire icon: the LUT, the atlas cell, the index list.
 fn mark_mesh(icon: u32) -> Mesh {
     use bevy::asset::RenderAssetUsages;
     use bevy::mesh::{Indices, PrimitiveTopology};
@@ -95,9 +82,8 @@ fn mark_mesh(icon: u32) -> Mesh {
     mesh
 }
 
-/// The marker's world transform for `unit` this frame — the seat (`0x6c70d8`) over the shared
-/// anchor/scale law. Generic over the joint-globals filter like [`overhead_anchor`] (the placer
-/// passes a disjoint query).
+/// The marker's transform for `unit` this frame, seated per `0x6c70d8`. Generic over the
+/// joint-globals filter, like [`overhead_anchor`].
 fn mark_place<F: bevy::ecs::query::QueryFilter>(
     unit: Entity,
     tf: &Transform,
@@ -110,9 +96,7 @@ fn mark_place<F: bevy::ecs::query::QueryFilter>(
     mounts: &Query<(), With<crate::entities::mount::MountChild>>,
 ) -> Transform {
     let anchor = overhead_anchor(unit, tf, attach, poses, fallback, globals, mounts);
-    // `scale` (the name's world height-law) drives ONLY the seat — the marker sits one
-    // line-pitch above the top of the name block. The quad SIZE is a fixed world unit
-    // (`0x6c7200`: `scale` never enters the marker geometry), not `scale`-scaled.
+    // `scale` drives only the seat, never the quad size (`0x6c7200`).
     let scale = height_scale(anchor.y - tf.translation.y);
     let lift = match plates.line_count(unit) {
         Some(lines) => (lines as f32 + 1.0) * scale,
@@ -125,11 +109,9 @@ fn mark_place<F: bevy::ecs::query::QueryFilter>(
     }
 }
 
-/// Drive the markers: walk the 8-slot board, resolve each marked guid to its streamed entity
-/// (an out-of-range mark simply doesn't draw — the client can't render a unit it can't see),
-/// gate on the plate exclusion, and (re)build the billboard entities. Runs after the name
-/// driver (the seat reads this frame's line counts) — spawn-frame seat here, the per-frame
-/// re-seat is [`place_raid_marks`].
+/// Walks the 8-slot board, resolves each marked guid to its streamed entity (an unstreamed unit
+/// draws nothing), applies the plate exclusion and (re)builds the billboards. Runs after the name
+/// driver, whose line counts seat it; [`place_raid_marks`] re-seats every frame.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 fn drive_raid_marks(
     mut commands: Commands,
@@ -161,8 +143,7 @@ fn drive_raid_marks(
             materials.add(StandardMaterial {
                 base_color: Color::WHITE,
                 base_color_texture: Some(asset_server.load::<Image>(MARK_TEXTURE)),
-                // The names' world-pass state: unlit, depth-TESTED (walls occlude), Blend
-                // (the shared skipped-depth-write divergence).
+                // The names' world-pass state: unlit, depth-tested, blended, no depth write.
                 unlit: true,
                 alpha_mode: AlphaMode::Blend,
                 cull_mode: None,
@@ -176,7 +157,7 @@ fn drive_raid_marks(
         let unit = (guid != 0)
             .then(|| index.0.get(&guid).copied())
             .flatten()
-            // The plate exclusion + a despawning unit both unmark the overlay.
+            // The plate exclusion and a despawning unit both drop the marker.
             .filter(|e| !vplates.0.contains(e) && units.contains(*e));
         let stale = match (marks.live[slot], unit) {
             (Some(live), Some(unit)) if live.unit == unit => continue, // placed per frame below
@@ -219,8 +200,8 @@ fn drive_raid_marks(
     }
 }
 
-/// Seat every live marker from THIS frame's propagated pose (the nameplates placer's twin —
-/// same PostUpdate window, so a moving unit's mark never trails its name).
+/// Seats every live marker from this frame's propagated pose, in the nameplate placer's window,
+/// so a moving unit's mark never trails its name.
 #[allow(clippy::type_complexity)]
 fn place_raid_marks(
     marks: Res<RaidMarks>,
@@ -244,7 +225,7 @@ fn place_raid_marks(
         let (Ok(tf), Ok((mut mtf, mut mglobal))) =
             (units.get(live.unit), mark_tfs.get_mut(live.marker))
         else {
-            continue; // spawned this frame and not yet flushed, or unit despawning — next frame
+            continue; // spawned this frame and not flushed, or the unit is despawning
         };
         let place = mark_place(
             live.unit,
@@ -262,9 +243,7 @@ fn place_raid_marks(
     }
 }
 
-/// Registers the marker driver (Update, after the name driver whose line counts seat it and the
-/// V-plate drive whose exclusion gates it) and the per-frame placer (PostUpdate, the nameplates
-/// placer's window).
+/// Registers the marker driver, after the name driver and the V-plate drive, and the placer.
 pub(crate) struct RaidMarksPlugin;
 
 impl Plugin for RaidMarksPlugin {
@@ -289,9 +268,7 @@ impl Plugin for RaidMarksPlugin {
 mod tests {
     use super::*;
 
-    /// The marker quad (`0x6c709a`) against the reference's laws: the LUT positions
-    /// (bottom-anchored, h-centered, one unit square) and the 4-column atlas cells (`col = idx&3`,
-    /// `row = idx>>2`, cell 0.25) — skull (Lua 8 = wire 7) lands on the second row's last cell.
+    /// Skull is Lua index 8, wire icon 7.
     #[test]
     fn mark_mesh_matches_the_lut_and_atlas_laws() {
         let mesh = mark_mesh(0);
diff --git a/crates/benilla-app/src/ranged_flex.rs b/crates/benilla-app/src/ranged_flex.rs
index 572973de..944a421d 100644
--- a/crates/benilla-app/src/ranged_flex.rs
+++ b/crates/benilla-app/src/ranged_flex.rs
@@ -1,58 +1,31 @@
-//! **The ranged weapon prop's own animation** (decision 2281) — the bow's limbs bend, the gun
-//! fires its muzzle blast.
+//! The ranged weapon prop's own animation: a bow's limbs bend, a gun fires its muzzle blast.
 //!
-//! An equipped ranged weapon is not just a mesh in a hand. The reference keeps its M2 *instance*
-//! at `[CGUnit+0xd24]` (written by the ranged-attach helper `0x611e10` @`0x611eca`, populated on
-//! any sheath→2) and re-arms **that model's own animation** from two keyframes on the body clip:
+//! The reference keeps the equipped ranged weapon's M2 instance at `[CGUnit+0xd24]` (written by
+//! `0x611e10` at `0x611eca` on any sheath to 2) and arms that model's own animation from two keys
+//! on the body clip:
 //!
-//! - **`$BWP`** (BowPull, keyed only in LoadBow 105 @0.434 s / LoadRifle 106 @0.433 s) →
-//!   `0x624cc0`: if the prop's model *owns* animation **160 BowPull** (`0x624cee push 0xa0; call
-//!   0x711960` — a presence test it bails on), play it on the prop at a rate that fits its
-//!   authored length into the body clip's REMAINING time (`0x624e31`'s computed float arg).
-//! - **`$BWR`** (BowRelease, keyed only in AttackBow 46 @0.033 s / AttackRifle 49 @0.000 s) →
-//!   `0x600159`, which **forks on the weapon family** and arms a different clip for each:
-//!   - the body is playing a **bow** clip (`0x5fcfb0`: 46 AttackBow / 105 LoadBow / 109 HoldBow) →
-//!     the prop plays **animation 0 (Stand)** (`0x600209`) — the drawn limbs relax;
-//!   - the body is playing a **rifle** clip (`0x5fcfd0`: 49 AttackRifle / 106 LoadRifle / 110
-//!     HoldRifle — guns AND crossbows) → the prop plays **animation 161 (BowRelease)**
-//!     (`0x600273`, `push 0xa1`).
+//! - `$BWP` (LoadBow 105 at 0.434 s, LoadRifle 106 at 0.433 s) goes to `0x624cc0`: if the prop
+//!   owns 160 BowPull (`0x624cee push 0xa0; call 0x711960`, a presence test it bails on), play it
+//!   at a rate that fits its length into the body clip's remaining time (`0x624e31`).
+//! - `$BWR` (AttackBow 46 at 0.033 s, AttackRifle 49 at 0.000 s) goes to `0x600159`, which forks on
+//!   the body clip's family: a bow clip (`0x5fcfb0`: 46, 105, 109) arms 0 Stand (`0x600209`), the
+//!   drawn limbs relaxing; a rifle clip (`0x5fcfd0`: 49, 106, 110, guns and crossbows) arms 161
+//!   BowRelease (`0x600273`, `push 0xa1`).
 //!
-//! **That second arm is the gun's muzzle blast, and it is why this file exists.** A firearm M2
-//! authors exactly two sequences — Stand(0) and BowRelease(161) — and hangs its whole flash on the
-//! second: `Firearm_2H_Rifle_A_01.m2` carries **seven** particle emitters, each holding a flat rate
-//! in every sequence (100/s, 50/s, 40/s, 30/s, 20/s) and keying only its **enabled gate** — shut
-//! across Stand, open from the head of 161 for a window of its own (34 ms, 134 ms, 4 × 200 ms,
-//! 334 ms: a spark, a flare, the body of the flash, a smoke tail). Bone 2, the parent of all seven
-//! emitter bones, is keyed a constant **+90° about Y** in 161 against 0° in Stand — which is what
-//! aims the blast down the barrel instead of straight up out of the receiver. 21 of the 22 firearms
-//! in the 5875 chain author 161; 25 bows and crossbows author 160 *and* 161; nothing else in the
-//! 571-model weapon corpus authors either. Without this arm the emitters build, pool and tick for
-//! ever on a sequence whose gate is shut, and a gun shot is silent art.
+//! The rifle arm is the gun's muzzle blast. A firearm M2 authors only Stand and BowRelease:
+//! `Firearm_2H_Rifle_A_01.m2`'s seven emitters hold a flat rate in every sequence and key only
+//! their enabled gate (the `u8` step track at `def+0x1dc`), shut across Stand and open from the
+//! head of 161 for 34 ms to 334 ms each. Bone 2, parent of all seven, is keyed +90° about Y in 161,
+//! aiming the blast down the barrel. 21 of the 22 firearms author 161, 25 bows and crossbows author
+//! 160 and 161, and no other weapon model authors either.
 //!
-//! **It is the GATE that is keyed, never the rate** — the track at `def+0x1dc`, outside the ten
-//! scalar ones, `u8`-valued, step-interpolated (decision 2286). A consumer that asks "does this
-//! emitter emit anything?" of the *rate* sees a non-zero constant in every sequence, for a bank
-//! that has never once been switched on; that false negative is why this shipped broken.
+//! Only four sites arm `[+0xd24]`: those three and the un-nock reset (`0x60f59d`). Thrown and wand
+//! (`0x5fcf90`: 107, 111, 112) match neither `$BWR` arm, so they get no prop animation.
 //!
-//! **The rifle arm is in the same function as the bow arm**, eleven instructions apart, and
-//! **exactly four** sites arm `[+0xd24]` — `0x624e31` (160), `0x600209` (0), `0x600273` (161) and
-//! `0x60f59d` (0, the reset below). Only **thrown and wand** have no prop re-anim: a third family
-//! predicate `0x5fcf90` = {107, 111, 112} exists and the `$BWR` handler never calls it, so those
-//! two match neither arm and get no prop animation at all.
-//!
-//! **Both arms sit under a gate, and it is the projectile queue** (decision 2288). `[CGUnit+0xac]`
-//! is not a spell-visual list, as this file first guessed from its readers — it is the queue of
-//! `CMissile` nodes waiting for the caster's release event, and `$BWR` reads it (`0x600182`) before
-//! draining it (`0x600294` → `0x60c940`, the launcher). So the prop's re-anim and the projectile's
-//! launch are two effects of one act: no missile queued, no flex. benilla already held that queue —
-//! [`crate::entities::PendingMissiles`], whose own doc named `+0xac` correctly long before this
-//! round — and the chain runs this arm ahead of the drain, which is the order the two addresses
-//! sit in.
-//!
-//! What this file does NOT own: the prop's rig and palette rows (the rider lane —
-//! [`benilla_world::rig_rider`], given a posed arm by 2281), the emitters' clock (`EmitClock::Host`
-//! on the prop root, wired at the attach), or the bowstring chord ([`crate::bowstring`], which now
-//! spans the *posed* limb tips because of this).
+//! Both `$BWR` arms are gated by `[CGUnit+0xac]`, the queue of `CMissile` nodes awaiting release
+//! ([`crate::entities::PendingMissiles`]): `$BWR` reads it (`0x600182`) before draining it
+//! (`0x600294` into `0x60c940`, the launcher), so no queued missile means no flex, and the flex
+//! runs ahead of the drain.
 
 use bevy::prelude::*;
 
@@ -60,57 +33,50 @@ use benilla_assets::ModelAnimations;
 
 use crate::creature_anim::AnimSoundEvent;
 
-/// `AnimationData.dbc` **160 BowPull** — the prop clip `$BWP` arms (`0x624e2a push 0xa0`).
+/// `AnimationData.dbc` 160 BowPull, the prop clip `$BWP` arms (`0x624e2a push 0xa0`).
 pub(crate) const BOW_PULL: u16 = 160;
-/// `AnimationData.dbc` **161 BowRelease** — the prop clip the RIFLE arm of `$BWR` plays
-/// (`0x60026c push 0xa1`). On a firearm this is the muzzle blast; on a bow it is authored and,
-/// per the byte fork above, never reached from here.
+/// `AnimationData.dbc` 161 BowRelease, the prop clip the rifle arm of `$BWR` plays (`0x60026c push
+/// 0xa1`): a firearm's muzzle blast. A bow authors it but never reaches it from here.
 pub(crate) const BOW_RELEASE: u16 = 161;
-/// The model-load bootstrap id — animation **0 Stand**, what the BOW arm of `$BWR` plays
-/// (`0x600205 push 0x0`) and what the un-nock's reset re-arms (`0x60f59d`): the drawn bow returns
-/// to rest.
+/// Animation 0 Stand, the model-load default: what the bow arm of `$BWR` plays (`0x600205 push
+/// 0x0`) and the un-nock reset re-arms (`0x60f59d`).
 const STAND: u16 = 0;
 
-/// `0x5fcfb0` verbatim — the body clips that make the wearer a **bow** shooter.
+/// `0x5fcfb0`: the body clips of a bow shooter.
 const BOW_FAMILY: [u16; 3] = [46, 105, 109]; // AttackBow · LoadBow · HoldBow
-/// `0x5fcfd0` verbatim — the body clips that make the wearer a **rifle** shooter (gun + crossbow).
+/// `0x5fcfd0`: the body clips of a rifle shooter (guns and crossbows).
 const RIFLE_FAMILY: [u16; 3] = [49, 106, 110]; // AttackRifle · LoadRifle · HoldRifle
 
-/// The unit's equipped **ranged weapon prop** — benilla's `[CGUnit+0xd24]`. On the prop root, put
-/// there by the equipment attach for the ranged slot when the display's model authors a flex clip
-/// (160 or 161); absent for every other held item, which is the reference's own population (nothing
-/// else is ever passed to `0x624cc0`/`0x600209`/`0x600273`).
+/// The unit's equipped ranged weapon prop, benilla's `[CGUnit+0xd24]`: on the prop root when the
+/// ranged display's model authors 160 or 161, absent for every other held item (nothing else
+/// reaches `0x624cc0`/`0x600209`/`0x600273`).
 #[derive(Component)]
 pub(crate) struct RangedProp {
-    /// The unit wearing it — the `$BWP`/`$BWR` keys arrive on *its* timeline, not the prop's.
+    /// The wearer: the `$BWP`/`$BWR` keys arrive on its timeline, not the prop's.
     pub(crate) owner: Entity,
 }
 
-/// Arm the prop's clip from the wearer's `$BWP`/`$BWR` keys.
-///
-/// Registered in the creature-anim chain immediately after
-/// [`crate::creature_anim::drive_nock_latch`], so a key lands the frame it is crossed: the two are
-/// the same handler pair in the reference (`$BWP` is `0x624cc0`'s prop arm *then* `0x624b2f`'s ammo
-/// attach; `$BWR` is `0x600209`/`0x600273`'s prop arm *then* `0x600299`'s detach), and the prop's
-/// pose has to be this frame's before the rider lane composes its palette rows from it.
+/// Arms the prop's clip from the wearer's `$BWP`/`$BWR` keys. Runs right after
+/// [`crate::creature_anim::drive_nock_latch`], the other half of the same reference handlers
+/// (`$BWP`: prop arm, then ammo attach `0x624b2f`; `$BWR`: prop arm, then detach `0x600299`), and
+/// before the rider lane composes the prop's palette rows.
 pub(crate) fn flex_ranged_props(
     mut events: MessageReader<AnimSoundEvent>,
     props: Query<(Entity, &RangedProp)>,
     // Disjoint from `props_mut` by the filter: a unit is never its own ranged prop.
     wearers: Query<(&AnimationPlayer, &ModelAnimations), Without<RangedProp>>,
     mut props_mut: Query<(&mut AnimationPlayer, &ModelAnimations), With<RangedProp>>,
-    // The `[+0xac]` gate — read here, drained by `entities::missile::spawn_missiles` on the same
-    // key. The creature-anim chain runs `.before(EntityVisualsSet)`, so this read lands ahead of
-    // that drain exactly as `0x600182` lands ahead of `0x600294`.
+    // The `[+0xac]` gate, drained by `entities::missile::spawn_missiles` on the same key. The
+    // creature-anim chain runs `.before(EntityVisualsSet)`, so this read precedes the drain as
+    // `0x600182` precedes `0x600294`.
     pending: Res<crate::entities::PendingMissiles>,
 ) {
     for ev in events.read() {
         let want = match &ev.ident {
             b"$BWP" => Some(BOW_PULL),
-            // **`0x60018a je 0x600299`** — no projectile waiting, no prop block at all. The gate
-            // is `$BWR`'s alone: `$BWP`'s handler (`0x624cc0`) reads nothing of the kind, and the
-            // nock-latch clear above it (`0x60016c`) and the ammo detach below it (`0x600299`) are
-            // both outside the skip, which is why `drive_nock_latch` stays ungated.
+            // `0x60018a je 0x600299`: no projectile waiting, no prop block. Only `$BWR` is gated;
+            // the nock-latch clear (`0x60016c`) and the ammo detach (`0x600299`) sit outside the
+            // skip, so `drive_nock_latch` stays ungated.
             b"$BWR" if !pending.releasing(ev.entity) => None,
             b"$BWR" => {
                 if BOW_FAMILY.contains(&ev.anim_id) {
@@ -119,30 +85,26 @@ pub(crate) fn flex_ranged_props(
                     Some(BOW_RELEASE)
                 } else {
                     // Neither family: the reference falls through to `0x60027a` and touches no
-                    // prop at all. Nothing in the shipped character models keys `$BWR` outside
-                    // 46/49, so this arm is the reference's own defensive one.
+                    // prop. No shipped character model keys `$BWR` outside 46/49.
                     None
                 }
             }
             _ => continue,
         };
         let Some(want) = want else { continue };
-        // The prop is found from the WEARER, exactly as `[+0xd24]` is: one ranged prop per unit.
+        // Found from the wearer, as `[+0xd24]` is: one ranged prop per unit.
         let Some((prop, _)) = props.iter().find(|(_, p)| p.owner == ev.entity) else {
             continue;
         };
         let Ok((mut player, anims)) = props_mut.get_mut(prop) else {
             continue;
         };
-        // **The two asks are not the same ask, and the asymmetry is real.** `$BWP` is guarded by
-        // `0x711960` — the *direct, unsubstituted* "does this model author id X" test — and bails
-        // when it fails: that is what confines BowPull to its 25 models, and what a firearm exits
-        // on, its whole cycle being the `$BWR` blast. `$BWR`'s arms carry no such guard, and
-        // `0x7121a0` does **not** silently no-op on a miss: `0x711bf0` substitutes through the
-        // model's own `PlayableAnimationLookup` first, and every weapon model that authors neither
-        // flex clip bakes both ids to Stand(0) (measured on the shipped weapon corpus: 571/571
-        // resolve). So a rifle-family body holding a model without 161 re-arms Stand, it does not
-        // leave the prop alone.
+        // `$BWP` is guarded by `0x711960`, the direct "does the model author this id" test, and
+        // bails on a miss, confining BowPull to its 25 models. The `$BWR` arms have no guard:
+        // `0x7121a0` first substitutes through the model's `PlayableAnimationLookup` (`0x711bf0`),
+        // and weapon models that author neither flex clip bake both ids to Stand (571 of 571
+        // shipped weapon models resolve), so a rifle-family body holding a model without 161
+        // re-arms Stand.
         let want = if want == BOW_PULL {
             if !anims.owns(BOW_PULL) {
                 continue;
@@ -157,15 +119,11 @@ pub(crate) fn flex_ranged_props(
         let Some(clip) = anims.clips.iter().find(|c| c.anim_id == want) else {
             continue;
         };
-        // `$BWP`'s rate: the reference fits BowPull's authored length into the body clip's
-        // REMAINING time (`0x624e31`'s computed float), so the draw completes exactly as the Load
-        // clip ends rather than finishing early and holding. Read off the wearer's own player at
-        // the clip the key fired from — `duration − seek` is the same quantity the reference
-        // builds from the block's window. Everything else plays at the literal 1.0 both `$BWR`
-        // arms push (`0x3f800000`).
+        // `$BWP` fits BowPull into the body clip's remaining time (`0x624e31`), so the draw ends
+        // with the Load clip; read as `duration − seek` off the wearer's player. Both `$BWR` arms
+        // push a literal 1.0 (`0x3f800000`).
         let speed = if want == BOW_PULL {
-            // **`n <= 0` is NO FLEX THAT SHOT, not a flex at 1.0** (`0x624d91 jle`): the
-            // reference abandons the whole arm when the body clip has no time left to fill.
+            // No time left means no flex that shot, not a flex at 1.0 (`0x624d91 jle`).
             let Some(left) = wearers
                 .get(ev.entity)
                 .ok()
@@ -178,18 +136,14 @@ pub(crate) fn flex_ranged_props(
         } else {
             1.0
         };
-        // op4 ARMS a model, it does not layer — the prop plays exactly one clip. Without the
-        // stop, Bevy leaves the previous node active and `playing_seq` (which the emitters' rate
-        // track reads) picks by weight between two equal claims.
+        // Arming replaces, it does not layer: without the stop Bevy keeps the previous node active
+        // and `playing_seq`, which the emitters' rate track reads, picks between two equal weights.
         player.stop_all();
         let active = player.play(clip.node);
         active.replay();
         active.set_speed(speed);
-        // **The instrument** (`WOW_MOVE_TRACE_TAGS=flex`), on the same clock as the `aev` key that
-        // asked for it. Whether a prop armed its clip is otherwise unobservable from outside the
-        // renderer — and "the blast did not fire" has three distinct causes (the key never
-        // arrived, the fork went the other way, the model owns no such clip) that look identical
-        // on screen.
+        // `WOW_MOVE_TRACE_TAGS=flex`, on the `aev` key's clock: tells a key that never arrived, a
+        // fork the other way and a missing clip apart.
         if benilla_assets::trace::enabled_for("flex") {
             benilla_assets::trace::line(
                 "flex",
@@ -201,9 +155,9 @@ pub(crate) fn flex_ranged_props(
                 ),
             );
         }
-        // The authored flags decide the wrap, as everywhere else: a firearm's Stand loops and its
-        // BowRelease clamps, a bow's three clips all clamp. A clamped flex holds its last frame
-        // until the next key re-arms it, which is the reference's own steady state.
+        // The authored flags decide the wrap: a firearm's Stand loops and its BowRelease clamps, a
+        // bow's three clips all clamp. A clamped flex holds its last frame until the next key, as
+        // in the reference.
         if clip.looping {
             active.repeat();
         } else {
@@ -212,8 +166,7 @@ pub(crate) fn flex_ranged_props(
     }
 }
 
-/// **The un-nock's reset — `0x60f59d`, and its condition is INVERTED.** Not "re-arms the prop to
-/// Stand(0) **after** release": the bytes say **UNLESS** it is releasing:
+/// The un-nock's reset (`0x60f59d`): re-arms Stand unless the prop is releasing.
 ///
 /// ```text
 /// 60f578  push -1 ; call 0x712090   ; the prop's CURRENT requested animation id
@@ -221,22 +174,10 @@ pub(crate) fn flex_ranged_props(
 /// 60f584  je 0x60f5a2               ; …then SKIP the reset
 /// ```
 ///
-/// **And the order is the law, not an implementation detail.** The reset lives inside the un-nock
-/// `0x60f530`, which `$BWR` itself reaches every shot (`0x600294` → `0x60c940` → `0x60c951`) —
-/// *after* the arm at `0x600273`. So the arm runs first and is exactly what that `cmp` reads back;
-/// build the two independently and a gun's muzzle blast is cancelled on the frame it starts. The
-/// guard exists for precisely this collision.
-///
-/// benilla reproduces the shape rather than the call graph: the un-nock's observable here is
-/// [`NockLatch`] leaving the wearer, which `$BWR` does every shot and every cancel path does too
-/// ([`crate::creature_anim::cancel_auto_repeat_local`], leaving the ranged sheath, a weapon
-/// change). Removals are visible a frame after the commands that make them apply, by which time a
-/// gun's prop is already on its 2 s BowRelease and the guard declines — which is the reference's
-/// outcome by the reference's own reasoning.
-///
-/// What it is actually *for* is the case no release covers: **a cancel while the bow is drawn.**
-/// BowPull(160) is a clamp, so a volley stopped mid-pull leaves the limbs bent at full draw for as
-/// long as the weapon stays in hand; this is what relaxes them.
+/// It sits in the un-nock `0x60f530`, which `$BWR` reaches every shot (`0x600294`, `0x60c940`,
+/// `0x60c951`) after its arm at `0x600273`, so the guard keeps a gun's blast alive. Here the
+/// un-nock is [`NockLatch`] leaving the wearer, on every `$BWR` and every cancel path, seen a frame
+/// later. Its real use is a cancel mid-draw: BowPull clamps, so this relaxes limbs at full draw.
 pub(crate) fn reset_ranged_props_on_unnock(
     mut unnocked: RemovedComponents<crate::creature_anim::NockLatch>,
     props: Query<(Entity, &RangedProp)>,
@@ -249,8 +190,8 @@ pub(crate) fn reset_ranged_props_on_unnock(
         let Ok((mut player, anims)) = players.get_mut(prop) else {
             continue;
         };
-        // `0x60f57f cmp eax,0xa1` — the prop's current requested id, not its clip time: a
-        // BowRelease that has already finished still reads 161 and is still skipped.
+        // `0x60f57f cmp eax,0xa1` reads the current requested id, not clip time: a finished
+        // BowRelease still reads 161 and is skipped.
         let releasing = player
             .playing_animations()
             .filter_map(|(node, _)| anims.clips.iter().find(|c| c.node == *node))
@@ -273,7 +214,7 @@ pub(crate) fn reset_ranged_props_on_unnock(
     }
 }
 
-/// Seconds left in the wearer's playing clip for `anim_id` — the `$BWP` rate's denominator.
+/// Seconds left in the wearer's playing clip for `anim_id`, the `$BWP` rate's denominator.
 fn remaining(player: &AnimationPlayer, anims: &ModelAnimations, anim_id: u16) -> Option<f32> {
     let clip = anims
         .clips
@@ -311,12 +252,10 @@ mod tests {
         }
     }
 
-    /// A model's animation table, with the **two lookups a real M2 carries** built from the clips:
-    /// `animation_lookup` (the reference's direct `0x711960` test, which gates `$BWP`) and
-    /// `playable_animation_lookup` (the substitution `0x711bf0` runs before every arm — every id
-    /// the model does not author resolves to Stand, as the shipped weapon corpus bakes it).
-    /// Leaving either empty is what a synthetic fixture gets wrong: `owns()` then answers `false`
-    /// for a sequence the model plainly has.
+    /// A model's animation table with both lookups a real M2 carries: `animation_lookup` (the
+    /// direct `0x711960` test) and `playable_animation_lookup` (the `0x711bf0` substitution, every
+    /// unauthored id resolving to Stand). With either empty, `owns()` answers `false` for an
+    /// authored clip.
     fn anims(clips: Vec<AnimClip>) -> ModelAnimations {
         let top = clips.iter().map(|c| c.anim_id).max().unwrap_or(0) as usize;
         let mut animation_lookup = vec![0xffffu16; top + 1];
@@ -343,8 +282,8 @@ mod tests {
         }
     }
 
-    /// A firearm prop: Stand(0) looping + BowRelease(161) clamped, and **no** BowPull — the real
-    /// `Firearm_2H_Rifle_A_01.m2` shape (see the real-asset pin below).
+    /// A firearm prop, the real `Firearm_2H_Rifle_A_01.m2` shape: Stand looping, BowRelease
+    /// clamped, no BowPull.
     fn gun() -> ModelAnimations {
         anims(vec![
             clip(STAND, 1, 0.333, true),
@@ -352,7 +291,7 @@ mod tests {
         ])
     }
 
-    /// A bow prop: Stand(0), BowPull(160), BowRelease(161) — `Bow_1H_Standard_A_01.m2`'s shape.
+    /// A bow prop, `Bow_1H_Standard_A_01.m2`'s shape.
     fn bow() -> ModelAnimations {
         anims(vec![
             clip(STAND, 1, 0.033, false),
@@ -361,8 +300,8 @@ mod tests {
         ])
     }
 
-    /// Spawn a wearer playing `body` and its prop, run the arm over one key, and report which
-    /// node the prop ended up playing (with its speed).
+    /// Spawns a wearer playing `body` and its prop, runs one key, and returns the prop's playing
+    /// node and speed.
     fn fire(
         prop_anims: ModelAnimations,
         body: u16,
@@ -391,8 +330,7 @@ mod tests {
                 RangedProp { owner: wearer },
             ))
             .id();
-        // A projectile queued on the wearer — the `[+0xac]` gate the `$BWR` arms sit under. Every
-        // leg but the gate's own test wants it open; `queue_a_shot` is what opens it.
+        // A shot queued on the wearer opens the `[+0xac]` gate.
         crate::entities::PendingMissiles::queue_a_shot(&mut app, wearer);
         app.world_mut().write_message(AnimSoundEvent {
             entity: wearer,
@@ -410,12 +348,7 @@ mod tests {
         armed
     }
 
-    /// **The fork the whole file exists for** (`0x600159`): the SAME `$BWR` key arms a different
-    /// clip on the prop depending on which weapon family the body is playing. A gun asked for
-    /// BowRelease(161) — its muzzle blast — and a bow for Stand(0), its limbs relaxing.
-    ///
-    /// The gun leg is the director's report: before this, nothing anywhere played 161, so the
-    /// seven emitters that carry the blast sat for ever on Stand's authored rate of zero.
+    /// `$BWR` forks on the body's weapon family (`0x600159`): a gun plays BowRelease, a bow Stand.
     #[test]
     fn bwr_forks_the_prop_clip_on_the_bodys_weapon_family() {
         // AttackRifle(49) → 161 on the gun.
@@ -444,13 +377,8 @@ mod tests {
         );
     }
 
-    /// **The `[+0xac]` gate** (`0x600182`/`0x60018a`, decision 2288): a `$BWR` with no projectile
-    /// waiting to be released arms nothing on the prop. The reference skips the whole block —
-    /// prop re-anim and cast-point reposition together — because the flex and the launch are two
-    /// effects of one act, and there is no act without a missile to throw.
-    ///
-    /// Asserted as the difference the gate makes: the SAME key, the same rifle body clip, with and
-    /// without a queued shot.
+    /// No projectile queued, no arm (`0x600182`/`0x60018a`): the same key and rifle body clip, with
+    /// and without a queued shot.
     #[test]
     fn a_bwr_with_no_projectile_queued_arms_nothing() {
         let mut app = App::new();
@@ -491,13 +419,11 @@ mod tests {
         );
     }
 
-    /// `$BWP` arms BowPull — and only on a model that HAS it. The reference makes that a literal
-    /// presence test it bails on (`0x624cee push 0xa0; call 0x711960`), and a firearm is exactly
-    /// the model it bails for: 21 of the 22 shipped firearms author 161 and none authors 160.
+    /// `$BWP` arms BowPull only on a model that authors it (`0x624cee push 0xa0; call 0x711960`);
+    /// no shipped firearm authors 160.
     #[test]
     fn bwp_pulls_only_a_prop_that_owns_bowpull() {
-        // BOTH legs supply a body clip with time left in it, so the firearm's `None` can only be
-        // the presence test — not the separate `n <= 0` bail the leg below covers.
+        // Both legs have time left in the body clip, so the firearm's `None` is the presence test.
         let load = |id: u16| Some((clip(id, 9, 1.0, false), 0.433));
         assert_eq!(
             fire(bow(), 105, load(105), b"$BWP").map(|(n, _)| n),
@@ -517,10 +443,8 @@ mod tests {
         );
     }
 
-    /// The pull's RATE: the reference stretches BowPull's authored length over the body clip's
-    /// REMAINING time (`0x624e31`'s computed float), so the draw completes as the Load clip ends
-    /// instead of finishing early and holding. HumanMale LoadBow(105) is 1.0 s and keys `$BWP` at
-    /// 0.434 s, so a 1.0 s BowPull has to run at ~1.767×.
+    /// HumanMale LoadBow(105) is 1.0 s and keys `$BWP` at 0.434 s, so a 1.0 s BowPull runs at about
+    /// 1.767×.
     #[test]
     fn the_pull_is_rate_matched_to_the_rest_of_the_load_clip() {
         let load = clip(105, 9, 1.0, false);
@@ -532,10 +456,8 @@ mod tests {
         );
     }
 
-    /// **The reset's guard** (`0x60f584 je`): the un-nock re-arms Stand **unless** the prop is
-    /// releasing. Taken the other way round — "reset after release" — a gun's muzzle blast is
-    /// cancelled on the frame it starts, because the reference reaches this reset from the very
-    /// `$BWR` that armed 161.
+    /// The un-nock re-arms Stand unless the prop is releasing (`0x60f584 je`); the other way round,
+    /// a gun's blast would die the frame it starts.
     #[test]
     fn the_unnock_resets_a_drawn_prop_but_never_a_releasing_one() {
         fn unnock(prop_anims: ModelAnimations, armed: u16) -> Option<AnimationNodeIndex> {
@@ -574,7 +496,7 @@ mod tests {
             Some(bow_stand),
             "a cancel mid-draw returns the limbs to rest"
         );
-        // A gun mid-blast is NOT touched — the whole point of the guard.
+        // A gun mid-blast is not touched.
         let gun_release = gun().clips[1].node;
         assert_eq!(
             unnock(gun(), BOW_RELEASE),
@@ -583,12 +505,7 @@ mod tests {
         );
     }
 
-    /// **The asset half, on the real chain** — the fact the whole feature rests on, and the one a
-    /// data-reading regression would break silently: a firearm's muzzle blast is authored ENTIRELY
-    /// on BowRelease(161), with every emitter's rate track keyed to zero on the loader idle.
-    ///
-    /// This is what makes "the prop never plays 161" invisible rather than obviously broken — the
-    /// emitters build, pool and tick, and pour nothing.
+    /// On the real chain: a firearm's muzzle blast is authored only on BowRelease(161).
     #[test]
     fn a_firearms_muzzle_blast_is_authored_only_on_bowrelease() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -607,12 +524,9 @@ mod tests {
 
         let emitters = benilla_formats::parse_m2_particle_emitters(&bytes).expect("emitters");
         assert_eq!(emitters.len(), 7, "the muzzle bank");
-        // **The discriminator is the GATE, not the rate** (decision 2286). Every one of the seven
-        // holds a constant rate in every sequence (100/s, 50/s, 40/s, 30/s, 20/s) and keys only
-        // `enabled` — the eleventh track at `def+0x1dc`, `u8`, step: flat 0 across Stand, and
-        // `0.000 = 1 → <its own window> = 0` in BowRelease. That is precisely why this defect was
-        // silent — a "does this emitter emit anything?" check on the rate says yes, on every
-        // sequence, for a bank that has never once been switched on.
+        // Each emitter holds a constant rate in every sequence and keys only `enabled` (the track
+        // at `def+0x1dc`, `u8`, step): 0 across Stand, 1 from the head of BowRelease for its own
+        // window.
         for (i, em) in emitters.iter().enumerate() {
             assert!(
                 em.timing.rate(Some(0), 0.0, 0.0) > 0.0,
@@ -629,9 +543,7 @@ mod tests {
                 em.timing.emitting(Some(1), 0.0, 0.0),
                 "emitter {i} opens at the head of BowRelease — this is the blast"
             );
-            // 1.0 s clears every window in the bank — the widest is the 334 ms smoke tail, and
-            // the assertion is deliberately the property rather than a per-emitter figure (2286
-            // corrected 2281's "0.2 s", which was the modal window read as the only one).
+            // 1.0 s clears every window in the bank; the widest is the 334 ms smoke tail.
             assert!(
                 !em.timing.emitting(Some(1), 1.0, 0.0),
                 "emitter {i} is over well before BowRelease's 2 s band ends"
@@ -639,9 +551,8 @@ mod tests {
         }
     }
 
-    /// The other half of the corpus law, so the `flexes` gate at the attach is pinned to data and
-    /// not to a guess: bows and crossbows author BOTH flex clips, an ordinary melee weapon
-    /// authors NEITHER (and so never gets a pose, a player or a hosted emitter clock).
+    /// Bows and crossbows author both flex clips and a melee weapon neither, which pins the
+    /// attach's `flexes` gate to data.
     #[test]
     fn only_ranged_weapon_models_author_the_flex_clips() {
         let data = benilla_formats::wow_data_or_skip!();
diff --git a/crates/benilla-app/src/realm_select/input.rs b/crates/benilla-app/src/realm_select/input.rs
index a7a51c36..9b8dee46 100644
--- a/crates/benilla-app/src/realm_select/input.rs
+++ b/crates/benilla-app/src/realm_select/input.rs
@@ -1,10 +1,6 @@
-//! The realm list's input — the reference's `RealmSelectButton_OnClick`/`OnDoubleClick`,
-//! `RealmList_OnOk`/`OnCancel`, `RealmListTab_OnClick`, `SortRealms`, and `RealmList_OnKeyDown`.
-//!
-//! **Every exit hides the dialog and touches nothing else.** `RealmList_OnOk` is
-//! `PlaySound; RealmList:Hide(); ChangeRealm(...)` and `RealmList_OnCancel` is
-//! `PlaySound; RealmList:Hide(); RealmListDialogCancelled()` — neither names a screen, because the
-//! screen it is standing on is the one the player goes back to (see [`super`]).
+//! The realm list's input: the reference's row clicks, `RealmList_OnOk`/`OnCancel`, the column
+//! sort and `RealmList_OnKeyDown`. Every exit only hides the dialog; neither names a screen, so the
+//! player stays on the screen underneath.
 
 use bevy::input::mouse::MouseWheel;
 use bevy::prelude::*;
@@ -16,7 +12,7 @@ use crate::sound::GlueSound;
 use super::screen::{RealmAction, MAX_ROWS};
 use super::{is_down, Realms};
 
-/// The double-click window — the same conventional interval the select screen uses.
+/// The double-click window, the interval the character select screen uses.
 const DOUBLE_CLICK_SECS: f32 = 0.4;
 
 /// Clicks: a row selects (a second one enters), the column headers sort, Okay enters, Cancel and
@@ -42,8 +38,7 @@ pub(super) fn clicks(
                 let Some(name) = realm_at(&realms, row) else {
                     continue;
                 };
-                // `RealmSelectButton_OnClick` also resets the refresh timer — a player working
-                // down the list should not have it re-sort under them every five seconds.
+                // `RealmSelectButton_OnClick` also resets the refresh timer.
                 realms.refresh_in = super::REFRESH_SECS;
                 let double = last_click
                     .as_ref()
@@ -57,8 +52,7 @@ pub(super) fn clicks(
             RealmAction::Ok => enter = true,
             RealmAction::Cancel => leave = Some(true),
             RealmAction::Close => leave = Some(false),
-            // `realm_set_primary_key` (0x46e9b0) — move-to-front, and the clicked column keeps
-            // the direction it already had unless it was already primary. See `Sort::click`.
+            // `0x46e9b0`: the clicked column moves to the front of the sort keys.
             RealmAction::Sort(key) => realms.sort.click(key),
         }
     }
@@ -109,9 +103,8 @@ pub(super) fn keys(
         scroll_into_view(&mut realms, to, n);
     }
 
-    // The wheel scrolls the window over the list, in the reference's own 16 px steps translated
-    // back to rows (`RealmListScrollFrame_OnVerticalScroll` divides the bar value by
-    // `REALM_BUTTON_HEIGHT`, so one notch is one row).
+    // One notch is one row: `RealmListScrollFrame_OnVerticalScroll` divides the bar value by
+    // `REALM_BUTTON_HEIGHT`.
     let notches = wheel_rows(&mut wheel_carry, wheel.read());
     if notches != 0 {
         let max = rows.len().saturating_sub(MAX_ROWS);
@@ -120,10 +113,8 @@ pub(super) fn keys(
     }
 }
 
-/// The rows this frame's wheel messages scroll the list by — positive is DOWN the list, one row
-/// per whole notch ([`WheelNotches`]). Each message is normalised to lines in its own unit first:
-/// a trackpad sends a gesture as a trickle of `Pixel` messages, and stepping a row per message
-/// ran the list to its end on a gentle swipe.
+/// Rows this frame's wheel messages scroll by, positive down, one per whole notch; each message is
+/// normalised to lines first, since a trackpad sends a trickle of `Pixel` messages.
 fn wheel_rows<'a>(
     carry: &mut WheelNotches,
     wheel: impl IntoIterator<Item = &'a MouseWheel>,
@@ -134,7 +125,7 @@ fn wheel_rows<'a>(
         .sum()
 }
 
-/// The realm on a given **screen** row, honouring the scroll offset.
+/// The realm on a given screen row, honouring the scroll offset.
 fn realm_at(realms: &Realms, row: usize) -> Option<String> {
     let rows = realms.rows();
     rows.get(realms.offset + row)
@@ -151,24 +142,14 @@ fn scroll_into_view(realms: &mut Realms, row: usize, total: usize) {
     }
 }
 
-/// `RealmList_OnCancel` — and `RealmListCloseButton`, which differs only in the sound
-/// (`with_sound`).
+/// `RealmList_OnCancel`, and the close X without the sound. `RealmListDialogCancelled`
+/// (`0x46ed20` -> `0x46b810`) does nothing off the login screen and there closes the realmd
+/// socket (`0x5b3320`) with no screen change; the character park ignores `Abandon` and the login
+/// park re-parks, dropping the socket.
 ///
-/// **The park's answer to `Abandon` is the whole difference between the two contexts**, and
-/// neither costs this function a branch — which is exactly the reference's own shape. Its
-/// `RealmListDialogCancelled` (`0x46ed20` → `0x46b810`, VERIFIED) opens by comparing the current
-/// glue screen's name against `"login"`: **not equal and it returns immediately**, so from
-/// character select the native does *nothing at all* — the realmd link, the world session and the
-/// operation record are untouched and `Hide()` is the entire effect. Equal, and it tail-jumps
-/// `CLoginMgr::Cancel` (`0x5b3320`), closing the realmd socket — **without any `SetGlueScreen`**,
-/// because the login screen was never left. Ours matches on both legs: the character park ignores
-/// `Abandon`, and the login-side park re-parks, which drops the `Logon` and its socket.
-///
-/// **One divergence, stated.** In the reference the X reaches only `CancelRealmListQuery`
-/// (`0x46ed10` → `0x46b7e0`: cancel the pending `COP_GET_REALMS` record, send nothing, close
-/// nothing), so from a login it leaves the realmd link up. Ours abandons on both, because our IO
-/// thread *parks* on the question rather than polling for it: a hidden dialog with the thread
-/// still blocked at the realm park is precisely the desync this whole redesign exists to remove.
+/// Deviation: the reference's X only cancels the pending realm query (`0x46ed10` -> `0x46b7e0`)
+/// and leaves the realmd link up; ours abandons, because the IO thread blocks at the realm park
+/// until answered.
 fn do_cancel(
     realms: &mut Realms,
     choice: &RealmChoice,
@@ -184,18 +165,11 @@ fn do_cancel(
 
 /// `RealmList_OnOk`: play the click, hide the frame, answer the park.
 ///
-/// **Deferred: the `REALM_IS_FULL` confirm.** The reference raises a Yes/No dialog first when the
-/// chosen realm's load band reads `Full` *and* you have no characters on it
-/// (`GlueDialogTypes["REALM_IS_FULL"]`). Ours enters directly, because the two-button `GlueDialog`
-/// that would ask lives inside the login screen (`crate::login::screen::spawn_dialog`) and lifting
-/// it into `crate::glue` is its own change — one this screen should not smuggle in. Shipping the
-/// check without the dialog would be worse than not having it: OK would silently do nothing.
-///
-/// The gap is narrow. `Full` is the `0x80` flag sentinel, which vmangos does not set, so the
-/// dialog is unreachable against the servers benilla connects to today.
+/// Not built: the reference's `REALM_IS_FULL` Yes/No confirm for a `Full` realm with no characters
+/// on it; ours enters directly. `Full` is the `0x80` flag, which vmangos never sets.
 fn try_enter(realms: &mut Realms, choice: &RealmChoice, sounds: &mut MessageWriter<GlueSound>) {
     let Some(realm) = realms.selected() else {
-        return; // nothing highlighted — the reference's Okay is disabled here
+        return; // the reference disables Okay with nothing highlighted
     };
     if is_down(realm) {
         return; // the reference disables OK for an offline realm
@@ -220,8 +194,7 @@ mod tests {
         }
     }
 
-    /// **A trackpad trickle scrolls the rows it adds up to, not a row per message** — ten
-    /// `Pixel` messages of a tenth of a line apiece are one notch, so at most one row.
+    /// Ten `Pixel` messages of a tenth of a line are one notch, so at most one row.
     #[test]
     fn a_trackpad_trickle_scrolls_only_the_rows_it_adds_up_to() {
         let mut carry = WheelNotches::default();
@@ -237,7 +210,7 @@ mod tests {
         );
     }
 
-    /// A mouse wheel's notch is one `Line` message and one row, as it always was.
+    /// A mouse wheel's notch is one `Line` message and one row.
     #[test]
     fn a_line_notch_scrolls_one_row() {
         let mut carry = WheelNotches::default();
diff --git a/crates/benilla-app/src/realm_select/load.rs b/crates/benilla-app/src/realm_select/load.rs
index 75307376..46b4a04d 100644
--- a/crates/benilla-app/src/realm_select/load.rs
+++ b/crates/benilla-app/src/realm_select/load.rs
@@ -1,98 +1,62 @@
-//! **The realm list's two computed columns** — the load band and the realm type — and the row
-//! colours that go with them.
+//! The realm list's two computed columns, the load band and the realm type, and the row colours.
 //!
-//! The load word a player reads (`Low` / `Medium` / `High` / `Full` / `New` / `Recommended`) is
-//! *not* the population the auth server sent. It is a **band**: the client takes the populations of
-//! **every realm it knows** — all categories, not the selected tab — computes their mean and a
-//! scaled standard deviation, and places each realm's population in that distribution. So the same realm reads `High` on a quiet
-//! list and `Low` on a busy one. Anything that printed the raw float would be showing a different
-//! word from the real client on every list.
-//!
-//! **A one-realm list is not a special case that reads `Medium`** — a tempting thing to assume, and
-//! wrong. The reference short-circuits `n <= 1` to `(mean = 1.0, stddev = 0.0)`, which is a real
-//! distribution of zero width, so the single realm is banded against the literal 1.0: below it
-//! reads `Low`, above it reads `High`, and only an exact 1.0 reads `Medium`. Our own vmangos realm
-//! advertises 0.06 and therefore reads **Low**, which is what the real client would show too.
-//!
-//! [`realm_load_stats`] and [`realm_load_classify`] are ports of `CGlue::RealmLoadStats`
-//! `0x46e510` and `CGlue::RealmLoadClassify` `0x46ec60`, including their x87 rounding
-//! behaviour — the accumulators round to `f32` every
-//! iteration because the binary stores them to `f32` slots inside the loop, while the mean, the
-//! sqrt and the band comparisons stay 53-bit. Kept faithful rather than tidied because the band
-//! edges are exactly where a rounding difference would flip a visible word.
-//!
-//! The band → string → colour mapping is the reference `GlueXML/RealmList.lua`'s
-//! `RealmListUpdate`, read literally.
+//! The load word is a band, not the population the auth server sent: the reference takes the
+//! mean and a scaled standard deviation over every realm it knows (all categories) and places each
+//! realm in that distribution. Ports of `CGlue::RealmLoadStats` `0x46e510` and
+//! `CGlue::RealmLoadClassify` `0x46ec60`, with their x87 rounding, since the band edges are where a
+//! rounding difference flips the word. The band to string to colour mapping is `RealmListUpdate`
+//! in `GlueXML/RealmList.lua`.
 
 use bevy::prelude::*;
 
-// ── The six glue font colours (`GlueXML/GlueFonts.xml` l.4-9) ──────────────────────────────────
-//
-// Glue has its own copies of the FrameXML globals; `BLUE_FONT_COLOR` exists ONLY here (FrameXML's
-// `Fonts.xml` ships five, not six) and the realm list is its one consumer in the whole glue tree.
+// ── The six glue font colours (`GlueFonts.xml:4-9`) ─────────────────────────────────────────────
+// `BLUE_FONT_COLOR` exists only in glue; FrameXML's `Fonts.xml` has the other five.
 
-/// `NORMAL_FONT_COLOR` — `{1.0, 0.82, 0}`.
+/// `NORMAL_FONT_COLOR`.
 pub(super) const NORMAL: Color = Color::srgb(1.0, 0.82, 0.0);
-/// `HIGHLIGHT_FONT_COLOR` — `{1.0, 1.0, 1.0}`.
+/// `HIGHLIGHT_FONT_COLOR`.
 pub(super) const HIGHLIGHT: Color = Color::srgb(1.0, 1.0, 1.0);
-/// `GRAY_FONT_COLOR` — `{0.5, 0.5, 0.5}`.
+/// `GRAY_FONT_COLOR`.
 pub(super) const GRAY: Color = Color::srgb(0.5, 0.5, 0.5);
-/// `GREEN_FONT_COLOR` — `{0.1, 1.0, 0.1}`.
+/// `GREEN_FONT_COLOR`.
 pub(super) const GREEN: Color = Color::srgb(0.1, 1.0, 0.1);
-/// `RED_FONT_COLOR` — `{1.0, 0.1, 0.1}`.
+/// `RED_FONT_COLOR`.
 pub(super) const RED: Color = Color::srgb(1.0, 0.1, 0.1);
-/// `BLUE_FONT_COLOR` — `{0, 0.749, 0.953}`.
+/// `BLUE_FONT_COLOR`.
 pub(super) const BLUE: Color = Color::srgb(0.0, 0.749, 0.953);
 
-/// `[0x8038d8]` = 0.6, the std-dev scale (`realm_load_stats`).
+/// The std-dev scale, 0.6 (`[0x8038d8]`).
 const STDDEV_MULT: f32 = f32::from_bits(0x3f19_999a);
 
-/// `realm_load_stats` (`CGlue::RealmLoadStats`, `0x46e510`): over the `populations` of **every**
-/// realm, compute `(mean, scaled_stddev)` where `mean = Σpop / n` and `scaled_stddev =
-/// sqrt(Σ(pop − mean)² / (n − 1)) · 0.6`.
-///
-/// The caller passes the flat list deliberately — see [`super::Realms::stats`] for why this is not
-/// the per-category statistic it looks like.
-///
-/// The sum and the variance accumulator are each rounded to `f32` every iteration (the binary
-/// stores them to `f32` slots in the loop); the mean and std-dev are 53-bit through the
-/// divide/sqrt/scale and stored as `f32`. With `n ≤ 1` the binary short-circuits to
-/// `(mean = 1.0, stddev = 0.0)`: a zero-width distribution centred on 1.0, not a "no opinion".
+/// `CGlue::RealmLoadStats` (`0x46e510`): `(mean, sqrt(Σ(pop − mean)² / (n − 1)) · 0.6)` over every
+/// realm's population. Both accumulators round to `f32` each iteration; the divide, sqrt and scale
+/// run at 53 bits. `n <= 1` gives `(1.0, 0.0)`, so a lone realm is banded against the literal 1.0.
 pub(super) fn realm_load_stats(populations: &[f32]) -> (f32, f32) {
     let n = populations.len();
     if n <= 1 {
         return (1.0, 0.0);
     }
-    // Σ population — accumulated and stored as f32 each step (`fld sum; fadd pop; fstp sum`).
+    // `fld sum; fadd pop; fstp sum`: stored as f32 each step.
     let mut sum: f32 = 0.0;
     for &pop in populations {
         sum = (f64::from(sum) + f64::from(pop)) as f32;
     }
-    // mean = sum / n (`fild n; fdivr sum; fstp mean`).
+    // `fild n; fdivr sum; fstp mean`.
     let mean = (f64::from(sum) / n as f64) as f32;
-    // Σ(pop − mean)² — accumulated and stored as f32 each step.
+    // Stored as f32 each step.
     let mut acc: f32 = 0.0;
     for &pop in populations {
         let d = f64::from(pop) - f64::from(mean);
         acc = (d * d + f64::from(acc)) as f32;
     }
-    // stddev = sqrt(acc / (n − 1)) · 0.6 (`fild n-1; fdivr acc; fsqrt; fmul 0.6; fstp stddev`).
+    // `fild n-1; fdivr acc; fsqrt; fmul 0.6; fstp stddev`.
     let stddev = ((f64::from(acc) / (n - 1) as f64).sqrt() * f64::from(STDDEV_MULT)) as f32;
     (mean, stddev)
 }
 
-/// `realm_load_classify` (`CGlue::RealmLoadClassify`, `0x46ec60`): map one realm's `population` to
-/// the load indicator `GetRealmInfo` returns, given the `mean`/`stddev` from [`realm_load_stats`]
-/// and the realm's flags byte.
-///
-/// Note the three sentinel bits are **not** wire flags: `benilla_protocol`'s parser synthesizes
-/// them from the magic populations the server sends instead, exactly as the reference's parser
-/// does, so by the time a realm reaches here the bit is set and the population is the rewritten
-/// one. See `auth::MAGIC_POPULATIONS`.
-///
-/// The three flag sentinels take priority, tested in this order, then the mean±stddev band. The
-/// band comparisons are 53-bit and **strict** — a population exactly on a band edge reads as
-/// normal, matching the x87 `fcomp` flag tests.
+/// `CGlue::RealmLoadClassify` (`0x46ec60`): the load indicator `GetRealmInfo` returns. The three
+/// sentinel bits, synthesized by the parser from magic populations as the reference's does, win in
+/// this order; then the band, whose 53-bit comparisons are strict, so an edge reads normal.
 pub(super) fn realm_load_classify(flags: u8, population: f32, mean: f32, stddev: f32) -> f32 {
     if flags & 0x20 != 0 {
         return -3.0;
@@ -112,17 +76,13 @@ pub(super) fn realm_load_classify(flags: u8, population: f32, mean: f32, stddev:
     0.0
 }
 
-/// The **Population** column: the authored key and colour for one realm's load indicator.
-///
-/// `RealmListUpdate` reads the classifier's float back as a ladder of exact comparisons against the
-/// sentinels, then signs — so the arms are the reference's, in the reference's order. `down`
-/// overrides every band: an offline realm reads `Offline` in grey whatever its population says.
+/// The Population column's key and colour: `RealmListUpdate`'s ladder, offline first, then the
+/// sentinels by exact comparison, then the sign.
 pub(super) fn load_column(down: bool, load: f32) -> (&'static str, Color) {
     if down {
         return ("REALM_DOWN", GRAY);
     }
-    // The three sentinels are compared for exact equality in the Lua (`load == -3.0`), which is
-    // sound because they are the classifier's own literals travelling unmodified.
+    // Exact equality is sound: the sentinels are the classifier's own literals.
     if load == -3.0 {
         ("LOAD_RECOMMENDED", BLUE)
     } else if load == -2.0 {
@@ -138,11 +98,8 @@ pub(super) fn load_column(down: bool, load: f32) -> (&'static str, Color) {
     }
 }
 
-/// The **Type** column: the authored key and colour for one realm's game type.
-///
-/// `pvp` and `rp` are two independent booleans in the reference's `GetRealmInfo`, and the Lua tests
-/// them in the order `pvp and rp` → `rp` → `pvp` → neither, so `RPPVP` is not "the RP colour" — it
-/// takes `NORMAL`, the same as a normal realm. Read literally rather than collapsed.
+/// The Type column's key and colour; the Lua tests `pvp and rp`, `rp`, `pvp`, then neither, so
+/// RP-PvP takes `NORMAL`, not the RP green.
 pub(super) fn type_column(realm_type: u32) -> (&'static str, Color) {
     let (pvp, rp) = pvp_rp(realm_type);
     match (pvp, rp) {
@@ -153,25 +110,10 @@ pub(super) fn type_column(realm_type: u32) -> (&'static str, Color) {
     }
 }
 
-/// The wire's realm **type** split into the reference's two booleans — **the one place** the
-/// mapping lives. `GetRealmInfo` returns `pvp`/`rp` for the realm list and `GetServerName` returns
-/// the same pair for the character screen's banner, so a second copy of this table is a second
-/// thing to get wrong.
-///
-/// **This is a `Cfg_Configs.dbc` join, not an enumeration** — `0x46efda` takes the realm's type
-/// dword and linearly scans the DBC for the row whose `RealmType` column matches, reading
-/// `PlayerKillingAllowed` → `pvp` and `RoleplayingRealm` → `rp`. (Note the key is the type at
-/// `[realm+0x04]`, the *first* dword on the wire; `[+0x130]` is `numCharacters`, not the type.)
-///
-/// The table below is the shipped `DBFilesClient\Cfg_Configs.dbc` transcribed — a frozen table in
-/// the same spirit as the `*_ICON_TCOORDS` in `crate::glue::art`, and the honest way to read it is
-/// as *data*, not as a rule. It is also why the natural guess is wrong: types **3 and 5 are PvP**
-/// and **7 is RP**, which an "0 normal / 1 pvp / 6 rp / 8 rppvp" reading silently gets wrong for
-/// any server that uses them.
-///
-/// A type with no row falls to `(false, false)` — the scan finds nothing and neither column is
-/// read. That is also what the two rows this table does not carry (the shipped DBC has 11; nine
-/// map a distinct `RealmType`) degrade to, and it is the safe answer for a server inventing one.
+/// The realm type as `(pvp, rp)`, shared by `GetRealmInfo` and `GetServerName`. The reference
+/// (`0x46efda`) scans `Cfg_Configs.dbc` for the row whose `RealmType` matches the realm's first
+/// wire dword and reads `PlayerKillingAllowed` and `RoleplayingRealm`; the table is that DBC
+/// transcribed (types 3 and 5 are PvP, 7 is RP), and a type with no row reads neither.
 pub(crate) fn pvp_rp(realm_type: u32) -> (bool, bool) {
     match realm_type {
         // RealmType → (PlayerKillingAllowed, RoleplayingRealm)
@@ -183,19 +125,11 @@ pub(crate) fn pvp_rp(realm_type: u32) -> (bool, bool) {
     }
 }
 
-/// The realm **name**'s colour, and the colour it takes under the cursor
-/// (`SetTextColor`/`SetHighlightTextColor` in `RealmListUpdate`).
-///
-/// The ladder is the reference's: offline first, then invalid, then "you have characters here",
-/// then the default gold. Note the reference's own gold here is `1.0, 0.78, 0` — a *different*
-/// value from `NORMAL_FONT_COLOR`'s `1.0, 0.82, 0`, hardcoded at the four call sites rather than
-/// taken from the global. Kept as it is written.
-/// The row gold `RealmListUpdate` writes — **a literal in the Lua** (`SetTextColor(1.0, 0.78,
-/// 0.0)`), not `NORMAL_FONT_COLOR`, which is 0.82. Four hundredths, and the reference is explicit
-/// about it in both places it appears (the name and the selection band's vertex colour), so it is
-/// pinned rather than folded into [`NORMAL`].
+/// The row gold, a literal in `RealmListUpdate` (`1.0, 0.78, 0`), not `NORMAL_FONT_COLOR`'s 0.82.
 pub(super) const ROW_GOLD: Color = Color::srgb(1.0, 0.78, 0.0);
 
+/// The realm name's colour and its highlight colour (`RealmListUpdate`): offline, then invalid,
+/// then has characters, then the row gold.
 pub(super) fn name_colors(down: bool, invalid: bool, characters: u8) -> (Color, Color) {
     if down {
         (GRAY, Color::srgb(0.8, 0.8, 0.8))
@@ -208,9 +142,8 @@ pub(super) fn name_colors(down: bool, invalid: bool, characters: u8) -> (Color,
     }
 }
 
-/// The colour the selection band behind the chosen row takes
-/// (`RealmListHighlightTexture:SetVertexColor`) — the name colour's ladder minus the offline arm,
-/// because an offline row cannot be the chosen one (`RealmListHighlight:Hide()`).
+/// The selection band's vertex colour: the name ladder without the offline arm, since an offline
+/// row hides the highlight.
 pub(super) fn highlight_color(invalid: bool, characters: u8) -> Color {
     if invalid {
         RED
@@ -221,7 +154,7 @@ pub(super) fn highlight_color(invalid: bool, characters: u8) -> Color {
     }
 }
 
-/// The player count beside the realm name — `"(3)"`, or nothing at all when they have none there.
+/// The character count beside the realm name, `"(3)"`, or nothing when there are none.
 pub(super) fn players_text(characters: u8) -> String {
     if characters > 0 {
         format!("({characters})")
@@ -234,10 +167,7 @@ pub(super) fn players_text(characters: u8) -> String {
 mod tests {
     use super::*;
 
-    /// The reference's `n <= 1` short circuit bands the single realm against the literal 1.0
-    /// rather than against itself, so `Medium` is the knife edge and not the default — the
-    /// assumption this pins against. The 0.06 case is our own vmangos realm, read off the live
-    /// realm list: it reads **Low**.
+    /// 0.06 is the population a stock vmangos realm advertises.
     #[test]
     fn a_single_realm_is_banded_against_the_literal_one_not_against_itself() {
         assert_eq!(realm_load_stats(&[]), (1.0, 0.0));
@@ -251,8 +181,7 @@ mod tests {
         assert_eq!(word(400.0), "LOAD_HIGH");
     }
 
-    /// The band is relative, which is the whole point of computing it: the SAME population reads
-    /// `High` against quiet neighbours and `Low` against busy ones.
+    /// The same population reads `High` against quiet neighbours and `Low` against busy ones.
     #[test]
     fn the_same_population_reads_differently_against_different_neighbours() {
         let quiet = [1.0f32, 1.0, 1.0, 9.0];
@@ -270,8 +199,7 @@ mod tests {
         );
     }
 
-    /// `mean = Σpop/n`, and `stddev = sqrt(Σ(pop−mean)²/(n−1)) · 0.6` — the sample std-dev, scaled.
-    /// Pinned against a hand-computed case so a "simplification" of the accumulator loop shows up.
+    /// A hand-computed case of the scaled sample std-dev.
     #[test]
     fn the_stats_are_the_sample_stddev_scaled_by_six_tenths() {
         let (mean, stddev) = realm_load_stats(&[2.0, 4.0, 4.0, 6.0]);
@@ -280,8 +208,7 @@ mod tests {
         assert!((stddev - 0.979_795_9).abs() < 1e-6, "stddev was {stddev}");
     }
 
-    /// The three flag sentinels beat the band, and they are tested in the reference's order — a
-    /// realm flagged both recommended (0x20) and full (0x80) reads `Recommended`.
+    /// Recommended (0x20) outranks full (0x80).
     #[test]
     fn the_flag_sentinels_outrank_the_band_and_each_other_in_order() {
         assert_eq!(realm_load_classify(0x20, 999.0, 1.0, 0.5), -3.0);
@@ -293,7 +220,7 @@ mod tests {
         assert_eq!(load_column(false, 2.0).0, "LOAD_FULL");
     }
 
-    /// An exactly-on-edge population reads as normal: the binary's comparisons are strict.
+    /// The reference's band comparisons are strict.
     #[test]
     fn a_population_exactly_on_a_band_edge_is_normal() {
         assert_eq!(realm_load_classify(0, 0.5, 1.0, 0.5), 0.0);
@@ -302,21 +229,20 @@ mod tests {
         assert_eq!(realm_load_classify(0, 1.6, 1.0, 0.5), 1.0);
     }
 
-    /// Offline beats every band, including the sentinels — the Lua tests `realmDown` first.
+    /// The Lua tests `realmDown` first.
     #[test]
     fn an_offline_realm_reads_offline_whatever_its_population_says() {
         assert_eq!(load_column(true, -3.0), ("REALM_DOWN", GRAY));
         assert_eq!(load_column(true, 2.0), ("REALM_DOWN", GRAY));
     }
 
-    /// The four wire types, and the colour each takes. `RPPVP` deliberately takes `NORMAL` — the
-    /// Lua's `pvp and rp` arm sets `NORMAL_FONT_COLOR`, not the RP green.
+    /// RP-PvP takes `NORMAL`: the Lua's `pvp and rp` arm sets `NORMAL_FONT_COLOR`.
     #[test]
     fn the_type_column_is_the_shipped_cfg_configs_rows() {
         for t in [0, 2, 4] {
             assert_eq!(type_column(t), ("GAMETYPE_NORMAL", NORMAL), "type {t}");
         }
-        // 3 and 5 are the rows a "0/1/6/8" reading gets wrong.
+        // Cfg_Configs rows 3 and 5 are PvP too.
         for t in [1, 3, 5] {
             assert_eq!(type_column(t), ("PVP_PARENTHESES", RED), "type {t}");
         }
@@ -328,7 +254,7 @@ mod tests {
         assert_eq!(type_column(77), ("GAMETYPE_NORMAL", NORMAL));
     }
 
-    /// The name ladder, and the gold that is NOT `NORMAL_FONT_COLOR`.
+    /// The default gold is not `NORMAL_FONT_COLOR`.
     #[test]
     fn the_name_ladder_is_offline_then_invalid_then_has_characters() {
         assert_eq!(name_colors(true, true, 5).0, GRAY);
@@ -338,7 +264,7 @@ mod tests {
         assert_ne!(crate::glue::art::GOLD, NORMAL);
     }
 
-    /// No characters on a realm means no count beside its name — not `"(0)"`.
+    /// Not `"(0)"`.
     #[test]
     fn a_realm_with_no_characters_shows_no_count() {
         assert_eq!(players_text(0), "");
diff --git a/crates/benilla-app/src/realm_select/mod.rs b/crates/benilla-app/src/realm_select/mod.rs
index c9b1cbeb..9c9630a9 100644
--- a/crates/benilla-app/src/realm_select/mod.rs
+++ b/crates/benilla-app/src/realm_select/mod.rs
@@ -1,73 +1,23 @@
-//! **Realm selection** — the glue screen between the login and character select, and the policy
-//! that decides whether the player ever sees it.
+//! Realm selection: the realm list dialog and the policy that decides whether the player sees it.
+//! Not [`crate::realmlist`], which is the logon server's address (the `realmList` CVar).
 //!
-//! For the project's whole life the client took `logon.realms.first()`: whichever realm the auth
-//! server happened to list first was the realm you played on, the reference's `Change Realm` button
-//! was drawn deliberately disabled, and the character screen's realm banner had nothing to show
-//! until the character list arrived carrying the realm as a passenger — which is why it read
-//! `Connecting…`, a string the real client does not have. The banner was the symptom; this module
-//! is the missing subsystem.
+//! `RealmList` is a `frameStrata="DIALOG"` frame, not a glue screen (`GlueParent.lua`'s
+//! `GlueScreenInfo` has no entry for it): it is shown over the current screen and hidden again,
+//! and that screen is where the player returns.
 //!
-//! **Not to be confused with [`crate::realmlist`]**, which is the *address of the logon server* —
-//! the reference's `realmList` CVar and its `realmlist.wtf`. The collision is the reference's own
-//! (`realmList` the CVar, `RealmList` the window) and is kept rather than invented away: one is
-//! where you dial, this is what answers.
+//! The IO thread publishes the list from two parks (`crate::net::io`), the login-side realm park
+//! and the character park, and takes one answer. The policy, in order:
 //!
-//! ## Not a screen — a dialog
+//! 1. `WOW_REALM`, matched case-insensitively; a name not on the list falls through.
+//! 2. The realm this session is on, so a logout or a dropped connection returns to it.
+//! 3. The remembered realm, the persisted `realmName` CVar.
+//! 4. An unattended run (`crate::run_mode::unattended`) takes the first realm that is up.
+//! 5. Otherwise the dialog.
 //!
-//! `RealmList` is **not** one of the glue screens. `GlueParent.lua`'s `GlueScreenInfo` table has
-//! entries for `login`, `charselect`, `realmwizard`, `charcreate`, `patchdownload`, `movie` and
-//! `credits` — and none for the realm list; `RealmList.xml` declares a `frameStrata="DIALOG"`
-//! frame that `RealmList_OnEvent` simply `Show()`s, and `RealmList_OnCancel` simply `Hide()`s.
-//! Whatever screen it went up over is still there underneath and is what the player is returned to.
-//!
-//! This shipped as a `ClientState` instead, and every symptom the director reported came out of
-//! that one error: Cancel had to pick a state to go to (it picked the login screen, so Change
-//! Realm's Cancel threw you out of the session), the character screen was torn down behind it, and
-//! — the bad one — a roster arriving while that state was up moved nothing, so Okay looked inert
-//! while the IO thread walked on to the character park. The next Cancel then sent an answer no
-//! park was listening for and every later login queued behind a thread two parks away: the client
-//! hung on "Connecting" with nothing in the log. It is a `shown` flag now, like the AddOns panel
-//! it shares a plate with, and the screen underneath is never touched.
-//!
-//! ## The parks
-//!
-//! The IO thread publishes the list from **two** parks (`crate::net::io`) and takes its answer on
-//! one channel: the *login-side* realm park (logon → **which realm?** → world handshake), and the
-//! *character* park, where Change Realm raises the same list over the select screen and the
-//! session underneath stays live. At each park the thread publishes facts and blocks; the app owns
-//! the policy. Here the policy is:
-//!
-//! 1. **`WOW_REALM`**, when set — the dev fast path past the screen, the realm-side twin of
-//!    `WOW_CHAR`. Matched case-insensitively; a name that is not on the list falls through rather
-//!    than failing, so a stale env var cannot strand a session.
-//! 2. **The realm this session is on** — a logout or a dropped connection comes back through this
-//!    park, and the answer is the realm you were already playing on, not a question.
-//! 3. **The remembered realm** — the `realmName` CVar, which 1.12 registers as a *persisted* CVar
-//!    for exactly this ("last realm connected to"). A launch that recognises its realm goes
-//!    straight to character select, and `Change Realm` is how you get back here.
-//! 4. **An unattended run takes the first realm that is up** — `crate::run_mode::unattended`
-//!    (`WOW_UNATTENDED`/`WOW_CAPTURE`/`WOW_RIG`). A smoke run, a capture and a rig leg have nobody
-//!    in the room to click OK, and a screen that waits forever is how a park becomes a hang. This
-//!    is deliberately `unattended` and not `env_login` — 1769's distinction: credentials in the
-//!    environment do not mean nobody is watching, but these three cannot be a person.
-//! 5. **Otherwise the dialog**, and the player picks.
-//!
-//! ## Change Realm
-//!
-//! Costs a world dial, not a login. The SRP6 session key authenticates against any world server on
-//! the account's realm list and the list itself is already in hand, so the character park serves
-//! the list **in place** — refreshing it on the realmd connection the cycle still holds — and only
-//! leaves when a realm is chosen. Cancel there does nothing at all, which is what makes it Cancel.
-//!
-//! That is the reference's shape, byte for byte:
-//! `CharacterSelect_ChangeRealm()` is `PlaySound + RequestRealmList(1)` and **names no screen**;
-//! `RequestRealmList` (`0x46ecf0` → `0x46b8d0`) sets `screenState = 4` and begins a
-//! `COP_GET_REALMS` on the realmd socket that is still open (it is closed at *world entry*,
-//! `0x46b70c`, not on the way to character select); and the world connection is **not** dropped by
-//! the button — only `ConnectToRealm` (`0x46b210`) drops it, once a realm is confirmed, deferring
-//! its dial to the disconnect handler. So the whole cost of opening the list is a list request,
-//! and the whole cost of cancelling is nothing.
+//! Change Realm costs a world dial, not a login. `RequestRealmList` (`0x46ecf0` -> `0x46b8d0`)
+//! begins a realm query on the realmd socket, which stays open until world entry (`0x46b70c`), and
+//! names no screen; only `ConnectToRealm` (`0x46b210`) drops the world connection, once a realm is
+//! chosen. So the character park serves the list in place and Cancel there does nothing.
 
 mod input;
 mod load;
@@ -81,18 +31,12 @@ use bevy::prelude::*;
 use crate::net::{RealmChoice, RealmListMessage, RealmRequest};
 use benilla_protocol::RealmInfo;
 
-/// The CVar naming the realm we are on — a **real 1.12 CVar** (`0x83f2d0`, persisted; the client
-/// builds its SavedVariables path `0x8539a8` from it), already registered by [`crate::cvars`] and
-/// pushed into the VM at world entry by `benilla_ui::script::UiScript::set_realm_name`.
-///
-/// Read here for the remembered-realm auto-pick. Its persisted value is the *previous* session's
-/// realm, which is precisely the question this policy asks.
+/// The persisted 1.12 CVar naming the last realm connected to (`0x83f2d0`); the SavedVariables
+/// path (`0x8539a8`) is built from it.
 pub(crate) const CVAR_REALM_NAME: &str = "realmName";
 
-/// How often the realm list is re-requested while the screen is up — `REALM_LIST_REFRESH_TIME`
-/// (`GlueXML/RealmList.lua` l.3), the reference's own 5 seconds. `RealmList_OnUpdate` counts it
-/// down and fires `RequestRealmList`, which is how a realm going offline or filling up shows up
-/// without a re-login.
+/// `REALM_LIST_REFRESH_TIME` (`RealmList.lua:3`): the re-request interval while the
+/// dialog is up.
 const REFRESH_SECS: f32 = 5.0;
 
 /// The realm list, the selection on it, and the policy's memory.
@@ -100,8 +44,7 @@ const REFRESH_SECS: f32 = 5.0;
 pub(crate) struct Realms {
     /// Every realm the auth server advertised, in wire order.
     pub(super) realms: Vec<RealmInfo>,
-    /// The highlighted row, **by realm name** — the list is re-published every few seconds and a
-    /// row index would drift under the player when a realm appears or disappears.
+    /// The highlighted row by realm name, so a refresh that adds or drops a realm cannot move it.
     selected: Option<String>,
     /// The category tab in front (`RealmList.selectedCategory`), by the wire's category byte.
     pub(super) category: Option<u8>,
@@ -109,29 +52,14 @@ pub(crate) struct Realms {
     pub(super) offset: usize,
     /// Which column the list is sorted on, and which way.
     pub(super) sort: Sort,
-    /// **Is the dialog up?** The reference's `RealmList:IsVisible()`, and the whole of its
-    /// screen-state: a frame that is shown over the current glue screen and hidden again.
-    ///
-    /// It is also the auto-answer's off switch. While the player is looking at the list, no
-    /// remembered realm may answer it for them — without that, the five-second refresh would
-    /// re-publish and the policy would enter the very realm they opened the dialog to leave.
+    /// `RealmList:IsVisible()`. While set, a published list is a refresh and is never
+    /// auto-answered.
     pub(super) shown: bool,
-    /// The realm this client considers **current** — the reference's `GetRealmInfo` `currentRealm`
-    /// return, which is the row `RealmListUpdate` highlights when nothing else is selected.
-    ///
-    /// **It is a string compare against the `realmName` CVar, and nothing else** (`0x46ef9e` reads
-    /// that CVar's current value through `0x5ab7d0` — the handle registered at `0x63db90`, help
-    /// `"Last realm connected to"` — and case-folds it against the realm record's
-    /// inline name at `realm+9`, pushing `1.0` on a match and `nil` otherwise; a 15-site census of
-    /// that getter found no competing mechanism anywhere in the image). It marks the realm you are
-    /// *connected to* on the character screen only because `ConnectToRealm` (`0x46b217`) writes the
-    /// CVar **before** it dials.
-    ///
-    /// Ours is that same fact tracked one step earlier: set when we answer a park with a realm,
-    /// seeded from the persisted CVar before we have. benilla's own `realmName` write lands at
-    /// world entry (`benilla_ui::script::UiScript::set_realm_name`), which is after the point the
-    /// highlight needs it, and moving that write is a change to the SavedVariables path this
-    /// screen has no business making.
+    /// `GetRealmInfo`'s `currentRealm`, the row highlighted when nothing else is. The reference
+    /// case-folds the `realmName` CVar (`0x46ef9e`, via `0x5ab7d0` on the handle from `0x63db90`)
+    /// against the realm name, and `ConnectToRealm` (`0x46b217`) writes the CVar before it dials.
+    /// Ours is set when we answer a park and seeded from the persisted CVar, because benilla
+    /// writes `realmName` only at world entry (`benilla_ui::script::UiScript::set_realm_name`).
     current: Option<String>,
     /// Seconds until the next refresh request.
     refresh_in: f32,
@@ -140,32 +68,23 @@ pub(crate) struct Realms {
     env_read: bool,
 }
 
-/// One of the realm list's four sort columns — `SortRealms`' string argument, as a type.
+/// One of the four sort columns, `SortRealms`' string argument.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(super) enum SortKey {
-    /// `SortRealms("characters")`, comparator case 0 — the per-account character count.
+    /// `SortRealms("characters")`, comparator case 0: the account's character count.
     Characters,
-    /// `SortRealms("load")`, case 1 — the computed load band, not the raw population.
+    /// `SortRealms("load")`, case 1: the computed load band, not the raw population.
     Load,
-    /// `SortRealms("name")`, case 2 — a case-folding compare.
+    /// `SortRealms("name")`, case 2: a case-folding compare.
     Name,
-    /// `SortRealms("mode")`, case 3 — the `(pvp, rp)` pair.
+    /// `SortRealms("mode")`, case 3: the `(pvp, rp)` pair.
     Type,
 }
 
-/// **The sort config: four `{key, descending}` records, walked in order.**
-///
-/// Not one key with a name tie-break, which is what this was first written as. The reference keeps
-/// all four (`0xb41f40`), and the comparator (`0x46e790`) walks them in order, stops at the first
-/// that does not tie, and negates the result if *that record's own* `descending` is set.
-///
-/// **The default is `[characters, load, name, mode]`, all ascending** — written once per process at
-/// `0x46e430`, so it is what a player sees on a fresh launch, and a column click persists for the
-/// whole session rather than resetting when the list refreshes. It is emphatically not
-/// name-ascending, which is the natural guess and the one this code shipped with.
-///
-/// "Ascending" for `Characters` means **higher count first**: the comparator returns `-1` iff
-/// `B.chars < A.chars`. Realms you already play on float to the top, which is the point.
+/// The sort config (`0xb41f40`): four `{key, descending}` records. The comparator (`0x46e790`)
+/// walks them in order and the first that does not tie decides, negated by its own `descending`.
+/// The default, `[characters, load, name, mode]` all ascending, is written once per process
+/// (`0x46e430`), so a click persists for the session. Ascending characters is higher count first.
 #[derive(Clone, Copy)]
 pub(super) struct Sort(pub(super) [(SortKey, bool); 4]);
 
@@ -181,10 +100,8 @@ impl Default for Sort {
 }
 
 impl Sort {
-    /// A column header click — the reference's `realm_set_primary_key` (`0x46e9b0`), which is
-    /// **move-to-front**: clicking the key already in record 0 toggles its own direction; clicking
-    /// any other shifts the records above it down and moves it to the front *keeping* the
-    /// direction it already had.
+    /// A column header click (`0x46e9b0`): the front key toggles its direction; any other moves
+    /// to the front keeping its direction, and the records it passes shift down.
     pub(super) fn click(&mut self, key: SortKey) {
         if self.0[0].0 == key {
             self.0[0].1 = !self.0[0].1;
@@ -200,8 +117,7 @@ impl Sort {
 }
 
 impl Realms {
-    /// The realms in the selected category, already ordered — the rows the screen draws, as
-    /// indices into [`Self::realms`].
+    /// The rows the screen draws: indices into [`Self::realms`] for the selected category, sorted.
     pub(super) fn rows(&self) -> Vec<usize> {
         let category = self.category;
         let (mean, stddev) = self.stats();
@@ -214,11 +130,9 @@ impl Realms {
             .collect();
         rows.sort_by(|&a, &b| {
             let (ra, rb) = (&self.realms[a], &self.realms[b]);
-            // Walk the four records in order; the first that does not tie decides, negated by
-            // *its own* direction rather than by a single global one.
             for (key, descending) in self.sort.0 {
                 let ord = match key {
-                    // Higher count first — see `Sort`.
+                    // Higher count first.
                     SortKey::Characters => rb.characters.cmp(&ra.characters),
                     SortKey::Load => {
                         let la = load::realm_load_classify(ra.flags, ra.population, mean, stddev);
@@ -232,21 +146,15 @@ impl Realms {
                     return if descending { ord.reverse() } else { ord };
                 }
             }
-            // All four tied. The reference returns 0 here too — but its `characters` case is
-            // **not antisymmetric** (on equal nonzero counts it answers `+1` for both `(a,b)` and
-            // `(b,a)`, because the strcmp meant to break that tie is clobbered one instruction
-            // later — a real, reachable defect, byte-verified). We do not reproduce it: a
-            // comparator that disagrees with itself is a logic error Rust's sort is entitled to
-            // punish, and the visible cost of the divergence is that two realms with the same
-            // character count keep a stable order instead of an arbitrary one.
+            // The reference's characters case answers +1 both ways on equal nonzero counts (its
+            // tie-break strcmp is clobbered), a defect not reproduced: all four tied is Equal.
             std::cmp::Ordering::Equal
         });
         rows
     }
 
-    /// The category bytes present, ascending — one tab each. The reference hides the tab strip
-    /// entirely when there is only one (`RealmList_UpdateTabs`: `if arg.n == 1 then tab:Hide()`),
-    /// which is every ordinary private server.
+    /// The category bytes present, ascending, one tab each; `RealmList_UpdateTabs` hides the strip
+    /// when there is only one.
     pub(super) fn categories(&self) -> Vec<u8> {
         let mut cats: Vec<u8> = self.realms.iter().map(|r| r.category).collect();
         cats.sort_unstable();
@@ -254,14 +162,8 @@ impl Realms {
         cats
     }
 
-    /// The population mean and scaled std-dev — the distribution each row's load band is placed in.
-    ///
-    /// **Over EVERY realm the client knows, not over the selected category.** This looked like a
-    /// per-category statistic and was written that way; `realm_load_stats` (`0x46e510`) is in fact
-    /// the whole realm-list rebuild, and its accumulator loop walks the flat all-categories array
-    /// unconditionally — the per-category bucketing in the same loop is a side effect, never a
-    /// bound. So a realm's word is measured against every other realm on the account's list, and
-    /// switching tabs does not move any row's band.
+    /// The load distribution, over every realm, not the selected category: `0x46e510` walks the
+    /// flat all-categories array, so switching tabs moves no band.
     pub(super) fn stats(&self) -> (f32, f32) {
         let pops: Vec<f32> = self.realms.iter().map(|r| r.population).collect();
         load::realm_load_stats(&pops)
@@ -278,17 +180,13 @@ impl Realms {
         self.selected = Some(name.to_string());
     }
 
-    /// Whether the OK button is live: a realm is highlighted and it is not offline.
-    ///
-    /// `RealmListUpdate` opens with `RealmListOkButton:Disable()` and only the highlighted-row
-    /// branches re-enable it, so a list with nothing selected has a dead Okay — which is what a
-    /// fresh login shows, since there is no current realm to preselect.
+    /// Whether Okay is live: `RealmListUpdate` disables it and only a highlighted, online row
+    /// re-enables it.
     pub(super) fn can_enter(&self) -> bool {
         self.selected().is_some_and(|r| !is_down(r))
     }
 
-    /// Raise the dialog (`RealmList:Show()` → `RealmList_OnShow`): reset the scroll, seat the
-    /// highlight on [`Self::current`], and start the refresh countdown.
+    /// `RealmList:Show()`: reset the scroll, highlight [`Self::current`], start the refresh timer.
     fn open(&mut self) {
         self.shown = true;
         self.offset = 0;
@@ -304,30 +202,25 @@ impl Realms {
         self.refresh_in = REFRESH_SECS;
     }
 
-    /// Answer a park with a realm — and remember it as [`Self::current`], the way the reference's
-    /// `ConnectToRealm` writes `realmName` on its way to the dial.
+    /// Answer a park with a realm and remember it as [`Self::current`].
     pub(super) fn enter(&mut self, choice: &RealmChoice, name: String) {
         self.current = Some(name.clone());
         let _ = choice.0.send(RealmRequest::Enter(name));
     }
 
-    /// `RealmList:Hide()` — and nothing else. The screen underneath was never touched.
+    /// `RealmList:Hide()`, and nothing else.
     pub(super) fn hide(&mut self) {
         self.shown = false;
     }
 }
 
-/// **Offline** — the realm is up in the list but not accepting connections (`realmDown` in
-/// `GetRealmInfo`, the row the reference greys out and refuses to enter).
-///
-/// Bit 0x02 of the wire's realm-flags byte. The client's realm record keeps the same byte at
-/// `[realm+0x08]` and `realm_select` (0x46ea20) skips a realm on its low bits when auto-picking.
+/// `GetRealmInfo`'s `realmDown`: flag bit 0x02, greyed and not enterable; the reference's
+/// auto-pick (`0x46ea20`) skips a realm on these low bits.
 pub(crate) fn is_down(realm: &RealmInfo) -> bool {
     realm.flags & 0x02 != 0
 }
 
-/// **Invalid** — the realm rejects this client build (`invalidRealm`, the row the reference paints
-/// red but still lets you try). Bit 0x01 of the same byte.
+/// `GetRealmInfo`'s `invalidRealm`: flag bit 0x01, painted red but still enterable.
 pub(super) fn is_invalid(realm: &RealmInfo) -> bool {
     realm.flags & 0x01 != 0
 }
@@ -341,11 +234,9 @@ impl Plugin for RealmSelectPlugin {
             Update,
             (
                 apply_realm_policy,
-                // Ungated by state on purpose: the dialog stands over the login screen and over
-                // character select alike, and `shown` is the only thing that decides.
+                // Ungated by state: the dialog stands over login and character select alike.
                 screen::drive_screen,
-                // Input first, then the row refresh — a click that moved the highlight shows on
-                // the frame it landed, not the next one.
+                // Input before the row refresh, so a click shows on the frame it landed.
                 smoke::debug_realm_smoke,
                 (
                     input::clicks,
@@ -363,10 +254,7 @@ impl Plugin for RealmSelectPlugin {
     }
 }
 
-/// Answer the realm park — or raise the dialog and let the player answer it.
-///
-/// Runs in every state: the list is published from the login-side park *and* from the character
-/// park, and this one system is the policy for both.
+/// Answer the realm park, or raise the dialog; the policy for both parks, in every state.
 fn apply_realm_policy(
     mut msgs: MessageReader<RealmListMessage>,
     mut realms: ResMut<Realms>,
@@ -380,20 +268,17 @@ fn apply_realm_policy(
     for msg in msgs.read() {
         realms.realms = msg.realms.clone();
         realms.refresh_in = REFRESH_SECS;
-        // Keep the tab across a refresh when it still names something real; a first list (or one
-        // that dropped what we had) falls back to the first.
+        // Keep the tab across a refresh while it still exists, else the first.
         let cats = realms.categories();
         if !realms.category.is_some_and(|c| cats.contains(&c)) {
             realms.category = cats.first().copied();
         }
 
-        // **A list published while the dialog is up is a refresh, never a question.** The player
-        // is looking at it; answering over their shoulder with the realm they are standing on is
-        // the button-that-does-nothing bug in its purest form.
+        // A list published while the dialog is up is a refresh, never a question.
         if realms.shown {
             continue;
         }
-        // The registered default is the empty string — a client that has never connected.
+        // The registered default is empty: a client that has never connected.
         let remembered = cvars
             .get(CVAR_REALM_NAME)
             .filter(|s| !s.is_empty())
@@ -415,24 +300,11 @@ fn apply_realm_policy(
     }
 }
 
-/// **Which realm answers this list without the player** — or `None`, meaning show the screen.
-///
-/// The arms, in order: an explicit `WOW_REALM`, the realm remembered from last time, then (only
-/// when nobody is in the room) the first realm the list draws. Pure, and lifted out of the system
-/// around it, because this ladder *is* the policy — the rest is plumbing.
-///
-/// Every arm requires the realm to be **up**. Auto-entering a realm the server says is offline
-/// would replace a screen that can explain itself with a dial that just fails.
+/// The realm that answers this list without the player, or `None` to show the dialog: the policy
+/// ladder in the module doc. Every arm requires the realm to be up.
 fn auto_answer(realms: &Realms, remembered: Option<&str>, unattended: bool) -> Option<String> {
-    // The named arms, matched case-insensitively — vmangos does not normalise realm names and a
-    // config file is hand-editable.
-    //
-    // **`current` sits ahead of the persisted CVar**, and it is not decoration: a clean logout and
-    // a lost session both come back through this park, and the realm to return to is the one this
-    // session is standing on. benilla writes `realmName` at world entry, so a session that never
-    // reached the world has nothing persisted — without this arm, a logout mid-way would answer
-    // the relist by *raising the dialog* over character select, which is not a question anybody
-    // asked.
+    // Case-insensitive: vmangos does not normalise realm names. `current` outranks the persisted
+    // CVar, which benilla writes only at world entry, so a logout before it still returns here.
     let named = [
         realms.env_realm.as_deref(),
         realms.current.as_deref(),
@@ -448,8 +320,7 @@ fn auto_answer(realms: &Realms, remembered: Option<&str>, unattended: bool) -> O
             .map(|r| r.name.clone())
     });
     named.or_else(|| {
-        // Nobody to click OK: take the first realm that will have us, in the order the list is
-        // drawn in, rather than parking on a screen no one will answer.
+        // Nobody to click Okay: the first realm up, in drawn order.
         unattended
             .then(|| {
                 realms
@@ -463,24 +334,18 @@ fn auto_answer(realms: &Realms, remembered: Option<&str>, unattended: bool) -> O
     })
 }
 
-/// The character screen's **Change Realm**: raise the dialog over the select screen and ask for a
-/// fresh list.
+/// Change Realm: raise the dialog over character select and ask for a fresh list; the session is
+/// untouched.
 ///
-/// The reference's order is the engine's — `CHANGE_REALM` requests the list and the arriving
-/// `OPEN_REALM_LIST` shows the frame. We show it immediately against the list already in hand and
-/// let the refresh land underneath, because the list *is* already in hand and a dialog that waits
-/// a round trip to appear reads as a dropped click.
-///
-/// Nothing here touches the session. The character park serves the refresh in place and stays
-/// exactly where it is, which is what lets Cancel mean nothing at all.
+/// Deviation: the reference shows the frame when `OPEN_REALM_LIST` arrives; ours shows at once
+/// against the list already in hand, so the click does not wait a round trip.
 pub(crate) fn open_over_char_select(realms: &mut Realms, choice: &RealmChoice) {
     realms.open();
     let _ = choice.0.send(RealmRequest::Refresh);
 }
 
-/// The reference's `RealmList_OnUpdate`: count down `REALM_LIST_REFRESH_TIME` and re-request the
-/// list. Only while the dialog is up — `RealmList_OnHide` calls `CancelRealmListQuery`, and a park
-/// is never refreshed behind the player's back.
+/// `RealmList_OnUpdate`: re-request the list every `REALM_LIST_REFRESH_TIME` while shown
+/// (`RealmList_OnHide` cancels the query).
 fn tick_refresh(time: Res<Time>, mut realms: ResMut<Realms>, choice: Res<RealmChoice>) {
     realms.refresh_in -= time.delta_secs();
     if realms.refresh_in <= 0.0 {
@@ -527,7 +392,7 @@ mod tests {
         }
     }
 
-    /// The two flag bits the row's look hangs on, and the fact they are independent.
+    /// The offline and invalid bits are independent.
     #[test]
     fn offline_and_invalid_are_separate_bits() {
         assert!(is_down(&realm("a", 1, 0, 0x02, 0, 1.0)));
@@ -537,18 +402,12 @@ mod tests {
         assert!(
             is_down(&realm("a", 1, 0, 0x03, 0, 1.0)) && is_invalid(&realm("a", 1, 0, 0x03, 0, 1.0))
         );
-        // The load sentinels live in the high bits and must not read as either.
+        // The load sentinels live in the high bits.
         let sentinel = realm("a", 1, 0, 0xE0, 0, 1.0);
         assert!(!is_down(&sentinel) && !is_invalid(&sentinel));
     }
 
-    /// A category tab scopes the **rows** — and deliberately NOT the load distribution.
-    ///
-    /// This is the correction that matters most here, because the wrong version looks right: the
-    /// mean and std-dev a row's word is measured against come from every realm the client knows,
-    /// so switching tabs re-filters the list without relabelling a single band. Scoping the stats
-    /// to the tab (which is what this code did first) makes the same realm read a different word
-    /// depending on which tab you are standing on.
+    /// The load distribution spans every realm, so switching tabs relabels no band.
     #[test]
     fn a_category_tab_scopes_the_rows_but_not_the_load_distribution() {
         let mut r = list(vec![
@@ -567,11 +426,11 @@ mod tests {
             mean_on_tab_one, mean_on_tab_two,
             "the distribution is global — the tab must not move it"
         );
-        // And it really is the global mean: (1 + 1 + 400) / 3, not the visible category's.
+        // (1 + 1 + 400) / 3.
         assert!((mean_on_tab_one - 134.0).abs() < 1e-3, "{mean_on_tab_one}");
     }
 
-    /// A single-category list draws no tabs — the reference hides the whole strip.
+    /// The reference hides the tab strip for a single category.
     #[test]
     fn one_category_is_the_ordinary_case_and_has_no_tabs() {
         let r = list(vec![
@@ -581,9 +440,7 @@ mod tests {
         assert_eq!(r.categories(), vec![1]);
     }
 
-    /// **The default order is characters → load → name → mode, all ascending** — the config the
-    /// binary writes once per process, and not the name-ascending this first shipped with. A realm
-    /// the account has characters on floats to the top; that is what "ascending" means for case 0.
+    /// The default order is characters, load, name, mode, all ascending; more characters first.
     #[test]
     fn the_default_sort_puts_realms_you_play_on_first() {
         let mut r = list(vec![
@@ -592,15 +449,11 @@ mod tests {
             realm("Mu", 1, 0, 0, 3, 1.0),
         ]);
         assert_eq!(names(&r), ["Mu", "Alpha", "Zeta"], "Mu has characters");
-        // With the counts equal the first record ties and the walk falls through to load, then to
-        // the name — so the remainder is alphabetical rather than arbitrary.
+        // Equal counts fall through to load, then name.
         r.realms[2].characters = 0;
         assert_eq!(names(&r), ["Alpha", "Mu", "Zeta"]);
     }
 
-    /// A column click is **move-to-front**, and the clicked column keeps the direction it already
-    /// had; only re-clicking the column already in front flips it. The records behind it survive,
-    /// which is what makes the fallthrough meaningful.
     #[test]
     fn a_column_click_moves_it_to_the_front_and_only_a_re_click_flips_it() {
         let mut sort = Sort::default();
@@ -630,8 +483,7 @@ mod tests {
         );
     }
 
-    /// The sort direction is **per record**, not one global flag: reversing the primary column must
-    /// not also reverse the tie-breaks behind it.
+    /// Reversing the primary column does not reverse the tie-breaks behind it.
     #[test]
     fn each_sort_record_carries_its_own_direction() {
         let mut r = list(vec![
@@ -647,8 +499,6 @@ mod tests {
         );
     }
 
-    /// The highlight is a NAME, so a realm appearing above it on a refresh does not move the
-    /// selection onto a different realm — the bug an index would have.
     #[test]
     fn the_selection_survives_a_realm_appearing_above_it() {
         let mut r = list(vec![realm("Mu", 1, 0, 0, 0, 1.0)]);
@@ -657,7 +507,7 @@ mod tests {
         assert_eq!(r.selected().map(|r| r.name.as_str()), Some("Mu"));
     }
 
-    /// A realm that vanished from the list is not selected any more, and OK is dead.
+    /// A realm that left the list is not selected, and Okay is dead.
     #[test]
     fn a_realm_that_left_the_list_is_no_longer_the_selection() {
         let mut r = list(vec![realm("Mu", 1, 0, 0, 0, 1.0)]);
@@ -667,11 +517,8 @@ mod tests {
         assert!(!r.can_enter());
     }
 
-    /// **Raising the dialog seats the highlight on the realm you are on** — the reference's
-    /// `GetRealmInfo` `currentRealm`, which `RealmListUpdate` highlights when nothing else is
-    /// selected. With no current realm nothing is selected and Okay is dead, which is exactly what
-    /// `RealmListUpdate` does: it opens with `RealmListOkButton:Disable()` and only the
-    /// highlighted-row branches turn it back on.
+    /// With no current realm nothing is highlighted and Okay stays disabled, as in
+    /// `RealmListUpdate`.
     #[test]
     fn opening_the_dialog_highlights_the_realm_you_are_on() {
         let mut r = list(vec![
@@ -699,8 +546,7 @@ mod tests {
         assert!(gone.selected().is_none());
     }
 
-    /// **Cancel hides the dialog and touches nothing else** — no screen change, because the
-    /// reference's `RealmList_OnCancel` is `Hide()` and the screen underneath was never left.
+    /// `RealmList_OnCancel` is `Hide()`; no screen change.
     #[test]
     fn hide_is_the_whole_of_cancel() {
         let mut r = list(vec![realm("Alpha", 1, 0, 0, 0, 1.0)]);
@@ -715,9 +561,6 @@ mod tests {
         );
     }
 
-    /// The policy ladder: `WOW_REALM` first, then the remembered realm, then — only when nobody
-    /// is in the room — the first row. Attended and with nothing remembered, the answer is the
-    /// dialog, which is the whole point of having one.
     #[test]
     fn the_auto_answer_ladder_is_env_then_remembered_then_unattended() {
         let mut r = list(vec![
@@ -739,10 +582,7 @@ mod tests {
         );
     }
 
-    /// **A logout comes back to the realm it left**, without asking. The relist arrives through the
-    /// same park a first login does, and the session's own realm has to outrank the persisted CVar
-    /// — which benilla only writes at world entry, so a session that never got there has nothing
-    /// persisted at all and would otherwise be asked to pick again.
+    /// The session's realm outranks the persisted `realmName`, which is the previous session's.
     #[test]
     fn a_relogin_returns_to_the_realm_this_session_is_on() {
         let mut r = list(vec![
@@ -759,8 +599,6 @@ mod tests {
         );
     }
 
-    /// A remembered realm that has left the list, or gone offline, must not strand the session: it
-    /// falls through to the screen, or — unattended — to a realm that is actually up.
     #[test]
     fn a_stale_or_offline_remembered_realm_falls_through() {
         let r = list(vec![
@@ -776,8 +614,7 @@ mod tests {
         );
     }
 
-    /// An offline realm can be highlighted but not entered — the reference disables its row AND
-    /// its OK button.
+    /// The reference disables an offline realm's Okay.
     #[test]
     fn an_offline_realm_cannot_be_entered() {
         let mut r = list(vec![realm("Down", 1, 0, 0x02, 0, 1.0)]);
diff --git a/crates/benilla-app/src/realm_select/screen.rs b/crates/benilla-app/src/realm_select/screen.rs
index bc2b3e27..ad980ccc 100644
--- a/crates/benilla-app/src/realm_select/screen.rs
+++ b/crates/benilla-app/src/realm_select/screen.rs
@@ -1,23 +1,11 @@
-//! The realm list's **layout** — the reference `GlueXML/RealmList.xml` arrangement rebuilt in Bevy
-//! UI, scaled to the window the way every glue screen is (the 1024×768 virtual screen times
-//! `height / 768`).
+//! The realm list's layout: `GlueXML/RealmList.xml` in Bevy UI, on the 1024×768 glue scale.
 //!
-//! A full-screen black-at-0.75 dim (the reference's own BACKGROUND layer, which also stops a click
-//! reaching the screen behind), then the 640×512 `HelpFrame` plate centred at the authored `+24`
-//! offset — the same plate the AddOns list uses, because `RealmList.xml` and `AddonList.xml` are
-//! the same panel. On it: the `UI-DialogBox-Header` title plate reading `SERVER_SELECTION`, the
-//! four sort-column headers, eighteen 512×16 realm rows at the authored 20 px pitch, the
-//! `UI-QuestLogTitleHighlight` selection band, the close X, and Okay / Cancel along the bottom.
+//! A full-screen dim, then the 640×512 `HelpFrame` plate (the AddOns list's) with the title plate,
+//! four sort headers, eighteen rows, the selection band, the close X, and Okay and Cancel. Rows are
+//! spawned empty and [`refresh_rows`] writes them every frame from [`super::Realms`].
 //!
-//! **Each row is four columns, and three of them are computed** — the type suffix, the character
-//! count, and the load word — see [`super::load`]. The row is spawned once with empty strings and
-//! [`refresh_rows`] writes it every frame from [`super::Realms`], which is what lets the list
-//! answer a five-second refresh without rebuilding the tree.
-//!
-//! **The category tab strip is not drawn.** The reference hides it whenever the list has a single
-//! category (`RealmList_UpdateTabs`), which is every server benilla connects to; with more than
-//! one we show every realm rather than stranding some behind a tab whose *name* we cannot yet
-//! source — see [`super`]'s note.
+//! The category tab strip is not built: `RealmList_UpdateTabs` hides it for a single category, and
+//! with several, only the first category's realms show.
 
 use bevy::prelude::*;
 use bevy::window::PrimaryWindow;
@@ -33,30 +21,27 @@ use super::{Realms, SortKey};
 
 use crate::char_select::wow_font;
 
-/// Over the glue screen it stands on (1100), over that screen's own dialogs (1200), and over the
-/// AddOns panel's tooltip (1220) — the reference's `frameStrata="DIALOG"` with `toplevel="true"`.
+/// `frameStrata="DIALOG"` with `toplevel`: above the glue screen, its dialogs and the AddOns
+/// tooltip (z 1100, 1200, 1220).
 const REALM_Z: i32 = 1250;
 
-/// The panel plate, straight off `RealmList.xml`.
+/// The panel plate, from `RealmList.xml`.
 const BG_W: f32 = 640.0;
 const BG_H: f32 = 512.0;
 /// `RealmListBackground`'s authored CENTER offset.
 const BG_CENTER_OFF_X: f32 = 24.0;
 
-/// `MAX_REALMS_DISPLAYED` (`RealmList.lua` l.2).
+/// `MAX_REALMS_DISPLAYED` (`RealmList.lua:2`).
 pub(super) const MAX_ROWS: usize = 18;
-/// The authored row pitch: a 16-tall button plus the 4 px anchor offset to the next.
-///
-/// Note this is NOT `REALM_BUTTON_HEIGHT` (`RealmList.lua` l.1 = 16), which the reference uses for
-/// the scrollbar's step while its buttons sit 20 apart. We scroll by whole rows, so only the pitch
-/// is load-bearing here.
+/// The row pitch: a 16-tall button plus the 4 px anchor offset; not `REALM_BUTTON_HEIGHT` (16),
+/// which is only the scrollbar's step.
 const ROW_PITCH: f32 = 20.0;
 /// `RealmListRealmButton1` at TOPLEFT (22, −56).
 const ROW0_LEFT: f32 = 22.0;
 const ROW0_TOP: f32 = 56.0;
 const ROW_W: f32 = 512.0;
 const ROW_H: f32 = 16.0;
-/// `RealmListHighlight` — wider than the row it sits behind.
+/// `RealmListHighlight`, wider than the row it sits behind.
 const HILIGHT_W: f32 = 557.0;
 
 /// The four sort columns: `(key, string key, left, width)`. The lefts chain off
@@ -71,8 +56,7 @@ const SORT_COLUMNS: [(SortKey, &str, f32, f32); 4] = [
 const SORT_H: f32 = 19.0;
 const SORT_CAP_L: f32 = 5.0;
 const SORT_CAP_R: f32 = 4.0;
-/// The sort header row's top edge: anchored BOTTOMLEFT to the plate's TOPLEFT at −50, so the
-/// 19-tall button's *bottom* is at 50.
+/// The sort header's top: its BOTTOMLEFT is anchored at −50 off the plate's TOPLEFT.
 const SORT_TOP: f32 = 50.0 - SORT_H;
 
 /// A row's four column boxes, chained off the `RealmListRealmButtonTemplate` anchors:
@@ -83,9 +67,8 @@ const COL_TYPE: (f32, f32) = (235.0, 50.0);
 const COL_PLAYERS: (f32, f32) = (336.0, 32.0);
 const COL_LOAD: (f32, f32) = (418.0, 115.0);
 
-/// Root of the realm-list screen (despawned whole on exit). `with_art`/`s` drive the same rebuild
-/// rule every glue screen uses: an artless early spawn upgrades when the client art lands, and a
-/// window resize rebuilds at the new glue scale.
+/// Root of the realm list; `with_art` and `s` trigger a rebuild when the art lands or the scale
+/// changes.
 #[derive(Component)]
 pub(super) struct RealmListUi {
     with_art: bool,
@@ -95,26 +78,22 @@ pub(super) struct RealmListUi {
 /// One clickable control on the screen.
 #[derive(Component, Clone, Copy, PartialEq, Eq)]
 pub(super) enum RealmAction {
-    /// A realm row (0-based *screen* row, resolved against the scroll offset at click time).
+    /// A realm row: the 0-based screen row, resolved against the scroll offset at click time.
     Row(usize),
     Ok,
-    /// The Cancel button, and ESCAPE — `RealmList_OnCancel`.
+    /// The Cancel button and Escape, `RealmList_OnCancel`.
     Cancel,
-    /// The close X, which is **not** the Cancel button. `RealmListCloseButton`'s whole OnClick is
-    /// `RealmList:Hide()`, and `GlueCloseButton` (`GlueTemplates.xml` l.4) declares no sound — so
-    /// the X is silent where Cancel plays `gsLoginChangeRealmCancel`. Same outcome for the player,
-    /// one fewer click in the room.
+    /// The close X: `RealmList:Hide()`, silent (`GlueCloseButton`, `GlueTemplates.xml:4`,
+    /// declares no sound) where Cancel plays `gsLoginChangeRealmCancel`.
     Close,
     Sort(SortKey),
 }
 
-/// Which screen row an entity belongs to — on the row button and on each of its four texts.
+/// The screen row of a row button and of each of its four texts.
 #[derive(Component, Clone, Copy)]
 pub(super) struct RowOf(pub(super) usize);
 
-/// Which of a row's four columns a text entity is. One component with four values rather than four
-/// marker types: the refresh then reads every column in **one** query and one loop, instead of four
-/// that differ only in which marker they filter on and which disjointness they have to declare.
+/// Which of a row's four columns a text entity is.
 #[derive(Component, Clone, Copy, PartialEq, Eq)]
 pub(super) enum Column {
     Name,
@@ -129,13 +108,7 @@ pub(super) struct RowHighlight;
 #[derive(Component)]
 pub(super) struct OkButton;
 
-/// Raise, rebuild and tear down the dialog — `RealmList:Show()` / `:Hide()`, plus the rebuild rule
-/// every glue tree here follows (an artless early spawn upgrades when the client art lands, and a
-/// window resize rebuilds at the new glue scale).
-///
-/// **Not a state transition.** The frame is shown over whatever glue screen is current and hidden
-/// again; nothing about that screen changes, which is the whole of `RealmList`'s lifecycle in the
-/// reference (see [`super`]).
+/// Spawn, rebuild and despawn the dialog as `shown` says, over whatever glue screen is current.
 pub(super) fn drive_screen(
     mut commands: Commands,
     realms: Res<Realms>,
@@ -208,11 +181,9 @@ fn spawn_screen(
         .spawn((
             RealmListUi { with_art, s },
             GlobalZIndex(REALM_Z),
-            // `enableMouse="true"` on a `setAllPoints` frame: the dialog eats every click that
-            // misses its own controls, so the screen underneath cannot be operated through it.
-            // (A `Button` with no `FocusPolicy` blocks, which is what we want here.)
+            // `enableMouse="true"` on a full-screen frame: clicks never reach the screen below.
             Button,
-            // The reference's own full-screen BACKGROUND layer: black at 0.75.
+            // The reference's full-screen BACKGROUND layer.
             BackgroundColor(Color::srgba(0.0, 0.0, 0.0, 0.75)),
             Node {
                 width: Val::Percent(100.0),
@@ -238,8 +209,8 @@ fn spawn_screen(
                 for row in 0..MAX_ROWS {
                     spawn_row(b, &font, row, s);
                 }
-                // Okay / Cancel — `GlueDialogButtonTemplate` at 125×35, Cancel at BOTTOMRIGHT
-                // (−46, +13) and Okay hung off its left edge with an 8 px overlap.
+                // `GlueDialogButtonTemplate` 125×35: Cancel at BOTTOMRIGHT (−46, +13), Okay off
+                // its left edge with an 8 px overlap.
                 let cancel_left = BG_W - 46.0 - 125.0;
                 let btn_top = BG_H - 13.0 - 35.0;
                 for (action, key, left) in [
@@ -268,7 +239,7 @@ fn spawn_screen(
         });
 }
 
-/// The six-piece `HelpFrame` plate — 640×512 in two rows of three.
+/// The six-piece `HelpFrame` plate, two rows of three.
 fn spawn_plate(b: &mut ChildSpawnerCommands, art: &GlueArt, s: f32) {
     match &art.help_frame {
         Some(hf) => {
@@ -330,7 +301,7 @@ fn spawn_header(
     );
 }
 
-/// `GlueCloseButton` at TOPRIGHT (−42, −3) — see [`RealmAction::Close`] for why it is not Cancel.
+/// `GlueCloseButton` at TOPRIGHT (−42, −3).
 fn spawn_close(b: &mut ChildSpawnerCommands, art: &GlueArt, font: &Handle<Font>, s: f32) {
     let mut x = b.spawn((
         RealmAction::Close,
@@ -382,10 +353,8 @@ fn spawn_close(b: &mut ChildSpawnerCommands, art: &GlueArt, font: &Handle<Font>,
     }
 }
 
-/// The four clickable column headers (`RealmSortButtonTemplate`): a three-slice
-/// `WhoFrame-ColumnTabs` plate, the label 8 in from the left with the `UI-SortArrow` beside it, and
-/// the `UI-Character-Tab-Highlight` sheen the shared [`crate::glue::glue_hilights`] pass lights on
-/// hover.
+/// The four column headers (`RealmSortButtonTemplate`): a three-slice `WhoFrame-ColumnTabs`
+/// plate, the label with `UI-SortArrow`, and the `UI-Character-Tab-Highlight` hover sheen.
 fn spawn_sort_headers(
     b: &mut ChildSpawnerCommands,
     art: &GlueArt,
@@ -403,7 +372,6 @@ fn spawn_sort_headers(
             abs(s, left, SORT_TOP, w, SORT_H),
         ))
         .with_children(|h| {
-            // The plate: 5-wide left cap, 4-wide right cap, the middle stretched between them.
             if let Some((tex, size)) = &art.column_tabs {
                 for (tc, l, cw) in [
                     (COLUMN_TAB_TC[0], 0.0, SORT_CAP_L),
@@ -420,7 +388,7 @@ fn spawn_sort_headers(
                     ));
                 }
             }
-            // The sheen, LEFT..RIGHT+4 and 24 tall — vertically centred on a 19-tall button.
+            // The sheen, LEFT..RIGHT+4 and 24 tall, centred on the button.
             if let Some(hi) = &art.tab_highlight {
                 h.spawn((
                     Hilight,
@@ -474,8 +442,7 @@ fn spawn_sort_headers(
     }
 }
 
-/// `RealmListHighlight` — one 557×16 band, moved to the selected row and vertex-coloured to match
-/// it (`RealmListHighlightTexture:SetVertexColor`).
+/// `RealmListHighlight`: one band, moved to the selected row and vertex-coloured to match it.
 fn spawn_highlight(b: &mut ChildSpawnerCommands, art: &GlueArt, s: f32) {
     let mut band = b.spawn((
         RowHighlight,
@@ -536,10 +503,8 @@ fn spawn_row(b: &mut ChildSpawnerCommands, font: &Handle<Font>, row: usize, s: f
     });
 }
 
-/// Write every visible row from the realm list — the reference's `RealmListUpdate`.
-///
-/// Runs every frame rather than on change, because the list is re-requested every five seconds and
-/// a realm's load band moves when *any other* realm's population does.
+/// `RealmListUpdate`: write every visible row, each frame, since any realm's population moves
+/// every band.
 #[allow(clippy::type_complexity)]
 pub(super) fn refresh_rows(
     realms: Res<Realms>,
@@ -564,11 +529,9 @@ pub(super) fn refresh_rows(
         Some(g) => g.text(key, key).to_string(),
         None => key.to_string(),
     };
-    // The screen row → realm index map for this frame, honouring the scroll offset.
     let at = |row: usize| visible.get(realms.offset + row).copied();
 
-    // The row under the cursor, if any — `RealmListRealmButtonTemplate`'s `HighlightFont`, which
-    // is the only hover state a row has (the template carries no HighlightTexture).
+    // A row's only hover state is the template's `HighlightFont`; it has no HighlightTexture.
     let mut hovered = None;
     for (RowOf(row), interaction, mut vis) in &mut rows {
         *vis = match at(*row) {
@@ -580,7 +543,6 @@ pub(super) fn refresh_rows(
         }
     }
 
-    // Where the selection band goes, decided while walking the name column.
     let mut band_row = None;
     for (RowOf(row), column, mut t, mut color) in &mut cols {
         let Some(realm) = at(*row).map(|i| &realms.realms[i]) else {
@@ -588,9 +550,7 @@ pub(super) fn refresh_rows(
         };
         let down = super::is_down(realm);
         let invalid = super::is_invalid(realm);
-        // `LockHighlight()` on the chosen row, `button:Disable()` on an offline one: the selected
-        // row wears its highlight font just as a hovered row does, and a disabled row wears
-        // neither.
+        // `LockHighlight()` on the chosen row, `Disable()` on an offline one.
         let is_selected = selected.as_deref() == Some(realm.name.as_str()) && !down;
         let lit = !down && (is_selected || hovered == Some(*row));
         let (new, c) = match column {
@@ -601,8 +561,7 @@ pub(super) fn refresh_rows(
                 let (normal, highlight) = load::name_colors(down, invalid, realm.characters);
                 (realm.name.clone(), if lit { highlight } else { normal })
             }
-            // `RealmListUpdate` recolours the selected row's type and load columns to
-            // HIGHLIGHT_FONT_COLOR — the two computed words go white under the band.
+            // `RealmListUpdate` turns the selected row's type and load `HIGHLIGHT_FONT_COLOR`.
             Column::Type => {
                 let (key, c) = load::type_column(realm.realm_type);
                 (text(key), if is_selected { load::HIGHLIGHT } else { c })
diff --git a/crates/benilla-app/src/realm_select/smoke.rs b/crates/benilla-app/src/realm_select/smoke.rs
index 60d5f5c9..9337728a 100644
--- a/crates/benilla-app/src/realm_select/smoke.rs
+++ b/crates/benilla-app/src/realm_select/smoke.rs
@@ -1,25 +1,11 @@
-//! **The realm-list boundary smoke** (`WOW_REALM_SMOKE=1`, run by `scripts/smoke.sh`) — the
-//! scripted walk that reproduces the failure this subsystem shipped with, so it can never come
-//! back silently.
+//! The realm-list boundary smoke (`WOW_REALM_SMOKE=1`, run by `scripts/smoke.sh`), against a
+//! real server:
 //!
-//! What broke, and why nothing caught it: the realm list was a `ClientState`, and the roster that
-//! arrives after Okay only moved the app off `Login`. So Okay published the pick, the IO thread
-//! entered the realm and walked on to the character park — and the app sat on the realm screen,
-//! looking exactly as if the button had done nothing. The next Cancel then sent its answer to a
-//! park two ahead of the thread, where nobody was listening, and every later login queued behind
-//! it: the client hung on "Connecting" with **nothing in the log**. Three screens' worth of
-//! symptoms, one missing transition, and no test in the workspace could see any of it, because
-//! every one of them models the app or the thread and the bug lived in the seam.
-//!
-//! So this leg drives the seam, against a real server:
-//!
-//! 1. from character select, **Change Realm** — the dialog goes up *over* the screen, which stays;
-//! 2. **Okay** on the realm we are already on — a real world re-dial, and the roster has to come
-//!    back with the dialog down and the screen still character select (the leg that was broken);
-//! 3. **Change Realm again, then Cancel** — the dialog goes down and the session underneath is
-//!    untouched, which is the whole of `RealmList_OnCancel`;
-//! 4. one more round trip through the park to prove the thread is still where the app thinks it
-//!    is: a second Okay that has to land.
+//! 1. from character select, Change Realm: the dialog goes up over the screen, which stays;
+//! 2. Okay on the current realm: a world re-dial whose roster arrives with the dialog down and the
+//!    screen still character select;
+//! 3. Change Realm again, then Cancel: the dialog goes down and the session is untouched;
+//! 4. one more Change Realm and Okay, proving the IO thread is at the park the app expects.
 //!
 //! Inert without the env.
 
@@ -30,32 +16,25 @@ use crate::net::{RealmChoice, RealmRequest};
 
 use super::Realms;
 
-/// How long each leg may take before the walk gives up and says which one stalled.
+/// How long each leg may take before the walk names the one that stalled.
 const LEG_TIMEOUT: f32 = 25.0;
-/// How long the walk waits to REACH character select before it says why it never started.
-///
-/// The whole login is inside this — dial, auth, realm list, roster — which is why it is not
-/// [`LEG_TIMEOUT`], and why it exists at all: leg 0 was the one leg with no predecessor to name
-/// it, so a walk that never reached the roster screen said nothing and ran out the caller's own
-/// timeout instead. `scripts/smoke.sh` then reported "the realm walk did not finish within the
-/// timeout", which is true of every possible failure and a cause for none of them.
+/// How long the walk waits to reach character select; the whole login is inside it.
 const ENTRY_TIMEOUT: f32 = 60.0;
-/// A beat with the dialog up, so a human watching sees it and a stuck frame has time to show.
+/// A beat with the dialog up, so a stuck frame has time to show.
 const DWELL: f32 = 1.0;
 
 #[derive(Default)]
 pub(super) struct Walk {
     phase: u8,
     mark: f32,
-    /// The roster generation we are waiting to move past — a realm entered is a roster replaced.
+    /// The roster count to reach: an entered realm sends a new roster.
     rosters: u32,
     seen: u32,
     /// The one-shot startup refusal has run.
     armed: bool,
 }
 
-/// The walk. Every leg names itself on the way in, so a timeout says which boundary stalled
-/// instead of "the client did not exit".
+/// The walk; every leg logs itself, so a timeout names the boundary that stalled.
 pub(super) fn debug_realm_smoke(
     mut msgs: MessageReader<crate::net::CharListMessage>,
     realms: ResMut<Realms>,
@@ -76,16 +55,8 @@ pub(super) fn debug_realm_smoke(
         error!("realm-smoke: FAILED — {why}");
         exit.write(AppExit::error());
     };
-    // **The walk needs the roster SCREEN, and two envs structurally deny it** — so refuse here,
-    // on the first frame, instead of spending a login and a timeout discovering it. `WOW_CHAR` is
-    // the enter-the-world fast path and `WOW_RIG` seats its own derived body; either one answers
-    // the very roster this walk stands on, and neither can be waited out.
-    //
-    // Inherited rather than typed is the case worth naming. `scripts/smoke.sh` runs this leg out
-    // of the same shell as everything else and now scrubs `WOW_*` before it starts — but this
-    // check is the guard for the leg itself, not for that one caller: an agent reproducing a
-    // realm-list report by hand types `WOW_REALM_SMOKE=1 cargo run` into a shell that has been
-    // exporting probe credentials all session, and gets told why in the first second.
+    // `WOW_CHAR` and `WOW_RIG` each seat a body and answer the roster this walk drives, so
+    // either one, even inherited from the shell, fails the walk on its first frame.
     if !walk.armed {
         walk.armed = true;
         if let Some((key, value)) = ["WOW_CHAR", "WOW_RIG"]
diff --git a/crates/benilla-app/src/realmlist.rs b/crates/benilla-app/src/realmlist.rs
index 590ee82b..2b68d0ec 100644
--- a/crates/benilla-app/src/realmlist.rs
+++ b/crates/benilla-app/src/realmlist.rs
@@ -1,36 +1,20 @@
-//! The **realmlist** — the address benilla dials for the logon (realmd) handshake, and the one
-//! setting a player cannot start the game without (decision 1667).
+//! The realmlist: the `host[:port]` benilla dials for the logon handshake.
 //!
-//! The reference client has no UI for this at all: it registers a CVar named `realmList` — help
-//! text *"Address of realm list server"*, default `us.logon.worldofwarcraft.com:3724` — and loads
-//! it from a plain-text `realmlist.wtf` beside the executable, which every private server's setup
-//! page tells you to open in Notepad. (All four strings are byte-verified in `WoW.exe`, adjacent
-//! in the string table at the CVar's registration site, `0x5ab6a6`.) benilla keeps the
-//! **name, the `host[:port]` shape and the help string**, and replaces the text editor with a
-//! control on the login screen.
+//! The reference registers the CVar `realmList` (help "Address of realm list server", at
+//! `0x5ab6a6`) and loads it from `realmlist.wtf` beside the executable, with no UI. benilla keeps
+//! the name, the shape and the help string. Deviation: the value lives in `config.toml` with every
+//! other CVar and is edited from a login-screen control, because local state is one folder and one
+//! config file.
 //!
-//! **It is a CVar, in `config.toml` with every other setting — not a `realmlist.wtf` of our own.**
-//! The reference splits the file for reasons that are entirely its own (the installer and the
-//! patcher write the realmlist without touching a player's `Config.wtf`), and benilla has neither.
-//! Decision 0954's law is one folder and one config file; a second file would buy nothing and
-//! would fork the atomic-write, unknown-key-preservation and debounce machinery that already
-//! exists. `GetCVar("realmList")` answers, which is also what the reference's own console does.
-//!
-//! **`$WOW_HOST` still wins for the session** and never reaches the file — the same law
-//! `WOW_UI_SCALE`/`WOW_FARCLIP` run under (`crate::cvars`' module doc). Every probe, smoke run and
-//! harness leg sets it, so the env path is the one that must not change behaviour: its value is
-//! taken **verbatim**, not through [`normalize`], so nothing that connects today can start
-//! failing a syntax check.
+//! `$WOW_HOST` wins for the session, is never written to the file, and is taken verbatim, not
+//! through [`normalize`].
 
 use bevy::prelude::*;
 
-/// Installs [`Realmlist`]. Its own plugin (rather than a line in `CvarPlugin`) because every other
-/// CVar knob resource is owned by the module it belongs to, and because the resource has to exist
-/// before `cvars::load_config` applies the saved value at `Startup` — `lib.rs` orders it there.
+/// Installs [`Realmlist`], which must exist before `cvars::load_config` applies the saved value.
 pub(crate) struct RealmlistPlugin;
 
-/// `realmList`'s change callback (1667, 2303): a string row — a value that is not an address
-/// is consumed with a warn, and the resource keeps its truth.
+/// `realmList`'s change callback: a value that is not an address is ignored with a warning.
 pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut realmlist: ResMut<Realmlist>) {
     if !ev.is(CVAR_REALMLIST) {
         return;
@@ -48,44 +32,31 @@ impl Plugin for RealmlistPlugin {
     }
 }
 
-/// The CVar name — the reference's own spelling, `realmList`.
+/// The CVar name, the reference's spelling.
 pub(crate) const CVAR_REALMLIST: &str = "realmList";
 
-/// benilla's registered default.
-///
-/// **Not the reference's** `us.logon.worldofwarcraft.com:3724`, which is a knowing divergence and
-/// a small one: that host has not resolved since 2019, so shipping it would mean every first
-/// launch begins with a DNS failure. benilla is a client for servers you run or choose, and the
-/// one it can assume is the one on the machine it is running on — which is also what every
-/// existing `WOW_HOST`-less dev and capture run already dials.
+/// Deviation: the local machine's server, not the reference's
+/// `us.logon.worldofwarcraft.com:3724`, because that host no longer resolves.
 pub(crate) const DEFAULT_REALMLIST: &str = "localhost";
 
-/// The dialog box's `letters` cap. The reference's login boxes are 16 (`AccountLogin.xml`); a
-/// hostname needs far more, and 64 covers any real DNS name (253 is the protocol limit, but
-/// nothing a player types by hand approaches it) while still bounding the field.
+/// The dialog box's `letters` cap. Deviation: 64, where the reference's login boxes cap at 16
+/// (`AccountLogin.xml`), because a hostname needs more.
 pub(crate) const MAX_LETTERS: usize = 64;
 
-/// The address the next logon attempt dials, as `host[:port]` — [`benilla_protocol::host_port`]
-/// supplies [`benilla_protocol::AUTH_PORT`] when the port is left off.
-///
-/// The session's live value, so a change takes effect on the **next attempt** with no relaunch.
-/// It is deliberately not read by the IO thread: the host travels on each
-/// [`crate::net::LoginRequest`], exactly as the credentials have since decision 0539 — an attempt
-/// carries everything about itself, and a mid-flight edit cannot repoint the attempt already on
-/// the wire.
+/// The address the next logon attempt dials, as `host[:port]` (the port defaults to
+/// [`benilla_protocol::AUTH_PORT`]). It travels on each [`crate::net::LoginRequest`], so an edit
+/// never repoints an attempt in flight.
 #[derive(Resource, Debug, Clone, PartialEq, Eq)]
 pub(crate) struct Realmlist {
     address: String,
-    /// `$WOW_HOST` owns this session. The screen still shows the address (a harness run that
-    /// dialed the wrong server should say so on its face), but the control is disabled and
-    /// nothing is written to `config.toml`.
+    /// `$WOW_HOST` owns this session: the address shows, the control is disabled, nothing persists.
     pinned_by_env: bool,
 }
 
 impl Default for Realmlist {
     fn default() -> Self {
         match std::env::var("WOW_HOST") {
-            // Verbatim, not normalized — see the module doc.
+            // Verbatim, not normalized.
             Ok(host) if !host.trim().is_empty() => Realmlist {
                 address: host,
                 pinned_by_env: true,
@@ -99,11 +70,7 @@ impl Default for Realmlist {
 }
 
 impl Realmlist {
-    /// A realmlist at `address` with **no env pin**, whatever the ambient `$WOW_HOST` says.
-    ///
-    /// For tests only, and it exists because [`Default`] reads the environment: a suite run from a
-    /// shell that exports `WOW_HOST` (which every probe recipe in this repo does) would otherwise
-    /// assert against that shell's value and refuse every write.
+    /// A realmlist with no env pin, for tests, since [`Default`] reads `$WOW_HOST`.
     #[cfg(test)]
     pub(crate) fn unpinned(address: &str) -> Self {
         Realmlist {
@@ -112,18 +79,15 @@ impl Realmlist {
         }
     }
 
-    /// What the next attempt dials.
     pub(crate) fn address(&self) -> &str {
         &self.address
     }
 
-    /// Whether `$WOW_HOST` pinned this session (the control is disabled, nothing persists).
     pub(crate) fn pinned_by_env(&self) -> bool {
         self.pinned_by_env
     }
 
-    /// Point at `address` — already through [`normalize`]. Ignored while pinned by the env, so a
-    /// stray `SetCVar` cannot repoint a harness leg mid-run.
+    /// Points at an already normalized `address`; ignored while pinned by the env.
     pub(crate) fn set(&mut self, address: &str) {
         if self.pinned_by_env || self.address == address {
             return;
@@ -132,23 +96,13 @@ impl Realmlist {
     }
 }
 
-/// Normalize what a player typed or pasted into a `host[:port]`, or `None` if there is nothing
-/// usable in it.
-///
-/// **Syntax only, never reachability** — the deliberate line every comparable client draws
-/// (Veloren, ClassiCube, Terraria, Minecraft): a name that does not resolve, a closed port and a
-/// firewalled box are all indistinguishable without dialing, and a pre-connect probe would report
-/// a false negative on exactly the LAN/VPN-hosted vmangos box this client exists for. Those
-/// failures surface where they always have — the authored `LOGIN_FAILED` dialog, with the address
-/// on screen behind it.
-///
-/// It accepts a **pasted `realmlist.wtf` line** verbatim (`SET realmlist "logon.example.org"`),
-/// because that is the literal string every private server's setup page tells a player to copy,
-/// and pasting it is what they will try first.
+/// Normalizes typed or pasted text into a `host[:port]`, checking syntax only; reachability
+/// surfaces in the `LOGIN_FAILED` dialog. A pasted `realmlist.wtf` line
+/// (`SET realmlist "logon.example.org"`) is unwrapped to its value.
 pub(crate) fn normalize(input: &str) -> Option<String> {
     let mut s = input.trim();
 
-    // `SET realmlist <value>` / `set realmlist = <value>` — the .wtf line, unwrapped to its value.
+    // `SET realmlist <value>` or `set realmlist = <value>`.
     if let Some(rest) = strip_prefix_ci(s, "set") {
         if rest.starts_with(|c: char| c.is_whitespace()) {
             if let Some(value) = strip_prefix_ci(rest.trim_start(), "realmlist") {
@@ -156,8 +110,7 @@ pub(crate) fn normalize(input: &str) -> Option<String> {
             }
         }
     }
-    // One matched pair of quotes (the .wtf line quotes its value); `trim_matches` would eat a
-    // run of them, which is a different string than the one the player pasted.
+    // One matched pair of quotes only; `trim_matches` would eat a run of them.
     if s.len() >= 2 && s.starts_with('"') && s.ends_with('"') {
         s = &s[1..s.len() - 1];
     }
@@ -166,16 +119,12 @@ pub(crate) fn normalize(input: &str) -> Option<String> {
     if s.is_empty() || s.chars().count() > MAX_LETTERS {
         return None;
     }
-    // No whitespace and no control characters: an address with a space in it is a paste that
-    // brought a second word along, not a host.
+    // Whitespace or control characters mean the paste brought a second word along.
     if s.chars().any(|c| c.is_whitespace() || c.is_control()) {
         return None;
     }
-    // Mirror `host_port`'s own split exactly (`benilla-protocol`): a **single** colon means the
-    // suffix was meant as a port, so a non-numeric one is a typo worth naming here rather than a
-    // DNS failure thirty seconds later. Two or more colons is an IPv6 literal, which `host_port`
-    // deliberately leaves intact — so this leaves it intact too rather than inventing a second,
-    // stricter law for the same string.
+    // Mirrors `host_port`'s split: a single colon must carry a valid port; two or more colons
+    // are an IPv6 literal, left intact.
     if let Some((host, port)) = s.rsplit_once(':') {
         if !host.contains(':') && (host.is_empty() || port.parse::<u16>().is_err()) {
             return None;
@@ -184,8 +133,7 @@ pub(crate) fn normalize(input: &str) -> Option<String> {
     Some(s.to_string())
 }
 
-/// `s` without `prefix`, matched case-insensitively. `str::get` returns `None` on a non-boundary
-/// index, so a multi-byte character straddling the split can never be sliced through.
+/// `s` without `prefix`, case-insensitively; `str::get` refuses a non-boundary split.
 fn strip_prefix_ci<'a>(s: &'a str, prefix: &str) -> Option<&'a str> {
     s.get(..prefix.len())
         .filter(|head| head.eq_ignore_ascii_case(prefix))
@@ -209,8 +157,6 @@ mod tests {
         );
     }
 
-    /// The line a private server's setup page tells you to paste into `realmlist.wtf` — in every
-    /// spelling those pages actually use.
     #[test]
     fn a_pasted_wtf_line_is_unwrapped() {
         for line in [
@@ -228,7 +174,6 @@ mod tests {
         }
     }
 
-    /// A host that merely *starts* with the letters of the prefix is not a .wtf line.
     #[test]
     fn a_host_named_like_the_prefix_is_left_alone() {
         assert_eq!(
@@ -249,7 +194,6 @@ mod tests {
         assert_eq!(normalize(&"a".repeat(MAX_LETTERS + 1)), None);
     }
 
-    /// The port half of `host_port`'s law, enforced forward: a single colon means a port.
     #[test]
     fn a_single_colon_must_carry_a_real_port() {
         assert_eq!(normalize("logon.example.org:notaport"), None);
@@ -262,8 +206,6 @@ mod tests {
         );
     }
 
-    /// An IPv6 literal keeps `host_port`'s own answer: more than one colon is a raw address and
-    /// comes back intact, with the default port.
     #[test]
     fn an_ipv6_literal_is_left_intact() {
         assert_eq!(normalize("::1").as_deref(), Some("::1"));
@@ -275,7 +217,6 @@ mod tests {
         );
     }
 
-    /// Every value this module can hand out survives `host_port` — the one consumer downstream.
     #[test]
     fn the_default_is_a_host_the_protocol_can_split() {
         let (host, port) =
@@ -284,7 +225,6 @@ mod tests {
         assert_eq!(port, benilla_protocol::AUTH_PORT);
     }
 
-    /// A pinned session refuses to be repointed — the harness guard.
     #[test]
     fn an_env_pinned_realmlist_ignores_writes() {
         let mut r = Realmlist {
diff --git a/crates/benilla-app/src/run_mode.rs b/crates/benilla-app/src/run_mode.rs
index cc6bb5fe..47ce708c 100644
--- a/crates/benilla-app/src/run_mode.rs
+++ b/crates/benilla-app/src/run_mode.rs
@@ -1,64 +1,32 @@
-//! **What kind of run is this, and whose** — the always-present layer, on the player's side of the
-//! `dev` seam (decisions 0026 / 1173, built in 1174).
+//! What kind of run this is and whose: the always-present layer on the player's side of the `dev`
+//! seam. Every answer defaults to the player's (nobody drives the camera, the client starts at the
+//! login screen, no rig owns the pick); a dev build's instruments only move answers off those
+//! defaults. Gameplay reads this module, never `capture`, `debug_panel` or `perf`.
 //!
-//! Everything here answers a question about *the run itself*, and every answer has a
-//! **player-faithful default**: nobody is driving the camera, the client starts at the login
-//! screen, no rig owns the character pick, this checkout belongs to nobody in particular. A dev
-//! build's instruments then move those answers off their defaults — which is the one direction the
-//! seam allows. Gameplay reads this module; gameplay never reads `capture`, `debug_panel` or
-//! `perf`.
-//!
-//! It exists because the alternative kept losing. 0026 asked for "a player-safe home or default"
-//! for exactly this class of fact in June 2026 and named two of them; by August there were 24
-//! references from non-dev code into the instruments (1173), because the facts had no home and the
-//! nearest thing that already knew the answer was the instrument itself.
-//!
-//! The engine drew the same line for itself one layer down: [`benilla_world::dev_state`]'s
-//! `deterministic_run` reads `$WOW_CAPTURE` on its own account, because "run deterministically" is
-//! a property of the world and the world must be able to ask it with no harness above it at all.
-//! **One environment variable, several readers, no shared symbol** — that is the pattern, and
-//! [`scenario_active`] below is its app-side twin. Keep the two in step.
+//! [`benilla_world::dev_state`]'s `deterministic_run` reads `$WOW_CAPTURE` on its own, as
+//! [`scenario_active`] does here; the two must stay in step.
 
 use bevy::prelude::*;
 
-/// **Something other than the player is authoring the camera and the avatar this run.**
-///
-/// Inserted by the capture harness, which is the only thing that ever drives them; a player build
-/// compiles no inserter, so the resource simply never exists and every `run_if` below reads as
-/// "the player is in charge" for free. The *type* lives here rather than in `capture` for one
-/// reason: `player::control`, `player::server_ride`, the self-model fade and the UI pass all name
-/// it in a run condition, and a run condition that names a dev type is a dependency on dev.
+/// Something other than the player authors the camera and the avatar this run. Only the capture
+/// harness inserts it; the type lives here because non-dev run conditions name it.
 #[derive(Resource)]
 pub(crate) struct CaptureMode;
 
-/// The rig's derived character name (decision 0651), when `$WOW_RIG` names a body.
-///
-/// Inserted by `capture::ProbeRigPlugin` at build time; absent otherwise — which is the player
-/// answer, and the answer in any run the rig is not driving. The character-select roster reads it
-/// to know that the pick is already spoken for, so it must not also honour `$WOW_CHAR`: the rig may
-/// have to *create* its body first, and the `WOW_CHAR` fast path is a one-shot that structurally
-/// cannot wait for that. Before 1174 the roster asked the harness directly.
+/// The rig's derived character name when `$WOW_RIG` names a body, inserted by
+/// `capture::ProbeRigPlugin`. While present the roster ignores `$WOW_CHAR`: the rig may have to
+/// create its body first, and the `WOW_CHAR` one-shot cannot wait for that.
 #[derive(Resource)]
 pub(crate) struct RigCharacter(pub(crate) String);
 
-/// **Is a capture running?** (`$WOW_CAPTURE` set.)
-///
-/// Read before any plugin builds — it decides whether the net thread starts, what size the window
-/// opens at, and whether clutter/anim-LOD randomness is pinned. All of those are properties of the
-/// run, not of the harness, and all of them must have an answer in a build with no harness in it.
-/// See the module doc for why this reads the variable rather than asking `capture`.
+/// Is a capture running (`$WOW_CAPTURE` set)? Read before any plugin builds: it decides whether
+/// the net thread starts, the window size, and whether clutter and anim-LOD randomness is pinned.
 pub(crate) fn scenario_active() -> bool {
     std::env::var("WOW_CAPTURE").is_ok()
 }
 
-/// **Is the player UI opted into this capture?** — the harness's [`crate::capture::ui_opted_in`],
-/// forwarded from here for the same reason [`scenario_active`] lives here: three consumers outside
-/// the harness need the answer (the UI load, the synthetic unit feed, the window size), and **all
-/// of them must still compile in a build with no harness in it**. `mod capture` is
-/// `#[cfg(feature = "dev")]`; this module is not.
-///
-/// `false` in a player build is the correct answer and not a stub: that binary has no scenario
-/// table and no `$WOW_CAPTURE` handling, so there is no capture for the UI to be opted into.
+/// Is the player UI opted into this capture? Forwards [`crate::capture::ui_opted_in`] for readers
+/// outside the harness; `false` in a player build, which has no capture to opt into.
 #[cfg(feature = "dev")]
 pub(crate) fn capture_ui_opted_in() -> bool {
     crate::capture::ui_opted_in()
@@ -69,68 +37,34 @@ pub(crate) fn capture_ui_opted_in() -> bool {
     false
 }
 
-/// **Do the credentials come from the environment?** (`$WOW_USER` and `$WOW_PASS`, both — the
-/// login screen's env fast path.)
-///
-/// The player answer is `false`, and it is the default: with neither set the client opens at the
-/// login screen and waits for somebody to type. Setting both says *"log in without waiting for me
-/// to type"* — and **that is the only thing it says.** It is not a claim about who is in the room;
-/// [`unattended`] is the fact for that, and keeping the two apart is decision 1769. There is no
-/// default account: one credential without the other is a typed login, and `$WOW_CHAR` alone is
-/// the roster's fast path after one (`char_select`), not a login.
+/// Do the credentials come from the environment (`$WOW_USER` and `$WOW_PASS`, both)? That means
+/// "log in without typing" and nothing about who is present; [`unattended`] answers that. One
+/// credential alone is a typed login, and `$WOW_CHAR` alone is only the roster's fast path.
 pub(crate) fn env_login() -> bool {
     ["WOW_USER", "WOW_PASS"]
         .iter()
         .all(|k| std::env::var_os(k).is_some())
 }
 
-/// **Is there nobody here?** (`$WOW_UNATTENDED`, or the two runs that are automated by
-/// construction: `$WOW_CAPTURE` and `$WOW_RIG`.)
+/// Is nobody at the keyboard? `false` unless the run declares itself with `$WOW_UNATTENDED`, or is
+/// a capture (`$WOW_CAPTURE`) or a rig (`$WOW_RIG`), which cannot be a person. Env login
+/// credentials alone never make a run unattended: a player may launch with them. The doubt goes
+/// one way because a wrong "attended" costs a probe a timeout, while a wrong "unattended" makes a
+/// player's client fight another for their account. A scripted run declares itself, as
+/// `docs/CONTRIBUTING.md`, "Running it unattended" says.
 ///
-/// The player answer is `false` and it is the **default**, like every other answer in this module:
-/// a client with nobody at the keyboard is the exception, and an exception declares itself. The
-/// direction is the whole point — guessing "attended" when a probe is running costs that probe a
-/// timeout, loudly; guessing "unattended" when a person is playing ships them a client that fights
-/// another client for their account, silently. Those two are not worth the same, so the doubt goes
-/// one way.
-///
-/// **This is the fact [`env_login`] was mistaken for, twice.** Env credentials mean "log in without
-/// typing"; they say nothing about the room — and the director plays with
-/// `WOW_USER=… WOW_PASS=… cargo play`, the example line in `.cargo/config.toml`. So
-/// every session they played read as "a harness": a typed password's refusal killed the process
-/// (fixed on 2026-08-28 by asking `announced` — direct evidence — instead of the environment) and,
-/// the half that fix left standing, a kick sent the client racing to take the account back instead
-/// of to the login screen. That is decision 1262's reported bug, reappearing three weeks later
-/// with not one line of its code changed, because the fact underneath it was never true. 1769.
-///
-/// `WOW_CAPTURE` and `WOW_RIG` are folded in because they *cannot* be a person: a capture authors
-/// the camera and a rig drives the body, so a run that sets either has already said what it is and
-/// cannot forget to. Everything else declares — `scripts/smoke.sh`, `cine.sh`, `summon-live.sh`
-/// and an ad-hoc probe run (`docs/CONTRIBUTING.md`, "Running it unattended") all pass
-/// `WOW_UNATTENDED=1`.
-///
-/// Read by whatever may act *instead of* a person: the lost-session verdict (decision 1262 — the
-/// session-loss readers never call this directly, [`crate::net::DisconnectedMessage::new`] asks
-/// once at the wire edge and every reader acts on the verdict it carries) and the two `FATAL`
-/// exits that keep a driverless run from burning its wall-clock on a dialog (decision 1371).
+/// Read by what acts instead of a person: [`crate::net::DisconnectedMessage::new`] (the
+/// lost-session verdict, taken once at the wire edge) and the `FATAL` exits.
 pub(crate) fn unattended() -> bool {
     ["WOW_UNATTENDED", "WOW_CAPTURE", "WOW_RIG"]
         .iter()
         .any(|k| std::env::var_os(k).is_some())
 }
 
-/// **This run cannot get past the screen it is on — may the client end it instead of a person?**
-/// (decision 1371's `FATAL` marker, resting on 1769's fact.)
-///
-/// `true` only for a run that has declared itself [`unattended`]: it exits non-zero on the one
-/// greppable marker a leg runner keys on, rather than parking a driverless run on a dialog for
-/// its whole wall-clock. Otherwise the dialog stays up for whoever is there.
-///
-/// The `false` arm still speaks, when the credentials came from the environment: a probe that
-/// quietly parks for 300 s instead of failing in 5 is precisely what 1769's default trades away,
-/// so the log names the declaration that buys the old behaviour back. Both arms live here because
-/// three call sites — two in [`crate::login`], one in [`crate::char_select`] — must not drift
-/// apart on either the verdict or the marker a leg runner greps for.
+/// A run stuck on a dialog: `true` (exit) only when the run is [`unattended`], logging the `FATAL`
+/// marker a leg runner greps for; otherwise the dialog stays up, with a hint when the credentials
+/// came from the environment. The call sites in [`crate::login`] and [`crate::char_select`] share
+/// it so the verdict and the marker cannot drift apart.
 pub(crate) fn fatal_when_driverless(why: &str) -> bool {
     if unattended() {
         error!("login: FATAL — {why}; exiting");
@@ -146,14 +80,9 @@ pub(crate) fn fatal_when_driverless(why: &str) -> bool {
     false
 }
 
-/// **Which screen the client starts on.** A player starts at the login screen, always; a capture
-/// boots straight into the world (no net, no picker), and a *glue* capture boots onto the very
-/// screen it photographs.
-///
-/// The one place this module forwards into the dev half, and deliberately the only one: the answer
-/// is needed *before the plugins build* (it is `CharSelectPlugin`'s `start`), so it cannot be a
-/// resource an instrument inserts the way [`CaptureMode`] and [`RigCharacter`] are. The forward is
-/// one call, in one direction, and the player arm names nothing at all.
+/// The screen the client starts on: a player at the login screen, a capture straight in the world,
+/// a glue capture on the screen it photographs. Needed before the plugins build, so it forwards
+/// into the dev half rather than reading a resource.
 pub(crate) fn start_state() -> crate::char_select::ClientState {
     #[cfg(feature = "dev")]
     {
@@ -165,44 +94,23 @@ pub(crate) fn start_state() -> crate::char_select::ClientState {
     }
 }
 
-/// **Does this build offer developer affordances at all?** `false` in a player build.
-///
-/// The generalisation of 1176's one-door rule, and the thing that record should have written
-/// (decision 1179). A dev affordance does not have to live in a dev module: the world map's
-/// Alt-click jump is in `ui_world_map`, the `/castvis` family is in `ui_chat`, the dev key plane's
-/// cost is in `bindings`. None of them names a dev root, so none of them fails to compile, and all
-/// of them shipped to players in 1174 exactly as free-fly did.
-///
-/// So the question a gameplay module asks is not "is the debug panel compiled in" — it is **"may I
-/// offer this at all"**, and there is one place to ask it. Held by
-/// [`tests::the_dev_plane_has_exactly_one_door`].
+/// Does this build offer developer affordances at all? `false` in a player build. A dev affordance
+/// may sit in a gameplay module (the world map's Alt-click jump, `/castvis`), so it asks here.
+/// Held by [`tests::the_dev_plane_has_exactly_one_door`].
 pub(crate) fn dev_affordances() -> bool {
     cfg!(feature = "dev")
 }
 
-/// **Did a dev-chord affordance just fire?** `Ctrl`+`Shift`+*key*, and `false` in a player build.
-///
-/// The one door onto the dev plane, and the reason it exists: the plane is
-/// [`benilla_world::modkeys::dev_chord`], which lives in the **engine** (1160 moved it there —
-/// "nothing about which two modifiers are the dev plane is a debug-panel opinion"), and the engine
-/// is always compiled. So a gameplay module asking for a dev chord creates **no symbol into a dev
-/// module**, compiles clean with `--no-default-features`, and ships a live dev affordance to a
-/// player. That is exactly what happened: 1174 landed a green player build in which `Ctrl+Shift+F`
-/// still flew the camera through the world, `+G` still teleported the avatar, and `+M` still muted
-/// the game (decision 1176).
-///
-/// Routing every non-dev reader through here makes the whole plane dark at once rather than five
-/// keys at a time, and makes the next dev chord dark for free. The build gate cannot see this class
-/// — nothing fails to compile — so it is held by [`tests::the_dev_plane_has_exactly_one_door`]
-/// instead, in the suite the gates already run.
+/// Did a dev chord (`Ctrl`+`Shift`+key) fire? `false` in a player build. The engine's
+/// [`benilla_world::modkeys::dev_chord`] is always compiled, so a gameplay module calling it
+/// directly would ship a live dev key to players with no build failure; every non-dev reader comes
+/// through here instead. Held by [`tests::the_dev_plane_has_exactly_one_door`].
 pub(crate) fn dev_chord(keys: &ButtonInput<KeyCode>, key: KeyCode) -> bool {
     dev_affordances() && benilla_world::modkeys::dev_chord(keys, key)
 }
 
-/// The free-fly hint the take-control line carries, or empty when there is no chord to advertise.
-/// A player build must not offer a key that does nothing. Spelled from
-/// [`benilla_world::modkeys::DEV_CHORD`] like every other surface that names the plane, so it
-/// cannot drift from what the chord actually listens for.
+/// The take-control line's free-fly hint, spelled from [`benilla_world::modkeys::DEV_CHORD`];
+/// empty in a player build, which must not offer a key that does nothing.
 pub(crate) fn free_fly_hint() -> String {
     #[cfg(feature = "dev")]
     {
@@ -217,24 +125,11 @@ pub(crate) fn free_fly_hint() -> String {
     }
 }
 
-/// **This crate's source directory on a dev build, `None` in a player build** — the seam's second
-/// door, and the one [`dev_affordances`] cannot be.
-///
-/// `dev_affordances()` answers "may I offer this", at runtime. Part of the seam is not about
-/// offering anything: it is about a **string being absent from the binary**.
-/// `env!("CARGO_MANIFEST_DIR")` names the build machine's home directory, and a runtime `if` does
-/// not remove it — the literal is still compiled in, still in `strings`, still shipped. 1174's
-/// pool-slot guard made exactly that mistake one level down ("inert in a player build" read as
-/// "absent from a player build"), and decision 1175 is entirely about a binary that stops
-/// depending on the machine that built it. So this `cfg` has to be real, and it lives here, once,
-/// behind a value instead of scattered across the modules that need it.
-///
-/// Two callers, both resolving content or state and neither of them an affordance:
-/// [`crate::ui_script`]'s dev probe into `assets/ui` (so editing FrameXML costs no recompile) and
-/// [`crate::local_state`]'s project-folder home. Both get `None` in a player build and fall through
-/// to the compiled-in copy and to `<exe dir>` respectively, with no path literal in the binary.
-///
-/// Held by [`tests::the_dev_plane_has_exactly_one_door`] like the rest of the seam.
+/// This crate's source directory on a dev build, `None` in a player build. The `cfg` must be real,
+/// not a runtime check: `env!("CARGO_MANIFEST_DIR")` names the build machine, and the literal must
+/// be absent from a player binary. Read by [`crate::ui_script`] (live `assets/ui`) and
+/// [`crate::local_state`] (the project-folder home); held by
+/// [`tests::the_dev_plane_has_exactly_one_door`].
 pub(crate) fn dev_source_dir() -> Option<&'static std::path::Path> {
     #[cfg(feature = "dev")]
     {
@@ -246,38 +141,24 @@ pub(crate) fn dev_source_dir() -> Option<&'static std::path::Path> {
     }
 }
 
-/// The pre-connect **account guard**, consulted by the login policy's env fast path
-/// ([`crate::login`]). Returns `Err(explanation)` when this checkout declares the account its
-/// scripted runs log in as ([`declared_identity`]) and the fast path is about to authenticate as
-/// anything else: a login KICKS whoever holds the account — a player mid-session, or another
-/// checkout's probe, whose kicked client (the 0065 teardown) despawns every net entity, so that
-/// run's next sample reads a unit-less world and prints garbage.
-///
-/// The declaration is a file, never the build directory: a path is nobody's identity. Without
-/// one (a plain clone, a player build) the guard is inert — it has no business having an opinion
-/// about a login it cannot attribute. That is why this lives here and not in `preflight`
-/// (decision 0649's home for it, until 1174 made `preflight` dev-only): gameplay's login policy
-/// calls it, and gameplay may not call an instrument.
-///
-/// `WOW_ALLOW_ACCOUNT=1` is the escape hatch for the rare deliberate cross-account run; it turns the
-/// refusal into a warning rather than silence, because the kick still happens.
+/// The pre-connect account guard on the env fast path ([`crate::login`]): `Err(explanation)` when
+/// this checkout declares an account ([`declared_identity`]) and the login is for another, because
+/// a login kicks whoever holds the account. Inert without a declaration. `WOW_ALLOW_ACCOUNT=1`
+/// turns the refusal into a warning.
 pub(crate) fn account_guard(user: &str) -> Result<(), String> {
     guard_for(declared_identity().as_ref(), user)
 }
 
 /// What `.probe-identity` at the project root declares: the account a scripted run from this
-/// checkout logs in as (`WOW_USER=`, `WOW_PASS=`, `WOW_CHAR=`, one per line; never committed —
-/// `.gitignore` carries it). A machine that runs several checkouts against one server gives each
-/// its own account this way, and `scripts/probe-identity.sh` reads the same file.
+/// checkout logs in as (`WOW_USER=`, `WOW_PASS=`, `WOW_CHAR=`, one per line, gitignored). Also read
+/// by `scripts/probe-identity.sh`.
 #[derive(Debug, PartialEq, Eq)]
 pub(crate) struct DeclaredIdentity {
     pub(crate) user: String,
     pub(crate) character: String,
 }
 
-/// The declaration, read off the project folder — `dev` only, the install resolver's own
-/// project-folder rung: a player build has no source tree to name (decision 1175), and no
-/// declared identity to keep.
+/// The declaration, read off the project folder; a player build has none.
 #[cfg(feature = "dev")]
 pub(crate) fn declared_identity() -> Option<DeclaredIdentity> {
     let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
@@ -291,8 +172,8 @@ pub(crate) fn declared_identity() -> Option<DeclaredIdentity> {
     None
 }
 
-/// The file's three lines, as an identity — `None` unless the account and the character are
-/// both there (the password is the scripts' business, never this crate's).
+/// The file as an identity, `None` unless both the account and the character are there; the
+/// password is never read.
 #[cfg_attr(not(feature = "dev"), allow(dead_code))]
 fn parse_identity(text: &str) -> Option<DeclaredIdentity> {
     let field = |key: &str| {
@@ -307,7 +188,7 @@ fn parse_identity(text: &str) -> Option<DeclaredIdentity> {
     })
 }
 
-/// [`account_guard`]'s decision, with the declaration passed in so it is testable without a file.
+/// [`account_guard`]'s decision, with the declaration passed in.
 fn guard_for(declared: Option<&DeclaredIdentity>, user: &str) -> Result<(), String> {
     let Some(id) = declared else {
         return Ok(());
@@ -323,11 +204,9 @@ fn guard_for(declared: Option<&DeclaredIdentity>, user: &str) -> Result<(), Stri
     ))
 }
 
-/// The word a rig appends to the bodies it mints for this checkout (`<Race3><Class3><word>[f]`),
-/// so that several checkouts against one server never collide on a character name: the declared
-/// character, lowercased, without a leading `probe` — a probe fleet names its bodies
-/// `Probe<word>`, and the word is the identity. `None` without a declaration; the rig then
-/// configures the body it logged in as.
+/// The word a rig appends to this checkout's bodies (`<Race3><Class3><word>[f]`) so checkouts
+/// never collide on a name: the declared character, lowercased, without a leading `probe`. `None`
+/// without a declaration; the rig then configures the body it logged in as.
 pub(crate) fn rig_suffix() -> Option<String> {
     Some(suffix_of(&declared_identity()?.character))
 }
@@ -348,23 +227,12 @@ fn suffix_of(character: &str) -> String {
 mod tests {
     use super::*;
 
-    /// **The dev plane has exactly one door** (decision 1176).
-    ///
-    /// The player-build gate (`cargo build -p benilla --no-default-features`) catches a *symbol*
-    /// crossing into a dev module. It cannot catch this: `benilla_world::modkeys::dev_chord` is
-    /// engine, always compiled, so a gameplay module that asks it for `Ctrl+Shift+F` compiles
-    /// perfectly in a player build and ships free-fly to a player. 1174 landed exactly that, green.
-    ///
-    /// So the rule is checked instead of remembered, the way 0789 checks the probe clock: outside
-    /// the dev roots, `dev_chord` is [`super::dev_chord`]'s to call and nobody else's. A dev module
-    /// may call the engine's directly — it does not exist in a player build to be reached.
-    ///
-    /// This does NOT police [`benilla_world::modkeys::DEV_CHORD`], the display string: naming the
-    /// plane in a label is not offering a key.
+    /// Outside the dev roots, only [`super::dev_chord`] may call the engine's `dev_chord`, and no
+    /// file may name the `dev` feature: the player build gate cannot see either. The display
+    /// string [`benilla_world::modkeys::DEV_CHORD`] is exempt.
     #[test]
     fn the_dev_plane_has_exactly_one_door() {
-        // Everything that is compiled out by `--no-default-features`, plus this module, which is
-        // the door itself. Anything else asking the engine for a dev chord is the bug.
+        // Compiled out by `--no-default-features`, plus this module, the door itself.
         const DEV_ROOTS: &[&str] = &[
             "capture/",
             "debug_panel/",
@@ -377,14 +245,9 @@ mod tests {
             "lib.rs",
             "run_mode.rs",
         ];
-        // Assembled at runtime so the checker does not flag its own source — the same trick, and
-        // the same proof of teeth, as `capture::probes`' clock test.
+        // Assembled at runtime so the checker does not flag its own source.
         let needle = format!("modkeys::{}(", "dev_chord");
-        // The second clause: `#[cfg(feature = "dev")]` itself. Seam knowledge has exactly three
-        // addresses — this module (the always-present layer), `dev.rs` (the group), and `lib.rs`
-        // (the module declarations). A `cfg` attribute anywhere else means a gameplay module has
-        // learned the seam exists, which is the state 1174's whole diff cleared the tree out of,
-        // and which spreads one file at a time if nothing objects.
+        // `#[cfg(feature = "dev")]` belongs only in this module, `dev.rs` and `lib.rs`.
         let cfg_needle = format!("feature = {}dev{}", '"', '"');
 
         let src = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
@@ -433,8 +296,7 @@ mod tests {
         );
     }
 
-    /// **Two questions, two facts** (decision 1769) — and the fixture is the line the director
-    /// actually types, so a future merge of the two answers fails here rather than in their game.
+    /// Env credentials log in without typing but do not make the run unattended.
     #[test]
     fn env_credentials_are_not_a_claim_about_who_is_in_the_room() {
         use crate::local_state::test_env::{EnvGuard, ENV_LOCK};
@@ -452,9 +314,7 @@ mod tests {
             let _c = EnvGuard::unset("WOW_CHAR");
             assert!(!env_login() && !unattended());
         }
-        // `WOW_USER=… WOW_PASS=… cargo play`, `.cargo/config.toml`'s example, and the
-        // director's launch line since 2026-08-29. Log them in without typing, yes. Decide things
-        // on their behalf, no.
+        // `WOW_USER=… WOW_PASS=… cargo play`, `.cargo/config.toml`'s example: a player's launch.
         let _u = EnvGuard::set("WOW_USER", "player");
         let _p = EnvGuard::set("WOW_PASS", "secret");
         assert!(env_login(), "the fast path still submits for them");
@@ -473,17 +333,15 @@ mod tests {
     #[test]
     fn the_fast_path_is_the_declared_account_or_refused() {
         let id = parse_identity("WOW_USER=probe4\nWOW_PASS=secret\nWOW_CHAR=Probefour\n").unwrap();
-        // Our own account: the whole point of the declaration.
         assert!(guard_for(Some(&id), "probe4").is_ok());
         assert!(guard_for(Some(&id), "PROBE4").is_ok()); // vmangos accounts are case-insensitive
 
-        // Anyone else's account — a player's, another checkout's probe — kicks a live session.
+        // Anyone else's account kicks a live session.
         let player = guard_for(Some(&id), "player").unwrap_err();
         assert!(player.contains("probe4") && player.contains("kicks"));
         // The override hint belongs to the caller that can act on it, not to the reason.
         assert!(!player.contains("WOW_ALLOW_ACCOUNT"));
         assert!(guard_for(Some(&id), "probe7").is_err());
-        // No declaration, no standing.
         assert!(guard_for(None, "player").is_ok());
     }
 
@@ -503,11 +361,10 @@ mod tests {
 
     #[test]
     fn the_rig_word_is_the_declared_character_without_its_probe_prefix() {
-        // vmangos player names carry no digits, so a probe fleet spells its index: the word is
-        // what follows `Probe`, and the rig's `Taudru<word>` keeps one body per checkout.
+        // vmangos player names carry no digits, so a probe fleet spells its index.
         assert_eq!(suffix_of("Probefour"), "four");
         assert_eq!(suffix_of("Probezero"), "zero");
-        // Any other name is its own word, cut to what a 12-character name has room for.
+        // Any other name is its own word, cut to fit a 12-character name.
         assert_eq!(suffix_of("Tester"), "tester");
         assert_eq!(suffix_of("Longcharname"), "longch");
         assert_eq!(suffix_of("Probe"), "probe");
diff --git a/crates/benilla-app/src/screen_fade.rs b/crates/benilla-app/src/screen_fade.rs
index bd526f0c..dafa109e 100644
--- a/crates/benilla-app/src/screen_fade.rs
+++ b/crates/benilla-app/src/screen_fade.rs
@@ -1,62 +1,43 @@
-//! The engine's screen fade — the whole frame to black, and back.
+//! The engine's screen fade to black and back, the reference's general facility:
+//! - `0x4c0d10(ecx = completion fn, edx = its arg, [ebp+8] = seconds)` fades out, and the
+//!   completion runs when the screen reaches full black, not after a delay;
+//! - `0x4c1280(ecx, edx, seconds)` fades in, a no-op unless a fade is up.
 //!
-//! This is the reference's own facility, not a cinematic's private effect. Two entry points, both
-//! taking a duration in seconds:
-//!
-//! - **`0x4c0d10(ecx = completion fn, edx = its arg, [ebp+8] = seconds)` — fade OUT to black.** It
-//!   latches the completion pair and arms the fade; **the completion runs when the screen reaches
-//!   full black**, not after a delay on a parallel clock.
-//! - **`0x4c1280(ecx, edx, seconds)` — fade IN from black.** A no-op unless a fade is currently up.
-//!
-//! That distinction is the whole reason this module exists rather than a `Timer` at each call site.
-//! A cinematic boundary is not "wait 0.25 s, then advance" — it is "go black, and *when you are
-//! black*, advance". The two coincide only while the frame rate holds; under a hitch (and the shot
-//! boundary is exactly where the reference does a blocking terrain load) a delay-driven sequence
-//! shows the cut, and a completion-driven one cannot.
-//!
-//! **The completion callback does not cross into this module.** The reference stores a function
-//! pointer; an ECS system cannot, and faking it with a boxed closure in a `Resource` would buy
-//! nothing. Instead this owns only the ramp — alpha and phase — and exposes [`ScreenFade::is_black`]
-//! as a *level*. The caller keeps its own "which step is pending" state and runs it while black.
-//! Same sequencing, with the step left where it can see the data it needs.
-//!
-//! The one caller today is `crate::cinematic`. It is written as the general facility because that
-//! is what it is in the reference (`0x4c0d10` has callers well outside the cinematic band), not in
-//! anticipation of a second one here.
+//! Completion-driven matters under a hitch: a cinematic shot boundary does a blocking terrain
+//! load, and a delay-driven cut would show. The callback stays with the caller: this owns the
+//! ramp and exposes [`ScreenFade::is_black`] as a level, and the caller runs its pending step
+//! while black. The one caller is `crate::cinematic`.
 
 use bevy::prelude::*;
 
-/// The reference's fade duration at every cinematic boundary: `[0x804550] = 0.25`, in `.rdata` —
-/// genuinely read-only, so this is a constant in the image and not some global's default.
+/// The fade duration at every cinematic boundary: `[0x804550] = 0.25`, in `.rdata`.
 pub(crate) const CINEMATIC: f32 = 0.25;
 
 #[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
 enum Phase {
-    /// Nothing up: alpha 0, the world visible.
+    /// Alpha 0, the world visible.
     #[default]
     Clear,
     /// Ramping 0 → 1.
     Out,
-    /// Held at 1. **The fade stays here until someone calls [`ScreenFade::fade_in`]** — it does not
-    /// bounce on its own, because the caller's step runs in this phase and may take many frames.
+    /// Held at 1 until [`ScreenFade::fade_in`]: the caller's step runs here, maybe for many frames.
     Black,
     /// Ramping 1 → 0.
     In,
 }
 
-/// The screen fade's state. Drive it with [`fade_out`](ScreenFade::fade_out) /
-/// [`fade_in`](ScreenFade::fade_in); read it with [`is_black`](ScreenFade::is_black).
+/// The screen fade's state.
 #[derive(Resource, Default)]
 pub(crate) struct ScreenFade {
     alpha: f32,
     phase: Phase,
-    /// Seconds for a full 0→1 traverse; the ramp is linear in time over this.
+    /// Seconds for a full linear 0 to 1 ramp.
     seconds: f32,
 }
 
 impl ScreenFade {
-    /// Start going to black. Re-arming while already fading out keeps the alpha reached so far, so
-    /// a second request cannot restart the ramp from clear and show a flash of world.
+    /// Starts going to black; re-arming mid-fade keeps the alpha reached, so the world never
+    /// flashes.
     pub(crate) fn fade_out(&mut self, seconds: f32) {
         if self.phase == Phase::Black {
             return;
@@ -69,9 +50,8 @@ impl ScreenFade {
         }
     }
 
-    /// Come back from black. **A no-op unless a fade is currently up** — the reference's own
-    /// guard at `0x4c1280`, which matters because the tail of a shot arm fades in unconditionally
-    /// and must not paint a black ramp over a screen that was never darkened.
+    /// Comes back from black; a no-op unless a fade is up (`0x4c1280`), since a shot arm's tail
+    /// fades in unconditionally.
     pub(crate) fn fade_in(&mut self, seconds: f32) {
         if self.phase == Phase::Clear {
             return;
@@ -84,24 +64,18 @@ impl ScreenFade {
         }
     }
 
-    /// The screen is fully black **and holding**: the caller's boundary step runs now.
+    /// Fully black and holding: the caller's boundary step runs now.
     pub(crate) fn is_black(&self) -> bool {
         self.phase == Phase::Black
     }
 
-    /// Nothing up — no fade in progress and the world fully visible.
-    ///
-    /// Only the tests ask this today. It is the exact complement of the state `fade_in` refuses to
-    /// act on, so it is the honest way to assert a ramp came all the way home; it is not carried
-    /// as speculative API for a caller that does not exist.
+    /// No fade in progress and the world fully visible.
     #[cfg(test)]
     fn is_clear(&self) -> bool {
         self.phase == Phase::Clear
     }
 
-    /// Drop the fade with no ramp. For a teardown that must not leave the screen black behind it
-    /// (leaving the world mid-cinematic, a failed start), where a graceful fade-in has no frames
-    /// left to run in.
+    /// Drops the fade with no ramp, for a teardown that must not leave the screen black.
     pub(crate) fn clear(&mut self) {
         self.alpha = 0.0;
         self.phase = Phase::Clear;
@@ -140,14 +114,12 @@ impl Plugin for ScreenFadePlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<ScreenFade>()
             .add_systems(Startup, spawn_cover)
-            // `PostUpdate`: every boundary step this frame — the cinematic's arm, advance and end —
-            // has already run, so the cover drawn is the one that matches the state the frame will
-            // actually present. Ticking before them would advance the ramp on last frame's answer.
+            // `PostUpdate`: after this frame's boundary steps, so the cover matches their state.
             .add_systems(PostUpdate, drive_cover);
     }
 }
 
-/// One full-screen black node, spawned once and parked hidden — the loading cover's own shape.
+/// One full-screen black node, spawned once and parked hidden.
 fn spawn_cover(mut commands: Commands) {
     commands.spawn((
         FadeCover,
@@ -158,12 +130,8 @@ fn spawn_cover(mut commands: Commands) {
             ..default()
         },
         BackgroundColor(Color::NONE),
-        // **Above the loading cover (1000).** The reference hands the world-enter loading screen
-        // over to the cinematic *under* the black: `0x48edd0`'s first instruction dismisses the
-        // loading screen, and it runs at full black. A fade below the cover could not
-        // do that — the cover would be the thing on screen, and its dismissal would be a visible
-        // cut. Below the glue screens (1100) so a state change out of the world can never be
-        // trapped behind a fade that has no one left to clear it.
+        // Above the loading cover's z-index, 1000: `0x48edd0` dismisses the loading screen at
+        // full black. Below the glue screens' 1100, so leaving the world is never trapped.
         GlobalZIndex(1050),
         Visibility::Hidden,
     ));
@@ -176,9 +144,7 @@ fn drive_cover(
     mut was: Local<Option<Phase>>,
 ) {
     fade.tick(time.delta_secs());
-    // One line per edge, so a timeline (`scripts/cine.sh`) can see the boundaries at all. Four
-    // transitions per fade and two boundaries per single-shot cinematic is eight lines a run;
-    // without them the fade is invisible to every instrument we have.
+    // One line per edge, for a timeline (`scripts/cine.sh`).
     if *was != Some(fade.phase) {
         match fade.phase {
             Phase::Out => info!("screen fade: out"),
@@ -218,13 +184,10 @@ mod tests {
     fn a_fade_out_reaches_black_and_holds_there() {
         let mut fade = ScreenFade::default();
         fade.fade_out(CINEMATIC);
-        // Half the duration is half way, and emphatically NOT black yet.
         ticks(&mut fade, 5, CINEMATIC / 10.0);
         assert!(!fade.is_black(), "half a ramp is not black");
         ticks(&mut fade, 5, CINEMATIC / 10.0);
         assert!(fade.is_black(), "a full ramp reaches black");
-        // …and stays. The caller's boundary step may take many frames; the fade must not bounce
-        // back on its own while it runs.
         ticks(&mut fade, 100, CINEMATIC);
         assert!(fade.is_black(), "black holds until fade_in");
     }
@@ -243,8 +206,7 @@ mod tests {
 
     #[test]
     fn fade_in_on_a_clear_screen_does_nothing() {
-        // The reference's `0x4c1280` guard. The tail of the shot arm fades in unconditionally;
-        // on a screen that was never darkened that must not start a ramp *from* black.
+        // The `0x4c1280` guard.
         let mut fade = ScreenFade::default();
         fade.fade_in(CINEMATIC);
         assert!(fade.is_clear());
@@ -255,7 +217,6 @@ mod tests {
 
     #[test]
     fn re_arming_a_fade_out_does_not_restart_from_clear() {
-        // Two boundaries landing close together must not flash the world between them.
         let mut fade = ScreenFade::default();
         fade.fade_out(CINEMATIC);
         ticks(&mut fade, 5, CINEMATIC / 10.0);
diff --git a/crates/benilla-app/src/screenshot.rs b/crates/benilla-app/src/screenshot.rs
index 3dbe75c7..0b60d6d8 100644
--- a/crates/benilla-app/src/screenshot.rs
+++ b/crates/benilla-app/src/screenshot.rs
@@ -1,62 +1,21 @@
-//! **Print screen** (decision 1487) — the capture key, the writer, and the "Screen Captured" text
-//! that must never appear in the file it announces.
+//! Print screen: the capture, the file writer and the "Screen Captured" status, which must never
+//! appear in the shot it announces. The binding runs `TakeScreenshot()` (`WorldFrame.lua:46`),
+//! which hides `ScreenshotStatus` and calls `Screenshot()`; the engine later answers
+//! `SCREENSHOT_SUCCEEDED` or `SCREENSHOT_FAILED`.
 //!
-//! The reference's shape, which this reproduces exactly (its own `Bindings.xml` + `WorldFrame.lua`,
-//! read off the 1.12.1 install):
+//! Our UI quads are built at the top of `UiInput` and the binding runs at its bottom, so a capture
+//! on the press frame would still show a second press's fading status; [`ask_for_captures`]
+//! therefore holds each ask exactly one frame.
 //!
-//! ```text
-//! PRINTSCREEN → binding SCREENSHOT → TakeScreenshot()   [FrameXML]
-//!                                      ScreenshotStatus:Hide()   ← last frame's text, gone first
-//!                                      Screenshot()              [engine]
-//!                                    … the frame is captured …
-//! engine → SCREENSHOT_SUCCEEDED / SCREENSHOT_FAILED   → ScreenshotStatus shows, fades over 1.5 s
-//! ```
+//! Deviations:
+//! - PNG, not TGA, because a 32-bit Targa of a modern window is about 8 MB and few tools open it.
+//! - `benilla-config/Screenshots/`, not the install's, because benilla never writes the install.
 //!
-//! **That ordering is most of the answer to B261's third clause, and the rest is ours to arrange.**
-//! For a single press nothing can leak: `Screenshot()` returns nothing and the outcome comes back
-//! as an *event*, frames later, because the readback is asynchronous — the confirmation does not
-//! exist yet when the shutter fires. The leak is the SECOND press inside the 1.5 s fade, when the
-//! previous shot's "Screen Captured" is still on screen; that is what the reference's `Hide()`
-//! before the capture is for.
+//! The reference fires `SCREENSHOT_SUCCEEDED` even when the write fails, a bug not copied:
+//! [`report_captures`] answers `SCREENSHOT_FAILED` and logs the reason.
 //!
-//! **And on our pipeline that `Hide()` lands one frame too late** — measured, not reasoned:
-//! a live double press wrote the text straight into the second PNG. `ui_script`'s paint pass
-//! ticks the VM and builds this frame's UI quad list at the TOP of the `UiInput` set; the binding
-//! dispatch that runs `TakeScreenshot()` sits at the BOTTOM of that same set. So by the time the
-//! binding hides the frame, the quads carrying its text are already built, and the frame that then
-//! renders — and gets captured — still has the line in it. Nothing in the reference's design says
-//! otherwise; the real client simply does not build its draw list in that order.
-//!
-//! So [`ask_for_captures`] **holds each ask for one frame** ([`ScreenshotState::pending`]). The
-//! capture is requested on the frame AFTER the press, whose `paint_script` has rebuilt the quads
-//! with the frame hidden. One frame is the whole fix and also the minimum: any less and the stale
-//! quads are what gets photographed, any more and the shutter drifts from the keypress for no
-//! reason. `ui_script::screenshot_tests` pins the UI contract; this file's own test pins the
-//! deferral, and the live falsifier is a double press 0.6 s apart (decision 1487).
-//!
-//! **Two deliberate divergences, both recorded in 1487:**
-//!
-//! 1 · **PNG, where the reference writes TGA.** An uncompressed 32-bit Targa of a modern window is
-//!     ~8 MB and no ordinary tool on a 2026 desktop previews one. The mechanism, the folder and the
-//!     naming are otherwise the reference's.
-//! 2 · **`benilla-config/Screenshots/`, not `<install>/Screenshots/`** — decision 1486's rule:
-//!     benilla reads a WoW install and never writes to one. Same folder name, different parent.
-//!
-//! **One reference behaviour deliberately NOT transcribed.** The real client fires
-//! `SCREENSHOT_SUCCEEDED` whether or not the file was written — it discards the writer's return
-//! value, so the event means "the device gave us a buffer" — and it has already deleted the
-//! partial file. That is a bug, not a contract: [`report_captures`] answers `SCREENSHOT_FAILED`
-//! when the encode or the write actually failed, and puts the reason in the log.
-//!
-//! **Two gaps that ARE faithful**, named so they are not mistaken for oversights: a raw
-//! `Screenshot()` from a macro or addon skips `TakeScreenshot`'s `Hide()` and so can photograph a
-//! fading confirmation (the reference's hide is in Lua too, and inventing an engine-side one would
-//! be inventing behaviour); and the key does nothing at the glue screens, where the reference
-//! captures through hard-coded, unrebindable `OnKeyDown` handlers that print nothing — a separate
-//! slice, in the glue arc.
-//!
-//! Nothing here is dev-gated: this is a player feature, and it links in the `--no-default-features`
-//! player build like the rest of the UI arc.
+//! As in the reference, a raw `Screenshot()` from Lua skips the `Hide()`. The glue screens'
+//! capture keys are not built.
 
 use bevy::prelude::*;
 use bevy::render::view::screenshot::{Screenshot, ScreenshotCaptured};
@@ -66,33 +25,25 @@ use benilla_ui::script::UiScript;
 
 use crate::ui_script::{UiFeed, UiInput};
 
-/// The reference's own file stem (`WoWScrnShot_`), kept: a player who knows what WoW screenshots
-/// are called finds the same names here, and so does every screenshot-organizing tool the
-/// community has. Only the extension changes.
+/// The reference's file stem.
 const STEM: &str = "WoWScrnShot";
 
-/// What the writer thread reported back. The outcome is a two-state answer because the UI's is:
-/// `SCREENSHOT_SUCCEEDED` or `SCREENSHOT_FAILED`, nothing in between.
+/// The writer thread's answer.
 enum Outcome {
     Saved(std::path::PathBuf),
     Failed(String),
 }
 
-/// The capture arc's state: the channel the writer threads report through, and just enough clock
-/// memory to keep two captures in the same second from landing on the same name.
+/// The writer threads' channel and the naming clock.
 #[derive(Resource)]
 struct ScreenshotState {
     tx: crossbeam_channel::Sender<Outcome>,
     rx: crossbeam_channel::Receiver<Outcome>,
-    /// The epoch second the last name was minted for, and how many have been minted for it.
-    /// **Held here rather than probed off the filesystem**: the write happens on a worker thread
-    /// and may not have created the file by the time the next name is needed, so "does it exist
-    /// yet?" is a race that silently overwrites. A counter on the main thread cannot lose.
+    /// The last name's epoch second and its count; counted here, not probed on disk, because the
+    /// worker may not have created the previous file yet.
     last_second: i64,
     within_second: u32,
-    /// Captures asked for on the PREVIOUS frame, waiting for this one to render. The one-frame
-    /// hold that keeps the status line out of the picture — see the module docs for the measured
-    /// reason it is needed at all.
+    /// Captures asked for on the previous frame (module doc).
     pending: u32,
 }
 
@@ -110,19 +61,11 @@ impl Default for ScreenshotState {
 }
 
 impl ScreenshotState {
-    /// The next file name, from the wall clock: `WoWScrnShot_MMDDYY_HHMMSS.png`, the reference's
-    /// own field order and zero padding.
+    /// `WoWScrnShot_MMDDYY_HHMMSS.png`, the reference's field order and padding.
     ///
-    /// **A second capture inside the same second gets `_2`, `_3`, … rather than overwriting.**
-    /// That is a divergence and a deliberate one: the reference's fixed-name write means a burst
-    /// of key presses leaves one file, which is a silent data loss the player only discovers
-    /// later. The suffix is outside the reference's grammar, so nothing that parses the faithful
-    /// name is broken by a name it will simply not match.
-    ///
-    /// **UTC, not local time** — the reference stamps local. The workspace carries no date
-    /// dependency and a local offset needs a timezone source, not different arithmetic; the Lua
-    /// `date()` global records the same divergence for the same reason
-    /// ([`benilla_ui::civil`]). Names stay unique and sort correctly either way.
+    /// A second capture in the same second gets `_2`, `_3`: the reference overwrites, so a burst
+    /// leaves one file, a data loss not copied. Deviation: UTC, not local time, because there is
+    /// no timezone source (as for Lua `date()`, [`benilla_ui::civil`]).
     fn next_name(&mut self, now: i64) -> String {
         if now == self.last_second {
             self.within_second += 1;
@@ -147,17 +90,8 @@ impl ScreenshotState {
     }
 }
 
-/// Ask the renderer for one frame per queued `Screenshot()` call — **one frame after the call**.
-///
-/// The order within a frame is: spawn last frame's asks first, then drain this frame's. Both halves
-/// matter. Spawning first means the entity is in the world before the render extract at the end of
-/// THIS frame, whose UI quads `paint_script` rebuilt with the status line already hidden. Draining
-/// second means an ask made by the binding dispatch earlier in this same frame waits its turn
-/// rather than being photographed against the quads that were built before the hide — which is the
-/// bug this deferral exists for (module docs).
-///
-/// Ordered `.after(BindingSet)` so the drain deterministically sees an ask the binding just made,
-/// instead of depending on where an unconstrained system happened to land.
+/// Captures each `Screenshot()` one frame after the call. Spawn last frame's asks before draining
+/// this frame's: that order is the one-frame hold (module doc).
 fn ask_for_captures(
     mut commands: Commands,
     script: Option<NonSendMut<UiScript>>,
@@ -173,17 +107,9 @@ fn ask_for_captures(
     }
 }
 
-/// The readback landed: name the file and hand the encode+write to a worker.
-///
-/// **Off the main thread on purpose.** A 2560×1440 PNG encode is tens of milliseconds and this
-/// runs inside the frame; doing it here would drop frames every time the player takes a shot,
-/// which is the one moment they are looking at the picture. The answer comes back through the
-/// channel and is reported on whichever later frame it arrives — the UI already expects that,
-/// because the reference's outcome is an event too.
+/// Names the file and hands the encode and write to a worker, off the frame.
 fn write_capture(captured: On<ScreenshotCaptured>, mut state: ResMut<ScreenshotState>) {
-    // Nothing to write to: a hermetic capture/probe run (`$WOW_CAPTURE`), or a platform with no
-    // discoverable exe directory. Report the failure rather than dropping it silently — the UI
-    // says "Screen Capture Failed" and the player learns something.
+    // No folder under a `$WOW_CAPTURE` run or without an exe directory: report it as a failure.
     let Some(dir) = crate::local_state::screenshots_dir() else {
         let _ = state.tx.send(Outcome::Failed(
             "no benilla-config folder to write into".into(),
@@ -192,9 +118,7 @@ fn write_capture(captured: On<ScreenshotCaptured>, mut state: ResMut<ScreenshotS
     };
     let path = dir.join(state.next_name(benilla_ui::civil::unix_seconds()));
 
-    // `to_rgb8` drops alpha, which on an HDR target carries brightness rather than opacity — the
-    // same choice bevy's own `save_to_disk` makes, and for the same reason: kept, the picture is
-    // wrong.
+    // Drop alpha: on an HDR target it carries brightness, not opacity.
     let dynamic = match captured.image.clone().try_into_dynamic() {
         Ok(img) => img.to_rgb8(),
         Err(e) => {
@@ -221,12 +145,8 @@ fn write_capture(captured: On<ScreenshotCaptured>, mut state: ResMut<ScreenshotS
         .detach();
 }
 
-/// Report finished writes to the UI — the reference's `SCREENSHOT_SUCCEEDED` / `SCREENSHOT_FAILED`.
-///
-/// **Before [`UiInput`]**, the shape every other feed in this crate uses: the event is delivered at
-/// the top of a frame so the status text is laid out with everything else, and — the part that
-/// matters — this can only ever be a frame *after* the one that was captured, so the text it puts
-/// on screen cannot be in the picture.
+/// Fires `SCREENSHOT_SUCCEEDED` or `SCREENSHOT_FAILED` for finished writes, always a frame after
+/// the capture, so the status cannot be in the picture.
 fn report_captures(script: Option<NonSendMut<UiScript>>, state: Res<ScreenshotState>) {
     let Some(mut script) = script else {
         return;
@@ -234,8 +154,7 @@ fn report_captures(script: Option<NonSendMut<UiScript>>, state: Res<ScreenshotSt
     while let Ok(outcome) = state.rx.try_recv() {
         match outcome {
             Outcome::Saved(path) => {
-                // Announced at info: "where did my screenshot go" is the first question a player
-                // asks about a folder that is deliberately not where WoW put it (decision 1486).
+                // At info: the folder is not where WoW puts it.
                 info!("screenshot: wrote {}", path.display());
                 script.fire_event("SCREENSHOT_SUCCEEDED", Vec::new());
             }
@@ -267,15 +186,11 @@ impl Plugin for ScreenshotPlugin {
 mod tests {
     use super::*;
 
-    /// The reference's field order and padding, and the anti-clobber suffix — the two halves of
-    /// [`ScreenshotState::next_name`] that a reader would otherwise have to take on trust.
     #[test]
     fn names_follow_the_reference_and_never_collide() {
         let mut s = ScreenshotState::default();
-        // 2026-08-21T13:45:07Z — single digits in the day and the hour would be the padding bug.
+        // 2026-08-21T13:45:07Z.
         assert_eq!(s.next_name(1_787_319_907), "WoWScrnShot_082126_134507.png");
-        // Same second again: a suffix, not an overwrite. The reference would have written the
-        // same name twice and left one file.
         assert_eq!(
             s.next_name(1_787_319_907),
             "WoWScrnShot_082126_134507_2.png"
@@ -284,35 +199,26 @@ mod tests {
             s.next_name(1_787_319_907),
             "WoWScrnShot_082126_134507_3.png"
         );
-        // A new second resets the counter — the plain name is the overwhelmingly common one.
         assert_eq!(s.next_name(1_787_319_908), "WoWScrnShot_082126_134508.png");
-        // 2001-01-02T03:04:05Z: every field at its narrowest, and a year whose last two digits
-        // need the leading zero the reference's `%02d` gives them.
+        // 2001-01-02T03:04:05Z: every field needs its `%02d` zero.
         assert_eq!(s.next_name(978_404_645), "WoWScrnShot_010201_030405.png");
     }
 
-    /// **The one-frame hold, as a test** — the fix for the leak a live double press actually
-    /// produced (module docs). An ask made during frame N must not be spawned until frame N+1,
-    /// because frame N's UI quads were built before the binding hid the status line.
-    ///
-    /// Driven against the real system in a minimal app rather than by calling a helper: the claim
-    /// is about *scheduling*, and a helper that runs both halves in one call would pass whether or
-    /// not the deferral survives a future reorder.
+    /// An ask made during frame N is spawned on frame N+1.
     #[test]
     fn an_ask_is_held_for_one_frame_before_the_shutter() {
         let mut app = App::new();
         app.init_resource::<ScreenshotState>();
-        // The observer is irrelevant here — what is under test is when the entity appears — so the
-        // system runs with no VM and the asks are pushed by hand.
+        // No VM: the asks are pushed by hand.
         app.add_systems(Update, spawn_pending_only);
 
-        // Frame N: the binding asked. Nothing may be spawned yet.
+        // Frame N: the binding asked.
         app.world_mut().resource_mut::<ScreenshotState>().pending = 0;
         app.world_mut().resource_mut::<ScreenshotState>().pending += 1;
         let staged = app.world().resource::<ScreenshotState>().pending;
         assert_eq!(staged, 1, "the ask is staged, not yet a capture");
 
-        // Frame N+1: now it fires, against quads rebuilt with the line hidden.
+        // Frame N+1.
         app.update();
         assert_eq!(
             app.world().resource::<ScreenshotState>().pending,
@@ -328,7 +234,6 @@ mod tests {
             "and exactly one capture is requested"
         );
 
-        // A quiet frame asks for nothing.
         app.update();
         assert_eq!(
             app.world_mut()
@@ -339,10 +244,7 @@ mod tests {
         );
     }
 
-    /// [`ask_for_captures`]'s spawn half alone — the drain half needs a live VM, which a bare
-    /// `App` has no business building. Keeping the two in one system in production and splitting
-    /// only here would be the usual lie, so this calls the real thing with the VM absent, which is
-    /// exactly how it behaves at the character-select screen.
+    /// The real [`ask_for_captures`] with no VM, as at character select.
     fn spawn_pending_only(commands: Commands, state: ResMut<ScreenshotState>) {
         ask_for_captures(commands, None, state);
     }
diff --git a/crates/benilla-app/src/shaders.rs b/crates/benilla-app/src/shaders.rs
index 07eb4b88..e9fe21cc 100644
--- a/crates/benilla-app/src/shaders.rs
+++ b/crates/benilla-app/src/shaders.rs
@@ -1,23 +1,11 @@
-//! **The game's WGSL, compiled into the binary** (decision 1175).
-//!
-//! The five shaders under `src/shaders/` draw the *game's* own surface — the UI quad lane, the
-//! glue screen's additive pass, and the three gamma passes. 1171 moved them out of the engine's
-//! asset root and into this crate; 1175 stops serving them from a directory at all.
-//!
-//! They used to reach the asset server through a `game://` source registered with
-//! `concat!(env!("CARGO_MANIFEST_DIR"), "/assets")` — the build machine's source tree, baked into
-//! the binary. `embedded_asset!` keeps 1171's line (it is per-crate by construction) and drops the
-//! path: the interface cannot go missing because there is nothing to miss.
-//!
-//! The registration lives here, at the root of `src/`, for the path-arithmetic reason spelled out
-//! in `benilla_world::shaders` — the macro does not normalize, so a call from a submodule would
-//! bake that submodule's directory into the served path.
+//! The game's five WGSL shaders, embedded in the binary. Registered from the root of `src/`: the
+//! macro does not normalize paths, so a call from a submodule would bake its directory into the
+//! served path.
 
 use bevy::prelude::*;
 
-/// Compile the game's five WGSL files in and register them under
-/// `embedded://benilla_app/shaders/…`. Runs before anything can ask for one — added with the
-/// client's other plugins, after `DefaultPlugins` has created the registry it fills.
+/// Register the five shaders under `embedded://benilla_app/shaders/…`; added after `DefaultPlugins`
+/// creates the registry it fills.
 pub(crate) fn plugin(app: &mut App) {
     bevy::asset::embedded_asset!(app, "shaders/ui_quad.wgsl");
     bevy::asset::embedded_asset!(app, "shaders/ui_add.wgsl");
@@ -31,8 +19,7 @@ mod tests {
     use bevy::asset::io::AssetSourceId;
     use bevy::prelude::*;
 
-    /// The game's twin of `benilla_world::shaders`' test — see it for why the path is read back
-    /// rather than reasoned about, and why the loop is driven off the directory listing.
+    /// Reads every file in the directory back from its embedded path.
     #[test]
     fn every_game_shader_answers_at_its_embedded_path() {
         let mut app = App::new();
diff --git a/crates/benilla-app/src/shaders/ui_add.wgsl b/crates/benilla-app/src/shaders/ui_add.wgsl
index 7d8e77ac..f3f8f88c 100644
--- a/crates/benilla-app/src/shaders/ui_add.wgsl
+++ b/crates/benilla-app/src/shaders/ui_add.wgsl
@@ -1,8 +1,6 @@
-// WoW `alphaMode="ADD"` for Bevy UI, the glue highlight overlays: `AddUiMaterial::specialize` sets
-// the additive blend state, and this stage samples the authored sub-rect (`rect` is uv min/max; the
-// sheets keep the button region in a corner or quarter). The texel goes back to gamma bytes, so the
-// `SrcAlpha, One` blend is the reference's byte add `dst + texel * a` (EGxBlend 3,
-// `glBlendFunc(GL_SRC_ALPHA, GL_ONE)`).
+// `alphaMode="ADD"` for the glue highlight overlays: samples the sub-rect `rect` (uv min/max) and
+// returns gamma bytes, so the `SrcAlpha, One` blend is the reference's byte add `dst + texel * a`
+// (EGxBlend 3, `glBlendFunc(GL_SRC_ALPHA, GL_ONE)`).
 #import bevy_ui::ui_vertex_output::UiVertexOutput
 
 @group(1) @binding(0) var texture: texture_2d<f32>;
diff --git a/crates/benilla-app/src/shaders/ui_gamma.wgsl b/crates/benilla-app/src/shaders/ui_gamma.wgsl
index cfc1243d..95184ae1 100644
--- a/crates/benilla-app/src/shaders/ui_gamma.wgsl
+++ b/crates/benilla-app/src/shaders/ui_gamma.wgsl
@@ -1,8 +1,6 @@
-// The UI lane's one gamma decode, with the client's display-gamma ramp applied first: the value
-// sampled here is the byte the reference's RAMDAC would read. `ui_quad.wgsl` composites gamma bytes
-// into an `Rgba8UnormSrgb` target, so the sampler returns the value written and `srgb_to_linear`
-// re-encodes it to the exact byte in the swapchain (output mode `Skip`, no blit follows). RGB is
-// premultiplied by coverage; alpha is coverage, carries no gamma, and passes through.
+// The UI lane's one gamma decode, after the display-gamma ramp: the sampled value is the byte the
+// reference's RAMDAC would read, and `srgb_to_linear` re-encodes it to the exact swapchain byte.
+// Alpha is coverage and passes through.
 
 #import bevy_core_pipeline::fullscreen_vertex_shader::FullscreenVertexOutput
 
@@ -22,9 +20,8 @@ fn srgb_to_linear(c: vec3<f32>) -> vec3<f32> {
 fn fs_decode(in: FullscreenVertexOutput) -> @location(0) vec4<f32> {
     let ui = textureSample(screen_texture, screen_sampler, in.uv);
     var rgb = ui.rgb;
-    // The reference's hardware ramp `pow(i / 255, gamma)` (`0x591680`), with `rgb` as `i / 255`.
-    // The uniform branch keeps the default an exact identity: `pow(x, 1.0)` compiles to
-    // `exp2(log2(x))` and `log2(0)` is undefined, which the floor also guards for other gammas.
+    // The reference's hardware ramp `pow(i / 255, gamma)` (`0x591680`). The branch keeps gamma 1
+    // an exact identity and the floor guards `log2(0)` inside `pow`.
     if (ramp.x != 1.0) {
         rgb = pow(max(rgb, vec3<f32>(1e-6)), vec3<f32>(ramp.x));
     }
diff --git a/crates/benilla-app/src/shaders/ui_node_gamma.wgsl b/crates/benilla-app/src/shaders/ui_node_gamma.wgsl
index 9f8fa095..ffd4d66b 100644
--- a/crates/benilla-app/src/shaders/ui_node_gamma.wgsl
+++ b/crates/benilla-app/src/shaders/ui_node_gamma.wgsl
@@ -1,12 +1,8 @@
-// The glue screens' Bevy UI node shader on the UI gamma composite lane, vendored from
-// `bevy_ui_render` 0.18.1 `src/ui.wgsl`: upstream verbatim except `linear_to_srgb`, the fragment's
-// colour computation, and the dropped `#define_import_path` line (two modules claiming
-// `bevy_ui::ui_node` would collide). Re-diff against upstream on every Bevy upgrade: a structural
-// change fails pipeline validation, a fragment-side one drifts silently.
-//
-// The reference draws the glue screens into an 8-bit backbuffer, so every UI multiply and blend is
-// arithmetic on gamma bytes. This fragment outputs raw gamma into the `Rgba8UnormSrgb` target, so
-// the `(SrcAlpha, OneMinusSrcAlpha)` blend runs on gamma values; `ui_gamma.wgsl` decodes once.
+// The glue screens' Bevy UI node shader, vendored from `bevy_ui_render` 0.18.1 `src/ui.wgsl`,
+// verbatim except `linear_to_srgb`, the fragment's colour and the dropped `#define_import_path`
+// (two `bevy_ui::ui_node` modules would collide). Re-diff on every Bevy upgrade: a fragment-side
+// change drifts silently. The fragment outputs raw gamma, as the reference blends on 8-bit bytes;
+// `ui_gamma.wgsl` decodes once.
 
 #import bevy_render::view::View
 
@@ -24,8 +20,8 @@ fn enabled(flags: u32, mask: u32) -> bool {
     return (flags & mask) != 0u;
 }
 
-// Linear → sRGB on the IEC 61966-2-1 curve the hardware's sRGB store uses, so it inverts the
-// sampler's decode bit-for-bit in f32; keep identical to `ui_quad.wgsl`'s.
+// Linear to sRGB (IEC 61966-2-1), the exact inverse of the sampler's decode; keep identical to
+// `ui_quad.wgsl`'s.
 fn linear_to_srgb(c: vec3<f32>) -> vec3<f32> {
     let higher = 1.055 * pow(max(c, vec3<f32>(0.0)), vec3<f32>(1.0 / 2.4)) - 0.055;
     let lower = c * 12.92;
@@ -231,9 +227,8 @@ fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
     let texture_color = textureSample(sprite_texture, sprite_sampler, in.uv);
 
     // ── changed from upstream ──
-    // Upstream multiplies in linear. Each factor is encoded back to its authored sRGB byte and the
-    // multiply runs there, as the reference's FFP does; encoding the product instead diverges in
-    // the darks (sRGB's linear toe). Alpha is coverage and multiplies unchanged.
+    // Upstream multiplies in linear; here each factor goes back to its byte and the multiply runs
+    // there, as the reference's fixed-function pipeline does.
     let textured = enabled(in.flags, TEXTURED);
     let tint = linear_to_srgb(in.color.rgb);
     let texel = linear_to_srgb(texture_color.rgb);
diff --git a/crates/benilla-app/src/shaders/ui_quad.wgsl b/crates/benilla-app/src/shaders/ui_quad.wgsl
index 8ba8af8e..15055dde 100644
--- a/crates/benilla-app/src/shaders/ui_quad.wgsl
+++ b/crates/benilla-app/src/shaders/ui_quad.wgsl
@@ -1,17 +1,10 @@
-// The player-UI quad material, on the UI gamma composite lane. The reference draws the UI
-// fixed-function into an 8-bit backbuffer, so every UI multiply and blend is arithmetic on gamma
-// bytes: the fragment returns its texel to byte space, tints and premultiplies there, and outputs
-// raw gamma, which the `(One, OneMinusSrcAlpha)` blend composes in gamma, clamped at every write by
-// the 8-bit unorm target:
+// The player-UI quad material. The reference draws the UI fixed-function into an 8-bit
+// backbuffer, so the fragment tints and premultiplies on gamma bytes and outputs raw gamma for the
+// `(One, OneMinusSrcAlpha)` blend; `ui_gamma.wgsl` decodes once. One pipeline, a flag per mode:
 //   BLEND (EGxBlend 2, `SrcAlpha/OneMinusSrcAlpha`): out = (rgb·a, a) ⇒ dst·(1−a) + rgb·a
 //   ADD   (EGxBlend 3, `SrcAlpha/One`):              out = (rgb·a, 0) ⇒ dst      + rgb·a
-// so a per-material flag picks the mode on one pipeline. The frame's one gamma-to-linear decode
-// is `ui_gamma.wgsl`.
-//
-// BLPs load as `Rgba8UnormSrgb`, so the sampler returns a linearized texel and `linear_to_srgb`
-// restores the authored byte (exact in f32). That holds for every texture here, the portrait
-// booth's `Rgba8Unorm` bake (which stores linear bytes) included, except a SKIP_DECODE upload
-// (`gamma_texel`), which already holds the byte and must not be encoded twice.
+// `linear_to_srgb` restores the authored byte of every sampled texel except a SKIP_DECODE upload
+// (`gamma_texel`), which already holds it.
 // Deviation: bilinear filtering runs on the decoded texel, not on the gamma byte the reference
 // filters, because the booth bake stores linear bytes.
 
@@ -31,17 +24,14 @@ struct Vertex {
 }
 
 struct VertexOutput {
-    // Clip position out; in the fragment, the pixel coordinate (physical px) the screen mask uses.
+    // In the fragment, the physical pixel coordinate the screen mask uses.
     @builtin(position) position: vec4<f32>,
     @location(0) uv: vec2<f32>,
 #ifdef VERTEX_COLORS
     @location(1) color: vec4<f32>,
 #endif
-    // The run's colour off the per-instance `MeshTag` (a one-colour run draws white vertices), so a
-    // colour change is a component write, not a mesh or material change. One byte per channel, as
-    // the reference's `CImVector` (`SetVertexColor` quantises `×255 + 0.5` and folds the frame's
-    // alpha in bytes). Stored complemented, so an entity with no `MeshTag` (read as 0) is opaque
-    // white, untinted.
+    // The run's colour from the per-instance `MeshTag`, a byte per channel as the reference's
+    // `CImVector`. Stored complemented, so no `MeshTag` (0) is opaque white.
     @location(2) @interpolate(flat) tint: vec4<f32>,
 }
 
@@ -70,61 +60,47 @@ fn vertex(vertex: Vertex) -> VertexOutput {
 @group(2) @binding(0) var<uniform> additive: u32;
 @group(2) @binding(1) var quad_texture: texture_2d<f32>;
 @group(2) @binding(2) var quad_sampler: sampler;
-// Mask the quad to its inscribed circle in UV space: the unit portrait, whose round alpha stencil
-// the reference stamps into its 64² bake and this cuts at draw time.
+// Mask to the inscribed circle: the unit portrait's round stencil, which the reference stamps into
+// its 64² bake.
 @group(2) @binding(3) var<uniform> circular: u32;
-// The screen-anchored alpha mask (the minimap's `MinimapMask.blp`, DXT3, the circle ramp in its
-// alpha): `mask_rect` is its span in physical framebuffer px (min.xy, max.xy; z <= x disables), so
-// world-anchored tile quads pan under a fixed window; outside the rect is dropped. Sampled at
-// level 0: the sample sits in a branch on per-fragment coordinates, outside the uniform control
-// flow implicit derivatives need.
+// The screen-anchored alpha mask (the minimap's `MinimapMask.blp`): `mask_rect` is its span in
+// physical px (min.xy, max.xy; z <= x disables); outside it is dropped. Sampled at level 0 because
+// the sample sits in non-uniform control flow.
 @group(2) @binding(4) var<uniform> mask_rect: vec4<f32>;
 @group(2) @binding(5) var mask_texture: texture_2d<f32>;
 @group(2) @binding(6) var mask_sampler: sampler;
-// `Texture:SetDesaturated(1)`: the texture object's `+0x128` `CGxShader*` binds
-// `Shaders\Pixel\Desaturate.bls`, whose two working instructions are
+// `Texture:SetDesaturated(1)` binds `Shaders\Pixel\Desaturate.bls` (texture object `+0x128`):
 //     MUL result.color.w   , fragment.color.primary, texel   ; a = vertexColour.a x texel.a
 //     DP3 result.color.xyz , texel, c[0]                     ; rgb = dot(texel.rgb, LUMA)
-// A bound fragment program replaces the fixed-function MODULATE, so the vertex colour's RGB is
-// discarded (the 0.65 of FrameXML's `SetItemButtonDesaturated(button, 1, 0.65, 0.65, 0.65)` has
-// no effect) and only its alpha survives. The dot runs on the gamma byte, after `linear_to_srgb`.
+// It replaces the MODULATE, so the vertex colour's RGB has no effect, only its alpha. The dot runs
+// on the gamma byte.
 @group(2) @binding(7) var<uniform> desaturate: u32;
-// The texture is already premultiplied: only a portrait, paper-doll or dressing-room booth bake
-// (`UiQuad::premultiplied`), whose additive particles add light with no coverage. Every other
-// texture is straight alpha and is premultiplied here.
+// Set only for a booth bake (portrait, paper doll, dressing room), already premultiplied because
+// its additive particles add light with no coverage; every other texture is straight alpha.
 @group(2) @binding(8) var<uniform> premultiplied: u32;
-// Alpha-test reference, <= 0 disables; only the WMO-interior minimap tiles. The reference draws
-// them under EGxBlend 1: blending off and `glAlphaFunc(GL_GEQUAL, 0.87843144)`
-// (`.data 0x85ad20[1]` = 224, times the f32 reciprocal of 255), so a tile fragment is fully opaque
-// or discarded. The tested value is `texel.a × colour.a`, the MODULATE against the vertex dword
-// `(frameAlpha << 24) | 0xFFFFFF`. The screen mask stays out of it: the reference tests each tile
-// into an offscreen and cuts the mask at the blit.
+// Alpha-test reference, <= 0 disables; only the WMO-interior minimap tiles, which the reference
+// draws under EGxBlend 1: no blend, `glAlphaFunc(GL_GEQUAL, 224/255)` (`0x85ad20[1]`) on
+// `texel.a × frameAlpha`. The screen mask stays out: the reference cuts it at the offscreen blit.
 @group(2) @binding(9) var<uniform> alpha_ref: f32;
-// The texture was uploaded undecoded (`BlpVariant::MapTile`'s `GL_SKIP_DECODE_EXT`, the minimap
-// tiles), so the texel is already the authored gamma byte and skips `linear_to_srgb`. The
-// alpha-test arm ignores this flag and decodes explicitly for its un-encoded target.
+// Uploaded undecoded (`BlpVariant::MapTile`, the minimap tiles): the texel is already the gamma
+// byte. The alpha-test arm ignores this and decodes explicitly.
 @group(2) @binding(10) var<uniform> gamma_texel: u32;
-// The UV window this quad may sample, `(u_min, v_min, u_max, v_max)`, inset half a texel by the
-// producer; an axis with `min > max` is unclamped (UVs past `[0,1]`, the backdrop's tiling).
-// `CLAMP_TO_EDGE` clamps at the image edge, not at a `SetTexCoord` crop, so without this a
-// magnified atlas cell's outer pixels filter in the neighbouring cell.
+// The UV window this quad may sample, `(u_min, v_min, u_max, v_max)`, inset half a texel so a
+// magnified atlas cell never filters in its neighbour; `min > max` leaves an axis unclamped.
 @group(2) @binding(11) var<uniform> uv_clamp: vec4<f32>;
 
-// BT.601 luma, `Desaturate.bls`'s `PARAM c[0]` as raw f32 words `0x3E991687`, `0x3F1645A2`,
-// `0x3DE978D5`. Do not normalise them or compute them in f64: they sum to 1.0000000074505806, so
-// white lands just above 1.0 and relies on the output clamp.
+// BT.601 luma, `Desaturate.bls`'s `c[0]` as f32 words `0x3E991687`, `0x3F1645A2`, `0x3DE978D5`.
+// Do not normalise: they sum just above 1.0 and white relies on the output clamp.
 const LUMA: vec3<f32> = vec3<f32>(0.299, 0.587, 0.114);
 
-// Linear to sRGB: the IEC 61966-2-1 curve the hardware's sRGB conversion uses, so this inverts the
-// sampler's decode exactly in f32. Alpha has no gamma and never passes through here.
+// Linear to sRGB (IEC 61966-2-1), the exact inverse of the sampler's decode in f32.
 fn linear_to_srgb(c: vec3<f32>) -> vec3<f32> {
     let higher = 1.055 * pow(max(c, vec3<f32>(0.0)), vec3<f32>(1.0 / 2.4)) - 0.055;
     let lower = c * 12.92;
     return select(higher, lower, c <= vec3<f32>(0.0031308));
 }
 
-// sRGB to linear, for an undecoded texture (the minimap tiles): the hardware filters the authored
-// bytes and the conversion follows the filter, the reference's fixed-function order.
+// sRGB to linear for an undecoded texture: the reference filters the bytes, then converts.
 fn srgb_to_linear(c: vec3<f32>) -> vec3<f32> {
     let higher = pow((max(c, vec3<f32>(0.0)) + 0.055) / 1.055, vec3<f32>(2.4));
     let lower = c / 12.92;
@@ -133,9 +109,8 @@ fn srgb_to_linear(c: vec3<f32>) -> vec3<f32> {
 
 @fragment
 fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
-    // Branchless, so the sample stays in uniform control flow for implicit derivatives. The bounds
-    // are sorted first because `select` evaluates both arms: a disabled (`min > max`) axis must
-    // still hand `clamp` an ordered range.
+    // Branchless, for implicit derivatives. Sorted because `select` evaluates both arms and a
+    // disabled axis must still hand `clamp` an ordered range.
     let lo = min(uv_clamp.xy, uv_clamp.zw);
     let hi = max(uv_clamp.xy, uv_clamp.zw);
     let uv = select(in.uv, clamp(in.uv, lo, hi), uv_clamp.xy <= uv_clamp.zw);
@@ -145,22 +120,17 @@ fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
 #else
     let c = in.tint;
 #endif
-    // Back to the client's byte space, then tint there: `UiQuad.color` is a client-space sRGB value
-    // (FrameXML `<Color>`, `|cff…`, quality colours), so this is the fixed-function gamma-space
-    // `tint × texel`. A SKIP_DECODE texture (`gamma_texel`) is already in byte space.
+    // The tint is a client-space byte value (`<Color>`, `|cff…`), so `tint × texel` runs on bytes.
     let texel = select(linear_to_srgb(t.rgb), t.rgb, gamma_texel != 0u);
-    // Desaturate replaces the modulate: `c.rgb` is unread there, and only `c.a` reaches the alpha.
     var rgb = texel * c.rgb;
     if desaturate != 0u {
         rgb = vec3<f32>(dot(texel, LUMA));
     }
-    // `k` is the coverage the UI imposes: the vertex alpha (`SetAlpha`, the inherited frame alpha)
-    // and the two masks. It stays apart from the texel's own `t.a` because they premultiply
-    // differently: `k` scales a premultiplied source's colour and alpha alike, `t.a` weights the
-    // colour only on a straight source.
+    // `k`, the UI's coverage (frame alpha and masks), stays apart from `t.a`: it scales a
+    // premultiplied source's colour and alpha alike, while `t.a` weights only a straight source.
     var k = c.a;
     if circular != 0u {
-        // A soft edge 2% of the width wide, like the reference's stencil at portrait size.
+        // A soft edge 2% of the width, like the reference's stencil at portrait size.
         k *= 1.0 - smoothstep(0.48, 0.5, distance(in.uv, vec2<f32>(0.5)));
     }
     if mask_rect.z > mask_rect.x {
@@ -169,10 +139,8 @@ fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
         let m = textureSampleLevel(mask_texture, mask_sampler, clamp(muv, vec2<f32>(0.0), vec2<f32>(1.0)), 0.0).a;
         k *= m * inside;
     }
-    // The alpha-test arm (`alpha_ref`): pass is fully opaque, fail draws nothing. It returns the
-    // un-encoded texel, not `rgb`: it draws only into the minimap's 256² composite, an un-encoded
-    // float target whose blit quad takes `linear_to_srgb`, and the composite does no colour
-    // arithmetic, so there is no gamma-space multiply to keep.
+    // Alpha test: returns the linear texel, not `rgb`, because it draws only into the minimap's
+    // linear 256² composite, whose blit encodes.
     if alpha_ref > 0.0 {
         if t.a * c.a < alpha_ref {
             discard;
@@ -180,9 +148,8 @@ fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
         return vec4<f32>(srgb_to_linear(t.rgb) * c.rgb, 1.0);
     }
     let a = t.a * k;
-    // Premultiply in gamma: the hardware `SrcAlpha` factor would weight a linearized colour and
-    // inflate every soft edge and dim additive skirt. A premultiplied source (a booth bake) takes
-    // `k` alone; folding in `t.a` again would zero its additive light over empty pane space.
+    // Premultiply in gamma, not by the hardware `SrcAlpha`. A booth bake takes `k` alone: `t.a`
+    // again would zero its additive light over empty space.
     let weight = select(a, k, premultiplied != 0u);
     if additive != 0u {
         return vec4<f32>(rgb * weight, 0.0);
diff --git a/crates/benilla-app/src/shaders/ui_slice_gamma.wgsl b/crates/benilla-app/src/shaders/ui_slice_gamma.wgsl
index af7d76a3..66c51375 100644
--- a/crates/benilla-app/src/shaders/ui_slice_gamma.wgsl
+++ b/crates/benilla-app/src/shaders/ui_slice_gamma.wgsl
@@ -1,6 +1,6 @@
-// The glue screens' Bevy UI nine-patch and tiled shader on the UI gamma composite lane: every glue
-// `Backdrop` draws through it. Vendored from `bevy_ui_render` 0.18.1 `src/ui_texture_slice.wgsl`,
-// verbatim except `linear_to_srgb` and the final colour; re-diff on every Bevy upgrade.
+// The glue screens' Bevy UI nine-patch shader, which every glue `Backdrop` draws through. Vendored
+// from `bevy_ui_render` 0.18.1 `src/ui_texture_slice.wgsl`, verbatim except `linear_to_srgb` and
+// the final colour; re-diff on every Bevy upgrade.
 
 #import bevy_render::view::View;
 #import bevy_render::globals::Globals;
@@ -135,8 +135,8 @@ fn fragment(in: UiVertexOutput) -> @location(0) vec4<f32> {
     let atlas_uv = in.atlas_rect.xy + uv * (in.atlas_rect.zw - in.atlas_rect.xy);
 
     // ── Changed from upstream ──
-    // Upstream returns `in.color * textureSample(...)`. Both factors go back to gamma bytes before
-    // the multiply, the reference's gamma-space `SetBackdropColor` tint, so the blend is byte math.
+    // Upstream returns `in.color * textureSample(...)`; both factors go back to bytes first, as the
+    // reference's gamma-space `SetBackdropColor` tint.
     let texel = textureSample(sprite_texture, sprite_sampler, atlas_uv);
     return vec4<f32>(
         linear_to_srgb(in.color.rgb) * linear_to_srgb(texel.rgb),
diff --git a/crates/benilla-app/src/shutdown.rs b/crates/benilla-app/src/shutdown.rs
index 028221a1..992042ba 100644
--- a/crates/benilla-app/src/shutdown.rs
+++ b/crates/benilla-app/src/shutdown.rs
@@ -1,90 +1,33 @@
-//! **The application-exit edge** — the one place that says *where* "the client is going down" may
-//! be observed, because getting that wrong is silent and costs the player everything they changed
-//! (decision 1528).
+//! The application-exit edge: where "the client is going down" may be observed.
 //!
-//! ## The frame the app decides to quit is the last frame there is — but it is not always the only one
+//! Bevy's runner leaves the loop after the `app.update()` in which an `AppExit` appears. A window
+//! close writes it in `PostUpdate` (`exit_on_all_closed`), after every `Update` system, so a saver
+//! in `Update` never sees the exit a player causes. [`on_app_exit`] puts savers in `Last`, after
+//! every announcement.
 //!
-//! Bevy's runner checks `App::should_exit()` **after** `app.update()` returns and, if an `AppExit`
-//! is there, leaves the event loop (`bevy_winit::state`, `run_app_update`'s tail). So a system that
-//! wants to run "on the way out" gets its chance in the same `Main` pass in which the exit was
-//! announced — and only if it runs *after* the announcement.
+//! On macOS one more `Main` pass can run after `event_loop.exit()`, and `exit_on_all_closed`
+//! announces again on every frame with no window, so the set runs only on the rising edge
+//! ([`the_exit_frame`]): firing `PLAYER_LEAVING_WORLD` and `PLAYER_LOGOUT` twice would reach every
+//! addon twice.
 //!
-//! What it does **not** get is a guarantee that the pass is the last one (decision 1537). On macOS
-//! `event_loop.exit()` is a request, not a return: events already queued still dispatch, and one
-//! more `about_to_wait` → `run_app_update` can land before the loop unwinds. `exit_on_all_closed`
-//! has no latch of its own — it writes an `AppExit` on **every** frame its window query is empty —
-//! so that extra pass announces the exit a second time and every shutdown system reading
-//! `MessageReader<AppExit>` runs twice. Observed on the real client, in `scripts/smoke.sh`, roughly
-//! one run in three: two `"No windows are open, exiting"` lines 50 ms apart, the second on the far
-//! side of winit's own `"Closing window 0v0"`, with a complete duplicate save burst under each.
-//!
-//! Rewriting the same files twice is harmless; **firing `PLAYER_LEAVING_WORLD`/`PLAYER_LOGOUT`
-//! into every addon's Lua twice is not**. So the set runs on the *edge*: [`the_exit_frame`] opens
-//! on the first frame of a run of announcements and stays shut for the rest of it.
-//!
-//! Announcements do not all arrive early. The one a **player** produces is the latest of all:
-//! clicking the window's close button posts `WindowCloseRequested`, `close_when_requested`
-//! (`Update`) despawns the window, and `exit_on_all_closed` (**`PostUpdate`**) writes the
-//! `AppExit` (`bevy_window`'s own placement, 0.18.1). Every `Update` system has already run by
-//! then. So *"read `MessageReader<AppExit>` in `Update`"* — which is what three of our five
-//! shutdown systems did — cannot see the exit a player actually causes, and no later frame will
-//! give it a second look.
-//!
-//! **Measured, not reasoned**: the real client, in the world, closed by its own window button
-//! wrote *nothing* — no `saved-variables.lua`, no per-addon `saved/*.lua`, no `addons/*.txt`, no
-//! camera pose, no `config.toml`. Every addon's settings and every UI toggle the session changed
-//! were lost, and the next login came up on whatever the last *graceful* exit had written. That is
-//! the director's *"addon settings don't save between logins"* in one line.
-//!
-//! ## The rule
-//!
-//! **Register it here, never by hand.** [`on_app_exit`] puts the system in `Last`, which runs after
-//! `PostUpdate` in the same `Main` pass and therefore after every announcement Bevy can make. Two
-//! systems already lived there and had quietly been right the whole time
-//! (`hover_log::report_on_exit`, `perf::stall::beat` — whose own comment says *"no later frame will
-//! run to unlatch anything"*); this makes that the rule instead of a coincidence.
-//!
-//! ## What this does NOT fix, said out loud
-//!
-//! An exit the process is never told about in ECS terms still loses the session:
-//!
-//! - **macOS `Cmd+Q`** goes `terminate:` → `applicationWillTerminate:` → winit's `LoopExiting`,
-//!   with no `app.update()` anywhere in it — so there is no schedule to run in. Handled a layer
-//!   down instead, by [`benilla_world::mac_quit`], which re-points that menu item at
-//!   `performClose:` so the gesture becomes the window close above.
-//! - **A crash, a `SIGKILL`, a wedged teardown.** Nothing survives those, and the reference client
-//!   loses settings to them too (decision 1128 kept its no-autosave shape deliberately). If we ever
-//!   want to beat that, it is an autosave design and its own decision — not a fourth place to read
-//!   `AppExit`.
+//! Not covered: macOS `Cmd+Q` runs no `app.update()` and is re-pointed at `performClose:` by
+//! [`benilla_world::mac_quit`]; a crash or `SIGKILL` loses the session, as in the reference, which
+//! has no autosave.
 
 use bevy::ecs::schedule::ScheduleConfigs;
 use bevy::ecs::system::ScheduleSystem;
 use bevy::prelude::*;
 
-/// Every system that persists state as the client goes down. A set rather than bare `Last`
-/// registrations so the ordering question ("does the CVar flush see the VM the UI teardown just
-/// replaced?") has somewhere to be answered when it comes up.
+/// Every system that persists state as the client goes down.
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub(crate) struct OnAppExit;
 
-/// Marks the one-time `configure_sets` below as done — [`on_app_exit`] is called once per shutdown
-/// system, and the set's edge condition must be attached exactly once however many of them there are.
+/// The set's edge condition is attached once, however many savers register.
 #[derive(Resource)]
 struct ExitSetLatched;
 
-/// **The rising edge of "the app is exiting"** — true on the first frame of a run of `AppExit`
-/// announcements, false for every frame the run continues (decision 1537).
-///
-/// An *edge*, not a once-per-process latch, because that is what the tail is for and because the
-/// two are not the same thing. `exit_on_all_closed` re-announces on every frame its window query is
-/// empty, so the extra `Main` pass macOS can pump after `event_loop.exit()` produces a second,
-/// immediately-consecutive announcement — suppressed here. A *later* announcement with a quiet
-/// frame in between is a different shutdown, and is served: that is how a harness drives more than
-/// one exit through one `App`, which `cvars`' persistence test does.
-///
-/// A run condition on the set rather than a latch inside each shutdown system, because the systems
-/// are registered from eight different modules and "has this edge already been served" is a
-/// property of the edge, not of any one saver.
+/// True on the first frame of a run of `AppExit` announcements. An edge, not a once-per-process
+/// latch: an exit after a quiet frame is a new shutdown, as a test harness drives.
 fn the_exit_frame(mut exits: MessageReader<AppExit>, mut announced: Local<bool>) -> bool {
     let now = exits.read().next().is_some();
     let rising = now && !*announced;
@@ -92,11 +35,8 @@ fn the_exit_frame(mut exits: MessageReader<AppExit>, mut announced: Local<bool>)
     rising
 }
 
-/// Register a system that must run on the frame the app decides to exit.
-///
-/// The schedule is not the caller's choice — that is the whole point of the function existing (see
-/// the module header). Call it with a system that reads `MessageReader<AppExit>` and does its work
-/// when the read is non-empty; the set's own edge condition guarantees it is asked once per exit.
+/// Registers a system to run once on the frame the app decides to exit; it reads
+/// `MessageReader<AppExit>` and works when the read is non-empty.
 pub(crate) fn on_app_exit(app: &mut App, systems: ScheduleConfigs<ScheduleSystem>) -> &mut App {
     if !app.world().contains_resource::<ExitSetLatched>() {
         app.insert_resource(ExitSetLatched);
@@ -110,8 +50,7 @@ mod tests {
     use super::*;
     use bevy::window::{PrimaryWindow, Window, WindowCloseRequested, WindowPlugin};
 
-    /// How many frames the probe ran on. A resource rather than a `Local` so the test can read it
-    /// back — and a count rather than a flag, because "ran twice" is one of the things under test.
+    /// How many frames the probe ran on.
     #[derive(Resource, Default)]
     struct Saw(u32);
 
@@ -121,18 +60,13 @@ mod tests {
         }
     }
 
-    /// `bevy_window`'s close takes **two** frames — `close_when_requested` marks the window
-    /// `ClosingWindow` on the frame the request arrives and despawns it on the next, and only then
-    /// does `exit_on_all_closed` find no windows. Both are driven here so the test measures the
-    /// real sequence rather than a shortened one.
+    /// `bevy_window`'s close takes two frames: mark `ClosingWindow`, then despawn.
     fn close_and_exit(app: &mut App) {
         app.update();
         app.update();
     }
 
-    /// An app with `bevy_window`'s real close→exit systems and one window, plus a probe registered
-    /// by `place`. No winit: `close_when_requested` and `exit_on_all_closed` are plain systems and
-    /// they are the two that decide when the `AppExit` lands.
+    /// `bevy_window`'s real close and exit systems, one window, and a probe placed by `place`.
     fn app_with_probe(place: fn(&mut App)) -> App {
         let mut app = App::new();
         app.add_plugins(WindowPlugin {
@@ -150,9 +84,6 @@ mod tests {
         app
     }
 
-    /// **The director's bug, reproduced.** A player closes the window; a shutdown system in
-    /// `Update` never learns the client is exiting, because the `AppExit` is not written until
-    /// `PostUpdate` — and the runner leaves the loop before another frame starts.
     #[test]
     fn an_update_system_never_sees_the_exit_a_window_close_produces() {
         let mut app = app_with_probe(|app| {
@@ -171,8 +102,6 @@ mod tests {
         );
     }
 
-    /// …and the fix, at the same edge: [`on_app_exit`] places it in `Last`, after `PostUpdate`,
-    /// so the same close is observed on the frame it happens.
     #[test]
     fn on_app_exit_sees_the_exit_a_window_close_produces() {
         let mut app = app_with_probe(|app| {
@@ -187,10 +116,7 @@ mod tests {
         );
     }
 
-    /// The other four roots announce from `Update` (a `/quit` from Lua, the logout-complete edge,
-    /// the capture harness). `Last` is after those too, so one placement covers every announcement
-    /// rather than winning a scheduler lottery — which is what the old `Update` placement was doing
-    /// on the paths where it happened to work.
+    /// A `/quit`, the logout edge and the capture harness announce from `Update`.
     #[test]
     fn on_app_exit_also_sees_an_exit_announced_from_update() {
         let mut app = App::new();
@@ -204,13 +130,7 @@ mod tests {
         assert_eq!(app.world().resource::<Saw>().0, 1);
     }
 
-    /// **The exit can be announced twice, and the tail must still run once** (1537).
-    ///
-    /// `exit_on_all_closed` has no latch: with the window gone it writes an `AppExit` on every
-    /// frame it runs. macOS pumps one more `Main` pass after `event_loop.exit()` often enough to
-    /// fail `scripts/smoke.sh` about one run in three — and a second pass means a second
-    /// `PLAYER_LOGOUT` into every addon's Lua, not merely a second identical file write. Driven
-    /// here by running past the exit frame, which is exactly what that extra pass is.
+    /// Running past the exit frame is the extra pass macOS can pump.
     #[test]
     fn a_second_announcement_does_not_run_the_tail_again() {
         let mut app = app_with_probe(|app| {
@@ -237,9 +157,6 @@ mod tests {
         );
     }
 
-    /// …and an edge is not a once-per-process latch. A harness that drives an exit, carries on, and
-    /// drives another gets both — which is how `cvars`' persistence test writes `config.toml` twice
-    /// through one `App`, and the reason [`the_exit_frame`] detects an edge rather than spending.
     #[test]
     fn a_later_exit_after_a_quiet_frame_is_a_new_edge() {
         let mut app = App::new();
@@ -248,7 +165,7 @@ mod tests {
 
         app.world_mut().write_message(AppExit::Success);
         app.update();
-        app.update(); // quiet — nothing announced, so the edge re-arms
+        app.update(); // quiet: the edge re-arms
         app.world_mut().write_message(AppExit::Success);
         app.update();
 
diff --git a/crates/benilla-app/src/smart_rect.rs b/crates/benilla-app/src/smart_rect.rs
index 0fc1359d..5e3e7a71 100644
--- a/crates/benilla-app/src/smart_rect.rs
+++ b/crates/benilla-app/src/smart_rect.rs
@@ -1,50 +1,30 @@
-//! **SmartScreenRect** — the client's shared draw-time anti-overlap placement solver
-//! (`UIUtil\SmartScreenRect`). Every frame each participant submits its desired screen rect; the
-//! solver relocates it off the rects already claimed **this frame in its own bucket** and then
-//! claims the result, so later rects dodge earlier ones. Exactly two buckets exist in 5875 and
-//! they never interact: **nameplates (bucket 0)** and **combat worldtext (bucket 1)** — a plate
-//! never pushes a number. This is the mechanism behind the reference's whole non-overlap feel:
-//! plates bounce off each other, a late number shoves the earlier one upward, crits (whose
-//! measured half-extents balloon with the scale pop) both push and get pushed harder, and a
-//! pushed rect **snaps back** the frame its blocker expires because the desire is re-derived
-//! from the anchor every frame — the solver keeps no cross-frame state at all.
+//! SmartScreenRect, the client's per-frame anti-overlap placement solver
+//! (`UIUtil\SmartScreenRect`). Each rect is relocated off the rects already claimed this frame in
+//! its bucket, then claimed. 5875 has two buckets that never interact: nameplates (0) and combat
+//! worldtext (1). No state crosses frames, so a pushed rect snaps back when its blocker goes.
 //!
-//! The law, transcribed to our Y-DOWN logical-pixel viewport (the ref computes in the Y-UP gx
-//! device space `[0,G44]×[0,G48]`; every clamp below is bound-symmetric, so the mirror is exact):
-//! - **Solve** (`0x5097a0`): bounded FIFO/BFS. Seed = the input rect band-clamped on-screen
-//!   (`0x509bf0` mode 0); its region (3×3, `0x509d80`) picks a 4-try push-direction order
-//!   ([`ORDER`], `.rdata 0x8087e0`) fixed for the whole solve. Each dequeued node tries the 4
-//!   directions in region order: a push against the **first** strictly-overlapping claimed rect
-//!   (`0x509220`, zero padding — touching edges do not overlap) lands the node **edge-to-edge**
-//!   with the blocker (`0x5091c0/0x509300/0x509360/0x5093c0`); an *unmoved* try means the spot
-//!   is free — **adopt immediately**; a moved rect is enqueued for re-checking against the whole
-//!   bucket. Dequeues are capped at `(⌊W/w⌋+1)·(⌊H/h⌋+1)` (`0x509dd0`); exhaustion returns the
-//!   input unmodified — an unplaceable rect draws overlapping at its anchor, never hides.
-//! - **Seat tail** (shared by both seats `0x509520`/`0x509ec0`): clamp the solved rect's center-X
-//!   to `[halfW, W−halfW]` and its physical-TOP edge to `[halfH, H−halfH]`, rebuild top-anchored,
-//!   re-normalize on-screen (`0x509e20`), then **claim** (`0x509660`).
-//! - The node-strategy skip at `0x509874` is dead in 5875 (`+0x18` is never written past the
-//!   ctor's `-1`) and the `showsmartrects` CVar has no readers — the solver is unconditionally
-//!   live and every node tries all four directions. Both are replicated by simply not porting
-//!   them.
+//! Our viewport is Y-down logical pixels; the reference's gx device space is Y-up, and every clamp
+//! is symmetric, so the mirror is exact.
+//! - Solve (`0x5097a0`), a bounded BFS: the seed is the input clamped to the bands (`0x509bf0`
+//!   mode 0), whose region (`0x509d80`) fixes the four-direction [`ORDER`]. A push against the
+//!   first strictly overlapping claimed rect (`0x509220`) lands edge-to-edge; an unmoved try is
+//!   adopted at once, a moved one is queued. Dequeues are capped at
+//!   `(floor(W/w)+1)(floor(H/h)+1)` (`0x509dd0`); exhaustion returns the input, drawn overlapping.
+//! - Seat tail (`0x509520`, `0x509ec0`): clamp center-X and the top edge half-extent inside,
+//!   rebuild top-anchored, normalize (`0x509e20`), claim (`0x509660`).
+//! - The node-strategy skip at `0x509874` is dead in 5875 and `showsmartrects` has no readers, so
+//!   neither is ported.
 
 use std::collections::VecDeque;
 
 use bevy::math::{Rect, Vec2};
 
-/// The near-TOP band, gx device units (`.rdata [0x8087cc]` = 0.0375): a rect whose physical top
-/// edge is within `0.0375 × diagonal` px of the screen top is "near top" (region bit 2) and its
-/// push order avoids UP. One gx unit = the screen diagonal (`√(W²+H²)` px).
+/// The near-top band (`[0x8087cc]`), in gx units, where one unit is the screen diagonal.
 const DDC_NEAR_TOP: f32 = 0.0375;
-/// The near-BOTTOM band (`.rdata [0x8087d0]` = 0.01875): within `0.01875 × diagonal` px of the
-/// screen bottom (region bit 3) the order avoids DOWN. The X "bands" are the literal screen
-/// edges (`[0x8087d4]/[0x8087d8]` = 0.0) — bits 0/1 fire only when the rect is partly off-screen.
+/// The near-bottom band (`[0x8087d0]`); the X bands (`[0x8087d4]`, `[0x8087d8]`) are 0.0.
 const DDC_NEAR_BOTTOM: f32 = 0.01875;
 
-/// The 9-region × 4-try push-direction order (`.rdata 0x8087e0`), strategy ids 0=UP 1=LEFT
-/// 2=RIGHT 3=DOWN (the `0x808870` table slots, physical Y-UP directions). Every region avoids
-/// pushing further off its violated edge; the center region tries UP first — the reference's
-/// signature "the number jumps up".
+/// The push order per region (`0x8087e0`): 0 up, 1 left, 2 right, 3 down (`0x808870` slots).
 const ORDER: [[u8; 4]; 9] = [
     [0, 2, 3, 1], // 0 center:                UP RIGHT DOWN LEFT
     [1, 0, 2, 0], // 1 near bottom:           LEFT UP RIGHT UP
@@ -54,34 +34,27 @@ const ORDER: [[u8; 4]; 9] = [
     [0, 1, 0, 1], // 5 off right + near bottom
     [0, 2, 0, 2], // 6 off left  + near bottom
     [3, 1, 3, 1], // 7 off right + near top
-    [3, 2, 3, 2], // 8 off left  + near top, and the catch-all
+    [3, 2, 3, 2], // 8 off left  + near top
 ];
 
-/// One claim bucket: the screen rects already placed this frame, in seat order. Each producer
-/// owns its bucket (`Local`), clears it at the top of its frame pass ([`Self::clear`] =
-/// `0x509500`), and seats through [`Self::resolve`] + [`Self::claim`]. Seat order is priority:
-/// the first-claimed rect never moves, later ones push off it.
+/// One claim bucket, the rects placed this frame; the first claimed never moves.
 #[derive(Default)]
 pub(crate) struct SmartBucket(Vec<Rect>);
 
 impl SmartBucket {
-    /// The per-frame reset (`0x509500`): count to zero, capacity kept.
+    /// The per-frame reset (`0x509500`).
     pub(crate) fn clear(&mut self) {
         self.0.clear();
     }
 
-    /// The shared seat law minus the claim: normalize on-screen → solve → clamp the resolved
-    /// (center-X, top-edge) → rebuild top-anchored → normalize. Callers [`Self::claim`] the
-    /// result (the plate seat snaps to whole pixels in between — a recorded benilla divergence,
-    /// not ref law).
+    /// The seat without the claim. Deviation: the plate caller snaps the result to device
+    /// pixels before [`Self::claim`], so its border art blits 1:1.
     pub(crate) fn resolve(&self, desired: Rect, viewport: Vec2) -> Rect {
         let (w, h) = (desired.width(), desired.height());
         let (half_w, half_h) = (w * 0.5, h * 0.5);
         let input = normalize(desired, viewport);
         let solved = self.solve(input, viewport);
-        // The resolve wrapper's output pair (`0x509720`): resolved center-X + resolved physical
-        // TOP edge (Y-down: min.y), each clamped half-extent inside (`max()` keeps an
-        // over-wide rect centered instead of NaN-flipping the clamp bounds).
+        // `0x509720`'s center-X and top edge; `max()` keeps an over-wide rect's bounds ordered.
         let cx =
             ((solved.min.x + solved.max.x) * 0.5).clamp(half_w, (viewport.x - half_w).max(half_w));
         let top = solved
@@ -91,45 +64,41 @@ impl SmartBucket {
         normalize(Rect::new(cx - half_w, top, cx + half_w, top + h), viewport)
     }
 
-    /// Append to the bucket (`0x509660`) — subsequent rects this frame dodge it.
+    /// `0x509660`.
     pub(crate) fn claim(&mut self, rect: Rect) {
         self.0.push(rect);
     }
 
-    /// The bounded-BFS relocation core (`0x5097a0`). Returns the first collision-free placement
-    /// in region-preference order, or `input` unchanged when the bound exhausts.
+    /// The bounded BFS (`0x5097a0`).
     fn solve(&self, input: Rect, viewport: Vec2) -> Rect {
         let (seed, flags) = clamp_to_bands(input, viewport);
         let region = region_index(flags);
-        // `0x509dd0`: how many rects of this size tile the screen — the dequeue cap. A
-        // degenerate size saturates the cast; such a rect never strictly overlaps and adopts
-        // on its first try.
+        // `0x509dd0`. A degenerate size saturates, but never overlaps, so adopts at once.
         let bound = ((viewport.x / input.width()).trunc() as i64 + 1)
             .saturating_mul((viewport.y / input.height()).trunc() as i64 + 1);
         let mut queue = VecDeque::from([seed]);
         for _ in 0..bound {
             let Some(node) = queue.pop_front() else {
-                return input; // worklist dry (every branch went off-screen) — keep the anchor
+                return input; // every branch went off-screen
             };
-            // The per-try off-screen skip (`0x509bf0` mode≠0) tests the NODE's rect, which is
-            // constant across its four tries — hoisted to one test per node.
+            // The per-try skip (`0x509bf0` mode 1) tests the node, so it is hoisted.
             if band_flags(node, viewport) != 0 {
                 continue;
             }
             for strategy in ORDER[region as usize] {
                 let candidate = push(&self.0, node, strategy);
                 if candidate == node {
-                    return candidate; // unmoved = overlaps nothing — adopt
+                    return candidate; // unmoved: overlaps nothing
                 }
                 queue.push_back(candidate);
             }
         }
-        input // bound exhausted — draw overlapping at the anchor
+        input
     }
 }
 
-/// The hard on-screen clamp (`0x509e20`): size-preserving translate, per-edge, the ref's
-/// physical order bottom → top → left → right (so an oversize rect pins at the top / right).
+/// The on-screen clamp (`0x509e20`), physical bottom, top, left, right, so an oversize rect pins
+/// top and right.
 fn normalize(r: Rect, viewport: Vec2) -> Rect {
     let mut r = r;
     if r.max.y > viewport.y {
@@ -155,9 +124,7 @@ fn normalize(r: Rect, viewport: Vec2) -> Rect {
     r
 }
 
-/// The region-flag word (`0x509bf0`), Y-down: bit0 off LEFT edge, bit1 off RIGHT edge, bit2
-/// physical top edge inside the near-TOP band, bit3 physical bottom edge inside the near-BOTTOM
-/// band. Bands scale with the screen diagonal (gx device units).
+/// The region flags (`0x509bf0`): bit 0 off left, 1 off right, 2 near top, 3 near bottom.
 fn band_flags(r: Rect, viewport: Vec2) -> u8 {
     let diag = viewport.length();
     let mut flags = 0;
@@ -176,24 +143,11 @@ fn band_flags(r: Rect, viewport: Vec2) -> u8 {
     flags
 }
 
-/// `0x509bf0` mode 0: the flags PLUS a size-preserving clamp of each offending edge back to its
-/// band boundary (X to the screen edge, Y to the band edge) — the solve's seed rect.
+/// `0x509bf0` mode 0: the flags and the seed, each offending edge clamped to its band.
 ///
-/// **The offending edge is ASSIGNED the boundary and its opposite derived from the size** — the
-/// law's own spelling (`bit2 → top = Y_hi; bottom = Y_hi − height`), and not the equivalent
-/// translate-by-the-gap this shipped with, because the two are not equivalent in `f32` and the
-/// difference is a whole plate jumping 19 px for one frame (decision 2172).
-///
-/// The seed this returns is immediately re-tested by [`band_flags`] inside [`SmartBucket::solve`]
-/// (the per-node skip, `0x509bf0` mode 1), and the boundary test is a strict `<`/`>`, so a seed
-/// sitting EXACTLY on the boundary passes. `r.min.y + (band - r.min.y)` does not land exactly on
-/// `band`: for most inputs it does, and for the ones where the subtraction loses a bit it lands
-/// one ULP below — the seed then re-fires its own flag, every try is skipped, the worklist empties
-/// and the solve returns the UNCLAMPED input, which the seat tail clamps to half a plate from the
-/// screen top instead. Measured on a Goldshire walk (the `vpl` trace): a plate riding the near-top
-/// band at 27.54 px dropped to 9.0 for exactly one frame and came back, three times in ten
-/// seconds — at `scr.y = 8.064` and nowhere either side of it, which is the signature of a
-/// rounding tie rather than of any law.
+/// The edge is assigned the boundary and its opposite derived from the size, as the reference
+/// does: translating by the gap can land one ULP short in `f32`, the seed then fails the strict
+/// re-test in [`SmartBucket::solve`], and the plate pops to the seat clamp for a frame.
 fn clamp_to_bands(r: Rect, viewport: Vec2) -> (Rect, u8) {
     let diag = viewport.length();
     let flags = band_flags(r, viewport);
@@ -218,12 +172,8 @@ fn clamp_to_bands(r: Rect, viewport: Vec2) -> (Rect, u8) {
     (r, flags)
 }
 
-/// The 3×3 region index — the exact `0x509d80` decision tree, byte-read for all 16 flag words
-/// (the degenerate multi-flag combos included; region 8 is not a catch-all): **bit0
-/// (off left) dominates and ignores bit1 beneath it;
-/// bit2 (near top) is next and ignores bit3 beneath it; then bit1; then bit3.** So off-both-X
-/// (flags 3) is region 4, spanning-both-bands (flags 12) is region 2 — never reachable by a
-/// plate or a number, but exact.
+/// The 3x3 region (`0x509d80`), for all 16 flag words: bit 0 dominates and ignores bit 1, then
+/// bit 2 ignoring bit 3, then bit 1, then bit 3.
 fn region_index(flags: u8) -> u8 {
     if flags & 1 != 0 {
         if flags & 4 != 0 {
@@ -252,10 +202,8 @@ fn region_index(flags: u8) -> u8 {
     }
 }
 
-/// One strategy try (`0x808870[strategy]` → `0x509220(dir)` + the axis-pair shift): scan the
-/// claimed rects in seat order; against the FIRST strict overlap, translate the node edge-to-edge
-/// past the blocker in the strategy's direction (0=UP 1=LEFT 2=RIGHT 3=DOWN, physical). No
-/// overlap → the node comes back unchanged (the adopt signal).
+/// One try (`0x808870`, `0x509220`): push edge-to-edge off the first strict overlap
+/// (`0x5091c0`, `0x509300`, `0x509360`, `0x5093c0`), or return the node unchanged.
 fn push(claimed: &[Rect], r: Rect, strategy: u8) -> Rect {
     let Some(c) = claimed
         .iter()
@@ -266,7 +214,7 @@ fn push(claimed: &[Rect], r: Rect, strategy: u8) -> Rect {
     let mut r = r;
     match strategy {
         0 => {
-            // UP: physical bottom (max.y) lands on the blocker's physical top (min.y).
+            // Up.
             let d = r.max.y - c.min.y;
             r.min.y -= d;
             r.max.y -= d;
@@ -282,7 +230,7 @@ fn push(claimed: &[Rect], r: Rect, strategy: u8) -> Rect {
             r.max.x += d;
         }
         _ => {
-            // DOWN: physical top (min.y) lands on the blocker's physical bottom (max.y).
+            // Down.
             let d = c.max.y - r.min.y;
             r.min.y += d;
             r.max.y += d;
@@ -303,18 +251,7 @@ mod tests {
         r
     }
 
-    /// **A plate riding the near-top band seats at the band edge, at EVERY approach height.**
-    ///
-    /// The seed clamp puts an offending edge on its band boundary and the per-node skip then
-    /// re-tests that same rect against the same boundary with a strict compare, so the clamp has
-    /// to land ON it, exactly. Translating by the gap instead lands one ULP below for some inputs;
-    /// the seed then skips itself, the worklist empties, `solve` returns the UNCLAMPED input and
-    /// the seat tail parks it half a plate from the screen top — 19 px above where the previous
-    /// frame drew it, for one frame, and back.
-    ///
-    /// The walk is the live one that found it: a 73×18 plate at the probe's 640×360 viewport,
-    /// approaching the band from above a tenth of a pixel at a time. `scr.y = 8.064` is the value
-    /// that popped on the director's screen; the sweep is here so the next such value cannot.
+    /// A 73x18 plate at 640x360 swept toward the band: the seed clamp must land exactly on it.
     #[test]
     fn a_plate_in_the_near_top_band_never_pops_to_the_seat_clamp() {
         const VP2: Vec2 = Vec2::new(640.0, 360.0);
@@ -334,7 +271,6 @@ mod tests {
         }
     }
 
-    /// A free rect adopts unmoved on its first try — the every-frame fast path.
     #[test]
     fn free_rect_stays_put() {
         let mut b = SmartBucket::default();
@@ -342,8 +278,6 @@ mod tests {
         assert_eq!(seat(&mut b, r), r);
     }
 
-    /// Center region: the second of two identical rects is pushed UP (Y-down: smaller y),
-    /// landing edge-to-edge — bottom on the first one's top, zero gap.
     #[test]
     fn center_pushes_up_abutting() {
         let mut b = SmartBucket::default();
@@ -355,9 +289,7 @@ mod tests {
         assert_eq!((pushed.min.x, pushed.max.x), (500.0, 540.0), "x untouched");
     }
 
-    /// A third co-anchored rect goes SIDEWAYS, not twice-up: BFS explores the seed's children
-    /// in region order (UP first), but the UP child still overlaps the second rect while the
-    /// RIGHT child is free — fewest-pushes wins, the reference's "side, up, all sorts".
+    /// The up child still overlaps the second rect while the right child is free.
     #[test]
     fn third_goes_right_not_twice_up() {
         let mut b = SmartBucket::default();
@@ -369,11 +301,10 @@ mod tests {
         assert_eq!((third.min.y, third.max.y), (380.0, 400.0), "one push only");
     }
 
-    /// Near the top of the screen (region 2) UP is avoided: the first try is LEFT.
     #[test]
     fn near_top_pushes_left() {
         let mut b = SmartBucket::default();
-        // Top band at 1024×768: 0.0375 × 1280 = 48 px — a rect whose top edge is above y=48.
+        // The band at 1024x768 is 0.0375 x 1280 = 48 px.
         let r = Rect::new(500.0, 10.0, 540.0, 30.0);
         let first = seat(&mut b, r);
         let pushed = seat(&mut b, r);
@@ -388,8 +319,6 @@ mod tests {
         );
     }
 
-    /// The seed band-clamp (`0x509bf0` mode 0): a rect inside the near-top band is pulled down
-    /// to the band edge before solving, and its region (from the PRE-clamp flags) still avoids UP.
     #[test]
     fn seed_clamps_to_band() {
         let b = SmartBucket::default();
@@ -398,21 +327,16 @@ mod tests {
         assert_eq!(seated.min.y, 48.0, "top edge on the 0.0375·diag band");
     }
 
-    /// Two overlapping full-screen rects exhaust the bound and the second returns at its anchor
-    /// (unplaceable draws overlapping, never hides).
     #[test]
     fn exhaustion_keeps_original() {
         let mut b = SmartBucket::default();
         let r = Rect::new(0.0, 0.0, 1024.0, 768.0);
         seat(&mut b, r);
-        // Every push lands fully off-screen; the off-screen node skip dries the worklist.
         let second = b.resolve(r, VP);
         assert_eq!(second.width(), 1024.0);
         assert_eq!(second.height(), 768.0);
     }
 
-    /// The blocker-expiry snap-back: the solver is stateless across frames, so the same desire
-    /// against an empty bucket lands at the anchor again.
     #[test]
     fn snaps_back_when_blocker_gone() {
         let mut b = SmartBucket::default();
@@ -423,8 +347,7 @@ mod tests {
         assert_eq!(seat(&mut b, r), r, "back at the anchor next frame");
     }
 
-    /// The full 16-word `0x509d80` tree — every combination, byte-derived (not just 9 rows, one
-    /// per region).
+    /// All 16 flag words of `0x509d80`.
     #[test]
     fn region_index_table() {
         let expected = [0, 4, 3, 4, 2, 8, 7, 8, 1, 6, 5, 6, 2, 8, 7, 8];
@@ -433,7 +356,6 @@ mod tests {
         }
     }
 
-    /// Strict overlap: touching edges do NOT collide (zero padding).
     #[test]
     fn touching_edges_do_not_overlap() {
         let mut b = SmartBucket::default();
diff --git a/crates/benilla-app/src/swing_refusal.rs b/crates/benilla-app/src/swing_refusal.rs
index 3681eb47..a2f32bc8 100644
--- a/crates/benilla-app/src/swing_refusal.rs
+++ b/crates/benilla-app/src/swing_refusal.rs
@@ -1,23 +1,18 @@
-//! **The melee swing refusal** — what the client does with the server's answers to a
+//! The melee swing refusal: what the client does with the server's answers to a
 //! `CMSG_ATTACKSWING` it will not honour.
 //!
-//! **Six opcodes, FOUR arms.** `0x145` NOTINRANGE and `0x146` BADFACING take one each; `0x148`
-//! DEADTARGET and `0x149` CANT_ATTACK share arm 4 verbatim; `0x147` NOTSTANDING is never wired at
-//! all; and `0x14e` `SMSG_CANCEL_COMBAT` — the forced cancel, registered by the *spell* TU
-//! (`0x5e3308` → handler `0x5e7dd0`), which is why `0x625520`'s eight-opcode census never names it
-//! — is arm 4's body **byte-identical**, down to the `__LINE__` it pushes. So the whole family is
-//! two arms that latch a message and two that silently stop the attack.
+//! Six opcodes, four arms: `0x145` NOTINRANGE and `0x146` BADFACING latch a message; `0x148`
+//! DEADTARGET, `0x149` CANT_ATTACK and `0x14e` `SMSG_CANCEL_COMBAT` (handler `0x5e7dd0`, whose
+//! body is arm 4's byte for byte) stop the attack silently; `0x147` NOTSTANDING is never
+//! registered, and vmangos never sends it.
 //!
-//! The server refuses a swing on the **edge** alone (vmangos `Unit::AttackerStateUpdate`'s
-//! `swingError` switch, `Objects/Unit.cpp:405-475`: each arm sends only when
-//! `GetLastSwingErrorMsg() != <result>`), so a player standing out of range gets **one** packet,
-//! not one per swing timer. The repeat the player actually sees is the client's own, and it is a
-//! **latch plus a cooldown**, never a per-packet toast:
+//! The server sends a refusal only on its edge (vmangos `Unit.cpp:406-472`), so the repeat the
+//! player sees is the client's own latch and cooldown:
 //!
 //! ```text
 //! 0x625a8a  (0x145 NOTINRANGE)  ecx = 1 ; call 0x5ecdb0     ; latch code 1
 //! 0x625aa1  (0x146 BADFACING)   ecx = 2 ; call 0x5ecdb0     ; latch code 2
-//! 0x625ab8  (0x148 DEADTARGET / 0x149 CANT_ATTACK)          ; NO message — StopAttack, nothing else
+//! 0x625ab8  (0x148 DEADTARGET / 0x149 CANT_ATTACK)          ; no message, StopAttack only
 //!
 //! 0x5ecdb0  [0xc4d758] = code ; [0xc4c270] = OsGetAsyncTimeMs()    ; the code + "show at"
 //!
@@ -29,42 +24,12 @@
 //!             [0xc4c270] = now + 0xfa0                                  ; re-arm, 4000 ms
 //! ```
 //!
-//! Three consequences, all of them visible, none of them guessable from the packet alone:
-//!
-//! 1. **The first line is immediate** — the latch writes `now`, and the tick's test is
-//!    `now - stored >= 0`, so the very next tick shows it.
-//! 2. **It repeats every 4 s while the refusal stands**, because nothing about the *packet*
-//!    drives the display; the latch does, and it survives until something clears it.
-//! 3. **A dead or unattackable target says nothing at all.** `0x148` and `0x149` share arm 4
-//!    verbatim — the client cannot even tell them apart — and that arm raises no message on any
-//!    surface: it resolves the active player and calls StopAttack
-//!    ([`crate::creature_anim::stop_attack_local`]) on it. Which is right: the target is dead or
-//!    friendly, the attack ends, and the reason is already on screen from elsewhere.
-//!
-//! **What clears the latch is a landed swing.** `SMSG_ATTACKERSTATEUPDATE`'s arm calls `0x5ea800`
-//! (at `0x6259b6`) when the attacker **is the active player** (`0x5fa6d0`, a guid compare against
-//! `0x468550`) and the **victim resolves** as a streamed unit — and `0x5ea800`'s first act, ahead
-//! of everything else it does, is `0x5ecdb0(0)`. So the moment a swing connects the stale "too far
-//! away" stops repeating; while none does, it keeps saying so. `0x5e2510`, a module init, clears
-//! it the same way.
-//!
-//! Both edges ride ONE message ([`SwingRefusalEdge`]) written by two arms of the same net drain,
-//! so they are consumed in **packet order** — the reference processes them in one synchronous
-//! dispatch, and a refusal and a landing that arrive in the same frame must not be reordered.
-//!
-//! Two consequences of the latch being written **unconditionally** — both reproduced here, both
-//! easy to lose in a refactor:
-//!
-//! - a **second** refusal packet resets the deadline to `now`, so it **defeats the 4 s cooldown**
-//!   and re-shows on the next tick; a NOTINRANGE→BADFACING flip shows at once for the same reason;
-//! - the **re-arm precedes the print** (`0x5ec9bc` then `0x5ec9c2`), so the 4 s advance happens
-//!   even when the line is then swallowed by a missing GlobalString.
-//!
-//! `SMSG_ATTACKSWING_NOTSTANDING` (`0x147`) is in neither this module nor
-//! [`benilla_protocol::messages::opcode`]: the reference never registers it, and vmangos never
-//! sends it (`Player::SendAttackSwingNotStanding` has zero callers).
-//!
-//! Decision 2037.
+//! So the first line shows on the next tick and repeats every 4 s while the latch stands. A
+//! landed swing clears it: `SMSG_ATTACKERSTATEUPDATE`'s arm calls `0x5ea800` (at `0x6259b6`) when
+//! the attacker is the active player and the victim resolves, and its first act is `0x5ecdb0(0)`.
+//! A second refusal rewrites the deadline to now, defeating the cooldown, and the re-arm precedes
+//! the print (`0x5ec9bc`, `0x5ec9c2`), so it happens even when the string is missing. Both edges
+//! ride one message ([`SwingRefusalEdge`]) so they are consumed in packet order.
 
 use std::time::Duration;
 
@@ -75,69 +40,40 @@ use crate::creature_anim::{AttackSeam, Engaged};
 use crate::net::SelfPlayer;
 use crate::ui_action::{UiError, UiErrorKeys};
 
-/// The reference's re-arm interval — `0x5ec9b6 add ecx,0xfa0`.
+/// The reference's re-arm interval (`0x5ec9b6`).
 const REPEAT: Duration = Duration::from_millis(0xfa0);
 
-/// One edge of the swing-refusal seam, off the net drain in **packet order** — see the module
-/// header for why they share a message rather than taking one each.
+/// One edge of the swing-refusal seam, off the net drain in packet order.
 #[derive(Message, Clone, Copy, Debug)]
 pub(crate) enum SwingRefusalEdge {
     /// The server refused our swing (`0x145`/`0x146`/`0x148`/`0x149`).
     Refused(AttackSwingError),
-    /// `SMSG_CANCEL_COMBAT` (`0x14e`) — the server forced our attack to stop
-    /// (`Unit::CombatStop`, `Unit::StopAttackFaction`, `Unit::InterruptAttacksOnMe`, a resisted
-    /// feign death). Its own message rather than a fifth `AttackSwingError`, because it is a
-    /// different opcode family; that its ARM is the same one is the finding, and it is expressed
-    /// where the arms are dispatched.
+    /// `SMSG_CANCEL_COMBAT` (`0x14e`): the server forced our attack to stop (`Unit::CombatStop`,
+    /// `Unit::StopAttackFaction`, `Unit::InterruptAttacksOnMe`, a resisted feign death).
     CombatCancelled,
-    /// One of OUR swings landed on a victim we can see — arm 5's `0x5ea800` call at `0x6259b6`,
-    /// whose first act is the latch clear. **Both** of the reference's gates are applied at the
-    /// write site, which is the only place holding the guids: GATE A, the attacker is the local
-    /// player (`0x6259a8 test al,al; je`, `0x5fa6d0`), and GATE B, the victim resolves
-    /// (`0x6259b1 test eax,eax; je`). The leg is entered by fall-through alone — 0 branches into
-    /// `[0x6259ac, 0x6259b7]`, 1 rel32 caller of `0x5ea800`, 0 address-takes.
-    ///
-    /// GATE B is exactly `0x468460(ecx = 8)`, i.e. **"resolves, as a UNIT"** — its two zero
-    /// returns are "guid absent from the object index" and "resolved but the type mask misses the
-    /// bit". benilla's index lookup covers the first and not the second, and the gap is
-    /// unreachable: this packet's victim is a unit or a player server-side, and a player's mask
-    /// carries the UNIT bit too. Stated rather than tightened, because the sibling uses of the
-    /// same lookup two lines away (the full-block synthesis, the impact fallback) ask the index
-    /// the same question, and one arm asking it differently would read as a distinction.
+    /// One of our swings landed on a victim we can see (`0x6259b6`). The write site applies both
+    /// gates: the attacker is the local player (`0x5fa6d0`) and the victim resolves as a unit
+    /// (`0x468460(8)`); benilla checks presence only, which is equivalent since the victim is
+    /// always a unit or player.
     Landed,
 }
 
-/// The latched refusal — the reference's `[0xc4d758]` (which code) and `[0xc4c270]` (when the next
-/// line is due).
-///
-/// **One `Option` over the pair**, not two fields, because the reference's timestamp has no meaning
-/// while its code is `0`: `0x5ecdb0` writes both in the same breath, and the tick reads the second
-/// only after the first has passed its `cmp eax,1`/`cmp eax,2`. `None` IS code `0` — the value both
-/// clear sites push, and the value the tick falls through on. The `Duration` is an absolute time,
-/// not a countdown, exactly as the reference stores it.
-///
-/// A re-implementation modelling this as `(Option<Code>, Instant)` must not assume the
-/// timestamp is zero when the code is — the reference's clear writes `now`, not `0`. Pairing them
-/// inside the `Option` is how that warning is answered rather than obeyed: there is no timestamp
-/// to be wrong about while the code is absent, and every transition into `Some` writes a fresh
-/// one.
+/// The latched refusal: the reference's `[0xc4d758]` (the code) and `[0xc4c270]` (the absolute
+/// time the next line is due). `None` is code 0, whose timestamp the tick never reads.
 #[derive(Resource, Default)]
 struct SwingRefusal(Option<(Latched, Duration)>);
 
-/// The two refusals that latch. [`AttackSwingError::DeadOrUnattackable`] is deliberately absent:
-/// arm 4 writes no latch, so there is no third code to hold.
+/// The two refusals that latch; arm 4 writes no latch.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 enum Latched {
-    /// Code `1` → `DisplayError(0xd8)` = `ERR_BADATTACKPOS`, "You are too far away!".
+    /// Code 1: `DisplayError(0xd8)`, `ERR_BADATTACKPOS`.
     NotInRange,
-    /// Code `2` → `DisplayError(0xd7)` = `ERR_BADATTACKFACING`, "You are facing the wrong way!".
+    /// Code 2: `DisplayError(0xd7)`, `ERR_BADATTACKFACING`.
     BadFacing,
 }
 
 impl Latched {
-    /// The `GlobalStrings.lua` key the reference's error id resolves to — catalog rows `0xd8`/
-    /// `0xd7` ([`benilla_ui::messages`]) — so the text and its localization come out of the
-    /// player's own file like every other line.
+    /// The `GlobalStrings.lua` key the reference's error id resolves to.
     const fn key(self) -> &'static str {
         match self {
             Self::NotInRange => "ERR_BADATTACKPOS",
@@ -147,23 +83,19 @@ impl Latched {
 }
 
 impl SwingRefusal {
-    /// `0x5ecdb0(ecx = code)` — latch the refusal and make the next line due **now**.
+    /// `0x5ecdb0(code)`: latch the refusal, due now.
     fn latch(&mut self, code: Latched, now: Duration) {
         self.0 = Some((code, now));
     }
 
-    /// `0x5ecdb0(ecx = 0)` — the clear both of the reference's zero sites push.
+    /// `0x5ecdb0(0)`.
     fn clear(&mut self) {
         self.0 = None;
     }
 }
 
-/// Consume this frame's edges in packet order: latch a refusal, clear on a landing, and run the
-/// shared `0x148`/`0x149` arm's one and only act.
-///
-/// The StopAttack lives here rather than in the net drain because [`AttackSeam`] is the whole
-/// write set `0x5ecac0` needs, and because putting it beside the latch keeps arm 4's "stop, and
-/// say nothing" legible as one fact.
+/// Consume this frame's edges in packet order: latch a refusal, clear on a landing, and stop the
+/// attack for the silent arm.
 fn apply_swing_refusals(
     mut edges: MessageReader<SwingRefusalEdge>,
     time: Res<Time>,
@@ -181,10 +113,8 @@ fn apply_swing_refusals(
                 debug!("swing refused: bad facing");
                 refusal.latch(Latched::BadFacing, time.elapsed());
             }
-            // The two SILENT arms — arm 4 (`0x625ab8`, for `0x148`/`0x149`) and
-            // `SMSG_CANCEL_COMBAT`'s own `0x5e7dd0`, whose bodies are byte-identical. No latch, no
-            // message on any surface; only the stop, and `0x5ecac0`'s own engaged guard decides
-            // whether even that sends anything.
+            // `0x625ab8` and `0x5e7dd0`: no latch, no message, only the stop, whose own engaged
+            // guard (`0x5ecac0`) decides whether it sends anything.
             SwingRefusalEdge::Refused(AttackSwingError::DeadOrUnattackable)
             | SwingRefusalEdge::CombatCancelled => {
                 debug!("swing stopped by the server — silently ({edge:?})");
@@ -195,19 +125,10 @@ fn apply_swing_refusals(
     }
 }
 
-/// The reference's per-player tick `0x5ec950` — the whole display side of this seam.
-///
-/// Every gate is the reference's, in its order: the active player, an attack target set
-/// ([`Engaged`] is benilla's `[+0xc48]`, see [`crate::creature_anim::stop_attack_local`]), the
-/// cooldown, then the code. The re-arm happens **only when a line is actually shown** — the
-/// reference reaches `0x5ec9b6` from the two code arms alone and its `else` jumps past it.
-///
-/// **Once per rendered frame is the exact cadence, not merely a fast-enough one.** `0x5ec950` is
-/// `CGPlayer_C` vtable `0x80af78` **slot 14** (`+0x38`), and the only dispatcher of that slot
-/// image-wide is `0x48160c` inside `0x4815d0`, on the `CWorldFrame::OnPaint` chain
-/// (`0x483460` → `0x48361d` → `0x681070` → `0x683dd0` → `0x481540`). Culling does not skip it —
-/// it only changes the pass — and neither does a first-person camera. A Bevy `Update` system is
-/// that, and the 4000 ms gate makes the match exact rather than approximate.
+/// The reference's per-player tick `0x5ec950`, gated in its order: an attack target set
+/// ([`Engaged`] is `[+0xc48]`), the cooldown, then the code; it re-arms only when a line shows.
+/// It runs once per rendered frame (vtable `0x80af78` slot 14, called only from `0x48160c` on the
+/// world paint), as an `Update` system does.
 fn show_swing_refusal(
     time: Res<Time>,
     mut refusal: ResMut<SwingRefusal>,
@@ -218,7 +139,7 @@ fn show_swing_refusal(
         return;
     };
     if engaged.is_empty() {
-        return; // `[+0xc48] == 0` — no attack target, so nothing to complain about
+        return; // `[+0xc48] == 0`: no attack target
     }
     let now = time.elapsed();
     if now < due {
@@ -228,12 +149,8 @@ fn show_swing_refusal(
     errors.0.push(UiError::key(code.key()));
 }
 
-/// **Entering** the world drops the latch — the reference's `0x5e2510`, reached from
-/// `ClientInitializeGame 0x401570` (`0x401648` → `0x5e253a`), which runs **once per
-/// world entry, not once per process**. So a fresh world cannot inherit the last one's refusal.
-///
-/// Nothing else clears it, and never the passage of time: what actually silences a repeating
-/// refusal in play is a landed swing, or the attack target going away (the tick's second gate).
+/// Entering the world drops the latch: the reference's `0x5e2510`, from `ClientInitializeGame`
+/// (`0x401570`), which runs once per world entry.
 fn on_world_enter(mut refusal: ResMut<SwingRefusal>) {
     refusal.clear();
 }
@@ -246,10 +163,8 @@ impl Plugin for SwingRefusalPlugin {
             .add_message::<SwingRefusalEdge>()
             .add_systems(
                 Update,
-                // After the drain that writes the edges, and before the unit feeds, so a key
-                // queued this frame is resolved and shown by `ui_action::feed_actions` on the same
-                // frame rather than the next. Chained, so a refusal that arrives this frame is
-                // latched before the tick reads the latch.
+                // After the drain that writes the edges and before the unit feeds, so a queued
+                // key shows the same frame; chained so a refusal is latched before the tick.
                 (apply_swing_refusals, show_swing_refusal)
                     .chain()
                     .after(benilla_world::schedule::WorldStage::Net)
@@ -270,7 +185,7 @@ mod tests {
         Duration::from_secs(s)
     }
 
-    /// The latch makes the line due immediately; the re-arm is exactly 4 s later.
+    /// The latch makes the line due immediately; the re-arm is 4 s later.
     #[test]
     fn the_first_line_is_immediate_and_the_repeat_is_four_seconds() {
         let mut r = SwingRefusal::default();
@@ -283,21 +198,19 @@ mod tests {
         assert_eq!(secs(100) + REPEAT, Duration::from_millis(104_000));
     }
 
-    /// A **second** refusal defeats the 4 s cooldown: `0x5ecdb0` writes the deadline
-    /// unconditionally, so the next tick shows again at once — and a NOTINRANGE→BADFACING flip
-    /// shows immediately rather than 4 s later.
+    /// A second refusal defeats the 4 s cooldown: `0x5ecdb0` writes the deadline unconditionally.
     #[test]
     fn a_second_refusal_packet_defeats_the_cooldown() {
         let mut r = SwingRefusal::default();
         r.latch(Latched::NotInRange, secs(100));
-        // …the tick shows the line and re-arms for 104 s…
+        // The tick shows the line and re-arms for 104 s,
         r.0 = Some((Latched::NotInRange, secs(100) + REPEAT));
-        // …and a second packet one second later puts it due NOW, not at 104 s.
+        // and a second packet one second later puts it due now.
         r.latch(Latched::BadFacing, secs(101));
         assert_eq!(r.0, Some((Latched::BadFacing, secs(101))));
     }
 
-    /// A landed swing clears it — the reason the line stops instead of repeating forever.
+    /// A landed swing clears it.
     #[test]
     fn a_landed_swing_clears_the_latch() {
         let mut r = SwingRefusal::default();
@@ -306,15 +219,14 @@ mod tests {
         assert_eq!(r.0, None);
     }
 
-    /// Both keys are catalog rows, and they are the two the reference's error ids name — the
-    /// `push 0xd8`/`push 0xd7` at `0x5ec9a5`/`0x5ec9b1`.
+    /// The keys are the reference's error ids, `0xd8`/`0xd7` at `0x5ec9a5`/`0x5ec9b1`.
     #[test]
     fn the_two_keys_are_the_reference_error_ids() {
         let pos = benilla_ui::messages::by_key(Latched::NotInRange.key()).expect("0xd8 is a row");
         let facing = benilla_ui::messages::by_key(Latched::BadFacing.key()).expect("0xd7 is a row");
         assert_eq!(pos.id, 0xd8);
         assert_eq!(facing.id, 0xd7);
-        // Both go to the red line, not to chat — the catalog's own `kind`, not a choice here.
+        // Both go to the red error line, by the catalog's own `kind`.
         assert_eq!(pos.kind, benilla_ui::messages::MsgKind::Error);
         assert_eq!(facing.kind, benilla_ui::messages::MsgKind::Error);
     }
diff --git a/crates/benilla-app/src/test_support.rs b/crates/benilla-app/src/test_support.rs
index 7e801ff1..320d11af 100644
--- a/crates/benilla-app/src/test_support.rs
+++ b/crates/benilla-app/src/test_support.rs
@@ -1,7 +1,4 @@
-//! Helpers for the crate's **structural tests** — the ones that read this crate's own source
-//! and insist on a shape (decisions 1290, 2220, 2279). A structural test exists where the
-//! failure is silent at runtime, so the check has to happen at the line; these are the readers
-//! they share.
+//! Source readers shared by the crate's structural tests, which check this crate's own code.
 
 /// Every `.rs` file under `root`, recursively.
 pub(crate) fn rust_files(root: &std::path::Path) -> Vec<std::path::PathBuf> {
@@ -28,7 +25,7 @@ pub(crate) fn src_dir() -> std::path::PathBuf {
     std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src")
 }
 
-/// A file's path under `src/`, with forward slashes — the key every `EXEMPT` table uses.
+/// A file's path under `src/`, with forward slashes: the key every `EXEMPT` table uses.
 pub(crate) fn rel_path(file: &std::path::Path) -> String {
     let src = src_dir();
     file.strip_prefix(&src)
@@ -37,18 +34,14 @@ pub(crate) fn rel_path(file: &std::path::Path) -> String {
         .replace('\\', "/")
 }
 
-/// One `fn` item as the scanners see it: its name, its parenthesised parameter list, and its
-/// body (the text between the outermost braces), each found by bracket matching so a scan
-/// sees a signature or a body rather than whatever text happens to follow.
+/// One `fn` item: name, parameter list and body, each found by bracket matching.
 pub(crate) struct FnItem<'a> {
     pub name: &'a str,
     pub params: &'a str,
     pub body: &'a str,
 }
 
-/// Every `fn` in `text`. A `fn` with no body (a trait method signature) comes back with an
-/// empty body; a generic parameter list before the `(` is tolerated in the shapes this
-/// codebase writes.
+/// Every `fn` in `text`; a bodiless signature comes back with an empty body.
 pub(crate) fn fn_items(text: &str) -> Vec<FnItem<'_>> {
     let bytes = text.as_bytes();
     let mut out = Vec::new();
@@ -66,8 +59,7 @@ pub(crate) fn fn_items(text: &str) -> Vec<FnItem<'_>> {
             continue;
         };
         let params = &text[open + 1..close];
-        // The body: the first `{` after the parameter list, unless a `;` (a bodiless
-        // signature) or another `fn` comes first.
+        // The body: the first `{` after the parameters, unless a `;` comes first.
         let tail = &text[close + 1..];
         let body = match (tail.find('{'), tail.find(';')) {
             (Some(b), Some(s)) if s < b => "",
@@ -85,7 +77,7 @@ pub(crate) fn fn_items(text: &str) -> Vec<FnItem<'_>> {
     out
 }
 
-/// The parenthesised parameter list of every `fn` in `text` — see [`fn_items`].
+/// The parameter list of every `fn` in `text`.
 pub(crate) fn fn_parameter_lists(text: &str) -> Vec<&str> {
     fn_items(text).into_iter().map(|f| f.params).collect()
 }
diff --git a/crates/benilla-app/src/text_filter.rs b/crates/benilla-app/src/text_filter.rs
index f8f0bd31..dc14991d 100644
--- a/crates/benilla-app/src/text_filter.rs
+++ b/crates/benilla-app/src/text_filter.rs
@@ -1,83 +1,43 @@
-//! The two 1.12 text filters — `profanityFilter`'s **masker** and `spamFilter`'s **predicate**
-//! (decision 2077; an emulated run of the binary's own compile/exec over the shipped lists).
+//! The two 1.12 text filters: the `profanityFilter` masker (`0x4a1a60`) over `ChatProfanity.dbc`
+//! and the `spamFilter` predicate (`0x4a1ca0`) over `SpamMessages.dbc`, both PCRE lists compiled
+//! once at startup and never reloaded.
 //!
-//! Both are **PCRE over shipped DBCs**, not word lists: `ChatProfanity.dbc` (2289 rows) feeds the
-//! masker `0x4a1a60`, `SpamMessages.dbc` (28 gold-seller URL patterns) feeds the predicate
-//! `0x4a1ca0`. The reference compiles them once at startup and never reloads.
+//! The masker self-gates on `[0x843600]` (read at `0x4a1a66`), so no call site tests the CVar. Each
+//! matched byte becomes the next of `!@#$%^&*` (`.rdata 0x806458`) through a process-global index
+//! (`[0xb6e5f0]`) that is never reset, so the phase carries across matches and messages. Patterns
+//! apply in list order, not text order, every occurrence, and the length never changes.
 //!
-//! ## The masker (`0x4a1a60`) — in place, length-preserving, phase-carrying
+//! Only the chat chokepoint is wired. The reference masks twelve more sites, not built here: the
+//! mail subject, `GetInboxText`, `GetGuildInfo`, the two guild-record accessors, the roster MOTD
+//! and info, `GetGuildRosterInfo`, `GuildControlGetRankName`, item text, `SendChatMessage` and the
+//! guild-event MOTD; seven of them pass the `dl = 1` memo, which re-blits a cached string without
+//! advancing the index.
 //!
-//! It **self-gates**: `[0x843600]` (the `profanityFilter` mirror) is read at `0x4a1a66`, at the head
-//! of the transform, which is why all thirteen of its call sites are CVar-gated without any of them
-//! testing the CVar. That is reproduced here — [`TextFilter::mask`] takes the switch, and no call
-//! site repeats it.
+//! The predicate has one call site, in the chat chokepoint; it never edits the text, and a hit
+//! drops the line silently.
 //!
-//! Per matched span it overwrites **one byte per byte** from `.rdata 0x806458` = `!@#$%^&*`,
-//! advancing a **process-global index `[0xb6e5f0]` that is never reset**. So the mask phase carries
-//! across matches, across messages and across subsystems for the whole session — a client that
-//! restarts the cycle per message diverges visibly on the second censored word. Patterns apply in
-//! **list order, not text order**, every occurrence, and the string's length never changes (a
-//! multi-byte match becomes that many ASCII punctuation bytes, exactly as the reference's byte loop
-//! does).
-//!
-//! **Wired here: the chat chokepoint only** — the fourteen social chat types of `.rdata 0x8046d8`,
-//! which is the masker's largest consumer and the one the options row is about. The reference has
-//! twelve more call sites and they are named rather than quietly skipped: `SMSG_MAIL_LIST_RESULT`'s
-//! subject, `GetInboxText`, `GetGuildInfo`, the two guild-record accessors, `SMSG_GUILD_ROSTER`'s
-//! MOTD and info buffers, `GetGuildRosterInfo`, `GuildControlGetRankName`, item text before
-//! `ITEM_TEXT_READY`, `SendChatMessage`, and `SMSG_GUILD_EVENT`'s MOTD. Each needs the mask applied
-//! where that text enters our model rather than at the Lua getter (benilla publishes a model where
-//! the reference re-filters a raw store), which is a different piece of plumbing per subsystem.
-//!
-//! **The `dl = 1` memo lands with them, not before.** Seven of those twelve pass it, and it is
-//! observable: a cache hit re-blits the stored text so the mask index does *not* advance, which is
-//! what stops a roster string re-read every repaint from shimmering. Masking once as the text
-//! enters the model is that same behaviour by construction, so the memo is a thing those sites will
-//! need only if they mask at the getter. Shipping the leg now would be a method nothing calls.
-//!
-//! ## The predicate (`0x4a1ca0`) — a boolean, never an edit
-//!
-//! One call site image-wide, inside the chat chokepoint. It never touches the subject text; its
-//! out-buffer is written and discarded, and its memo cache is dead code in this build. A positive
-//! result **drops the line silently** — nothing is shown in its place.
-//!
-//! ## PCRE → `regex`, exactly
-//!
-//! Two translations, and both are the reference's own behaviour rather than a convenience:
-//!
-//! - **`\<` and `\>` are word boundaries, not literals.** Blizzard *patched* PCRE's escape table
-//!   (`.rdata 0x812330`) to give `\<`, `\>` and `\b` the identical code `−4`, so both are
-//!   non-directional `\b`. Stock PCRE has no `<`/`>` entries and would make them literals, which
-//!   would kill the entire ASCII half of `ChatProfanity`. The binary's own compiler, run on a
-//!   reversal control, agrees: `\>twat\<` behaves exactly like `\<twat\>`.
-//! - **CASELESS folds ASCII only** — the fold table `0x873c40` is the identity over `0x80..=0xff`.
-//!   `regex`'s own `(?i)` folds Unicode, which would match `É` where the reference matches nothing,
-//!   so instead both the pattern's literals and the subject are ASCII-lowercased and the match runs
-//!   case-*sensitively*. ASCII lowercasing never touches a UTF-8 continuation byte, so every match
-//!   offset maps back to the original string unchanged.
-//!
-//! The shipped patterns use only `. < > s` after a backslash and `? [ ] * + ^ $ .` as metacharacters
-//! — no backreferences, no lookaround — so `regex` runs them as PCRE would.
+//! Two PCRE translations are the reference's own behaviour. `\<` and `\>` are the non-directional
+//! `\b`: the client's patched escape table (`.rdata 0x812330`) gives all three the code -4.
+//! CASELESS folds ASCII only (the fold table `0x873c40` is the identity over `0x80..=0xff`), so
+//! the pattern literals and the subject are ASCII-lowercased and matched case-sensitively, which
+//! keeps every offset. The shipped patterns use no backreferences or lookaround.
 
 use bevy::prelude::*;
 use regex::{Regex, RegexSet};
 
 use benilla_formats::FilterPattern;
 
-/// `.rdata 0x806458` — the eight mask bytes, in order.
+/// `.rdata 0x806458`: the eight mask bytes, in order.
 const MASK_TOKENS: &[u8; 8] = b"!@#$%^&*";
 
-/// One compiled list: the set (for the cheap "which patterns can match at all" pass) beside the
-/// individual expressions, in **list order** — which is the order the mask law walks them in.
+/// One compiled list: the set for the cheap pass beside the expressions, in list order.
 struct PatternList {
     set: RegexSet,
     each: Vec<Regex>,
 }
 
 impl PatternList {
-    /// Compile a list, **skipping a row that fails** exactly as `0x6c94cf`'s success-only increment
-    /// leg does — so the live count is the number that compiled, not the row count. On the shipped
-    /// data none fails; a row that does is named, because the reference names it too.
+    /// Compile a list, skipping and naming a row that fails, as `0x6c94cf` does.
     fn compile(rows: &[FilterPattern], list: &str) -> Self {
         let mut patterns = Vec::with_capacity(rows.len());
         let mut each = Vec::with_capacity(rows.len());
@@ -94,8 +54,7 @@ impl PatternList {
                 ),
             }
         }
-        // The set is built from the same strings that compiled one by one, so it cannot disagree
-        // with `each` about what is in the list.
+        // Built from the strings that compiled, so it agrees with `each`.
         let set = RegexSet::new(&patterns).unwrap_or_else(|e| {
             error!("{list}: the pattern set would not build ({e}) — the filter is off");
             RegexSet::empty()
@@ -115,14 +74,8 @@ impl PatternList {
     }
 }
 
-/// **Translate one shipped PCRE pattern** into the equivalent `regex` expression: `\<`/`\>` become
-/// `\b`, every other escape is preserved verbatim, and literal ASCII is lowercased so the match can
-/// run case-sensitively against an ASCII-lowercased subject (the module doc says why).
-///
-/// The lowercasing deliberately does **not** reach the character after a backslash: `\S` and `\s`
-/// are different classes, and folding one into the other would silently change a pattern. The
-/// shipped lists only ever use `\.`, `\<`, `\>` and `\s`, so nothing rides on it today — but a
-/// locale archive is free to ship a pattern that does.
+/// Translate one shipped PCRE pattern to `regex`: `\<`/`\>` become `\b`, other escapes stay
+/// verbatim (never lowercased: `\S` is not `\s`), and literal ASCII is lowercased.
 fn translate(pattern: &str) -> String {
     let mut out = String::with_capacity(pattern.len());
     let mut chars = pattern.chars();
@@ -132,42 +85,33 @@ fn translate(pattern: &str) -> String {
             continue;
         }
         match chars.next() {
-            // The patched escape table: both are the non-directional `\b`.
+            // The patched escape table: both are `\b`.
             Some('<' | '>') => out.push_str("\\b"),
             Some(next) => {
                 out.push('\\');
                 out.push(next);
             }
-            // A trailing backslash is a compile error in PCRE too; let `Regex::new` report it.
+            // A trailing backslash is a compile error in PCRE too.
             None => out.push('\\'),
         }
     }
     out
 }
 
-/// ASCII-only lowercase — the reference's `CASELESS` fold, whose table is the identity over
-/// `0x80..=0xff`. Byte-for-byte, so every offset in the result names the same position in the
-/// original (a UTF-8 continuation byte is never touched: it is always `>= 0x80`).
+/// The reference's ASCII-only `CASELESS` fold, byte-aligned with the original.
 fn ascii_lower(text: &str) -> String {
     let mut s = text.to_owned();
-    // SAFETY-free equivalent of `make_ascii_lowercase` on the String's bytes: only ASCII letters
-    // change, so UTF-8 validity is preserved by construction.
     s.make_ascii_lowercase();
     s
 }
 
-/// The two switches, mirrored off their CVars — the reference's `[0x843600]` (`profanityFilter`)
-/// and `[0x843604]` (`spamFilter`), each written by that CVar's own change callback.
-///
-/// Both default **on**: `CVar::Register` at `0x402e68` and `0x402e8e` pushes the shared `"1"`
-/// literal `0x82e748` for each, and the registrar runs the callback on the registered default, so a
-/// fresh client boots with both mirrors set.
+/// The two switches mirrored off their CVars: the reference's `[0x843600]` (`profanityFilter`)
+/// and `[0x843604]` (`spamFilter`), both registered `"1"` (`0x402e68`, `0x402e8e`).
 #[derive(Resource, Debug, Clone, Copy)]
 pub(crate) struct TextFilterSwitches {
-    /// `profanityFilter` — the masker's self-gate.
+    /// `profanityFilter`, the masker's self-gate.
     pub(crate) profanity: bool,
-    /// `spamFilter` — the chat chokepoint's spam arm. The options row for it is **inverted**
-    /// ("Disable Spam Filter"), which is the row's business, not this flag's.
+    /// `spamFilter`; its options row ("Disable Spam Filter") is inverted.
     pub(crate) spam: bool,
 }
 
@@ -180,10 +124,8 @@ impl Default for TextFilterSwitches {
     }
 }
 
-/// The 14 chat types the reference's profanity arm is eligible for — `.rdata 0x8046d8`, read as a
-/// table of 14 dwords with the bound `0x38` at `0x49aabb`, i.e. **every player-authored social
-/// channel**. A type outside this table is never masked, which is why a monster's yell and a
-/// combat-log line reach the frame verbatim.
+/// The 14 player-authored chat types the reference masks (`.rdata 0x8046d8`, bound at `0x49aabb`);
+/// any other type, a monster's yell included, is never masked.
 pub(crate) const PROFANITY_MASKED_CHAT_TYPES: &[u8] = &[
     0x00, // SAY
     0x01, // PARTY
@@ -201,19 +143,17 @@ pub(crate) const PROFANITY_MASKED_CHAT_TYPES: &[u8] = &[
     0x5c, // BATTLEGROUND
 ];
 
-/// The two compiled lists plus the state the reference keeps beside them: the rotating mask index
-/// and the masker's per-string memo.
+/// The two compiled lists and the rotating mask index.
 #[derive(Resource)]
 pub(crate) struct TextFilter {
     profanity: PatternList,
     spam: PatternList,
-    /// `[0xb6e5f0]` — BSS, zero-init, advanced mod 8, **never reset**.
+    /// `[0xb6e5f0]`: zero-initialized, advanced mod 8, never reset.
     mask_index: usize,
 }
 
 impl Default for TextFilter {
-    /// An engine with no lists — what a machine with no client data gets. Both filters then pass
-    /// everything through, which is the same shape as the reference booting with an empty list.
+    /// No lists, without client data: both filters pass everything.
     fn default() -> Self {
         TextFilter {
             profanity: PatternList::empty(),
@@ -240,15 +180,9 @@ impl TextFilter {
         self.spam.len()
     }
 
-    /// `0x4a1ca0` — **does this text match the spam list?** A predicate, never an edit.
-    ///
-    /// The reference scans the shipped list then a server-pushed one (SMSG `0x332`) which starts
-    /// empty and stays empty unless the server sends it; vmangos never does, so there is one list
-    /// here. It does not exit early on a hit, but the only consumed output is the boolean, so a
-    /// first-match-wins scan is observably identical.
-    ///
-    /// `enabled` is the caller's `spamFilter`; the reference tests it *outside* this function (the
-    /// chokepoint's `esi`), unlike the masker's self-gate.
+    /// `0x4a1ca0`: whether the text matches the spam list. The reference also scans a server-pushed
+    /// list (SMSG `0x332`) that vmangos never sends. `enabled` is `spamFilter`, which the reference
+    /// tests at the call site.
     pub(crate) fn is_spam(&self, enabled: bool, text: &str) -> bool {
         if !enabled || text.is_empty() || self.spam.len() == 0 {
             return false;
@@ -256,10 +190,8 @@ impl TextFilter {
         self.spam.set.is_match(&ascii_lower(text))
     }
 
-    /// `0x4a1a60` with `dl = 0` — mask in place, return whether anything matched.
-    ///
-    /// **Self-gating, like the reference**: `enabled` is `profanityFilter`, tested here so no call
-    /// site has to.
+    /// `0x4a1a60` with `dl = 0`: mask in place, return whether anything matched. `enabled` is
+    /// `profanityFilter`, tested here as the reference does.
     pub(crate) fn mask(&mut self, enabled: bool, text: &mut String) -> bool {
         if !enabled || text.is_empty() || self.profanity.len() == 0 {
             return false;
@@ -267,18 +199,10 @@ impl TextFilter {
         self.mask_uncached(text)
     }
 
-    /// The transform itself — the byte loop of `0x4a1b6a`–`0x4a1ba6` under `0x4a1a60`'s pattern
-    /// walk.
-    ///
-    /// **Single pass, list order, over the mutating buffer.** The reference walks every pattern in
-    /// order against the buffer it is masking, so a pattern that only becomes matchable because an
-    /// *earlier* pattern masked something is caught, while one that would need a *later* pattern's
-    /// mask is not — it has already been passed. That asymmetry is reproduced here rather than
-    /// smoothed: the candidate set is re-derived after each pattern that actually wrote, and only
-    /// entries past the current one are kept.
+    /// The byte loop of `0x4a1b6a`-`0x4a1ba6`: one pass in list order over the mutating buffer, so
+    /// an earlier pattern's mask can enable a later match but never the reverse.
     fn mask_uncached(&mut self, text: &mut String) -> bool {
-        // The matching subject: ASCII-lowercased, byte-aligned with `text`, and masked in step so
-        // later patterns see what the reference's later patterns see.
+        // The subject is ASCII-lowercased, byte-aligned with `text` and masked in step.
         let mut subject = ascii_lower(text);
         let mut candidates: Vec<usize> = self.profanity.set.matches(&subject).iter().collect();
         let mut any = false;
@@ -291,16 +215,12 @@ impl TextFilter {
                 let (start, end) = (m.start(), m.end());
                 any = true;
                 if start == end {
-                    // The reference latches "something matched" before the length test and then
-                    // re-runs from an unadvanced cursor — i.e. an empty-matching pattern spins.
-                    // No shipped row can match empty (the test below holds that), so this is the
-                    // one place we decline to reproduce the reference and simply stop.
+                    // The reference spins on an empty match; this stops instead. No shipped row
+                    // can match empty (tested below).
                     break;
                 }
-                // One token per BYTE of the span — the reference's `mov [esi],cl / inc esi / dec
-                // eax` loop, so a three-byte character becomes three punctuation marks. The span is
-                // on char boundaries (a regex match always is) and the run is the same byte length,
-                // so both strings stay valid UTF-8 and stay byte-aligned with each other.
+                // One token per byte of the span, as the reference's loop writes; a match is on
+                // char boundaries, so both strings stay valid UTF-8 and aligned.
                 let run: String = (start..end)
                     .map(|_| {
                         let token = MASK_TOKENS[self.mask_index] as char;
@@ -317,8 +237,7 @@ impl TextFilter {
                 }
             }
             if wrote {
-                // The buffer moved: whatever can still match now is what the reference's remaining
-                // patterns would see. Keep only the ones it has not walked past.
+                // The buffer moved: re-derive the candidates past this pattern.
                 candidates = self
                     .profanity
                     .set
@@ -350,9 +269,7 @@ mod tests {
             .collect()
     }
 
-    /// `\<` and `\>` are **word boundaries**, and non-directional — the reversal control run
-    /// through the binary's own compiler, which could have failed: the reversed spelling behaves
-    /// identically to the ordinary one and to `\b`, and none of the three matches inside a word.
+    /// `\<` and `\>` are non-directional word boundaries, as the reference's compiler treats them.
     #[test]
     fn the_angle_escapes_are_non_directional_word_boundaries() {
         for spelling in [r"\<twat\>", r"\>twat\<", r"\btwat\b"] {
@@ -370,14 +287,8 @@ mod tests {
         }
     }
 
-    /// The mask is **in place, length-preserving, case-insensitive and unanchored where the pattern
-    /// is** — and the phase **carries across calls**. This is an oracle transcript, run against
-    /// the binary's own bytes, reproduced pattern for pattern.
-    ///
-    /// The list order is the oracle's: `\<fagg[aeiouy]t` before `\<twat\>`, which is what makes the
-    /// *later* word in the sentence take the *earlier* mask characters. Had the client scanned in
-    /// text order the assignment would come out the other way round — the control that could have
-    /// failed.
+    /// A transcript of the reference's masker: in place, length-preserving, caseless, the phase
+    /// carrying across calls, and list order giving the later word the earlier mask characters.
     #[test]
     fn the_masker_reproduces_the_oracle_transcript() {
         let mut f = TextFilter::new(&list(&[r"\<fagg[aeiouy]t", r"\<twat\>", "shit"]), &[]);
@@ -409,8 +320,7 @@ mod tests {
         );
     }
 
-    /// The switch is read **inside** the masker, which is why none of the thirteen call sites tests
-    /// it: with `profanityFilter = 0` the text is untouched and the phase does not move.
+    /// With `profanityFilter = 0` the text is untouched and the phase does not move.
     #[test]
     fn the_masker_self_gates_and_a_gated_call_does_not_move_the_phase() {
         let mut f = TextFilter::new(&list(&[r"\<twat\>"]), &[]);
@@ -420,9 +330,7 @@ mod tests {
         assert_eq!(f.mask_index, 0);
     }
 
-    /// A multi-byte match is masked **byte for byte**: the reference's loop writes one ASCII token
-    /// per byte of the span, so a three-byte character becomes three punctuation marks and the
-    /// string's byte length never changes.
+    /// A multi-byte match is masked byte for byte.
     #[test]
     fn a_non_ascii_match_is_masked_byte_for_byte() {
         let mut f = TextFilter::new(&list(&["傻B"]), &[]);
@@ -456,10 +364,8 @@ mod tests {
         );
     }
 
-    /// The shipped lists, compiled — every row, through the real chain. Two things are held: the
-    /// translation compiles all 2317 rows (the reference's own oracle measured zero failures, so a
-    /// skipped row here would be ours, not the data's), and **no shipped pattern can match the
-    /// empty string**, which is the assumption `mask_uncached`'s zero-length break rests on.
+    /// Every shipped row compiles (the reference compiles all of them), and none matches the empty
+    /// string, which `mask_uncached`'s zero-length break rests on.
     #[test]
     fn every_shipped_pattern_compiles_and_none_matches_empty() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -482,7 +388,7 @@ mod tests {
         }
     }
 
-    /// The shipped data end to end: the oracle's own sentences through the real lists.
+    /// The transcript's sentences through the real lists.
     #[test]
     fn the_shipped_lists_reproduce_the_oracle_sentences() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -507,9 +413,8 @@ mod tests {
     }
 }
 
-/// The chat chokepoint's view of the two filters — the engine and its switches in one
-/// [`SystemParam`], because a Bevy system takes at most sixteen parameters and `feed_chat` had
-/// already reached fifteen (the `SpeakerEffects` precedent, same file).
+/// The chat chokepoint's view of the two filters, one [`SystemParam`] to keep `feed_chat` under
+/// Bevy's sixteen-parameter limit.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct ChatTextFilter<'w> {
     filter: ResMut<'w, TextFilter>,
@@ -517,17 +422,9 @@ pub(crate) struct ChatTextFilter<'w> {
 }
 
 impl ChatTextFilter<'_> {
-    /// Arm 1 — should this line be **dropped**? (`0x49aac9`–`0x49ab33`.)
-    ///
-    /// The conjuncts, in the reference's own order: the type is not `CHAT_MSG_FILTERED` (`0x5b` —
-    /// the type the filter itself produces, so re-filtering it would be circular), the line does
-    /// not carry the `"GM"` chat tag, the viewer is not a GM, and `spamFilter` is on. Only then is
-    /// the predicate run.
-    ///
-    /// **A GM viewer skips this arm and still reaches the mask** — all three of the spam arm's
-    /// exits converge on `0x49abb7`, the profanity arm's entry, not on the epilogue `0x49afd7`.
-    /// (Reading it as "bypassing both arms" is wrong: it would make `spamFilter = 0` disable
-    /// profanity masking too.)
+    /// Arm 1 (`0x49aac9`-`0x49ab33`): whether to drop the line. In the reference's order: not
+    /// `CHAT_MSG_FILTERED`, no `"GM"` tag, a non-GM viewer, `spamFilter` on, then the predicate.
+    /// Every exit, a GM viewer's included, still reaches the mask arm (`0x49abb7`).
     pub(crate) fn should_drop(
         &self,
         chat_type: u8,
@@ -542,10 +439,8 @@ impl ChatTextFilter<'_> {
         self.filter.is_spam(self.switches.spam, text)
     }
 
-    /// Arm 2 — mask the line, if its type is one of the fourteen the reference's table names.
-    ///
-    /// Eligibility is the call site's (`[ebp-8]`, computed at `0x49aa98`–`0x49aac2`); the CVar is
-    /// the masker's own (`0x4a1a66`), so it is not tested here.
+    /// Arm 2: mask the line if its type is in the reference's table (`0x49aa98`-`0x49aac2`); the
+    /// CVar is the masker's own.
     pub(crate) fn mask_chat(&mut self, chat_type: u8, text: &mut String) {
         if !PROFANITY_MASKED_CHAT_TYPES.contains(&chat_type) {
             return;
@@ -554,12 +449,8 @@ impl ChatTextFilter<'_> {
     }
 }
 
-/// Load both lists off the patch chain, once, and install the engine.
-///
-/// The reference does this in its linear startup init (`0x402b7f → 0x6c91a0`) with **no reload
-/// path**, so a `Startup` system is the same shape. `.after(AssetSet::Open)` is load-bearing for
-/// the reason every other DBC load in this tree carries it: without it the chain does not exist
-/// yet, the `Option<Res<_>>` takes its `None` arm, and the filters are silently empty forever.
+/// Load both lists off the patch chain once, as the reference's startup init does
+/// (`0x402b7f → 0x6c91a0`). It must run after `AssetSet::Open`, or the filters are silently empty.
 fn load_text_filter_lists(
     mut commands: Commands,
     assets: Option<Res<benilla_assets::WorldAssets>>,
@@ -573,8 +464,7 @@ fn load_text_filter_lists(
             benilla_formats::load_spam_messages(&mut chain),
         )
     };
-    // A missing list is a filter that passes everything, not a boot failure — the same posture the
-    // reference has when a row will not compile: name it and carry on with what did.
+    // A missing list passes everything; name it and carry on.
     let profanity = profanity
         .inspect_err(|e| warn!("chat profanity filter unavailable: {e:#}"))
         .unwrap_or_default();
@@ -592,8 +482,8 @@ fn load_text_filter_lists(
 
 pub(crate) struct TextFilterPlugin;
 
-/// The two filter switches' change callback (decision 2303): flags — the reference's own
-/// callbacks (`0x403570`, `0x4035b0`) mirror `SStrToInt(newValue)` into a global the same way.
+/// The two switches' change callback, as the reference's `0x403570`/`0x4035b0` mirror
+/// `SStrToInt(newValue)` into a global.
 pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut switches: ResMut<TextFilterSwitches>) {
     match ev.key().as_str() {
         "profanityfilter" => switches.profanity = ev.flag(),
diff --git a/crates/benilla-app/src/text_reshape.rs b/crates/benilla-app/src/text_reshape.rs
index 31c7a498..ba01ab18 100644
--- a/crates/benilla-app/src/text_reshape.rs
+++ b/crates/benilla-app/src/text_reshape.rs
@@ -1,50 +1,12 @@
-//! **The re-shape a `bevy_ui` text root loses when its LAST span is despawned** — an upstream
-//! change-detection hole, netted here because falling into it is a hard crash whose panic names
-//! none of our code (decision 2212). The way in: enter the world in window mode, then maximize the
-//! window on Linux.
+//! Re-shapes a `bevy_ui` text root whose last span was despawned, which upstream misses.
 //!
-//! ## The hole
+//! Despawning the last `TextSpan` removes `Children` rather than changing it, so
+//! `detect_text_needs_rerender` never fires and the root keeps a multi-run buffer and a span list
+//! naming dead entities. The next re-layout without a re-shape, such as a window resize, indexes
+//! `glyph_info` past the shortened list and panics (`bevy_text-0.18.1/src/pipeline.rs:398`).
 //!
-//! A `bevy_ui` text block is a `Text` root plus its `TextSpan` children. Two pieces of state hang
-//! off the root and must agree:
-//!
-//! - `ComputedTextBlock::buffer` — the shaped cosmic-text buffer, whose every laid-out glyph
-//!   carries the **index of the run it came from** in its `metadata`;
-//! - `ComputedTextBlock::entities` — the span list that index is an index *into*, rebuilt only by
-//!   `TextPipeline::update_buffer`.
-//!
-//! `bevy_text::detect_text_needs_rerender` is what asks for a re-shape, and on the root it watches
-//! `Changed<Text>`, `Changed<TextFont>`, `Changed<TextLayout>`, `Changed<LineHeight>` and
-//! `Changed<Children>`. **Despawning the last child does not *change* `Children` — it REMOVES
-//! it** (`bevy_ecs`'s relationship `on_replace` hook queues a `remove::<Children>()` once the
-//! collection empties), and `Changed<T>` cannot fire for a component the entity no longer has. So
-//! a root emptied of spans keeps `needs_rerender == false`, keeps its multi-run buffer, and keeps
-//! an `entities` list naming dead entities.
-//!
-//! Nothing goes wrong until the node is re-laid-out **without** being re-shaped, which is exactly
-//! what `widget::text_system` does on any frame where the node's `ComputedNode` changed — a window
-//! resize, in other words. `TextPipeline::update_text_layout_info` rebuilds its per-span
-//! `glyph_info` by `iter_many`-ing the stored `entities`, and `iter_many` *skips* the dead ones, so
-//! the list comes back short while the buffer's glyphs still carry `metadata == 1`. The next line
-//! is `self.glyph_info[span_index]` (`bevy_text-0.18.1/src/pipeline.rs:398`) and the client is
-//! gone. Nothing about this is platform-specific: Linux is simply where somebody maximized a
-//! window after the loading screen had put its tip away.
-//!
-//! ## The net
-//!
-//! [`reshape_emptied_text_roots`] restores the invariant the upstream detector cannot see: a
-//! `Text` root that just lost its `Children` component is marked changed, one system before the
-//! detector runs, so the block is re-shaped in the same frame and can never be re-laid-out stale.
-//!
-//! It is a **net, not the mechanism** — the site that emptied a node is still expected to leave it
-//! coherent (`game_tip::empty_tip` is the one that did not, and it does now). The net exists
-//! because the failure mode is a crash rather than a wrong pixel, and because the panic points at
-//! third-party code: B383 cost a pastebin core dump and a session to attribute.
-//!
-//! **Scope: `bevy_ui` text only.** `bevy_sprite`'s `Text2d` has the identical hole and no entry
-//! here, because this tree spawns none — and the in-game interface's own `FontString`s do not go
-//! through `bevy_ui` at all (they shape through `cosmic-text` under the UI pass, 0068 §2). What is
-//! left on `bevy_ui::Text` is the glue screens, the debug panel, and the loading screen's tip.
+//! This is a net: the site that empties a node should still leave it coherent. It covers
+//! `bevy_ui` text only; `Text2d` has the same hole, but this tree spawns none.
 
 use bevy::prelude::*;
 use bevy::text::detect_text_needs_rerender;
@@ -55,19 +17,13 @@ impl Plugin for TextReshapePlugin {
     fn build(&self, app: &mut App) {
         app.add_systems(
             PostUpdate,
-            // Ordered against the detector itself rather than against `UiSystems::Content`: the
-            // one thing that has to be true is that the mark lands before the detector reads it,
-            // and naming the system says so where a set name would only imply it.
+            // The mark must land before the detector reads it.
             reshape_emptied_text_roots.before(detect_text_needs_rerender::<Text>),
         );
     }
 }
 
-/// Mark a `Text` root changed when it loses its `Children` — see the module header.
-///
-/// `RemovedComponents<Children>` fires for every entity in the world that shed a hierarchy this
-/// frame (models, portraits, the streamed scene), so the body is a single archetype lookup that
-/// misses for all of them; only a live text root reaches the write.
+/// Marks a `Text` root changed when it loses its `Children`.
 fn reshape_emptied_text_roots(
     mut emptied: RemovedComponents<Children>,
     mut roots: Query<&mut Text>,
@@ -79,12 +35,8 @@ fn reshape_emptied_text_roots(
     }
 }
 
-/// **The two `bevy_ui` calls that bracket a text node, driven by hand** — so a test can put a text
-/// block into the state a real frame leaves it in, and then run the frame that used to crash.
-///
-/// `bevy_ui`'s own `UiPlugin` cannot: it wants a render app, a camera and a window to produce the
-/// `ComputedNode` change a resize is. What it does *around* the node is only these two pipeline
-/// calls, in this order, and both are `pub` — so the reproduction is exact without any of that.
+/// The two `bevy_ui` pipeline calls around a text node, driven by hand, since `UiPlugin` needs a
+/// render app, a camera and a window.
 #[cfg(test)]
 pub(crate) mod harness {
     use bevy::ecs::system::RunSystemOnce;
@@ -96,27 +48,18 @@ pub(crate) mod harness {
     };
     use bevy::ui::widget::TextUiReader;
 
-    /// A node box wide enough that the test strings lay out on one line and narrow enough that the
-    /// numbers stay small. Nothing in the mechanism depends on it.
+    /// Wide enough for one line; nothing depends on it.
     const BOUNDS: TextBounds = TextBounds::new(400.0, 200.0);
 
-    /// Everything a headless text block needs: `TextPlugin` for the pipeline resources and its
-    /// embedded default font (the only face an `AssetServer`-less test can shape with), plus the
-    /// two asset stores the glyph atlas fills.
+    /// `TextPlugin` with its embedded default font, and the glyph atlas's asset stores.
     pub(crate) fn add_text_plugins(app: &mut App) {
         app.add_plugins(bevy::text::TextPlugin);
         app.init_asset::<TextureAtlasLayout>();
         app.init_asset::<Image>();
     }
 
-    /// Point the root and every span at the embedded default font, so [`shape`] can run without an
-    /// asset load. Runtime resolves the real face off the patch chain instead.
-    ///
-    /// **`bypass_change_detection`, and the test suite does not work without it.** This stands in
-    /// for the face the runtime would have resolved when the node was spawned, so it must not read
-    /// as a `TextFont` change — `detect_text_needs_rerender` watches exactly that, and a harness
-    /// that quietly asks for a re-shape every time it shapes cannot observe a missing one. It cost
-    /// three of these tests a false green before the flag went on.
+    /// Points the root and spans at the embedded default font. It bypasses change detection: a
+    /// `TextFont` change would request the re-shape the tests check is missing.
     fn use_default_font(app: &mut App, root: Entity) {
         let spans: Vec<Entity> = app
             .world()
@@ -130,8 +73,7 @@ pub(crate) mod harness {
         }
     }
 
-    /// Shape the block, the way `widget::measure_text_system` does — the call that (re)fills
-    /// `ComputedTextBlock::entities` and clears `needs_rerender`.
+    /// Shapes the block as `widget::measure_text_system` does.
     pub(crate) fn shape(app: &mut App, root: Entity) {
         use_default_font(app, root);
         app.world_mut()
@@ -163,12 +105,8 @@ pub(crate) mod harness {
             .expect("the embedded default font shapes headless");
     }
 
-    /// **The frame a window resize is**, in the order `UiPlugin` runs it: the detector, then the
-    /// re-shape it asked for (`measure_text_system`), then the re-layout every node whose
-    /// `ComputedNode` moved gets (`text_system`). The last of the three is what panicked.
-    ///
-    /// Any system the app has scheduled `.before(detect_text_needs_rerender::<Text>)` — the net in
-    /// this module, when the plugin is installed — runs first, exactly as it would live.
+    /// A resize frame in `UiPlugin`'s order: the detector, the re-shape it asked for, then the
+    /// re-layout (`text_system`).
     pub(crate) fn resize_frame(app: &mut App, root: Entity) {
         app.update();
         if app
@@ -212,9 +150,7 @@ pub(crate) mod harness {
             .expect("the relayout succeeds");
     }
 
-    /// An app with the text stack and the real detector scheduled where `UiPlugin` puts it.
-    /// `net` installs [`super::TextReshapePlugin`] — the two tests below run the same world with
-    /// and without it.
+    /// The text stack and the real detector; `net` installs [`super::TextReshapePlugin`].
     pub(crate) fn text_app(net: bool) -> App {
         let mut app = App::new();
         app.add_plugins((MinimalPlugins, bevy::asset::AssetPlugin::default()));
@@ -233,8 +169,7 @@ mod tests {
     use bevy::prelude::*;
     use bevy::text::ComputedTextBlock;
 
-    /// A two-run block: the root's own text plus one `TextSpan` child, which is the shape every
-    /// coloured string in this tree has (`|cffffd100Tip:|r …`, the glue's markup runs).
+    /// The root's text plus one `TextSpan`, the shape of every coloured string.
     fn two_run_root(app: &mut App) -> Entity {
         let root = app
             .world_mut()
@@ -263,11 +198,7 @@ mod tests {
         root
     }
 
-    /// **The hole itself, named at the level the crash needs.** Despawning the last span leaves
-    /// `needs_rerender` false — `Children` was removed, not changed — so `bevy_ui` will re-lay-out
-    /// a buffer whose glyphs point at a run that no longer exists. This asserts the *broken*
-    /// upstream behaviour on purpose: it is the premise the net and every emptying site rest on,
-    /// and a bevy release that closes the hole should fail here and retire both.
+    /// Asserts the upstream hole on purpose: a bevy that closes it fails here and retires the net.
     #[test]
     fn upstream_misses_the_last_spans_despawn() {
         let mut app = text_app(false);
@@ -291,11 +222,7 @@ mod tests {
         );
     }
 
-    /// **The crash itself.** The same sequence with the net taken out:
-    /// the resize frame re-lays-out the stale buffer and `bevy_text` indexes `glyph_info[1]` of a
-    /// one-entry list. Pinned as a `should_panic` because it is the whole justification for the
-    /// net — when a bevy release closes the hole this fails, and the net (and this test, and the
-    /// premise test above) go with it.
+    /// Without the net, `bevy_text` indexes `glyph_info[1]` of a one-entry list.
     #[test]
     #[should_panic(expected = "index out of bounds")]
     fn without_the_net_the_resize_panics_inside_bevy_text() {
@@ -309,10 +236,6 @@ mod tests {
         resize_frame(&mut app, root);
     }
 
-    /// **B383, end to end.** Same world, plus the net: the emptied root is marked for re-shape, so
-    /// the resize frame re-shapes before it re-lays-out and the pipeline never indexes a dead run.
-    /// Without [`super::TextReshapePlugin`] this same sequence panics inside `bevy_text` with
-    /// `index out of bounds` at `pipeline.rs:398` — the client's own crash.
     #[test]
     fn the_net_reshapes_an_emptied_root_before_the_next_resize() {
         let mut app = text_app(true);
@@ -331,7 +254,6 @@ mod tests {
             "the net marks the emptied root for a re-shape"
         );
 
-        // The frame the report is about. It must not panic, and it must leave the block honest.
         resize_frame(&mut app, root);
         assert_eq!(
             app.world()
@@ -342,8 +264,6 @@ mod tests {
         );
     }
 
-    /// The control: a root that keeps a span through a resize is untouched by any of this — the
-    /// net must not be doing the re-shaping in the ordinary case.
     #[test]
     fn a_root_that_kept_its_span_is_not_reshaped() {
         let mut app = text_app(true);
diff --git a/crates/benilla-app/src/textinput/clipboard.rs b/crates/benilla-app/src/textinput/clipboard.rs
index d1021296..cba73877 100644
--- a/crates/benilla-app/src/textinput/clipboard.rs
+++ b/crates/benilla-app/src/textinput/clipboard.rs
@@ -1,62 +1,27 @@
-//! The host OS pasteboard seam — the one place benilla talks to the platform clipboard.
-//!
-//! The UI engine is engine-free and can't reach the OS clipboard, so the three clipboard chords
-//! ([`keymap::Chord`]) resolve host-side: copy/cut write out what `editbox_copy`/`editbox_cut`
-//! hand back, paste reads the pasteboard and feeds `UiScript::paste`.
-//!
-//! **Why this is a held resource with a per-platform backend, and not `arboard::Clipboard::new()`
-//! per call.** Both halves of copy/paste were broken on Linux, for two independent reasons
-//! (decision 0702):
-//!
-//! 1. **On X11 the handle *is* the clipboard.** An X11 selection has no backing store: the owning
-//!    client serves the bytes on request, so the clipboard lives exactly as long as the connection
-//!    that owns it. arboard keeps one process-global connection plus a server thread and tears the
-//!    whole thing down in `Drop` as soon as the last handle goes (its `MIN_OWNERS == 3` check —
-//!    a lone handle *is* the last one), first offering the data to a clipboard manager. So a fresh
-//!    handle per copy relinquishes the selection the instant the copy returns: with no clipboard
-//!    manager running — a bare WM, the common gaming setup — text copied out of benilla vanishes
-//!    immediately. One handle, held for the process lifetime, is the fix. macOS and Windows never
-//!    showed this because `NSPasteboard` and the Win32 clipboard both take ownership of the *data*,
-//!    not of a live connection, which is exactly why the per-call pattern read as fine.
-//! 2. **Our window is Wayland; arboard here is X11-only.** benilla builds with bevy's `wayland`
-//!    feature on, so on a Wayland session winit hands us a native Wayland window with no X11
-//!    surface at all — while `arboard`, without its **non-default** `wayland-data-control` feature,
-//!    only ever speaks X11. Reading then finds no X11 CLIPBOARD owner and fails with
-//!    `ContentNotAvailable`: precisely the reported "can't paste into the client on Linux".
-//!    Turning arboard's Wayland feature on is *not* the fix — it speaks `wlr-data-control`, a
-//!    privileged clipboard-manager protocol GNOME/Mutter deliberately does not implement, and
-//!    wl-clipboard-rs' own README points windowed apps at `smithay-clipboard` instead. So Wayland
-//!    goes through `smithay-clipboard`, which drives the **standard** `wl_data_device` from our own
-//!    winit `wl_display` and seat — the protocol every compositor supports.
-//!
-//! Windows needs none of this: `clipboard-win` resolves with no feature gates and the Win32
-//! clipboard is store-backed, so the chord table ([`keymap`]) was already the whole story
-//! there.
+//! The host OS pasteboard, the one place benilla talks to the platform clipboard. One handle is
+//! held for the whole run because on X11 the owning connection is the clipboard: arboard drops the
+//! selection with its last handle. A Wayland window goes through `smithay-clipboard`'s standard
+//! `wl_data_device` on our own `wl_display`, since arboard here speaks only X11.
 
 use std::ffi::c_void;
 
 use bevy::prelude::*;
 use bevy::window::RawHandleWrapper;
 
-/// One platform pasteboard, behind just the two operations the chord table needs. Boxed as a trait
-/// object so the entire Wayland half — crate, types, and `unsafe` — stays inside one `cfg` block
-/// instead of sprouting a `cfg` on every enum variant and match arm.
+/// One platform pasteboard; a trait object so the Wayland half stays inside one `cfg` block.
 trait Pasteboard {
-    /// The pasteboard's text. `Ok(None)` is the ordinary "nothing text-shaped on it" case (an empty
-    /// clipboard is not an error); `Err` is a genuine failure worth a `warn!`.
+    /// The pasteboard's text; `Ok(None)` when it holds no text, `Err` for a real failure.
     fn read_text(&mut self) -> Result<Option<String>, String>;
 
-    /// Put `text` on the pasteboard.
     fn write_text(&mut self, text: &str) -> Result<(), String>;
 
-    /// What to call this backend in a log line.
+    /// The backend's name for log lines.
     fn name(&self) -> &'static str;
 }
 
 impl Pasteboard for arboard::Clipboard {
     fn read_text(&mut self) -> Result<Option<String>, String> {
-        // `ContentNotAvailable` is arboard's "empty, or holds no format we asked for" — the normal
-        // nothing-to-paste case, not a failure to report.
+        // `ContentNotAvailable` is arboard's empty clipboard, not a failure.
         match self.get_text() {
             Ok(text) if text.is_empty() => Ok(None),
             Ok(text) => Ok(Some(text)),
@@ -70,7 +35,6 @@ impl Pasteboard for arboard::Clipboard {
     }
 
     fn name(&self) -> &'static str {
-        // The backend arboard itself picked, which is the part worth naming in a bug report.
         if cfg!(target_os = "macos") {
             "arboard/NSPasteboard"
         } else if cfg!(windows) {
@@ -81,8 +45,7 @@ impl Pasteboard for arboard::Clipboard {
     }
 }
 
-/// The Wayland half: the standard `wl_data_device` through our own `wl_display`. Gated to the
-/// platforms `smithay-clipboard` is a dependency on (see `Cargo.toml`) — Linux and the BSDs.
+/// The Wayland half; the gate must match `smithay-clipboard`'s target in `Cargo.toml`.
 #[cfg(all(unix, not(any(target_os = "macos", target_os = "android"))))]
 mod wl {
     use super::Pasteboard;
@@ -92,15 +55,15 @@ mod wl {
             match self.load() {
                 Ok(text) if text.is_empty() => Ok(None),
                 Ok(text) => Ok(Some(text)),
-                // Nothing offered for this seat — the Wayland spelling of an empty clipboard.
+                // Nothing offered for this seat: an empty clipboard.
                 Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
                 Err(e) => Err(e.to_string()),
             }
         }
 
         fn write_text(&mut self, text: &str) -> Result<(), String> {
-            // `store` is infallible: it hands the text to the clipboard thread, which then serves
-            // it to whoever asks for as long as we hold the seat.
+            // `store` hands the text to the clipboard thread, which serves it while we hold the
+            // seat.
             self.store(text.to_string());
             Ok(())
         }
@@ -111,12 +74,9 @@ mod wl {
     }
 }
 
-/// The `wl_display` behind the primary window, or `None` when this isn't a Wayland session (X11,
-/// macOS, Windows) — which is exactly the signal to fall back to [`arboard`].
-///
-/// Taken from bevy's own [`RawHandleWrapper`] rather than `WAYLAND_DISPLAY`: `smithay-clipboard`
-/// needs *our* connection (it works off the seat holding our keyboard focus), and the env var only
-/// says a Wayland session exists, not that winit chose it.
+/// The primary window's `wl_display`, or `None` off Wayland, which selects [`arboard`]. Read from
+/// the window handle, not `WAYLAND_DISPLAY`, because `smithay-clipboard` needs winit's own
+/// connection.
 #[cfg(all(unix, not(any(target_os = "macos", target_os = "android"))))]
 pub(crate) fn wayland_display(handle: Option<&RawHandleWrapper>) -> Option<*mut c_void> {
     match handle?.get_display_handle() {
@@ -125,8 +85,7 @@ pub(crate) fn wayland_display(handle: Option<&RawHandleWrapper>) -> Option<*mut
     }
 }
 
-/// Off the Wayland-capable platforms there is no `wl_display` to find, so the backend is always
-/// [`arboard`].
+/// Off the Wayland-capable platforms the backend is always [`arboard`].
 #[cfg(not(all(unix, not(any(target_os = "macos", target_os = "android")))))]
 pub(crate) fn wayland_display(_handle: Option<&RawHandleWrapper>) -> Option<*mut c_void> {
     None
@@ -135,12 +94,11 @@ pub(crate) fn wayland_display(_handle: Option<&RawHandleWrapper>) -> Option<*mut
 /// Build the Wayland backend for `display`.
 ///
 /// # Safety
-/// `display` must be a live `wl_display` that outlives the returned backend. It comes from bevy's
-/// [`RawHandleWrapper`], which holds an `Arc` on the window keeping the connection alive, and the
-/// backend lives in a resource dropped during app teardown.
+/// `display` must be a live `wl_display` that outlives the returned backend; the window handle's
+/// `Arc` keeps the connection alive until app teardown drops the backend.
 #[cfg(all(unix, not(any(target_os = "macos", target_os = "android"))))]
 fn open_wayland(display: *mut c_void) -> Box<dyn Pasteboard> {
-    // SAFETY: see the doc comment — `display` is winit's own live `wl_display`.
+    // SAFETY: `display` is winit's own live `wl_display`, per the doc comment.
     Box::new(unsafe { smithay_clipboard::Clipboard::new(display) })
 }
 
@@ -149,9 +107,8 @@ fn open_wayland(_display: *mut c_void) -> Box<dyn Pasteboard> {
     unreachable!("wayland_display() only yields Some on Wayland-capable platforms")
 }
 
-/// The session's display-server environment, appended to the clipboard log lines. A clipboard bug
-/// report is nearly useless without it — "paste does nothing on Linux" has at least three different
-/// causes depending on these three variables, and asking the reporter costs a round trip.
+/// The session's display-server variables, appended to the clipboard log lines, since a Linux
+/// paste failure depends on them.
 fn session_note() -> String {
     if !cfg!(unix) || cfg!(target_os = "macos") {
         return String::new();
@@ -165,23 +122,16 @@ fn session_note() -> String {
     )
 }
 
-/// The process-wide handle on the OS pasteboard.
-///
-/// A `NonSend` resource, for three reasons that all point the same way: neither backend is `Sync`,
-/// macOS's `NSPasteboard` must be touched from the main thread, and — the load-bearing one — the
-/// handle has to be *held* for the whole run or X11 copy silently does nothing (module docs).
+/// The process-wide handle on the OS pasteboard, a `NonSend` resource held for the whole run.
 #[derive(Default)]
 pub(crate) struct HostClipboard {
     backend: Option<Box<dyn Pasteboard>>,
-    /// Opening is attempted exactly once. A failure is sticky: a box with no usable clipboard
-    /// shouldn't re-attempt (and re-warn) on every keystroke.
+    /// Opening is attempted once; a failure is not retried on every keystroke.
     opened: bool,
 }
 
 impl HostClipboard {
-    /// Resolve the backend on first use. Deferred rather than done at startup because the Wayland
-    /// pointer comes from the window, and lazily because a run that never copies anything should
-    /// never open a pasteboard connection at all.
+    /// Resolve the backend on first use, once the window gives the Wayland pointer.
     fn ensure(&mut self, wl_display: Option<*mut c_void>) {
         if self.opened {
             return;
@@ -202,7 +152,7 @@ impl HostClipboard {
         }
     }
 
-    /// The pasteboard's text, or `None` if it's empty, non-text, or unavailable.
+    /// The pasteboard's text, or `None` if it is empty, non-text or unavailable.
     pub(crate) fn read(&mut self, wl_display: Option<*mut c_void>) -> Option<String> {
         self.ensure(wl_display);
         let backend = self.backend.as_mut()?;
@@ -219,7 +169,7 @@ impl HostClipboard {
         }
     }
 
-    /// Put `text` on the pasteboard (the copy/cut half).
+    /// Put `text` on the pasteboard.
     pub(crate) fn write(&mut self, wl_display: Option<*mut c_void>, text: &str) {
         self.ensure(wl_display);
         let Some(backend) = self.backend.as_mut() else {
diff --git a/crates/benilla-app/src/textinput/keymap.rs b/crates/benilla-app/src/textinput/keymap.rs
index 20026db0..88aa2b81 100644
--- a/crates/benilla-app/src/textinput/keymap.rs
+++ b/crates/benilla-app/src/textinput/keymap.rs
@@ -1,24 +1,13 @@
-//! The per-OS text-editing keymap: one pure table from a physical keypress + modifier snapshot
-//! to what it *means* for a focused EditBox — an engine [`EditAction`], or one of the three
-//! clipboard operations (kept host-side: they need the OS pasteboard). The engine owns what each
-//! action *does* (the byte-verified box law); this module owns only which chord means which
-//! action on which OS — the director's "everything OS-native" call (decision 0301).
-//!
-//! The Windows/Linux table doubles as the reference law where the 1.12 client had a chord at all
-//! (the key handler `0x77b160`: Ctrl+arrows word-granular, Ctrl+A/C/X/V, the Ctrl/Shift+Insert +
-//! Shift+Delete CUA mirrors). Ctrl+Backspace/Delete word deletes are modern-OS additions with no
-//! 1.12 counterpart; the whole macOS table is the platform's native law (Cmd/Option families),
-//! not the (Windows) reference's.
-//!
-//! One rule spans both of those platforms and is easy to miss: **AltGr is not Ctrl**. Windows and
-//! Linux both deliver AltGr as Ctrl+Alt, and European layouts type real letters with it, so the
-//! Ctrl letter chords all exclude it (decision 0702) — see [`chord_pc`].
+//! The per-OS text-editing keymap: a keypress and modifiers to an engine [`EditAction`] or a
+//! host-side clipboard operation. The Windows/Linux table is the reference's key handler
+//! (`0x77b160`: Ctrl+arrows by word, Ctrl+A/C/X/V, Ctrl/Shift+Insert, Shift+Delete).
+//! Deviation: macOS takes the Cocoa text-field chords and Ctrl+Backspace/Delete delete a word,
+//! because editing follows each OS's own text fields.
 
 use benilla_ui::script::{EditAction, EditUnit};
 use bevy::input::keyboard::KeyCode;
 
-/// The modifier snapshot a chord is read against. `sup` is the Super family — Cmd on macOS, the
-/// OS key elsewhere.
+/// The modifier snapshot a chord is read against; `sup` is Cmd on macOS, the OS key elsewhere.
 #[derive(Clone, Copy, Default)]
 pub(crate) struct Mods {
     pub(crate) shift: bool,
@@ -30,18 +19,17 @@ pub(crate) struct Mods {
 /// What a keypress means for the focused box.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub(crate) enum Chord {
-    /// A semantic edit — hand to `UiScript::editbox_action`.
+    /// A semantic edit for `UiScript::editbox_action`.
     Edit(EditAction),
     /// Copy the selection to the OS clipboard (`UiScript::editbox_copy` + host write).
     Copy,
-    /// Cut: copy + delete the selection.
+    /// Copy, then delete the selection.
     Cut,
     /// Paste the OS clipboard (host read + `UiScript::paste`).
     Paste,
 }
 
-/// The chord table: what `key` under `m` means, `None` when it means nothing (an unbound key —
-/// the caller falls through to plain character input, minus command-modified chars).
+/// What `key` under `m` means; `None` falls through to character input.
 pub(crate) fn chord(key: KeyCode, m: Mods, mac: bool) -> Option<Chord> {
     if mac {
         chord_mac(key, m)
@@ -50,9 +38,8 @@ pub(crate) fn chord(key: KeyCode, m: Mods, mac: bool) -> Option<Chord> {
     }
 }
 
-/// macOS: the Cocoa text-field law. Option = word, Cmd = line edge (moves and deletes alike);
-/// Cmd+A/C/X/V; plain Up/Down = history recall, Shift/Cmd'd Up/Down = the line edges. The
-/// Ctrl-plane (Cocoa's Emacs set: Ctrl+A/E/K…) is deliberately unbound — decision 0301.
+/// macOS, the Cocoa text-field chords: Option is a word, Cmd the line edge; plain Up/Down recall
+/// history. Cocoa's Emacs Ctrl set is left unbound.
 fn chord_mac(key: KeyCode, m: Mods) -> Option<Chord> {
     use EditUnit::{Char, Edge, Word};
     let mv = |unit, back| {
@@ -74,8 +61,7 @@ fn chord_mac(key: KeyCode, m: Mods) -> Option<Chord> {
                 mv(Char, back)
             }
         }
-        // Cmd+Up/Down = document start/end (the edges of a single-line box); Shift+Up/Down
-        // extends there; plain Up/Down = the chat box's history recall.
+        // Cmd+Up/Down is the box's start/end; Shift extends there.
         KeyCode::ArrowUp | KeyCode::ArrowDown => {
             let back = key == KeyCode::ArrowUp;
             if m.sup || m.shift {
@@ -90,8 +76,6 @@ fn chord_mac(key: KeyCode, m: Mods) -> Option<Chord> {
         }
         KeyCode::Home => mv(Edge, true),
         KeyCode::End => mv(Edge, false),
-        // The delete family: Cmd = clear to the line edge ("clear the whole input" from the
-        // end), Option = one word.
         KeyCode::Backspace => {
             if m.sup {
                 del(Edge, true)
@@ -118,8 +102,7 @@ fn chord_mac(key: KeyCode, m: Mods) -> Option<Chord> {
     }
 }
 
-/// Windows/Linux: the Ctrl law — the reference client's own chords where 1.12 had them
-/// (`0x77b160`), plus the modern Ctrl word-deletes.
+/// Windows/Linux: the reference's chords (`0x77b160`) plus the Ctrl word deletes.
 fn chord_pc(key: KeyCode, m: Mods) -> Option<Chord> {
     use EditUnit::{Char, Edge, Word};
     let mv = |unit, back| {
@@ -131,7 +114,7 @@ fn chord_pc(key: KeyCode, m: Mods) -> Option<Chord> {
     };
     let del = |unit, back| Some(Chord::Edit(EditAction::Delete { unit, back }));
     match key {
-        // Ctrl picks the word-granular helper — the ref's own fork on its Ctrl test `0x41f8f0(1)`.
+        // Ctrl picks the word helper, as the reference forks on its Ctrl test `0x41f8f0(1)`.
         KeyCode::ArrowLeft | KeyCode::ArrowRight => {
             let back = key == KeyCode::ArrowLeft;
             if m.ctrl {
@@ -140,18 +123,16 @@ fn chord_pc(key: KeyCode, m: Mods) -> Option<Chord> {
                 mv(Char, back)
             }
         }
-        // Plain Up/Down only: the history recall (a modified arrow means nothing here).
+        // Plain Up/Down only: history recall.
         KeyCode::ArrowUp if !(m.ctrl || m.alt || m.shift || m.sup) => {
             Some(Chord::Edit(EditAction::HistoryPrev))
         }
         KeyCode::ArrowDown if !(m.ctrl || m.alt || m.shift || m.sup) => {
             Some(Chord::Edit(EditAction::HistoryNext))
         }
-        // Ctrl+Home/End = plain Home/End in a single-line box.
         KeyCode::Home => mv(Edge, true),
         KeyCode::End => mv(Edge, false),
-        // Shift+Delete = Cut — the CUA mirror the ref itself honors (`0x77b160`) — else the
-        // modern Ctrl word-delete, else one char.
+        // Shift+Delete cuts, as the reference does (`0x77b160`).
         KeyCode::Backspace => {
             if m.ctrl {
                 del(Word, true)
@@ -168,17 +149,11 @@ fn chord_pc(key: KeyCode, m: Mods) -> Option<Chord> {
                 del(Char, false)
             }
         }
-        // The other CUA mirrors the ref honors: Ctrl+Insert = copy, Shift+Insert = paste.
+        // The reference's other CUA mirrors: Ctrl+Insert copies, Shift+Insert pastes.
         KeyCode::Insert if m.ctrl => Some(Chord::Copy),
         KeyCode::Insert if m.shift => Some(Chord::Paste),
-        // `&& !m.alt` is AltGr, and it is load-bearing on both Windows and Linux. AltGr is
-        // delivered as Ctrl+Alt, and it is how European layouts type real letters: on a Polish
-        // layout AltGr+A is `ą`, AltGr+C `ć`, AltGr+X `ź`. Without the exclusion those four
-        // keystrokes are eaten as Select-All/Copy/Cut/Paste and the letter never reaches the box —
-        // the character is simply untypeable in chat. Both platforms' own edit controls resolve it
-        // this way (Ctrl+Alt+A is not Select All anywhere AltGr exists), and the char-input branch
-        // in `input.rs` already lets the AltGr plane through for exactly this reason; the chord
-        // table has to agree with it or it just intercepts the key first. Decision 0702.
+        // `!m.alt` excludes AltGr, which arrives as Ctrl+Alt and types letters on European
+        // layouts (Polish AltGr+A is `ą`); must agree with the char-input branch in `input.rs`.
         KeyCode::KeyA if m.ctrl && !m.alt => Some(Chord::Edit(EditAction::SelectAll)),
         KeyCode::KeyC if m.ctrl && !m.alt => Some(Chord::Copy),
         KeyCode::KeyX if m.ctrl && !m.alt => Some(Chord::Cut),
@@ -216,7 +191,6 @@ mod tests {
     fn mac_table() {
         use EditAction::*;
         use EditUnit::*;
-        // Plain arrows: char moves; Option: word; Cmd: edge; Shift extends.
         assert_eq!(
             edit(chord(KeyCode::ArrowLeft, NONE, true)),
             Move {
@@ -253,7 +227,6 @@ mod tests {
                 extend: true
             }
         );
-        // Up/Down: plain = history; Shift or Cmd = the edges.
         assert_eq!(edit(chord(KeyCode::ArrowUp, NONE, true)), HistoryPrev);
         assert_eq!(edit(chord(KeyCode::ArrowDown, NONE, true)), HistoryNext);
         assert_eq!(
@@ -272,7 +245,6 @@ mod tests {
                 extend: false
             }
         );
-        // The delete family: Cmd+Backspace clears to the start, Option+Backspace one word.
         assert_eq!(
             edit(chord(KeyCode::Backspace, SUP, true)),
             Delete {
@@ -294,7 +266,6 @@ mod tests {
                 back: false
             }
         );
-        // Cmd+A/C/X/V; the Ctrl plane is unbound; plain letters mean nothing.
         assert_eq!(edit(chord(KeyCode::KeyA, SUP, true)), SelectAll);
         assert_eq!(chord(KeyCode::KeyC, SUP, true), Some(Chord::Copy));
         assert_eq!(chord(KeyCode::KeyX, SUP, true), Some(Chord::Cut));
@@ -307,7 +278,6 @@ mod tests {
     fn pc_table() {
         use EditAction::*;
         use EditUnit::*;
-        // Ctrl+arrows = the ref's word fork; plain = char.
         assert_eq!(
             edit(chord(KeyCode::ArrowLeft, CTRL, false)),
             Move {
@@ -324,10 +294,8 @@ mod tests {
                 extend: true
             }
         );
-        // Plain Up/Down = history; any modifier unbinds them.
         assert_eq!(edit(chord(KeyCode::ArrowUp, NONE, false)), HistoryPrev);
         assert_eq!(chord(KeyCode::ArrowUp, SHIFT, false), None);
-        // Home/End; Ctrl+Backspace/Delete word deletes.
         assert_eq!(
             edit(chord(KeyCode::End, SHIFT, false)),
             Move {
@@ -350,20 +318,16 @@ mod tests {
                 back: false
             }
         );
-        // Ctrl+A/C/X/V + the CUA mirrors (Ctrl/Shift+Insert, Shift+Delete).
         assert_eq!(edit(chord(KeyCode::KeyA, CTRL, false)), SelectAll);
         assert_eq!(chord(KeyCode::KeyC, CTRL, false), Some(Chord::Copy));
         assert_eq!(chord(KeyCode::KeyV, CTRL, false), Some(Chord::Paste));
         assert_eq!(chord(KeyCode::Insert, CTRL, false), Some(Chord::Copy));
         assert_eq!(chord(KeyCode::Insert, SHIFT, false), Some(Chord::Paste));
         assert_eq!(chord(KeyCode::Delete, SHIFT, false), Some(Chord::Cut));
-        // Super means nothing on this side.
         assert_eq!(chord(KeyCode::KeyA, SUP, false), None);
     }
 
-    /// AltGr — delivered as Ctrl+Alt on both Windows and Linux — types real letters on European
-    /// layouts (`ą`/`ć`/`ź` on a Polish one), so it must fall through to character input rather
-    /// than being swallowed as the Ctrl clipboard chord. Regression for decision 0702.
+    /// AltGr arrives as Ctrl+Alt and types letters on European layouts (Polish `ą`, `ć`, `ź`).
     #[test]
     fn altgr_letters_are_not_clipboard_chords() {
         const ALTGR: Mods = Mods {
@@ -378,7 +342,6 @@ mod tests {
                 "AltGr+{key:?} must reach character input, not act as a clipboard chord"
             );
         }
-        // The exclusion is exactly AltGr: plain Ctrl is still the chord.
         assert_eq!(
             edit(chord(KeyCode::KeyA, CTRL, false)),
             EditAction::SelectAll
diff --git a/crates/benilla-app/src/textinput/mod.rs b/crates/benilla-app/src/textinput/mod.rs
index c3a15318..e3d010fa 100644
--- a/crates/benilla-app/src/textinput/mod.rs
+++ b/crates/benilla-app/src/textinput/mod.rs
@@ -1,28 +1,7 @@
-//! **The one text-input law, host half.** Every text field in the client — the FrameXML EditBoxes
-//! (chat, `/who`, the StaticPopup) and the three glue-screen fields (login account/password, the
-//! character name, the delete confirmation) — resolves its keystrokes here.
-//!
-//! There are three parts, and the split is deliberate:
-//!
-//! - [`keymap`] — *which chord means what*, per OS. The one place Ctrl+V vs Cmd+V is decided
-//!   (decision 0301).
-//! - [`clipboard`] — *the OS pasteboard*, one held handle per process, per-platform backend
-//!   (decision 0702).
-//! - [`feed_key`] (here) — the glue between them and the **engine's** byte-verified box law
-//!   ([`EditBoxState`], decision 0704). It owns no editing semantics of its own.
-//!
-//! ## Why this module exists
-//!
-//! The editing law was reachable only through the Lua UI runtime, so the glue screens — which have
-//! no Lua VM — each hand-rolled a three-case imitation: append a printable char, Backspace, Tab.
-//! No caret movement, no selection, no Ctrl+A, and no clipboard at all. Worse, they matched on
-//! winit's `logical_key`, which is `Character("v")` for Ctrl+V, so **pasting into the login box
-//! typed a literal `v` into the password**. Four fields, four different laws, three of them wrong.
-//!
-//! Now the law is [`EditBoxState`]'s (pure, no Lua — decision 0704) and the *routing* is this
-//! module's, so a field gets the whole thing by owning an `EditBoxState` and calling [`feed_key`].
-//! The FrameXML path keeps its own dispatcher because it must also fire Lua handlers and route
-//! focus through the widget arena, but it reads the same [`keymap`] and the same [`clipboard`].
+//! The host half of text input: [`keymap`] maps chords per OS, [`clipboard`] holds the OS
+//! pasteboard, and [`feed_key`] routes a key into the engine's [`EditBoxState`], which owns the
+//! editing itself. The glue-screen fields call [`feed_key`]; the FrameXML EditBoxes have their own
+//! dispatcher, which fires Lua handlers, over the same keymap and clipboard.
 
 use std::ffi::c_void;
 
@@ -38,16 +17,13 @@ pub(crate) mod keymap;
 pub(crate) use clipboard::{wayland_display, HostClipboard};
 pub(crate) use keymap::{chord, Chord, Mods};
 
-/// Adds the process-wide OS pasteboard. Nothing else here is a system: [`feed_key`] is a plain
-/// function each screen calls from its own input pass, because every screen already owns its focus
-/// model (the login form's two-field enum, the dialog's single box) and inverting that into a
-/// component-driven focus would be churn for no gain.
+/// Adds the process-wide OS pasteboard; [`feed_key`] is called from each screen's own input pass.
 pub(crate) struct TextInputPlugin;
 
 impl Plugin for TextInputPlugin {
     fn build(&self, app: &mut App) {
-        // Held for the whole run: on X11 dropping the handle *is* clearing the clipboard
-        // (decision 0702). `NonSend` — no backend is `Sync`, NSPasteboard is main-thread-only.
+        // Held for the whole run: on X11 dropping the handle clears the clipboard. `NonSend`: no
+        // backend is `Sync`, and NSPasteboard is main-thread-only.
         app.init_non_send_resource::<HostClipboard>();
     }
 }
@@ -62,10 +38,7 @@ pub(crate) fn mods_now(keys: &ButtonInput<KeyCode>) -> Mods {
     }
 }
 
-/// Which characters a field accepts. The box law's own `numeric` flag covers digits-only; this
-/// covers the one other rule the client has — a character name is letters (the create screen's
-/// `is_ascii_alphabetic` guard). It is applied to **pasted** text as well as typed, which the old
-/// hand-rolled screens could not do at all, having no paste.
+/// Which characters a field accepts, typed or pasted; the box's own `numeric` flag covers digits.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum CharFilter {
     /// Everything printable (the login boxes).
@@ -94,20 +67,14 @@ impl CharFilter {
 /// What [`feed_key`] did with a key press.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum FieldKey {
-    /// The field handled it — an edit, a caret move, or a clipboard operation. The screen must not
-    /// also act on this key.
+    /// The field handled it; the screen must not also act on this key.
     Consumed,
-    /// Not a text-editing key. The screen decides (ENTER submits, ESCAPE cancels, TAB cycles
-    /// focus) — those are the screen's semantics, not the field's, exactly as the FrameXML box
-    /// hands ENTER/ESCAPE/TAB to its own scripts.
+    /// Not a text-editing key; the screen decides, as the FrameXML box hands ENTER, ESCAPE and TAB
+    /// to its scripts.
     Passthrough,
 }
 
-/// Feed one key press to `field`. The whole shared law in one call: the per-OS chord table decides
-/// what the chord means, [`EditBoxState`] executes it, and the clipboard trio resolves against the
-/// held host pasteboard.
-///
-/// `wl_display` comes from [`wayland_display`] — `None` off Wayland.
+/// Feed one key press to `field`. `wl_display` comes from [`wayland_display`], `None` off Wayland.
 pub(crate) fn feed_key(
     field: &mut EditBoxState,
     ev: &KeyboardInput,
@@ -119,8 +86,7 @@ pub(crate) fn feed_key(
     if ev.state != ButtonState::Pressed {
         return FieldKey::Passthrough;
     }
-    // The three box-event keys are the screen's, always — even though a chord table entry could
-    // claim them. This mirrors the FrameXML split (`script::editbox::key_input`).
+    // The box-event keys are always the screen's, as in `script::editbox::key_input`.
     if matches!(
         ev.key_code,
         KeyCode::Enter | KeyCode::NumpadEnter | KeyCode::Escape | KeyCode::Tab
@@ -144,20 +110,17 @@ pub(crate) fn feed_key(
             }
             Chord::Paste => {
                 if let Some(text) = clipboard.read(wl_display) {
-                    // Filter before the box sees it, so a name box can't be pasted full of digits.
                     field.paste(&filter.keep(&text));
                 }
             }
         }
         return FieldKey::Consumed;
     }
-    // Plain character input. A command-modified char never types (Cmd/Ctrl+L must not insert "l"),
-    // but Ctrl+Alt passes: that is AltGr, the plane European layouts type real characters with —
-    // the same guard the FrameXML feed uses, and the reason the chord table excludes AltGr too
-    // (decision 0702).
+    // A command-modified char never types, but Ctrl+Alt (AltGr) does; the FrameXML feed and the
+    // chord table use the same guard.
     if !(mods.sup || (mods.ctrl && !mods.alt)) {
         if let Some(text) = &ev.text {
-            // C0 control characters are consumed-but-inert, as in the box's own `char_input`.
+            // C0 control characters are dropped, as in the box's own `char_input`.
             let printable = filter.keep(text);
             if !printable.is_empty() {
                 field.insert(&printable);
@@ -168,9 +131,7 @@ pub(crate) fn feed_key(
     FieldKey::Passthrough
 }
 
-/// A fresh single-line field with `max_letters` (0 = unlimited) and optional password masking —
-/// the glue screens' constructor, so they never hand-assemble an [`EditBoxState`] and quietly miss
-/// a flag.
+/// A fresh single-line field with `max_letters` (0 = unlimited) and optional password masking.
 pub(crate) fn field(max_letters: usize, password: bool) -> EditBoxState {
     EditBoxState {
         max_letters,
@@ -179,9 +140,8 @@ pub(crate) fn field(max_letters: usize, password: bool) -> EditBoxState {
     }
 }
 
-/// Advance the caret blink and report whether it is currently drawn — the box's own blink law
-/// (`E+0x370`/`E+0x374`, ctor default 0.5 s), so a glue caret and a chat caret blink identically.
-/// An unfocused field always reports "hidden" without accumulating.
+/// Advance the caret blink and report whether it is drawn: the box's own blink (`E+0x370`,
+/// `E+0x374`, default 0.5 s). An unfocused field is hidden and does not accumulate.
 pub(crate) fn tick_caret(field: &mut EditBoxState, focused: bool, dt: f32) -> bool {
     if !focused {
         return false;
@@ -200,9 +160,6 @@ pub(crate) fn tick_caret(field: &mut EditBoxState, focused: bool, dt: f32) -> bo
 mod tests {
     use super::*;
 
-    /// The name box takes letters only — and the filter runs on **pasted** text too, which is the
-    /// case the old hand-rolled screens could not express at all (they had no paste). Regression
-    /// for decision 0704.
     #[test]
     fn letters_filter_applies_to_pasted_text() {
         assert_eq!(CharFilter::Letters.keep("Bob123"), "Bob");
@@ -210,16 +167,12 @@ mod tests {
         assert_eq!(CharFilter::Letters.keep("123"), "");
     }
 
-    /// `Any` keeps everything printable but still drops control characters — a pasted newline must
-    /// never reach a single-line box as a literal.
     #[test]
     fn any_filter_keeps_printables_and_drops_controls() {
         assert_eq!(CharFilter::Any.keep("pass word!"), "pass word!");
         assert_eq!(CharFilter::Any.keep("one\ntwo\r"), "onetwo");
     }
 
-    /// A letters-only paste still honours the box's own cap, because the filter feeds
-    /// `EditBoxState::paste`, which enforces `max_letters` like any other insert.
     #[test]
     fn a_filtered_paste_still_obeys_max_letters() {
         let mut f = field(4, false);
@@ -227,8 +180,7 @@ mod tests {
         assert_eq!(f.text, "abcd");
     }
 
-    /// A password field masks its display but never its buffer — the login password box relies on
-    /// this, and on `selected_text` yielding the mask rather than the secret.
+    /// Copying from a password field yields the mask, not the secret.
     #[test]
     fn a_password_field_masks_display_and_copies() {
         let mut f = field(0, true);
diff --git a/crates/benilla-app/src/transport.rs b/crates/benilla-app/src/transport.rs
index b4e54a57..e758a3f1 100644
--- a/crates/benilla-app/src/transport.rs
+++ b/crates/benilla-app/src/transport.rs
@@ -1,34 +1,22 @@
-//! Transports (decision 0438) — the client-computed cycle, two drives, one subsystem.
+//! Transports, whose cycle the client computes. The server never streams a transport's position,
+//! only an anchor: the movement block's `UPDATE_FLAG_TRANSPORT` u32, its path-progress ms at
+//! create, re-sent on every re-create.
 //!
-//! The server never streams a transport's position. It sends one **anchor** — the movement
-//! block's `UPDATE_FLAG_TRANSPORT` u32, the server's path-progress ms clock at create — and the
-//! client computes everything else, per GameObject type:
+//! - Type 15 (`MO_TRANSPORT`, boats and zeppelins): a timetable from `TaxiPathNode.dbc` and the
+//!   template's `(taxiPathId, moveSpeed, accelRate)` ([`benilla_formats::TransportTimetable`]),
+//!   sampled at `(anchor + elapsed) % period`.
+//! - Type 11 (`TRANSPORT`, elevators and trams): the `TransportAnimation.dbc` keyframe path keyed
+//!   by template entry, at `spawn + R(spawn_quat)·lerp(keyframes, (anchor + elapsed) % period)`
+//!   ([`benilla_formats::elevator_sample`], the reference's `0x5f6280`; vmangos does the same in
+//!   `ElevatorTransport::Update`, `Transport.cpp:396`).
 //!
-//! - **Type 15 (`MO_TRANSPORT`, boats/zeppelins):** the whole timetable (per-leg Catmull-Rom
-//!   splines + stop-to-stop trapezoid times, [`benilla_formats::TransportTimetable`]) from
-//!   `TaxiPathNode.dbc` and the template's `(taxiPathId, moveSpeed, accelRate)` tuple; the boat
-//!   sits at `timetable((anchor + local_elapsed) % period)` every frame.
-//! - **Type 11 (`TRANSPORT`, elevators/lifts/trams — decision 0438 phase 3's second consumer):**
-//!   the authored keyframe path from `TransportAnimation.dbc` keyed by the **template entry**;
-//!   the car sits at `spawn + R(spawn_quat)·lerp(keyframes, (anchor + local_elapsed) % period)`
-//!   ([`benilla_formats::elevator_sample`] — the client's path evaluator `0x5f6280`; vmangos
-//!   `ElevatorTransport::Update` is the same math server-side).
-//!
-//! Re-creates (map transitions, the server's mid-course "update frames") re-anchor the clock;
-//! decision 0318's replace semantics make that free.
-//!
-//! The armed entity is the ordinary streamed GameObject — the display (WMO for boats, M2 for
-//! elevator cars), its collider, and its `Transform` all pre-exist on the GO-entity path
-//! (decision 0438 §2); this module only *moves* it. Riding hangs off the same component set for
-//! both drives — the mover's platform frame keys on [`Transport`], not on the drive.
+//! This module only moves the streamed GameObject; riding keys on [`Transport`], not the drive.
 
 use std::collections::HashMap;
 use std::sync::Arc;
 use std::time::Instant;
 
-// avian's own public AABB/tree republish system, registered by name below. Aliased because the
-// chain's concern is *when* it runs, not whose it is — and because the upstream name says what it
-// does to colliders, not why this app needs it a second time each frame.
+// avian's own AABB and collider-tree refresh, run a second time each frame in the chain below.
 use avian3d::collider_tree::update_moved_collider_aabbs as republish_moved_collider_aabbs;
 use avian3d::prelude::{Collider, Position, RigidBody, Rotation};
 use benilla_formats::{
@@ -49,46 +37,19 @@ pub(crate) struct TransportPlugin;
 impl Plugin for TransportPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<Timetables>()
-            // `.after(AssetSet::Open)` is load-bearing: the chain resource lands via Commands in
-            // that set, and an unordered Startup system races it and silently finds no
-            // `WorldAssets` (bit us on the first live run — every downstream log went quiet).
+            // After `AssetSet::Open`, whose Commands insert `WorldAssets`; unordered, this finds
+            // none and silently does nothing.
             .add_systems(
                 Startup,
                 setup_taxi_nodes.after(benilla_assets::AssetSet::Open),
             )
             .add_systems(
                 Update,
-                // After the net drain (fresh anchors/re-anchors applied), before the player's
-                // input stage — the boat must be at its this-frame pose before the mover reads
-                // the world (phase 2's platform carry rides exactly this edge).
-                //
-                // **[`republish_moved_collider_aabbs`] is the third link, and it is here because
-                // of a general engine truth, not a lift one** (decision 1663): *a collider moved
-                // in `Update` is invisible to `Update`'s own spatial queries until the next
-                // physics step, by up to one frame of its own travel.* avian refreshes
-                // `ColliderAabb`, `EnlargedAabb` and the `ColliderTrees` proxies in
-                // `ColliderTreeSystems::UpdateAabbs`, which sits in `PhysicsSchedule` — i.e. in
-                // `FixedPostUpdate`, **before** `Update` — while [`tick_transports`] writes the
-                // deck's pose *in* `Update`. Every `Update`-side spatial query
-                // (`SpatialQuery::aabb_intersections_with_aabb`, which is how the mover's
-                // ground/step/slide casts enumerate candidates — `benilla_world::collision`) is
-                // therefore pruned against the deck's **previous-frame** box.
-                //
-                // At 60 Hz that is centimetres and harmless. On one long frame — a backgrounded
-                // window is at least one ~1 s frame (decisions 0713/0906) — a Thunder Bluff lift
-                // descends 7.3 yd while its box stays put, the box ends up *above* the rider it
-                // is carrying, the down-probe enumerates no deck at all, and the rider is
-                // declared airborne on the very platform they are standing on. Two such frames in
-                // a row and `Time<Virtual>`'s clamped 250 ms lands a full gravity step on the
-                // second one: the body drops 1.2 yd through the deck and never re-earns it,
-                // because the deck is now above the probe. That is the reported fall-through, and
-                // 1663 records the measured chain.
-                //
-                // The system is avian's own, public, and read-only on `LastPhysicsTick` — it
-                // writes no tick resource, so running it a second time in the frame is
-                // idempotent, and the next physics step simply recomputes what has not moved
-                // since. It sweeps *every* collider, not just transports; 1663 records the
-                // measured per-frame cost of that sweep in a streamed outdoor scene.
+                // After the net drain and before input, so the deck is posed before the mover
+                // reads the world. avian refreshes collider AABBs in `FixedPostUpdate`, before
+                // `Update`, so without [`republish_moved_collider_aabbs`] the mover's casts see the
+                // deck's previous-frame box, above its rider after one long frame. It writes no
+                // tick resource, so a second run is idempotent; it sweeps every collider.
                 (
                     arm_transports,
                     reseek_ridden_transport_at_worldport,
@@ -102,10 +63,8 @@ impl Plugin for TransportPlugin {
                     .after(benilla_world::schedule::WorldStage::Net)
                     .before(benilla_world::schedule::WorldStage::Input),
             )
-            // …and the ride frame LAST, after the mover has decided what we are standing on this
-            // frame ([`crate::player::Player::ride`] is written inside `PlayerControlSet`). Its
-            // consumers — the particle and ribbon sims — run in `PostUpdate`, so the deferred
-            // insert has landed by the time anything reads it.
+            // The ride frame last, after `PlayerControlSet` decides what we stand on; its
+            // consumers, the particle and ribbon sims, run in `PostUpdate`.
             .add_systems(
                 Update,
                 stamp_ride_frames.after(crate::player::PlayerControlSet),
@@ -113,50 +72,39 @@ impl Plugin for TransportPlugin {
     }
 }
 
-/// The create-block anchor: the server's path-progress ms + the local instant it arrived.
-/// Inserted (and re-inserted, on every re-create) by the net apply's `object_create` arm for a
-/// GameObject whose movement block carried `UPDATE_FLAG_TRANSPORT`.
+/// The create-block anchor: the server's path-progress ms and the local instant it arrived,
+/// inserted on every create that carries `UPDATE_FLAG_TRANSPORT`.
 #[derive(Component)]
 pub(crate) struct TransportAnchor {
     pub(crate) progress_ms: u32,
     pub(crate) at: Instant,
 }
 
-/// A pending type-11 elevator/lift: everything its arm needs, captured off the create block by
-/// the net apply (no template round-trip — the keyframe path is keyed by the template **entry**,
-/// which the create's `OBJECT_FIELD_ENTRY` already carries). Replaced by [`Transport`] once the
-/// keyframe catalog answers; a GO whose entry has no authored path stays seeded-and-frozen (the
-/// same silence the reference affords it).
+/// A pending type-11 lift, captured off the create block: its keyframe path is keyed by the
+/// template entry, which `OBJECT_FIELD_ENTRY` carries, so no template query is needed.
 #[derive(Component)]
 pub(crate) struct ElevatorSeed {
-    /// `gameobject_template` entry — `TransportAnimation.dbc`'s `TransportID` key.
+    /// `gameobject_template` entry, `TransportAnimation.dbc`'s `TransportID` key.
     pub(crate) entry: u32,
-    /// The stationary spawn position (raw WoW coords) — the movement block's `HAS_POSITION`
-    /// slot (a transport create never carries `GAMEOBJECT_POS_*`).
+    /// Spawn position (raw WoW coords), from the movement block: a transport create carries no
+    /// `GAMEOBJECT_POS_*`.
     pub(crate) base_pos: [f32; 3],
-    /// The spawn facing (wire orientation, WoW radians) — the car's constant rendered heading.
+    /// Spawn facing (WoW radians), the car's constant heading.
     pub(crate) yaw: f32,
-    /// `GAMEOBJECT_ROTATION` — the spawn's local-rotation quaternion the keyframe offsets
-    /// rotate through. `None` on a wire that carried no component (falls back to a pure-yaw
-    /// quat built from `yaw`, which is exactly what the live spawn rows encode anyway).
+    /// `GAMEOBJECT_ROTATION`, the spawn quaternion the keyframe offsets rotate through; `None`
+    /// falls back to the pure-yaw quat, which is what spawn rows encode.
     pub(crate) quat: Option<[f32; 4]>,
 }
 
-/// A ticking transport. Armed by [`arm_transports`]: a boat once the ask-once template answer
-/// (the `(taxiPathId, moveSpeed, accelRate)` tuple) lands; an elevator as soon as the keyframe
-/// catalog is open (its create block already carried everything else).
+/// A ticking transport, armed by [`arm_transports`].
 #[derive(Component)]
 pub(crate) struct Transport {
     drive: Drive,
-    /// Last frame's `moving` — the dock/depart edge detector behind the trace log (the phase-1
-    /// reconciliation instrument: a "the boat isn't where the server thinks" report is settled
-    /// against these timestamps, never by eye — decision 0438 phasing).
+    /// Last frame's `moving`, for the dock and depart log lines.
     was_moving: bool,
 }
 
-/// The two cycle evaluators behind one component (decision 0438 §5: elevators are "the same
-/// subsystem, second consumer" — the rider frame, the worldport spare, and the instruments all
-/// key on [`Transport`] and never care which drive is underneath).
+/// The two cycle evaluators; consumers key on [`Transport`], never on the drive.
 enum Drive {
     /// Type 15: the client-computed taxi-path timetable.
     Taxi(Arc<TransportTimetable>),
@@ -164,13 +112,9 @@ enum Drive {
     Lift(Lift),
 }
 
-/// **No map field, deliberately** (decision 1654). A lift's map is not a datum it owns: vmangos
-/// hands a player the whole map's transport set on entry (`Map::SendInitTransports`) and takes it
-/// back on the way out, so a type-11 is only ever resident for someone standing on its own map —
-/// the car is always on the map *you* are on. 0611 stamped `CurrentMap` here at arm time, which in
-/// the login frame is the startup seed (`arm_transports` runs a stage before `player::wire_in`
-/// writes the real map), and the off-map hide below then hid every lift on Kalimdor for the whole
-/// session — the director's Thunder Bluff report, and B168's Gnomeregan lift.
+/// No map field: vmangos sends a player the map's whole transport set on entry
+/// (`Map::SendInitTransports`, `Map.cpp:1719`), so a lift is always on the viewer's map. At login
+/// `CurrentMap` is still the startup seed when lifts arm, so a stamped map would hide them.
 struct Lift {
     frames: Arc<Vec<ElevatorKeyframe>>,
     period_ms: u32,
@@ -181,8 +125,7 @@ struct Lift {
 }
 
 impl Transport {
-    /// Which drive is underneath — for the instruments only (`WOW_LIFT_CENSUS`); no consumer
-    /// keys on it (decision 0438 §5: the drive is private by design).
+    /// Which drive is underneath, for the instruments only (`WOW_LIFT_CENSUS`).
     pub(crate) fn drive_label(&self) -> &'static str {
         match &self.drive {
             Drive::Taxi(_) => "taxi",
@@ -197,26 +140,15 @@ impl Transport {
         }
     }
 
-    /// The transport's live cycle position for an anchor — the rider math needs the same
-    /// number the tick used, so it lives here.
+    /// The live cycle position for an anchor, shared by the tick and the rider math.
     pub(crate) fn cycle_ms(&self, anchor: &TransportAnchor) -> u32 {
         let progress = u64::from(anchor.progress_ms) + anchor.at.elapsed().as_millis() as u64;
         (progress % u64::from(self.period_ms().max(1))) as u32
     }
 
-    /// Re-anchor this transport's clock so its cycle sits at the head of `map_id`'s leg, and
-    /// return the sample there **plus the cycle instant it was moved to, if it moved at all**.
-    /// `None` if the drive has no leg on that map (a lift never does).
-    ///
-    /// The anchor is stored as `progress_ms` + the instant it was taken, so seeking is simply
-    /// "restamp both": the clock runs on from the new cycle position exactly as it would have.
-    ///
-    /// **The second element must be how the caller decides whether anything happened.** The stored
-    /// `progress_ms` is the server's own uptime-scale path progress until a seek replaces it —
-    /// unbounded, and nothing like a cycle position — so "did it change?" cannot be answered by
-    /// comparing it against a `% period` cycle value. Doing exactly that made the healthy
-    /// already-agreed crossing print `our path clock was 157334 ms behind` with a target of
-    /// 35081741 ms, which is 9.7 hours: the server's uptime, not a position in a 350 s loop.
+    /// Re-anchor the clock to the head of `map_id`'s leg unless the cycle is already on that map;
+    /// returns the sample and the cycle instant it moved to, if it moved (the only sound test, as
+    /// `progress_ms` is uptime-scale until a seek). `None` when no leg is on that map.
     pub(crate) fn reseek_to_map(
         &self,
         anchor: &mut TransportAnchor,
@@ -226,10 +158,7 @@ impl Transport {
             return None;
         };
         let cycle = self.cycle_ms(anchor);
-        // **Already there — leave the clock alone.** The healthy crossing is the common case, and
-        // seeking anyway would rewind the cycle to the head of the frame we are mid-way through,
-        // throwing away up to a leg of progress and jerking the deck backwards under the rider.
-        // Only a clock that actually disagrees with the server gets corrected.
+        // Already there: seeking would rewind to the leg's head and jerk the deck backwards.
         let here = t.sample(cycle);
         if here.map == map_id {
             return Some((here, None));
@@ -240,11 +169,9 @@ impl Transport {
         Some((t.sample(target), Some(target)))
     }
 
-    /// Whether any leg of this transport's cycle lies on `map_id` — the cross-map worldport's
-    /// spare predicate (decision 0455). **A lift always answers no** (1654): the spare exists so a
-    /// *ridden boat* survives the seam mid-cycle, and a lift never spans one — the server re-sends
-    /// the destination map's whole transport set on arrival (`SendInitTransports`), so a lift
-    /// despawns and streams back like every other object.
+    /// Whether any leg of the cycle lies on `map_id`, the cross-map worldport's spare predicate. A
+    /// lift answers no: the server re-sends the destination's transports on arrival
+    /// (`SendInitTransports`), so a lift despawns and streams back like any object.
     pub(crate) fn touches_map(&self, map_id: u32) -> bool {
         match &self.drive {
             Drive::Taxi(t) => t.touches_map(map_id),
@@ -252,11 +179,8 @@ impl Transport {
         }
     }
 
-    /// The cycle sample — position/heading/map/motion at `cycle_ms`, both drives. `here` is the
-    /// map the viewer is on: a **taxi** ignores it (its timetable knows which continent each leg
-    /// lies on, which is the whole point of the off-map hide), and a **lift** reports it, because
-    /// a type-11 exists only for players standing on its own map. That is the honest answer to
-    /// "which map is this position expressed in", and it is what [`Lift`] refuses to store.
+    /// The sample at `cycle_ms`. `here` is the viewer's map: a taxi ignores it (its timetable
+    /// knows each leg's map), a lift reports it, as a type-11 exists only on the viewer's map.
     fn sample(&self, cycle_ms: u32, here: u32) -> TransportSample {
         match &self.drive {
             Drive::Taxi(t) => t.sample(cycle_ms),
@@ -272,18 +196,14 @@ impl Transport {
         }
     }
 
-    /// The live sample for an anchor — the same pose the tick writes this frame. For
-    /// instruments (the crossing probe reads dock state + the deck drop point off it).
+    /// The live sample for an anchor, the pose the tick writes this frame; for instruments.
     pub(crate) fn sample_at(&self, anchor: &TransportAnchor, here: u32) -> TransportSample {
         self.sample(self.cycle_ms(anchor), here)
     }
 }
 
-/// The transport path data: `TaxiPathNode.dbc` + the per-path timetables built from it, shared
-/// across instances (the Menethil boat and its return-leg twin share one build; `None` in
-/// `built` = a failed build, remembered so it isn't retried every frame) — and the
-/// `TransportAnimation.dbc` keyframe catalog for the type-11 lifts, shared the same way (the
-/// two Mesa cars of one entry share one `Arc`).
+/// `TaxiPathNode.dbc` with the per-path timetables built from it (`None` in `built` is a failed
+/// build, not retried), and the `TransportAnimation.dbc` lift keyframes, both shared by path.
 #[derive(Resource, Default)]
 struct Timetables {
     nodes: Option<TaxiPathNodes>,
@@ -302,7 +222,7 @@ fn setup_taxi_nodes(mut timetables: ResMut<Timetables>, world_assets: Option<Res
             info!("taxi path nodes: {} paths", nodes.len());
             timetables.nodes = Some(nodes);
         }
-        // No taxi data ⇒ boats render frozen at their create pose — degraded, not broken.
+        // Without taxi data boats stay at their create pose.
         Err(e) => warn!("taxi path nodes unavailable, transports stay put: {e:#}"),
     }
     match load_elevator_paths(&mut chain) {
@@ -310,30 +230,20 @@ fn setup_taxi_nodes(mut timetables: ResMut<Timetables>, world_assets: Option<Res
             info!("transport animations: {} lift paths", paths.len());
             timetables.elevators = Some(paths);
         }
-        // Same degradation as the boats: no keyframes ⇒ cars park at their spawn point.
+        // Without keyframes cars stay at their spawn point.
         Err(e) => warn!("TransportAnimation unavailable, lifts stay put: {e:#}"),
     }
 }
 
-/// Arm anchored GameObjects: a **boat** (type 15) once its template answer (the taxi tuple)
-/// lands — build (or reuse) the path's timetable; a **lift** (type 11, [`ElevatorSeed`]) as
-/// soon as the keyframe catalog is open — its create block already carried everything else.
-/// The query is a handful of entities at most (the map's transports), so polling is free; the
-/// boat's ask-once template request was already made at create (`go_templates.request` in the
-/// apply arm).
-///
-/// **The lift arm reads no world state at all** (1654): at login every type-11 on the map arms in
-/// the same drain that carries `SMSG_LOGIN_VERIFY_WORLD`, one stage before `player::wire_in`
-/// writes `CurrentMap` — so anything captured from the world *here* is captured stale.
+/// Arm anchored GameObjects: a boat once its template's taxi tuple lands, a lift
+/// ([`ElevatorSeed`]) once the keyframe catalog is open. The lift arm reads no world state: at
+/// login it runs a stage before `player::wire_in` writes `CurrentMap`.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 fn arm_transports(
     mut commands: Commands,
     mut timetables: ResMut<Timetables>,
     templates: Res<GameObjectTemplates>,
-    // `Or<…, With<ElevatorSeed>>`: a re-created lift is already armed (`Transport` present) but
-    // carries a fresh seed from the new create block — it re-enters here so the seed is consumed
-    // (a fresh, identical arm) instead of lingering. Boats never carry a seed, so for them the
-    // filter is exactly `Without<Transport>` as before.
+    // A re-created lift is already armed but carries a fresh seed, so it re-enters to consume it.
     pending: Query<
         (Entity, &Guid, Option<&ElevatorSeed>),
         (
@@ -346,20 +256,18 @@ fn arm_transports(
         return;
     }
     for (entity, guid, seed) in &pending {
-        // — the lift arm (decision 0438 phase 3's second consumer) —
+        // The lift arm.
         if let Some(seed) = seed {
             let Timetables {
                 elevators, lifts, ..
             } = &mut *timetables;
             let Some(paths) = elevators.as_ref() else {
-                continue; // no client data — stays frozen
+                continue; // no client data: stays frozen
             };
             let Some(frames) = paths.entry(seed.entry) else {
-                // No authored path for this entry: park it at its spawn pose for good (the
-                // real client's behaviour for a pathless type-11). The anchor goes too, so
-                // the entity leaves this query instead of re-polling as a mistaken boat — and
-                // the spawn-hidden state lifts (anchored creates spawn `Hidden` until their
-                // first ticked pose, which a parked car never gets).
+                // No authored path: park it at its spawn pose, as the reference does. The anchor
+                // goes too, so it leaves this query, and it is unhidden (anchored creates spawn
+                // `Hidden` until their first ticked pose).
                 warn!(
                     "transport: no TransportAnimation path for entry {} (guid {:#x}) — parked",
                     seed.entry, guid.0
@@ -368,9 +276,7 @@ fn arm_transports(
                     .entity(entity)
                     .remove::<(ElevatorSeed, TransportAnchor)>()
                     .insert(Visibility::default())
-                    // The one insert-based visibility flip: `Visibility`'s require chain just
-                    // re-added the sweep row a net root sheds at spawn — strip it again
-                    // (benilla_world::vis_chain).
+                    // Inserting `Visibility` re-adds the sweep row a net root sheds at spawn.
                     .vis_chain_only();
                 continue;
             };
@@ -379,8 +285,7 @@ fn arm_transports(
                 .or_insert_with(|| Arc::new(frames.to_vec()))
                 .clone();
             let period_ms = elevator_period_ms(&frames);
-            // A wire that carried no rotation quat falls back to the pure-yaw quat of the
-            // spawn facing — the identical encoding every live 1.12 spawn row uses.
+            // No rotation on the wire: the pure-yaw quat, the encoding 1.12 spawn rows use.
             let quat = seed.quat.unwrap_or_else(|| {
                 let (s, c) = (seed.yaw * 0.5).sin_cos();
                 [0.0, 0.0, s, c]
@@ -406,21 +311,19 @@ fn arm_transports(
             continue;
         }
 
-        // — the boat arm —
+        // The boat arm.
         let Some(mo) = templates.get(guid.0).and_then(|t| t.mo_transport) else {
-            continue; // template answer not in yet — next frame
+            continue; // template answer not in yet: next frame
         };
         let Timetables { nodes, built, .. } = &mut *timetables;
         let Some(nodes) = nodes.as_ref() else {
-            continue; // no client data — stays frozen
+            continue; // no client data: stays frozen
         };
         let timetable = built
             .entry(mo.taxi_path_id)
             .or_insert_with(|| {
                 let t = nodes.path(mo.taxi_path_id).and_then(|path| {
-                    // The build self-pins its cycle length to the real client's own bookkeeping
-                    // (`0x5f4cc0`, bit-exact against all nine server-sniff periods), so the
-                    // period on the label IS the server's.
+                    // The build pins its period to the reference's own bookkeeping (`0x5f4cc0`).
                     let t = TransportTimetable::build(path, mo.move_speed, mo.accel_rate)?;
                     info!(
                         "transport: path {} timetable built — period {} ms",
@@ -438,10 +341,8 @@ fn arm_transports(
             })
             .clone();
         if let Some(timetable) = timetable {
-            // Kinematic, not the GO-attach default of Static: this body moves every frame, and
-            // avian rebuilds the kinematic collider tree per step by design (the static tree is
-            // incremental, tuned for immobile geometry). The mover's casts see it either way —
-            // spatial queries traverse all trees — but the label matches the motion.
+            // Kinematic, not the GO default of Static: it moves every frame, and avian's static
+            // tree is tuned for immobile geometry.
             commands.entity(entity).insert((
                 Transport {
                     drive: Drive::Taxi(timetable),
@@ -453,13 +354,9 @@ fn arm_transports(
     }
 }
 
-/// The per-frame transport tick — the client's own `(progress + anchor) % period` leg walk
-/// (`0x5f50a0`, decision 0438): sample the timetable, write the pose. Translation +
-/// rotation only — the renderer bakes model scale into the transform (`write_pose`'s law).
-/// Off-map samples (the boat is sailing the other continent's leg) hide the model; the server
-/// removes the GO around the same time, so this is belt-and-braces for the transition frames.
-/// **A lift can never trip it** (decision 1654): its sample is expressed in the map passed in, so
-/// the term is a boat's alone — which is what it always meant, and what 0611's stamped map broke.
+/// The per-frame tick, the reference's `(progress + anchor) % period` leg walk (`0x5f50a0`):
+/// sample and write translation and rotation (model scale is baked in by the renderer). An
+/// off-map sample, a boat on the other continent's leg, hides the model; a lift never trips it.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 fn tick_transports(
     current_map: Option<Res<CurrentMap>>,
@@ -491,11 +388,7 @@ fn tick_transports(
                 sample.map,
             );
         }
-        // Write-on-change only, on every component here (1473): a docked leg samples the
-        // identical pose each frame, and the unconditional writes this replaces re-dirtied the
-        // deck's whole subtree — transform propagation over every submesh plus a `Visibility`
-        // re-propagation — for every docked elevator on the map, every frame.
-        // Boats only, by construction — see this system's doc.
+        // Write on change only: a docked deck samples the same pose every frame.
         if sample.map != current_map.0 {
             visibility.set_if_neq(Visibility::Hidden);
             continue;
@@ -505,23 +398,10 @@ fn tick_transports(
     }
 }
 
-/// Write one sampled transport pose into the render transform **and** avian's own components.
-///
-/// The avian mirror is not optional: its `Transform`→`Position` sync runs in the physics schedule
-/// (before `Update`), so without it the mover's same-frame casts see the deck one frame behind —
-/// ~0.5 yd astern at cruise. Since 1663 the chain republishes the moved collider's AABB inline
-/// too, so a pose written here is fully visible to this frame's queries however far it jumped.
-///
-/// Write-on-change on every component (1473): a docked leg samples the identical pose each frame,
-/// and unconditional writes re-dirty the deck's whole subtree — transform propagation over every
-/// submesh plus a `Visibility` re-propagation — for every docked elevator on the map, every frame.
-///
-/// **Takes `&mut Mut<Transform>`, not `&mut Transform`, and that is the whole point of the
-/// signature.** Reaching through `Mut` with `DerefMut` sets the change flag unconditionally, so a
-/// helper that took a plain `&mut Transform` would re-dirty the deck's subtree on every call —
-/// exactly the per-frame propagation 1473 removed, reintroduced by the act of factoring the write
-/// out of its loop. The existing `a_docked_lift_stops_dirtying_its_transform_and_visibility` test
-/// catches it; this comment is here so the next factoring does not have to rediscover why.
+/// Write a sampled pose into the transform and avian's `Position`/`Rotation`: avian syncs
+/// `Transform` before `Update`, so without the mirror this frame's casts see last frame's deck.
+/// Takes `&mut Mut<Transform>` so the change flag is set only on a real change; a plain
+/// `&mut Transform` would re-dirty the deck's whole subtree every frame.
 fn write_deck_pose(
     sample: &TransportSample,
     transform: &mut Mut<Transform>,
@@ -530,7 +410,7 @@ fn write_deck_pose(
 ) {
     let translation = benilla_assets::coords::wow_to_bevy(sample.pos);
     let heading = Quat::from_rotation_y(sample.heading);
-    // Read through `Deref` (no flag), write through `DerefMut` (flag) — only when it changed.
+    // Read through `Deref` (no flag), write through `DerefMut` (flag), only on a change.
     if transform.translation != translation || transform.rotation != heading {
         transform.translation = translation;
         transform.rotation = heading;
@@ -547,37 +427,18 @@ fn write_deck_pose(
     }
 }
 
-/// **Put the ridden transport on the destination map in the worldport frame itself** (decision
-/// 2026), so the rider's world pose is not composed through the source continent's coordinates.
+/// Put the ridden transport on the destination map in the worldport frame, so `wire_in` composes
+/// the rider's pose through the destination continent's coordinates rather than off its grid.
 ///
-/// **This exists because of a divergence of ours, not a gap in the server.** The server does send
-/// a fresh create for the boat we are standing on: `Map::SendInitSelf` builds it *first*
-/// (`Map.cpp:1698-1702`), which is the only reason `SendInitTransports` then skips
-/// `player->GetTransport()` (`Map.cpp:1719`) — a skip that reads like an omission and is not one.
-/// That create re-anchors the clock exactly. But it lands a round trip *after* the worldport ack,
-/// and decision 0455's spared transport is asked for a pose in the worldport frame itself, before
-/// it. This fills that window; the server's create then supersedes it.
+/// The reference keeps nothing across `SMSG_NEW_WORLD`: `0x401bc0` destroys every object
+/// (`0x467700` → `0x467800`), builds a manager on the destination map (`0x464ff0`) and rebuilds
+/// rider and transport from the post-ack creates. We spare the ridden transport instead; the
+/// server's create for it (`Map.cpp:1698-1702`, which is why `SendInitTransports` skips it at
+/// `Map.cpp:1726`) re-anchors it a round trip later, and this fills that window.
 ///
-/// **The reference has no such window, because it keeps nothing.** `SMSG_NEW_WORLD` (`0x401bc0`)
-/// destroys every object in the manager (`0x467700` → `0x467800`) and builds a fresh one already
-/// set to the destination map (`0x464ff0`), then rebuilds both rider and transport from the
-/// post-ack CREATE blocks; the worldport composes nothing at all, and streams around the raw wire
-/// pose. Our spare — and therefore this — is the price of not doing that. Whether to adopt the
-/// reference's purge-and-rebuild wholesale is the recorded follow-on (2026).
-///
-/// **Why this system writes the pose itself instead of leaving it to [`tick_transports`].**
-/// `CurrentMap` is still the *source* map this frame — `player::wire_in` inserts the new one, and
-/// a command insert lands at the next flush — so `tick_transports` would compare the freshly
-/// sought sample against the old map, take its off-map arm, and hide the boat with its transform
-/// unwritten. This system knows the destination map explicitly from the message, so it needs no
-/// resource at all. From the next frame `tick_transports` agrees and takes over.
-///
-/// **Order matters and is enforced by the chain:** this runs before `tick_transports` (which must
-/// not undo it) and both run `.before(WorldStage::Input)`, so `wire_in` composes the rider's world
-/// pose through a transform that is already the destination continent's. Without that, the rider
-/// is composed through the source continent's coordinates — off the destination's WDT grid, where
-/// nothing streams, the loading cover cannot clear and there is no ground under the body.
-#[allow(clippy::type_complexity)] // one Bevy system's full input set — as `tick_transports`
+/// It writes the pose itself because `CurrentMap` still names the source map this frame, so
+/// [`tick_transports`] would hide the deck. Order: before it, and before `WorldStage::Input`.
+#[allow(clippy::type_complexity)] // one Bevy system's full input set
 fn reseek_ridden_transport_at_worldport(
     mut worldports: MessageReader<crate::net::WorldportMessage>,
     player: Res<crate::player::Player>,
@@ -592,8 +453,7 @@ fn reseek_ridden_transport_at_worldport(
     )>,
 ) {
     for w in worldports.read() {
-        // Only a transfer the server carried us through on a transport, and only while we are in
-        // fact still on one — the same predicate `wire_in`'s riding branch uses.
+        // Only a transport transfer while still riding, `wire_in`'s riding predicate.
         if w.transport_entry.is_none() {
             continue;
         }
@@ -614,15 +474,9 @@ fn reseek_ridden_transport_at_worldport(
             );
             continue;
         };
-        // Silent when we were already there (the healthy crossing — the two clocks agreed and the
-        // seek was a no-op, which `moved_to == None` is the ONLY sound way to detect). Loud when it
-        // moved, carrying **how far behind the server our own path clock was**: this is the only
-        // measurement of client-vs-server transport drift the client can take.
-        //
-        // Measured **forward around the cycle**, because a crossing is very often the cycle wrap
-        // (on taxi path 241 the Kalimdor legs are the *first* frames, so "cross to Kalimdor" IS
-        // the wrap): a plain `after - before` reports a 144 ms nudge as −356 140 ms and reads as
-        // the clock running half a cycle ahead, which is the opposite of what happened.
+        // When the clock moved, log how far behind the server's our path clock was, measured
+        // forward around the cycle: a crossing is often the cycle wrap (path 241's Kalimdor legs
+        // come first), where a plain `after - before` goes negative.
         if let Some(after) = moved_to {
             let period = transport.period_ms().max(1);
             let behind =
@@ -639,33 +493,15 @@ fn reseek_ridden_transport_at_worldport(
     }
 }
 
-/// Frames the ridden transport's map may disagree with [`CurrentMap`] before it is a fault rather
-/// than the one-frame seam artefact — see [`watch_ridden_transport_map`]. Three, matching the
-/// loading screen's own `CLEAR_AFTER_READY_FRAMES` debounce: long enough to outlast any single
-/// deferred resource write, short enough that a real stall is named while it is still on screen.
+/// Frames the ridden transport's map may disagree with [`CurrentMap`] before it is logged; one
+/// frame of it is normal at every crossing.
 const DISAGREEMENT_GRACE_FRAMES: u32 = 3;
 
-/// **Tripwire: the boat we are STANDING ON says it is on another map.**
-///
-/// [`tick_transports`] leaves an off-map transport's `Transform` unwritten (and hides it) — for a
-/// boat sailing the other continent's leg that is right, and for a boat we are *riding* it is the
-/// one state that must never happen. Its pose is what [`crate::player::wire_in`] composes our own
-/// world position from at a cross-map worldport (decision 0455), so a frozen source-map pose puts
-/// the body at *that continent's* coordinates on *this* map: off the destination's WDT grid, where
-/// nothing streams, the loading cover cannot clear (`total == 0` never reads ready) and there is no
-/// ground to stand on. That is the 2026-09-05 report — a minute of loading screen on the
-/// Booty Bay ferry, then a fall through the world.
-///
-/// It arises from our own path clock disagreeing with the server's about *when* the crossing
-/// happens — measured live at 32 ms and 144 ms on the Orgrimmar zeppelin, in the two directions.
-/// One line per sustained entry into the state, with the numbers needed to size it.
-///
-/// **A single frame of it is normal and must not warn.** `CurrentMap` is written by
-/// `player::wire_in` with a command insert, so it lands one frame after the worldport that
-/// [`reseek_ridden_transport_at_worldport`] handled — for that one frame the freshly sought
-/// transport legitimately reads the *new* map while the resource still reads the old, which is
-/// the inverse of the pathology and fired on every healthy crossing before this grace existed.
-/// Hence a consecutive-frame count: only a state that *persists* is the one worth a line.
+/// Tripwire: the transport we ride samples another map. Its frozen off-map pose is what
+/// [`crate::player::wire_in`] composes our body through at a worldport, which lands it off the
+/// destination's grid; it arises when our path clock and the server's disagree about the
+/// crossing. One frame is normal: `CurrentMap` is written by a command insert, a frame after
+/// [`reseek_ridden_transport_at_worldport`], so only a persisting state logs, once per entry.
 fn watch_ridden_transport_map(
     current_map: Option<Res<CurrentMap>>,
     player: Res<crate::player::Player>,
@@ -713,28 +549,21 @@ fn watch_ridden_transport_map(
     );
 }
 
-/// An observed mover's pose in a transport's local frame — the `MOVEFLAG_ONTRANSPORT` tail of
-/// its `LIVING` create block or `MSG_MOVE_*` relay (decision 0438 phase 2: "observed riders stop
-/// discarding it"). [`compose_riders`] re-anchors the entity through the named transport's live
-/// matrix every frame; the local pose itself only changes when the next packet lands (no
-/// between-packet extrapolation in the deck frame yet — deck NPCs stand still, and a walking
-/// rider corrects at its packet rate). Inserted/updated/removed by the net apply.
+/// An observed mover's pose in a transport's frame, the `MOVEFLAG_ONTRANSPORT` tail of its
+/// `LIVING` create block or `MSG_MOVE_*` relay. [`compose_riders`] carries it every frame; the
+/// local pose changes only per packet, with no extrapolation in the deck frame.
 #[derive(Component)]
 pub(crate) struct TransportRider {
     pub(crate) transport_guid: u64,
-    /// Rider position in the transport's local frame, raw WoW coords (as on the wire).
+    /// Position in the transport's frame, raw WoW coords.
     pub(crate) local_pos: [f32; 3],
-    /// Rider facing in the transport's local frame (WoW radians) — world facing is
-    /// `local + transport yaw` (the GetAbsoluteFacing law).
+    /// Facing in the transport's frame (WoW radians); world facing is `local + transport yaw`.
     pub(crate) local_orientation: f32,
 }
 
-/// Compose every observed rider's world pose through its transport's this-frame matrix — chained
-/// after [`tick_transports`], so the deck carries its riders in the same frame it moves. Also
-/// refreshes [`RemoteMotion`]'s canonical WoW pose so every downstream consumer (nameplates, the
-/// animation selector, the landing predictor) sees the carried position; the extrapolator ran
-/// earlier (WorldStage::Net) and this simply wins the frame. A rider whose boat isn't streamed
-/// in (or is off-map) keeps its last relayed world pose — the server despawns the pair together.
+/// Compose each observed rider's world pose through its transport's this-frame pose, after
+/// [`tick_transports`], and refresh [`RemoteMotion`]'s WoW pose to match. A rider whose transport
+/// is not streamed keeps its last world pose; the server despawns the pair together.
 fn compose_riders(
     guid_index: Res<crate::net::GuidIndex>,
     boats: Query<&Transform, (With<Transport>, Without<TransportRider>)>,
@@ -766,39 +595,21 @@ fn compose_riders(
     }
 }
 
-/// **Re-ground a deck-splined rider onto the deck it is walking on** (decision 1936's correction).
+/// Re-ground a rider on a grounded deck spline onto the deck. The reference treats a grounded
+/// `SMSG_MONSTER_MOVE_TRANSPORT` spline as a plain one: the transport guid is in neither
+/// `0x616cb0`'s predicate nor `0x634040`'s dispatch, `0x616d03` zeroes the Z delta, and the WALK
+/// resolver `0x6367b0` re-derives Z from a world trace (`0x636e52`) at the composed position,
+/// whose class mask from `0x6315f0` (`0x100111`) has the `0x100000` bit that admits GameObject
+/// meshes, the deck among them.
 ///
-/// The tempting reading — "a transport spline's Z is authoritative, because there is no terrain
-/// under a boat" — is what benilla shipped for a few hours, and the reference refutes it. The
-/// transport guid appears in **neither** `0x616cb0`'s predicate **nor** `0x634040`'s dispatch: a
-/// grounded `SMSG_MONSTER_MOVE_TRANSPORT` spline takes the *same* fork as a plain one,
-/// `0x616d03` zeroes its Z-delta and the WALK resolver `0x6367b0` re-derives Z off the world trace
-/// (`0x636e52`: `pos.z -= hitDistance`). The reason that does not drop the unit into the sea is
-/// that the query runs at the **composed world position**, and the class mask `0x6315f0` yields
-/// `0x100111` whose `0x100000` bit unconditionally admits GameObject meshes — a boat's `.wmo`
-/// being in the global map-object list precisely because it is a type-11/15 GameObject.
+/// It runs here, not in [`crate::net::ground_clamp_creatures`] (in `WorldStage::Net`), because
+/// only after [`compose_riders`] and [`republish_moved_collider_aabbs`] are the rider's position
+/// and the deck's box this frame's. The height goes to the `Transform`, not `local_pos`, which
+/// [`compose_riders`] recomposes from every frame.
 ///
-/// **So the deck's grounding is the ordinary grounding, moved one step later.** It cannot live in
-/// [`crate::net::ground_clamp_creatures`] with every other unit's, because that system runs inside
-/// `WorldStage::Net` — *before* [`compose_riders`] — where a deck rider's `Transform` is still
-/// last frame's composed pose and its fresh position exists only as a transport-local offset. Here
-/// the deck is at its this-frame pose, its collider AABB has just been republished
-/// ([`republish_moved_collider_aabbs`], decision 1663 — without which the probe would be pruned
-/// against the deck's previous-frame box) and the rider's world position is on the transform. One
-/// probe, at the reference's own moment.
-///
-/// The corrected Y is written to the `Transform` and not back into
-/// [`TransportRider::local_pos`], deliberately: [`compose_riders`] recomputes the world pose from
-/// the local one every frame, so a write-back would be re-derived away next frame anyway, and the
-/// correction is idempotent as it stands. [`crate::net::RemoteMotion`]'s canonical pose moves with
-/// it, as it does in `compose_riders`.
-///
-/// **A named gap.** The reference has a *third* regime this does not model: `0x616af0`'s anti-warp
-/// guard snaps `pos := base + sampledOffset` verbatim — wire Z included — and bypasses the
-/// re-ground entirely whenever the horizontal step exceeds 3 yd (`[0x80c5bc]` = 9.0, squared) or
-/// 60 yd/s. For a creature freshly placed on a deck that is the common *first* substep, so our
-/// first frame re-grounds where the reference would take the wire Z. It settles to the same place
-/// on the next frame either way.
+/// Not modelled: `0x616af0`'s anti-warp guard takes the wire Z verbatim, skipping the re-ground,
+/// when the horizontal step exceeds 3 yd (`[0x80c5bc]` = 9.0, squared) or 60 yd/s, the common
+/// first substep on a deck; ours re-grounds that frame, and both settle the same the next.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 fn ground_deck_riders(
     world: benilla_world::collision::WorldCollision,
@@ -811,21 +622,19 @@ fn ground_deck_riders(
         (With<TransportRider>, Without<Transport>),
     >,
 ) {
-    /// The probe's reach above and below the rider's seat — the creature clamp's own numbers
-    /// (`GROUND_CLAMP_UP`/`_DOWN`), for the same reason: enough to clear a slightly-high server Z
-    /// and to follow a step down, not enough to grab a deck one storey up.
+    /// The probe's reach above and below the seat, the creature clamp's
+    /// (`GROUND_CLAMP_UP`/`_DOWN`): short of a deck one storey up.
     const UP: f32 = 2.5;
     const DOWN: f32 = 4.0;
     for (mut transform, motion, spline) in &mut riders {
-        // Only a GROUNDED deck path. A flying one owns its altitude (the `0x200` bit is the same
-        // one that decides the point encoding and the resolver arm), and a world-frame spline is
-        // `ground_clamp_creatures`' business, not ours.
+        // Only a grounded deck path: a flying one (the `0x200` bit) owns its altitude, and a
+        // world-frame spline is `ground_clamp_creatures`'.
         if spline.deck.is_none() || !spline.grounded {
             continue;
         }
         let origin = transform.translation + Vec3::Y * UP;
         let Some(hit) = world.ray_body(origin, Dir3::NEG_Y, UP + DOWN) else {
-            continue; // nothing under the rider — leave the composed pose alone
+            continue; // nothing under the rider: keep the composed pose
         };
         let y = origin.y - hit.distance;
         if y == transform.translation.y {
@@ -838,22 +647,12 @@ fn ground_deck_riders(
     }
 }
 
-/// Publish the **ride frame** onto every model standing on a transport — the reference's
-/// `SetMoveBase` install (`0x617170`/`0x618970` → `0x718910` → `[CM2Model+0x17c]`), which is the
-/// frame a rider's world-space effects are *stored* in ([`benilla_world::ride_frame`]).
-///
-/// Two riders, one component. The **body we steer** takes the mover's own platform attach
-/// ([`crate::player::Player::ride_entity`] — the deck collider that grounded us), and every
-/// **observed** rider takes the wire's transport tail ([`TransportRider`]). Everything hung off
-/// either — a held weapon, its enchant streamer, a spell kit — inherits it through the
-/// `ParentModel` chain rather than being stamped itself, which is exactly how the reference
-/// propagates `[model+0x17c]` to a model's children every frame (`0x7142c1` in the animate
-/// kernel `0x714260`).
-///
-/// Why this is a component and not a field on `Transport`: the fact is *per rider*, it changes on
-/// a step, and `benilla-world` — which owns the emitters that consume it — cannot see either
-/// `Player` or `TransportRider`. Decision 1591 named this seam and left it unbuilt; the director's
-/// weapon-trail report on the Thunder Bluff lift is what it costs.
+/// Publish the ride frame onto every model standing on a transport, the reference's `SetMoveBase`
+/// install (`0x617170`/`0x618970` → `0x718910` → `[CM2Model+0x17c]`), the frame a rider's
+/// world-space effects are stored in ([`benilla_world::ride_frame`]). The body we steer takes the
+/// mover's platform attach, an observed rider its [`TransportRider`] tail; attached models inherit
+/// it through `ParentModel`, as the reference propagates `[model+0x17c]` to children every frame
+/// (`0x7142c1` in the animate kernel `0x714260`).
 fn stamp_ride_frames(
     mut commands: Commands,
     player: Res<crate::player::Player>,
@@ -867,14 +666,12 @@ fn stamp_ride_frames(
         want.insert(me, deck);
     }
     for (rider, on) in &riders {
-        // A rider whose transport isn't streamed in keeps no frame: there is no pose to store
-        // against, and the server despawns the pair together anyway (`compose_riders`' note).
+        // A rider whose transport is not streamed in keeps no frame.
         if let Some(&deck) = guid_index.0.get(&on.transport_guid) {
             want.insert(rider, deck);
         }
     }
-    // Reconcile rather than re-stamp: an unchanged rider must not touch its component at all, so
-    // change detection stays quiet on a deck full of passengers.
+    // Reconcile rather than re-stamp, so an unchanged rider's component is never touched.
     for (model, current) in &stamped {
         match want.remove(&model) {
             Some(deck) if deck == current.0 => {}
@@ -896,11 +693,8 @@ mod tests {
     use super::*;
     use benilla_formats::ElevatorKeyframe;
 
-    /// The Ratchet–Booty Bay ferry's real timetable (taxi path 241) — the seam the 2026-09-05
-    /// report rode. Real data on purpose: a hand-built path is not a substitute here, because the
-    /// builder's map-change skip dance plus the client period pin can silently truncate a short
-    /// synthetic cycle so the far continent's legs are never reachable, and a test written against
-    /// that proves nothing about the code under test.
+    /// The Ratchet–Booty Bay ferry's real timetable (taxi path 241): the builder can truncate a
+    /// short synthetic cycle so the far continent's legs are never reached.
     fn ferry_241(chain: &mut benilla_formats::Chain) -> Transport {
         let cat = benilla_formats::load_taxi_path_nodes(chain).expect("TaxiPathNode.dbc");
         let nodes = cat.path(241).expect("taxi path 241 (Ratchet–Booty Bay)");
@@ -911,15 +705,8 @@ mod tests {
         }
     }
 
-    /// **The seam re-anchor moves the clock onto the destination map — and only when it has to**
-    /// (decision 2026). Composing the rider through a transport still sampling the *source*
-    /// continent is what put a body at Booty Bay's coordinates on Kalimdor, off the destination's
-    /// tile grid, where nothing streams and the loading cover cannot clear.
-    ///
-    /// Path 241 is the case that matters and the reason this is not a synthetic test: its Kalimdor
-    /// legs are the *first* frames of the cycle, so "cross to Kalimdor" is the **cycle wrap**, not
-    /// an interior map change. A seek that only handled the interior case would leave exactly the
-    /// reported ferry broken.
+    /// Path 241's Kalimdor legs are the first frames of the cycle, so crossing to Kalimdor is the
+    /// cycle wrap, not an interior map change.
     #[test]
     fn the_seam_reanchor_lands_on_the_new_map_and_leaves_an_agreeing_clock_alone() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -927,7 +714,7 @@ mod tests {
         let transport = ferry_241(&mut chain);
         let period = transport.period_ms();
 
-        // Ask the built timetable where each continent's legs actually fall rather than assuming.
+        // Where each continent's legs fall in the built timetable.
         let on = |map: u32| {
             (0..period)
                 .step_by(500)
@@ -936,8 +723,7 @@ mod tests {
         };
         let (on_azeroth, on_kalimdor) = (on(0), on(1));
 
-        // Standing on Azeroth's leg, told we are now on Kalimdor: the clock moves, and it moves
-        // onto Kalimdor — the stored anchor, not merely the returned sample.
+        // On Azeroth's leg, told Kalimdor: the stored anchor moves onto Kalimdor.
         let mut anchor = TransportAnchor {
             progress_ms: on_azeroth,
             at: Instant::now(),
@@ -956,9 +742,7 @@ mod tests {
             "the stored anchor must itself sit on Kalimdor, not just the returned sample"
         );
 
-        // Already there and told so: the clock is left exactly as it was. Seeking anyway would
-        // rewind to the head of the frame we are mid-way through and jerk the deck backwards
-        // under the rider — the healthy crossing is the common case and must cost nothing.
+        // Already on Kalimdor: the clock is left alone.
         let mut anchor = TransportAnchor {
             progress_ms: on_kalimdor,
             at: Instant::now(),
@@ -971,16 +755,12 @@ mod tests {
             anchor.progress_ms, on_kalimdor,
             "an agreeing clock must not be touched"
         );
-        // **And it must SAY it did nothing.** The stored anchor is the server's uptime-scale path
-        // progress until a seek replaces it, so a caller cannot infer "unchanged" by comparing it
-        // against a cycle value — it reported a 9.7-hour raw progress as a 157 s clock skew until
-        // this flag existed.
         assert_eq!(
             moved_to, None,
             "a no-op seek must report that it did not move the clock"
         );
 
-        // A map the path never visits has no answer — the caller warns rather than inventing one.
+        // A map the path never visits has no answer.
         let mut anchor = TransportAnchor {
             progress_ms: on_azeroth,
             at: Instant::now(),
@@ -992,9 +772,6 @@ mod tests {
         );
     }
 
-    /// A **lift** is never re-anchored across a seam (1654): a type-11 exists only for players on
-    /// its own map, it is despawned and re-created like any other object, and it has no taxi path
-    /// to seek along at all.
     #[test]
     fn a_lift_has_no_seam_to_reanchor() {
         let lift = Transport {
@@ -1008,7 +785,7 @@ mod tests {
         assert!(lift.reseek_to_map(&mut anchor, 1).is_none());
     }
 
-    /// A two-frame pause path at `base_pos` — the same lift both tests below drive.
+    /// A two-frame pause path at `base_pos`.
     fn parked_lift() -> Lift {
         Lift {
             frames: Arc::new(vec![
@@ -1028,11 +805,7 @@ mod tests {
         }
     }
 
-    /// A docked lift goes QUIET: `tick_transports` writes pose and visibility on change only
-    /// (1473) — the unconditional writes it replaces re-dirtied every docked elevator's whole
-    /// subtree (transform + `Visibility` propagation over all its submeshes), map-wide, every
-    /// frame. A two-frame pause path samples the identical pose forever, so after the first
-    /// arming write nothing may be marked changed.
+    /// A pause path samples the same pose forever, so after the arming write nothing changes.
     #[test]
     fn a_docked_lift_stops_dirtying_its_transform_and_visibility() {
         #[derive(Resource, Default)]
@@ -1077,17 +850,12 @@ mod tests {
         );
     }
 
-    /// **A lift is never hidden by the off-map term, whatever `CurrentMap` says** (decision 1654).
-    /// The off-map hide is the boat's: a ferry mid-cycle on the other continent's leg. 0611 gave
-    /// the lift a `map` stamped from `CurrentMap` at arm time — and `arm_transports` runs a stage
-    /// *before* `player::wire_in` writes that resource, so at login every type-11 on the map armed
-    /// against the startup seed and the term hid all of them for the session (Thunder Bluff; B168).
-    /// Driving the tick on a map the arm never saw is exactly that shape, and the car must show.
+    /// At login lifts arm before `CurrentMap` is written, so the off-map hide must never judge a
+    /// lift against a map.
     #[test]
     fn a_lift_is_visible_on_whatever_map_the_viewer_is_on() {
         let mut app = App::new();
-        // Alterac Valley — a real 1.12 map that carries no type-11 GO at all, so it is a map no
-        // lift could ever have been stamped with. The point is that the value cannot matter.
+        // Alterac Valley, a map with no type-11 GameObject: the value must not matter.
         app.insert_resource(CurrentMap(30))
             .add_systems(Update, tick_transports);
         let lift = app
@@ -1103,8 +871,7 @@ mod tests {
                     at: Instant::now(),
                 },
                 Transform::default(),
-                // As the net apply spawns an anchored transport: hidden until its first ticked
-                // pose. If the tick declines to unhide it, the car is solid and invisible.
+                // Anchored transports spawn hidden until their first ticked pose.
                 Visibility::Hidden,
             ))
             .id();
@@ -1114,7 +881,7 @@ mod tests {
             Some(&Visibility::Inherited),
             "the tick must unhide a lift on the viewer's map, not judge it against a stamped one"
         );
-        // And the pose it wrote is the car's own — base + its (zero) local offset, in Bevy axes.
+        // The pose is the base plus its zero offset, in Bevy axes.
         assert_eq!(
             app.world().get::<Transform>(lift).map(|t| t.translation),
             Some(benilla_assets::coords::wow_to_bevy([10.0, 20.0, 30.0])),
diff --git a/crates/benilla-app/src/tutorial.rs b/crates/benilla-app/src/tutorial.rs
index cd86f53c..bbf1eb0a 100644
--- a/crates/benilla-app/src/tutorial.rs
+++ b/crates/benilla-app/src/tutorial.rs
@@ -1,30 +1,20 @@
-//! The tutorial system (decision 1976; the reference's `[0x4b5150, 0x4b5a60)`): the two
-//! bit banks, the fire-once trigger, the acknowledge-and-send setter, the timers, the popup
-//! sound, and the trigger sites the app can produce — everything behind the stock
-//! `TutorialFrame.xml`.
+//! The tutorial system (the reference's `[0x4b5150, 0x4b5a60)`) behind the stock
+//! `TutorialFrame.xml`: two bit banks, the fire-once trigger, the acknowledge-and-send setter,
+//! the timers, the popup sound and the trigger sites.
 //!
-//! ## Two banks, not one (`0xb711b8`, `0xb711e4`)
+//! Both banks (`0xb711b8`, `0xb711e4`) are filled from the same `SMSG_TUTORIAL_FLAGS`; until it
+//! lands nothing fires. Bank A is fire-once: [`Tutorials::trigger`] tests and sets it and raises
+//! `TUTORIAL_TRIGGER(id + 1)`, never sending. Bank B is acknowledged: [`Tutorials::acknowledge`]
+//! tests it, sets both banks, cancels the id's timer and sends `CMSG_TUTORIAL_FLAG`. So A ⊇ B, and
+//! doing the thing suppresses its tutorial, account-wide.
 //!
-//! Both are filled byte for byte from the same `SMSG_TUTORIAL_FLAGS`, and until it lands no
-//! tutorial can fire. **Bank A** is the fire-once bank: [`Tutorials::trigger`] tests it, sets it,
-//! and raises `TUTORIAL_TRIGGER(id + 1)` — never sending. **Bank B** is the acknowledged bank:
-//! [`Tutorials::acknowledge`] (Lua's `FlagTutorial` and the C++ auto-acknowledge sites) tests it,
-//! sets the bit in BOTH banks, cancels the id's pending timer, and sends `CMSG_TUTORIAL_FLAG`.
-//! `ClearTutorials`/`ResetTutorials` write both banks and send. So A ⊇ B, and doing the thing
-//! (moving, chatting, adding a friend…) suppresses the tutorial about it, account-wide.
+//! `TriggerTutorial(id, delayMs)` (`0x4b5390`): with a zero delay the `TutorialPopup` cue plays and
+//! the event fires now; otherwise a timer holds it (the 10 s Targeting popup is the one site). The
+//! reference bounds-checks nothing; an id past the bank is a no-op here.
 //!
-//! ## The trigger (`0x4b5390`)
-//!
-//! `TriggerTutorial(id, delayMs)`: no bank → silent; bank-A bit set → silent; else the bit is
-//! set and, with a zero delay, the `TutorialPopup` cue plays and the event fires now; with any
-//! other delay (unsigned — the 10 s Targeting popup is the one site) a timer holds it. The
-//! reference bounds-checks nothing; ours refuses an id past the bank as a no-op.
-//!
-//! ## The sites (the callers of `0x4b5390` and `0x4b54c0`)
-//!
-//! Fifty-one trigger sites and seven acknowledge sites exist in the reference. The ones this app
-//! can produce are wired — the self-descriptor edges here, the packets and drains at their own
-//! seams through [`TutorialEvent`] — and the record names the rest with their conditions.
+//! The reference has fifty-one trigger sites and seven acknowledge sites (the callers of
+//! `0x4b5390` and `0x4b54c0`); the ones this app can produce reach here through
+//! [`TutorialEvent`] or the self-descriptor edges below.
 
 use std::time::{Duration, Instant};
 
@@ -37,8 +27,7 @@ use crate::net::{ClientCommand, EnteredWorldMessage, NetCommands, ObjectStore, S
 use crate::player::Player;
 use crate::ui_script::{UiFeed, UiInput};
 
-/// The popup cue `0x4b5390` plays on both legs (`0x846b68`), gated on `MasterSoundEffects` at
-/// the mixer like every SFX kit.
+/// The popup cue `0x4b5390` plays on both legs (`0x846b68`).
 const TUTORIAL_POPUP_SOUND: &str = "TutorialPopup";
 
 /// The internal (0-based) ids of the sites this app produces, named by their published title.
@@ -90,12 +79,11 @@ const LEVEL_TRIGGERS: [(u32, u32); 8] = [
 /// The Targeting popup's delay at its one site (`0x514a8d mov edx,0x2710`).
 pub(crate) const TARGETING_DELAY_MS: u32 = 10_000;
 
-/// The Movement popup's silence window (`0x482ff7`: elapsed − stamp − 90 000 ≥ 0) — inferred as
-/// ninety seconds after world enter with no movement input (the stamp getter `0x5143e0` is
-/// read, its meaning is not).
+/// The Movement popup's silence window (`0x482ff7`: elapsed - stamp - 90000 >= 0), taken as 90 s
+/// after world enter with no movement input; what the stamp (`0x5143e0`) holds is untraced.
 const MOVEMENT_SILENCE: Duration = Duration::from_millis(90_000);
 
-/// A site's ask of the tutorial system — written from wherever the reference's site lives.
+/// A site's ask of the tutorial system, written from wherever the reference's site lives.
 #[derive(Message, Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum TutorialEvent {
     /// `TriggerTutorial(id, delayMs)`: the fire-once leg.
@@ -118,8 +106,7 @@ enum TutorialSend {
     Reset,
 }
 
-/// A bank: `bit = bytes[id >> 3] & (1 << (id & 7))` — the client's `word = id >> 5` on
-/// little-endian dwords, byte-wise.
+/// A bank bit, byte-wise: the client's `id >> 5` dword indexing on little-endian dwords.
 fn bank_bit(bank: &[u8], id: u32) -> Option<bool> {
     bank.get((id >> 3) as usize)
         .map(|b| b & (1 << (id & 7)) != 0)
@@ -176,7 +163,7 @@ impl Tutorials {
         };
         match bank_bit(bank, id) {
             Some(false) => set_bank_bit(bank, id),
-            _ => return, // already set — or past the bank, which the reference would overrun
+            _ => return, // already set, or past the bank (the reference would overrun)
         }
         if delay_ms == 0 {
             self.fired.push(id + 1);
@@ -186,9 +173,9 @@ impl Tutorials {
         }
     }
 
-    /// `SetTutorialFlag(id)` (`0x4b54c0`): bank B's bit gates; both banks set; the id's timer
-    /// cancelled; the 0-based id sent. The reference dereferences an absent bank B; ours treats
-    /// that as a no-op.
+    /// `SetTutorialFlag(id)` (`0x4b54c0`): bank B's bit gates, both banks set, the id's timer
+    /// cancelled, the 0-based id sent. The reference dereferences an absent bank B; here it is a
+    /// no-op.
     pub(crate) fn acknowledge(&mut self, id: u32) {
         let Some(bank_b) = self.acknowledged.as_mut() else {
             return;
@@ -216,8 +203,7 @@ impl Tutorials {
         self.sends.push(TutorialSend::Clear);
     }
 
-    /// `ResetTutorials()`: every bit of both banks cleared — the timers NOT flushed — the empty
-    /// reset sent.
+    /// `ResetTutorials()`: every bit of both banks cleared, the timers kept, the empty reset sent.
     fn reset(&mut self) {
         for bank in [&mut self.fire_once, &mut self.acknowledged]
             .into_iter()
@@ -242,7 +228,7 @@ impl Tutorials {
         self.fired.extend(due);
     }
 
-    /// `SMSG_ITEM_PUSH_RESULT` for one of ours — the item-received handler's five sites, resolved
+    /// `SMSG_ITEM_PUSH_RESULT` for one of ours: the item-received handler's five sites, resolved
     /// on the next feed with the item's template.
     pub(crate) fn item_received(&mut self, entry: u32, bag: u8, slot: u32) {
         self.pushes.push((entry, bag, slot));
@@ -296,10 +282,9 @@ fn feed_tutorials(
         }
     }
 
-    // The item-received handler's sites, over the item's template: Backpack unconditionally;
-    // Equippable Items for an inventory type with an equip slot (inferred as any non-zero type —
-    // the reference's 23-bit mask (`0x809200`) is not decoded bit by bit); Hearthstones by entry;
-    // Ranged Weapons for a ranged type on a non-hunter; Keyrings by the slot band.
+    // The item-received sites: Backpack always; Equippable Items for any non-zero inventory type
+    // (the reference's 23-bit mask `0x809200` is not decoded); Hearthstones by entry; Ranged
+    // Weapons for a ranged type on a non-hunter; Keyrings by the slot band.
     let pushes = std::mem::take(&mut tutorials.pushes);
     let class = self_q.single().ok().and_then(|s| s.0.unit_class());
     for (entry, bag, slot) in pushes {
@@ -332,13 +317,8 @@ fn feed_tutorials(
             vec![ScriptValue::Int(i64::from(published))],
         );
     }
-    // **The bank is owed to every VM, not to the process** (decision 2131). What the acknowledged
-    // bank holds is the app's; whether a VM has been *told* it is that VM's, so the memory sits
-    // behind a [`crate::ui_script::VmMemo`] and expires with the session it was written against
-    // (1290/1291 — a `/reload` is a logout and a login back to back). A plain "changed since the
-    // last push" flag is the same mistake 2113 names: it answers "did the bank move?" when the
-    // question is "does THIS VM know it?", and after a reload the answer was no for the rest of
-    // the session.
+    // The bank is owed to every VM: what it has been told is per VM, so a `/reload`'s fresh VM
+    // is told again.
     let told = told.get(&script);
     if *told != tutorials.acknowledged {
         told.clone_from(&tutorials.acknowledged);
@@ -348,8 +328,8 @@ fn feed_tutorials(
 
 /// The self descriptor's `0x4b5390` edge sites: the `SMSG_LEVELUP_INFO` arm on the level rising,
 /// the ghost and resting flags, the PvP flag, the rested table's one live row, and the mover
-/// entering water — a change each, never the login descriptor. The memory is per world session:
-/// the bring-up resets it, so a re-login's first descriptor arms silently like the first one.
+/// entering water. Each fires on a change, never on the login descriptor; the bring-up resets the
+/// memory.
 fn watch_self(
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
     player: Res<Player>,
@@ -360,8 +340,7 @@ fn watch_self(
     if std::mem::take(&mut cascade.reset_watch) {
         *watch = SelfWatch::default();
     }
-    // The descriptor edges — a change, never the login descriptor (the watchers run on
-    // field changes; the first sight arms silently).
+    // The first sight of each field arms silently.
     if let Ok(store) = self_q.single() {
         let level = store.0.unit_level();
         let player_flags = store.0.player_flags();
@@ -391,8 +370,7 @@ fn watch_self(
             }
         }
         if let (Some(prev), Some(new)) = (watch.rest_state, rest_state) {
-            // The rested table: only rest state 1 names a tutorial (the other rows carry the
-            // sentinel), on the field's change.
+            // Only rest state 1 names a tutorial; the other rows carry the sentinel.
             if new != prev && new == 1 {
                 asks.write(TutorialEvent::trigger(id::RESTED));
             }
@@ -438,7 +416,7 @@ fn drain_tutorials(
 }
 
 /// The world-enter bring-up: the banks zeroed, then the bank captured during the login handshake
-/// applied if there was one (the world stream's copy lands through `SessionEvent` otherwise).
+/// applied if there was one.
 fn on_world_enter(
     mut entered: MessageReader<EnteredWorldMessage>,
     mut tutorials: ResMut<Tutorials>,
@@ -456,9 +434,9 @@ fn on_world_enter(
     }
 }
 
-/// The enter-world cascade `0x4908c0`'s two unconditional triggers — Welcome (`0x490a48`) then
-/// Questgivers (`0x490a51`) — run once per world session when the local player object exists,
-/// which is after the bank has landed on a stock server; and the Movement popup's silence window.
+/// The enter-world cascade `0x4908c0`'s two unconditional triggers, Welcome (`0x490a48`) then
+/// Questgivers (`0x490a51`), once per world session when the local player exists; and the
+/// Movement popup's silence window.
 #[derive(Resource, Default)]
 pub(crate) struct WorldEnterCascade {
     armed: bool,
@@ -498,7 +476,7 @@ pub(crate) struct InputHooks<'w> {
 }
 
 impl InputHooks<'_> {
-    /// A movement input this frame (`test ecx,0x1030` — INFERRED as the forward/side axes).
+    /// A movement input this frame (`test ecx,0x1030`, taken as the forward and side axes).
     pub(crate) fn moved(&mut self) {
         if let Some(c) = self.cascade.as_mut() {
             c.moved = true;
@@ -520,10 +498,9 @@ impl InputHooks<'_> {
     }
 }
 
-/// The window edges the reference triggers or acknowledges from inside its handlers: the
-/// trainer list (Trainers acknowledged, `0x4d74ae`), the vendor list (Vendors, `0x4fad32`), the
-/// taxi map (Travel, `0x4dbaa2`), and the group turning raid (Raid Groups, `0x4ba60d` — INFERRED
-/// as the raid-type edge; the row names only its non-zero argument).
+/// The window edges the reference's handlers fire from: the trainer list (Trainers acknowledged,
+/// `0x4d74ae`), the vendor list (Vendors, `0x4fad32`), the taxi map (Travel, `0x4dbaa2`), and the
+/// group turning raid (Raid Groups, `0x4ba60d`, taken as the raid-type edge).
 #[derive(Default)]
 struct WindowWatch {
     trainer: Option<u64>,
@@ -581,24 +558,10 @@ impl Plugin for TutorialPlugin {
                     run_world_enter_cascade.before(feed_tutorials),
                     watch_windows.before(feed_tutorials),
                     watch_self.after(on_world_enter).before(feed_tutorials),
-                    // **Not before the in-game UI exists** (decision 2232). This is the one feed
-                    // in 2226's 29-system audit that could still lose a login's own payload:
-                    // `run_world_enter_cascade` triggers WELCOME and QUESTGIVERS the moment
-                    // `SelfPlayer` exists, a 0-delay `trigger` pushes straight into `fired`, and
-                    // the `mem::take(&mut tutorials.fired)` below fires `TUTORIAL_TRIGGER` at
-                    // whatever VM is in the world. No `VmMemo` sits behind that publication, so
-                    // 2226's fresh session cannot bring it back.
-                    //
-                    // The VM guard already covers the *park* — it sits above the take, so a
-                    // parked frame returns with `fired` intact. What it does not cover is the
-                    // one-frame window where the wire is in-world and the boot VM is still live
-                    // (2214): `on_world_enter` reads `EnteredWorldMessage` out of the same drain
-                    // that writes it, so the arm, the trigger and the take can all land in that
-                    // one frame — the coin flip being whether `apply_net_updates`' spawn command
-                    // has applied yet, which nothing here declares an edge against.
-                    //
-                    // The gate costs nothing: the cascade still arms and still triggers, `fired`
-                    // simply waits, and the first frame with an interface delivers the set.
+                    // Not before the in-game UI exists: `fired` is taken once, with no `VmMemo`
+                    // behind it, so the login's Welcome and Questgivers fired into the boot VM
+                    // during the one frame it is still live in the world would be lost. `fired`
+                    // simply waits for the first frame with an interface.
                     feed_tutorials
                         .in_set(UiFeed)
                         .run_if(crate::ui_script::ingame_ui_up),
@@ -609,7 +572,7 @@ impl Plugin for TutorialPlugin {
     }
 }
 
-/// The tutorial flags' packet handler (in the net handler table since 2326).
+/// The tutorial flags' packet handler.
 mod net {
     use benilla_protocol::{SessionEvent, SessionEventKind};
     use bevy::prelude::*;
@@ -617,7 +580,7 @@ mod net {
     use super::Tutorials;
     use crate::net::NetHandlerApp;
 
-    /// Register the handler — called from [`super::TutorialPlugin`].
+    /// Register the handler, from [`super::TutorialPlugin`].
     pub(super) fn register(app: &mut App) {
         app.net_handler(SessionEventKind::TutorialFlags, on_flags);
     }
@@ -747,7 +710,7 @@ mod tests {
         assert_eq!(bank_bit(a.unwrap(), 32), None, "past a 4-byte bank");
     }
 
-    /// A bare app around [`feed_tutorials`] — the one system that owes the VM the bank.
+    /// A bare app around [`feed_tutorials`], the one system that owes the VM the bank.
     fn feeder() -> App {
         let mut app = App::new();
         app.init_resource::<Tutorials>()
@@ -765,19 +728,14 @@ mod tests {
             .unwrap()
     }
 
-    /// **The bank is owed to every VM** (decision 2131) — the `/reload` bug, reproduced.
-    ///
-    /// `ReloadUI()` is `end_ui_session` + the entry load back to back (1290/1291), and only the
-    /// first of those mints a VM: the world-entry path that fills the banks
-    /// ([`Tutorials::world_enter`]) never runs, so a push gated on "the bank moved" never fires
-    /// again. `TutorialsEnabled()` then answers nil for the rest of the session, the Show
-    /// Tutorials row loads OFF, and ticking it back on passes `BenillaOptionsFrame_SetTutorialsEnabled`'s
-    /// `~=` guard into `ResetTutorials()` — a `CMSG_TUTORIAL_RESET` that re-arms, account-wide,
-    /// every popup the player had already dismissed.
+    /// A `/reload`'s fresh VM is told the bank again, though no world entry refills it. Untold,
+    /// `TutorialsEnabled()` answers nil, the Show Tutorials row loads off, and ticking it passes
+    /// `UIOptionsFrame.lua:319`'s `~=` guard into `ResetTutorials()`, re-arming every dismissed
+    /// popup account-wide.
     #[test]
     fn a_rebuilt_vm_is_told_the_acknowledged_bank_again() {
         let mut app = feeder();
-        // The packet lands: one unacknowledged bit is all `TutorialsEnabled()` scans for.
+        // One unacknowledged bit is all `TutorialsEnabled()` scans for.
         let mut bank = vec![0xFFu8; 32];
         bank[0] = 0xFE;
         app.world_mut()
@@ -810,8 +768,7 @@ mod tests {
             .apply_flags(&[0u8; 32]);
         app.insert_non_send_resource(UiScript::new().expect("VM"));
         app.update();
-        // A bank the VM has already been told is not handed over again — proven by clearing it
-        // behind the feed's back and watching the next frame leave it cleared.
+        // Cleared behind the feed's back, a bank the VM was told stays cleared.
         app.world_mut()
             .non_send_resource_mut::<UiScript>()
             .set_tutorial_bank(None);
@@ -825,26 +782,16 @@ mod tests {
         assert!(enabled(&mut app), "a moved bank reaches the live VM");
     }
 
-    /// **The login's own tutorials wait for an interface** (decision 2232) — built on the REAL
-    /// plugin, so it fails if the gate is taken off the registration rather than off a copy of it.
-    ///
-    /// `TUTORIAL_TRIGGER` has no [`crate::ui_script::VmMemo`] behind it: `trigger` sets the bank
-    /// bit and pushes the id into `fired`, and the feed's `mem::take` fires it once at whatever VM
-    /// is in the world. So unlike every one-shot 2226 covers, a firing lost to a frameless VM
-    /// cannot be recovered by the entry load minting a new session — there is nothing left to
-    /// re-spend. `run_world_enter_cascade` puts WELCOME and QUESTGIVERS into exactly that position
-    /// on every login.
-    ///
-    /// Against the ungated shape the first assertion reads *"`fired` is empty — the login's two
-    /// tutorials were published to a VM with no frames and are gone for the session"*.
+    /// The login's own tutorials wait for an interface, on the real plugin's registration:
+    /// `TUTORIAL_TRIGGER` is fired once, so one published to a frameless VM is gone for the
+    /// session.
     #[test]
     fn the_world_enter_tutorials_are_not_fired_into_a_ui_less_vm() {
         let mut app = App::new();
         app.add_plugins(TutorialPlugin)
             .init_resource::<crate::items::Items>()
             .init_resource::<crate::sound::MessageSounds>()
-            // The plugin's other watchers' inputs — none of them is the subject here; they are
-            // present so the REAL plugin can be driven rather than a copy of one of its systems.
+            // The other watchers' inputs, so the real plugin can run.
             .init_resource::<crate::ui_trainer::TrainerOpen>()
             .init_resource::<crate::ui_merchant::MerchantOpen>()
             .init_resource::<crate::ui_taxi::TaxiState>()
@@ -854,8 +801,8 @@ mod tests {
         let (tx, _rx) = crossbeam_channel::unbounded();
         app.insert_resource(crate::net::NetCommands(tx));
 
-        // The deferral window (1978/2214): in the world on the wire, the entry load still owed,
-        // and a live boot VM that has strings and fonts but not one frame.
+        // The deferral window: in the world on the wire, the entry load still owed, and a live
+        // boot VM with no frames.
         app.insert_resource(State::new(crate::char_select::ClientState::InWorld));
         app.insert_resource(crate::ui_script::PendingEntryUiLoad);
         app.insert_non_send_resource(UiScript::new().expect("the boot VM"));
diff --git a/crates/benilla-app/src/ui_script/death_tests.rs b/crates/benilla-app/src/ui_script/death_tests.rs
index 45227f3d..1c900a88 100644
--- a/crates/benilla-app/src/ui_script/death_tests.rs
+++ b/crates/benilla-app/src/ui_script/death_tests.rs
@@ -177,7 +177,7 @@ fn resurrect_request_picks_variant_and_answers() {
         recovery_delay: 0.0,
         ..Default::default()
     });
-    s.fire_event("RESURRECT_REQUEST", vec![ScriptValue::Str("Pone".into())]);
+    s.fire_event("RESURRECT_REQUEST", vec![ScriptValue::Str("Healer".into())]);
     assert!(s.eval::<bool>("return StaticPopup1:IsVisible()").unwrap());
     assert_eq!(
         s.eval::<String>("return StaticPopup1.which").unwrap(),
@@ -187,7 +187,7 @@ fn resurrect_request_picks_variant_and_answers() {
     assert_eq!(
         s.eval::<String>("return StaticPopup1Text:GetText()")
             .unwrap(),
-        "Pone wants to resurrect you",
+        "Healer wants to resurrect you",
         "the offerer name formats into the no-sickness text"
     );
     assert!(s
@@ -213,7 +213,7 @@ fn resurrect_request_picks_variant_and_answers() {
             ..Default::default()
         }),
     );
-    s.fire_event("RESURRECT_REQUEST", vec![ScriptValue::Str("Pone".into())]);
+    s.fire_event("RESURRECT_REQUEST", vec![ScriptValue::Str("Healer".into())]);
     assert_eq!(
         s.eval::<String>("return StaticPopup1.which").unwrap(),
         "RESURRECT"
diff --git a/crates/benilla-app/src/video.rs b/crates/benilla-app/src/video.rs
index 8b0270c8..429a1538 100644
--- a/crates/benilla-app/src/video.rs
+++ b/crates/benilla-app/src/video.rs
@@ -1,90 +1,30 @@
-//! Player-facing **video settings** — the knobs that reach the window and the presentation path.
+//! Video settings that reach the window and the presentation path: 1.12's `gxWindow` and
+//! `gxVSync` rows (`OptionsFrame.lua:14`, `:9`) and the `gxResolution` windowed size.
 //!
-//! Two, both of them 1.12's own CVars over the Graphics page: **Display Mode** (`gxWindow`, the
-//! *Display Mode* row) and **VSync** (`gxVSync`, the *Vertical Sync* row).
+//! Deviation: `gxWindow "0"` is borderless fullscreen, not 1.12's exclusive mode-set at
+//! `gxResolution`, because Wayland has no client mode-setting (winit ignores
+//! `Fullscreen::Exclusive` there), X11's XRandR changes the desktop's mode and a crash leaves it
+//! changed, and macOS has no exclusive mode. Bevy's `WindowMode::Fullscreen` also panics on a live
+//! change that cannot resolve a monitor (`bevy_winit::winit_windows:91`, `system.rs:333`).
 //!
-//! # Display mode — the reference's CVar, deliberately not the reference's meaning (decision 1627)
+//! The `gx*` rows are latched until `RestartGx()`, as in 1.12; a restart re-asserts them against
+//! the window rather than re-creating the device, since wgpu reconfigures the surface live.
 //!
-//! 1.12 ships a **two-state** display model: `gxWindow "0"` takes the display with an exclusive
-//! mode-set at `gxResolution`, `gxWindow "1"` runs in a window (with `gxMaximize` for a maximized
-//! one). We keep the CVar, the row, and the default; we redefine `"0"`.
-//!
-//! **`"0"` here means BORDERLESS fullscreen** — a normal window sized to the monitor, flagged
-//! fullscreen to the compositor (`xdg_toplevel.set_fullscreen` on Wayland,
-//! `_NET_WM_STATE_FULLSCREEN` on X11, a native fullscreen window on macOS). We ship no exclusive
-//! mode at all, and that is not a shortcut — it is unavailable or pointless on all three targets:
-//!
-//! - **Wayland has no client-side mode-setting**, so there is nothing to implement: winit 0.30.13
-//!   answers `Fullscreen::Exclusive` with ``warn!("`Fullscreen::Exclusive` is ignored on Wayland")``
-//!   and leaves the window as it was (`platform_impl/linux/wayland/window/mod.rs:147,488`).
-//! - **On X11 it is XRandR mode-setting**, which changes the *desktop's* mode and, as winit's own
-//!   comment says, "does not provide a mechanism to … restore this to the desktop video mode as
-//!   macOS and Windows do" — a crash leaves the player's desktop at our resolution.
-//! - **On macOS** there is no exclusive mode to take.
-//!
-//! And the industry moved: SDL3 deleted `SDL_WINDOW_FULLSCREEN_DESKTOP` and made borderless-desktop
-//! what a fullscreen window *is* unless you opt into a mode with `SDL_SetWindowFullscreenMode`;
-//! WoW itself removed exclusive fullscreen in **8.0.1**, leaving Windowed and Windowed
-//! (Fullscreen) — VERIFIED at the source, not from the patch notes: Blizzard's own
-//! `Blizzard_SettingsDefinitions_Shared/Graphics.lua` (live, `classic` and `classic_era`, all
-//! identical) registers Display Mode as a **boolean** proxy and builds its dropdown from exactly
-//! two entries, `VIDEO_OPTIONS_WINDOWED_FULLSCREEN` and `VIDEO_OPTIONS_WINDOWED`. **Our two states
-//! are modern Classic's two states**, which is why 1650 wears them as that client's dropdown
-//! rather than 1.12's checkbox. (Modern hangs the boolean on `gxMaximize`, having deleted
-//! `gxWindow` outright; we keep `gxWindow`, which is the CVar our configs already persist.) Bevy's own `WindowMode::Fullscreen` arm is a liability besides — it `expect`s a
-//! monitor at creation and `panic!`s on a live change that cannot resolve one
-//! (`bevy_winit::winit_windows:91`, `system.rs:333`).
-//!
-//! **What this is worth, concretely.** Before 1627 the window was born `WindowMode::Windowed` at a
-//! hard-coded 1600×900 with nothing able to change it — larger than a Steam Deck's 1280×800 panel,
-//! and never flagged fullscreen. A window that does not fill gamescope's nested output is a
-//! documented input break upstream (ValveSoftware/gamescope#1086 — pointer trapped in the nested
-//! rect, clicks outside it dead; #1209 — tapping the letterbox warps the cursor to centre forever),
-//! whose recorded workaround is "set the game to fullscreen".
-//!
-//! **No `gxRestart`.** 1.12 flags its whole video block restart-required; ours takes effect on the
-//! click, the same stated departure [`apply_present_mode`] already makes for `gxVSync`.
-//!
-//! # VSync
-//!
-//! **Why it is a player setting and not a dev toggle.** It briefly lived as a checkbox on the perf
-//! HUD, where it existed to answer one instrument question — "is the GPU keeping up?" — because a
-//! synced frame reads as the display's grant whether it needed 3 ms or 16 (0717). That is the wrong
-//! home twice over: the HUD is `#[cfg(feature = "dev")]`, so a player build could never reach it,
-//! and vsync is not a diagnostic in the first place. It is the same option 1.12 shipped —
-//! `OptionsFrameCheckButtons["VERTICAL_SYNC"] = { index = 5, cvar = "gxVSync", gxRestart = 1 }`,
-//! Video Options, checkbox 5 — and the same one every engine since has kept. The instrument
-//! question keeps `$WOW_NOVSYNC=1`, which is where a measurement knob belongs.
-//!
-//! **We do not require the restart 1.12 did.** The reference's row carries `gxRestart = 1` because
-//! its device could not swap the presentation interval live; wgpu reconfigures the surface on the
-//! next frame, so the checkbox takes effect as you click it. A deliberate, stated departure.
-//!
-//! **`AutoNoVsync`, never `Immediate`.** On macOS/Metal, explicit `Immediate` both rails *and*
-//! takes ~1 s `nextDrawable` stalls — measured, and pinned at [`crate::capture::probe_uncap_mode`].
+//! Uncapped is `AutoNoVsync`, never `Immediate`: on Metal `Immediate` takes ~1 s `nextDrawable`
+//! stalls ([`crate::capture::probe_uncap_mode`]).
 
 use benilla_ui::script::ScreenResolution;
 use bevy::prelude::*;
 use bevy::window::{MonitorSelection, PresentMode, PrimaryWindow, WindowMode, WindowResolution};
 
-/// `$WOW_NOVSYNC=1` — the session-only measurement override. It wins over the config for the run
-/// and never reaches `config.toml` (registered in [`crate::cvars`]'s `session_owned` set), so a
-/// headless FPS-journal run can uncap without making the player's setting sticky.
+/// `$WOW_NOVSYNC=1`: uncap for this session only; it never reaches `config.toml` (the
+/// `session_owned` set in [`crate::cvars`]).
 pub(crate) fn novsync_env() -> bool {
     std::env::var("WOW_NOVSYNC").as_deref() == Ok("1")
 }
 
-/// Does this run **size its own window**, and therefore stay windowed whatever the config says?
-///
-/// Three sources, and the first two are named explicitly rather than left to the third because a
-/// capture that silently went fullscreen would render at the display's resolution instead of the
-/// scenario's — every visual regression diff in the tree is denominated in the window the scenario
-/// asks for, so this one must not depend on the machine's panel. The third is the general rule: an
-/// instrumented run's window is plumbing ([`benilla_world::bgwin`]), and the probe fleet sizes and
-/// parks it deliberately (decisions 0703/0709/1148).
-///
-/// Session-only, exactly like [`novsync_env`]: `gxWindow`/`gxResolution` are registered
-/// env-overridden while it holds, so the file's value neither reaches the window nor is saved over.
+/// Whether this run sizes its own window (a capture, a background run) and so stays windowed.
+/// Session-only: `gxWindow`/`gxResolution` are env-overridden while it holds, never saved over.
 pub(crate) fn windowed_env() -> bool {
     std::env::var_os("WOW_WIN").is_some()
         || std::env::var_os("WOW_CAPTURE").is_some()
@@ -92,39 +32,22 @@ pub(crate) fn windowed_env() -> bool {
         || benilla_world::bgwin::background_run()
 }
 
-/// `$WOW_WIN=WxH` in **logical** px — the one parser, so the window that is *asked for* and the
-/// window that is *checked* can never drift. It was spelled twice inline in `lib.rs` (once for the
-/// UI-fixture arm, once for the world arm) and is now spelled here once and read there.
+/// `$WOW_WIN=WxH` in logical px; the one parser, so the size asked for and the size checked agree.
 pub(crate) fn requested_window_size() -> Option<UVec2> {
     let v = std::env::var("WOW_WIN").ok()?;
     let (w, h) = v.split_once('x')?;
     Some(UVec2::new(w.parse().ok()?, h.parse().ok()?))
 }
 
-/// `$WOW_DPI=<f32>` — **render at a player's pixel grid, not this machine's.**
-///
-/// Every session here runs on a 2× panel; nearly every text-under-scale report the channel files
-/// comes from a 1080p/1440p one at 1×. That gap is not cosmetic. The two places our text meets the
-/// grid — the raster size (`TextEngine::ppem`, `round(logical × dpi)`) and the per-block vertical
-/// snap (`ui_text::layout::snap_block_top`) — are both *quantizers*, and a quantizer's error is
-/// denominated in device pixels: at 1× the same layout rounds twice as coarsely as it does here.
-/// A defect that is half a pixel at 2× is a whole one at 1×, which is the difference between
-/// invisible and reported (B209, B231, B232 — all from 1×, all reproduced here only by forcing
-/// this).
-///
-/// The override goes on the *window*, so `Window::scale_factor()` — the one number the text engine,
-/// the vplates raster and the world backdrop all read — answers with it, and `WOW_WIN` then means
-/// physical pixels one-to-one. The image a capture writes is byte-for-byte the framebuffer that
-/// player's GPU would scan out; on this display it is simply drawn at half the size.
-///
-/// Absent, nothing changes: the window keeps whatever the display reports.
+/// `$WOW_DPI=<f32>`: render at another display's pixel grid, since text rasterizing and snapping
+/// quantize in device pixels. It overrides the window's scale factor, so `WOW_WIN` then means
+/// physical pixels and a capture is the framebuffer that display would show.
 pub(crate) fn requested_dpi() -> Option<f32> {
     let v: f32 = std::env::var("WOW_DPI").ok()?.parse().ok()?;
     (v.is_finite() && v > 0.0).then_some(v)
 }
 
-/// Apply [`requested_dpi`] to a window resolution — the one place the knob is spent, so the size
-/// that is asked for and the grid it is asked for on cannot drift apart.
+/// Apply [`requested_dpi`] to a window resolution; the one place the knob is spent.
 pub(crate) fn at_requested_dpi(res: WindowResolution) -> WindowResolution {
     match requested_dpi() {
         Some(dpi) => res.with_scale_factor_override(dpi),
@@ -132,24 +55,21 @@ pub(crate) fn at_requested_dpi(res: WindowResolution) -> WindowResolution {
     }
 }
 
-/// The display modes benilla ships. **Two, and neither is the reference's mode-setting
-/// fullscreen** — the module doc says why.
+/// The display modes benilla ships; neither is the reference's mode-setting fullscreen.
 #[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
 pub(crate) enum DisplayMode {
-    /// Borderless, filling the monitor. `gxWindow "0"` — the reference's own default value, and
-    /// what every shipped game defaults to.
+    /// Borderless, filling the monitor: `gxWindow "0"`, the reference's default.
     #[default]
     Fullscreen,
     /// A window at [`VideoConfig::windowed`]. `gxWindow "1"`.
     Windowed,
 }
 
-/// The windowed size a fresh config gets: the 1600×900 that was the client's only size before
-/// 1627, so nothing about a windowed run moved when the mode setting landed.
+/// The windowed size a fresh config gets.
 pub(crate) const DEFAULT_WINDOWED: UVec2 = UVec2::new(1600, 900);
 
-/// `gxWindow`'s value → the mode. The reference's own parse for its 0/1 CVars is int + `!= 0`, and
-/// one function is the whole law so [`crate::cvars`]'s arm and the boot read cannot drift.
+/// `gxWindow`'s value to the mode, by the reference's 0/1 parse (int, `!= 0`); shared by
+/// [`crate::cvars`]'s arm and the boot read.
 pub(crate) fn display_from_flag(v: f32) -> DisplayMode {
     if v != 0.0 {
         DisplayMode::Windowed
@@ -158,9 +78,8 @@ pub(crate) fn display_from_flag(v: f32) -> DisplayMode {
     }
 }
 
-/// `gxResolution`'s value → a size. The reference's spelling (`"1280x800"`), whose own parse is
-/// `sscanf("%d%c%d")`; ours is stricter by one thing only — a zero extent is refused rather than
-/// handed to the windowing system.
+/// `gxResolution`'s value (`"1280x800"`, parsed by the reference with `sscanf("%d%c%d")`) to a
+/// size. A zero extent is refused rather than handed to the windowing system.
 pub(crate) fn parse_resolution(value: &str) -> Option<UVec2> {
     let (w, h) = value.split_once(['x', 'X'])?;
     let size = UVec2::new(w.trim().parse().ok()?, h.trim().parse().ok()?);
@@ -175,16 +94,9 @@ pub(crate) fn window_mode(display: DisplayMode, monitor: MonitorSelection) -> Wi
     }
 }
 
-/// The mode the primary window is **born** in — resolved before the `App` exists, because the
-/// alternative is worse than the frame it costs. Booting windowed and flipping at `Startup` (where
-/// [`crate::cvars`]'s `load_config` runs) is a visible flash on every launch, and under a
-/// compositor that only maps a fullscreen surface 1:1 it is a first second spent in exactly the
-/// broken input state 1627 exists to end.
-///
-/// `MonitorSelection::Primary`, not `Current`: at creation there is no current monitor —
-/// `bevy_winit::select_monitor` warns and answers `None` for `Current` — and "the monitor the
-/// window is on" is not a question with an answer before the window exists. A live toggle uses
-/// `Current`; [`apply_window_mode`] carries why the two never fight.
+/// The mode the primary window is born in, resolved before the `App` exists so a fullscreen launch
+/// does not flash windowed until `Startup`. `MonitorSelection::Primary`, since `Current` has no
+/// answer before the window exists (`bevy_winit::select_monitor`).
 pub(crate) fn boot_window_mode() -> WindowMode {
     let display = if windowed_env() {
         DisplayMode::Windowed
@@ -196,23 +108,16 @@ pub(crate) fn boot_window_mode() -> WindowMode {
     window_mode(display, MonitorSelection::Primary)
 }
 
-/// The windowed size the primary window is **born** at — `gxResolution`, read at the same pre-`App`
-/// moment and for the same reason as [`boot_window_mode`]. Ignored by winit while the mode is
-/// fullscreen (`bevy_winit` applies an inner size only on the `Windowed` arm), and the value
-/// [`apply_window_mode`] hands back on the way out of it.
+/// The windowed size the primary window is born at, `gxResolution`, read as [`boot_window_mode`]
+/// is; `bevy_winit` ignores it while fullscreen.
 pub(crate) fn boot_windowed_size() -> UVec2 {
     crate::cvars::boot_cvar("gxResolution")
         .and_then(|v| parse_resolution(&v))
         .unwrap_or(DEFAULT_WINDOWED)
 }
 
-/// The video knobs a CVar write can land on. Default = what the client ships: fullscreen, synced,
-/// matching the primary window's own boot values — see `lib.rs`'s window literal.
-///
-/// The **file** is deliberately not read here, only the environment (the posture `vsync` has had
-/// since 0294): the window literal resolves env-then-file for itself, `load_config` applies the
-/// file to this resource at `Startup`, and because both read the same key the reconcile is a no-op
-/// rather than a mode change one frame into the run.
+/// The video knobs a CVar write lands on. Defaults read only the environment; `load_config`
+/// applies the file at `Startup`, which the boot window already matches.
 #[derive(Resource, Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) struct VideoConfig {
     pub(crate) vsync: bool,
@@ -235,14 +140,8 @@ impl Default for VideoConfig {
     }
 }
 
-/// The present mode a vsync setting means.
-///
-/// **On is `PresentMode::default()` — Bevy's default, deliberately, not `AutoVsync`.** 0294 recorded
-/// running the engine default and that is `Fifo`: strict, never tears. `AutoVsync` is *not* a
-/// synonym — it resolves to `FifoRelaxed` where available, which permits a tear on a late frame.
-/// The dev HUD's old checkbox wrote `AutoVsync` on the way back on, so toggling it off and on
-/// silently left the client on a different mode than it booted with; naming one function the single
-/// mapping is what closes that.
+/// The present mode a vsync setting means. On is `PresentMode::default()` (`Fifo`, never tears),
+/// not `AutoVsync`, which resolves to `FifoRelaxed` and can tear on a late frame.
 pub(crate) fn present_mode(vsync: bool) -> PresentMode {
     if vsync {
         PresentMode::default()
@@ -253,10 +152,8 @@ pub(crate) fn present_mode(vsync: bool) -> PresentMode {
 
 pub(crate) struct VideoPlugin;
 
-/// **The Video Options block's change callbacks** (decision 2303) — the rows the reference
-/// registers from its one video-options registration block (`0x688470`), landing on the resources
-/// they drive. Each arm writes only its own resource, so a `ViewDistance` change is `farclip`
-/// moving and nothing else; the clamps are each row's own, stated beside it.
+/// The change callbacks of the reference's video-options registration block (`0x688470`); each
+/// arm writes only its own resource.
 pub(crate) fn on_cvar(
     ev: On<crate::cvars::CvarChanged>,
     mut cfg: ResMut<VideoConfig>,
@@ -271,43 +168,32 @@ pub(crate) fn on_cvar(
     use benilla_world::view::{FARCLIP_RANGE, MSAA_RANGE};
     let v = ev.num();
     match ev.key().as_str() {
-        // The one string row here (1627), composed in the reference's own `WxH` spelling. A
-        // value that is not a size is consumed with a warn and the window keeps its truth.
+        // A value that is not a size is ignored with a warning.
         "gxresolution" => match parse_resolution(&ev.new) {
             Some(size) => cfg.windowed = size,
             None => warn!("cvar gxResolution: unparseable value '{}' ignored", ev.new),
         },
-        // Vertical Sync — a flag like every other checkbox. `apply_present_mode` pushes it to
-        // the window when this resource moves; nothing else reads it.
         "gxvsync" => cfg.vsync = ev.flag(),
-        // Display mode (1627) — the reference's own polarity: `1` is WINDOWED (the row is
-        // "Windowed Mode"). `apply_window_mode` pushes it to the window when this moves.
+        // The reference's polarity: `1` is windowed (the row is "Windowed Mode").
         "gxwindow" => cfg.display = display_from_flag(v),
         "farclip" => view.farclip = v.clamp(*FARCLIP_RANGE.start(), *FARCLIP_RANGE.end()),
-        // The reference REFUSES an out-of-range write here rather than clamping (`0x688d90`
-        // echoes "NearClip must be in range 0.01 - 0.33" and returns 0). We clamp, which is the
-        // table's standing posture for every range — the consumer clamps at its own edge.
+        // Clamped, where the reference refuses an out-of-range write and keeps the value
+        // (`0x688d90` echoes "NearClip must be in range 0.01 - 0.33" and returns 0).
         "nearclip" => view.set_nearclip(v),
-        // Multisampling (1629) — the reference's own `atoi`-then-clamp `[1, 16]` at `0x63b250`,
-        // then the DEVICE's ceiling (1643): a count this GPU does not offer is not a setting
-        // that degrades, it is a wgpu validation error that kills the render thread on frame
-        // one. Clamping at the write covers every writer there is: the file, a Lua `SetCVar`,
-        // the dropdown, and the Defaults button. Latched: the camera reads this once, at spawn.
+        // The reference's `atoi` and clamp to `[1, 16]` (`0x63b250`), then this GPU's ceiling:
+        // an unoffered count is a wgpu validation error on the first frame. The camera reads it
+        // once, at spawn.
         "gxmultisample" => {
             let asked = (v as u32).clamp(*MSAA_RANGE.start(), *MSAA_RANGE.end());
             let granted = msaa_formats.clamp(asked);
             if granted != asked {
-                // At `warn`, the same posture as the seed clamp: the player asked for something
-                // and did not get it, and this is the only place that fact exists.
                 warn!("cvar gxMultisample: this GPU does not offer {asked}x multisampling — using {granted}x");
             }
             msaa.samples = granted;
         }
-        // The filter policy's two halves (1642). Both write a value nothing reads until the
-        // next launch — the process policy is published once at the end of `CvarLoad` — which
-        // is benilla's limitation, not a latch: the reference registers both with `flags = 1`
-        // and applies them live. `anisotropic` takes the reference's own parse-then-clamp
-        // `[1, 16]` (`0x689110`); `trilinear` is a flag like every other.
+        // Not applied until the next launch (the filter policy is published once at the end of
+        // `CvarLoad`); the reference registers both with `flags = 1` and applies them live.
+        // `anisotropic` takes the reference's clamp to `[1, 16]` (`0x689110`).
         "trilinear" => tex_filter.trilinear = ev.flag(),
         "anisotropic" => {
             tex_filter.aniso = (v as u32).clamp(
@@ -315,11 +201,8 @@ pub(crate) fn on_cvar(
                 *benilla_assets::ANISO_RANGE.end(),
             )
         }
-        // The panel's 0/1/2 lands as the density multiplier ×1/×2/×3; the clamp is the 1.12
-        // slider's own range (an off-grid hand-edit rides between stops, like every slider).
-        // The SAME knob has a second registered spelling (2151), MIRRORED below — the knob is
-        // already written, so the sibling row follows without a callback — so `GetCVar` never
-        // answers two detail levels for one ground cover.
+        // The panel's 0/1/2 is the density multiplier x1/x2/x3, clamped to the 1.12 slider's
+        // range. `frillDensity` is the same knob, mirrored so `GetCVar` never answers two levels.
         "worlddetail" => {
             clutter.density = v.clamp(0.0, 2.0) + 1.0;
             cvars.mirror(
@@ -327,11 +210,8 @@ pub(crate) fn on_cvar(
                 &clutter.frill_density().to_string(),
             );
         }
-        // …and in the reference's own cells-per-chunk, with the reference's own `[1, 256]`
-        // clamp rather than the stop's — `ClutterConfig::set_frill_density` carries both, and
-        // `terrain_stream::rescatter_clutter` re-scatters the loaded tiles off the resulting
-        // density change exactly as it does for the row above (0992's setter law, which is the
-        // callback's own chunk rebuild).
+        // The same knob in the reference's cells per chunk, clamped to `[1, 256]`
+        // (`ClutterConfig::set_frill_density`); the loaded tiles re-scatter off the change.
         "frilldensity" => {
             clutter.set_frill_density(v);
             cvars.mirror(
@@ -339,26 +219,19 @@ pub(crate) fn on_cvar(
                 &(clutter.density - 1.0).to_string(),
             );
         }
-        // Weather Intensity, the panel's 0..3 step 1 (2181). The reference's callback is
-        // `0x67b870`, a jump table (`0x67b8e8`) mapping 0/1/2/3 onto the quality cells
-        // {0.1, 0.33, 0.66, 1.0} in `[0x8680ec]`.
-        // What that table does with an off-grid int is NOT decoded, so the clamp here is the
-        // table's own standing posture rather than a fidelity claim — and it costs nothing
-        // either way, because `WeatherState::density_gain` already `.min(3)`s its own index.
+        // Weather Intensity 0..3: the reference's callback `0x67b870` jumps (`0x67b8e8`) to the
+        // quality cells {0.1, 0.33, 0.66, 1.0} at `[0x8680ec]`. Its off-grid handling is
+        // untraced; this clamps.
         "weatherdensity" => weather.weather_density = v.trunc().clamp(0.0, 3.0) as u8,
         _ => {}
     }
 }
 
-/// `/console detailDoodadAlpha [0..255]` — the reference's own console command (`0x6739a0`;
-/// registrar `0x63f9e0`, a command table and not `CVar::Register`, so it never persists — 1804
-/// does not apply to it). It is the **ground-clutter cutout reference**, the dial that decides
-/// where grass first appears: the detail-doodad draw alpha-tests `texel.a x distance_ramp`
-/// against it, so at the default 128 nothing survives past ~61 yd of the 70 yd horizon, and
-/// lowering it walks that onset out toward the horizon. The reference rejects an out-of-range
-/// value rather than saturating (`0x6739b9: cmp eax,0xff; jbe`), so out-of-range and
-/// unparseable are the same here: a readout with the usage. Bare = the readout (the reference
-/// reads an uninitialised stack slot there; a readout is the useful reading of "no argument").
+/// `/console detailDoodadAlpha [0..255]`, the reference's console command (`0x6739a0`, registered
+/// by `0x63f9e0` as a command, not a CVar, so it never persists): the ground-clutter cutout that
+/// `texel.a x distance_ramp` is tested against, so at the default 128 grass ends ~61 yd out of
+/// the 70 yd horizon. Out of range is rejected (`0x6739b9`) with a readout. A bare command also
+/// prints the readout, where the reference reads an uninitialised stack slot.
 fn detail_doodad_alpha(world: &mut World, args: &str) -> Vec<String> {
     let Some(mut clutter) = world.get_resource_mut::<benilla_world::clutter::ClutterConfig>()
     else {
@@ -395,10 +268,8 @@ impl Plugin for VideoPlugin {
             .add_systems(
                 Update,
                 (
-                    // After the tick, and after the CVar sync: the stock video window's Okay is
-                    // `SetCVar` per changed row and then `RestartGx()`, in one handler, so the
-                    // staged rows have to be in the registry before the commit reads it
-                    // (decision 2304).
+                    // After the tick and the CVar sync: the stock Okay handler calls `SetCVar` per
+                    // row, then `RestartGx()`, so the staged rows are registered before the commit.
                     (drain_restart_gx, (apply_present_mode, apply_window_mode))
                         .chain()
                         .after(crate::ui_script::UiInput)
@@ -410,26 +281,14 @@ impl Plugin for VideoPlugin {
     }
 }
 
-/// How many `RestartGx()` calls the interface has made — the video window's "apply the staged
-/// settings now" (decision 2177).
-///
-/// A generation counter rather than a flag: [`apply_present_mode`] and [`apply_window_mode`] each
-/// keep their own `Local` of the last value they acted on, so one bump forces exactly one
-/// re-assertion in each, whichever order they run in and however many frames apart.
+/// How many `RestartGx()` calls the interface has made. A counter, not a flag: each applier keeps
+/// its own last value, so one bump forces one re-assertion in each, in any order.
 #[derive(Resource, Default, Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) struct GxRestarts(u32);
 
-/// Move the interface's `RestartGx()` calls into [`GxRestarts`] — and **commit the latch**.
-///
-/// The `gx*` rows are latched, as the reference registers them (flags `3`, decision 2303): a
-/// `SetCVar("gxVSync", 0)` or a `/console gxWindow 1` is staged, `GetCVar` keeps answering the
-/// applied value, and nothing moves until `RestartGx()` — which in the reference re-creates the
-/// device and calls `CVar::Update 0x63e060` on each row from inside it. Here the commit is
-/// [`crate::cvars::Cvars::commit_latched`], its observers run at the sync point before the two
-/// appliers below, and what a restart means beyond that is "re-assert the settings against the
-/// window now" rather than "tear the device down": wgpu reconfigures the surface on the next
-/// present. The two systems below do the asserting; this one carries the request across the VM
-/// boundary and fires the commit.
+/// Carry `RestartGx()` calls into [`GxRestarts`] and commit the latched `gx*` rows (flags `3`),
+/// where the reference's restart calls `CVar::Update` (`0x63e060`) on each; `GetCVar` answers the
+/// applied value until then.
 fn drain_restart_gx(
     script: Option<NonSendMut<benilla_ui::script::UiScript>>,
     mut restarts: ResMut<GxRestarts>,
@@ -441,8 +300,7 @@ fn drain_restart_gx(
     };
     let asks = script.take_restart_gx_asks();
     if asks == 0 {
-        // Never touch the resources on a quiet frame: a `ResMut` deref-mut is a change signal, and
-        // both consumers below are gated on the value moving.
+        // A `ResMut` deref-mut is a change signal, so a quiet frame touches nothing.
         return;
     }
     restarts.0 = restarts.0.wrapping_add(asks);
@@ -455,25 +313,16 @@ fn drain_restart_gx(
     info!("video: RestartGx — {committed} staged setting(s) committed; re-asserting the display mode and present mode");
 }
 
-/// **The reference's own three filters on the resolution list** (`0x48bcfa`–`0x48bd18`), in its
-/// own order: keep iff `w/h >= 1.248`, `w >= 800`, `h >= 600`.
-///
-/// The aspect constant is `[0x804570]`, the f32 `1.2480000257492065` — chosen just under 5:4 so it
-/// admits 5:4, 4:3, 16:10 and 16:9 and rejects square and portrait modes. It is not a
-/// widescreen-only gate; the `widescreen` CVar is a separate switch [`SCREEN_FALLBACK`] describes.
+/// The reference's three filters on the resolution list (`0x48bcfa` to `0x48bd18`): keep when
+/// `w/h >= 1.248` (`[0x804570]`, just under 5:4, so square and portrait fail), `w >= 800` and
+/// `h >= 600`.
 fn offerable(r: ScreenResolution) -> bool {
     r.width >= 800 && r.height >= 600 && f64::from(r.width) / f64::from(r.height) >= 1.248
 }
 
-/// **What the list is when enumeration produces nothing** — the reference's four hardcoded modes,
-/// in its own append order (`0x48bda2`, `0x48bddf`, `0x48be43`, `0x48bea7`).
-///
-/// In the reference this is a "produced nothing" path, not an else: it is taken when the display
-/// enumeration survives no mode, when the `widescreen` CVar's record is missing, or when
-/// `widescreen == 0`. **benilla does not register `widescreen`** (`0x63a747`, registered default
-/// `"1"`), so only the first of the three reaches here — a headless run, or a monitor whose modes
-/// all fail [`offerable`]. Registering it would be a knob whose whole effect is to shrink this
-/// dropdown to these four, which is a setting on its own merits and not this list's business.
+/// The reference's four hardcoded modes, in its append order (`0x48bda2`, `0x48bddf`, `0x48be43`,
+/// `0x48bea7`), used when no enumerated mode survives [`offerable`]. The reference also takes this
+/// path when `widescreen` (`0x63a747`, default `"1"`) is 0; benilla does not register that CVar.
 const SCREEN_FALLBACK: [ScreenResolution; 4] = [
     ScreenResolution {
         width: 800,
@@ -493,39 +342,14 @@ const SCREEN_FALLBACK: [ScreenResolution; 4] = [
     },
 ];
 
-/// The pair [`publish_display_modes`] remembers between frames: the list it last pushed and the
-/// index into it. One name because they are one fact — a list without its index cannot be read —
-/// and because a `Local` spelling it inline is what `-D clippy::type-complexity` refuses.
+/// The list [`publish_display_modes`] last pushed and the current entry.
 type PublishedModes = Option<(Vec<ScreenResolution>, Option<ScreenResolution>)>;
 
-/// **What the Video options window's resolution dropdown offers, and where the client is in it** —
-/// the host half of `GetScreenResolutions` / `GetCurrentResolution` / `SetScreenResolution`
-/// (decision 2177).
-///
-/// The reference enumerates the graphics device's display modes, because picking one is a
-/// mode-set. benilla ships no exclusive mode at all (this module's doc walks why, per target), so
-/// what a pick here really changes is the **windowed size** — `gxResolution`, which
-/// `SetScreenResolution` writes and [`apply_window_mode`] applies on the next frame.
-///
-/// **The unit is LOGICAL pixels, not the monitor's physical mode table, and that is deliberate.**
-/// `gxResolution` already means a logical inner size everywhere else in this client
-/// ([`boot_windowed_size`] hands it straight to `WindowResolution`), so offering physical sizes
-/// would make the dropdown's rows and the CVar they write mean two different things on every
-/// HiDPI display — a 1600×900 pick landing a 3200×1800 window. One unit end to end beats matching
-/// the reference's spelling into a variable that means something else here.
-///
-/// The rows are the monitor's own distinct mode sizes plus its full size, in logical units, put
-/// through [`offerable`] — device data and the reference's own filters, not a ladder we invented —
-/// and [`SCREEN_FALLBACK`] when that survives nothing. The live window size is added by
-/// [`UiScript::set_screen_resolutions`] if it is not already among them, which is the common case
-/// (a 1600×900 window on a 4K panel, or anything below the 800×600 floor) and the one
-/// `CT_Viewport.lua:201` depends on: it reads its own screen size as `arg[GetCurrentResolution()]`
-/// and silently falls back to 4:3 on a miss.
-///
-/// **Recomputed on change, where the reference builds it once and never invalidates it** — its own
-/// list survives a `gxRestart`, a `widescreen` toggle and a monitor change (a 25-hit dword census
-/// of the count global says so). That is a cache bug to leave behind, not a mechanism: a client
-/// that can be dragged between monitors has to answer for the one it is on.
+/// The host half of `GetScreenResolutions` / `GetCurrentResolution`: the monitors' mode sizes and
+/// full sizes through [`offerable`], else [`SCREEN_FALLBACK`]; a pick sets the windowed size,
+/// `gxResolution`. The engine adds the live window size when missing, which `CT_Viewport.lua:201`
+/// needs. Deviation: sizes are logical px, because `gxResolution` is a logical inner size here.
+/// The list is recomputed on change; the reference builds its list once and never invalidates it.
 fn publish_display_modes(
     script: Option<NonSendMut<benilla_ui::script::UiScript>>,
     windows: Query<&Window, With<PrimaryWindow>>,
@@ -546,8 +370,7 @@ fn publish_display_modes(
     .filter(|r| r.width > 0 && r.height > 0);
     let mut offered: Vec<ScreenResolution> = Vec::new();
     for m in &monitors {
-        // The monitor's own scale — not the window's. A window straddling two displays reports
-        // whichever winit last gave it, and these rows describe the PANEL.
+        // The monitor's own scale, not the window's: these rows describe the panel.
         let scale = if m.scale_factor > 0.0 {
             m.scale_factor
         } else {
@@ -566,9 +389,7 @@ fn publish_display_modes(
     }
     offered.sort_by_key(|r| (u64::from(r.width) * u64::from(r.height), r.width, r.height));
     offered.dedup();
-    // **VM-keyed** (decision 1290): a `ReloadUI` replaces the VM, and the fresh one has been
-    // pushed nothing. A plain `Local` here would remember the OLD VM's list and skip the push
-    // that the new VM needs, leaving `GetScreenResolutions` empty for the rest of the session.
+    // Keyed by VM: a `ReloadUI` VM has been pushed nothing, so a plain `Local` would skip it.
     let memo = last.get(&script);
     if memo.as_ref() == Some(&(offered.clone(), current)) {
         return;
@@ -577,25 +398,9 @@ fn publish_display_modes(
     script.set_screen_resolutions(offered, current);
 }
 
-/// **Did the window actually get the size `$WOW_WIN` asked for?** Refuse the run if not.
-///
-/// The window manager is free to clamp a requested inner size to the display, and macOS does. The
-/// failure is silent and it invalidates comparisons: on 2026-08-26 an MSAA A/B produced one leg at
-/// 3200x1800 and the other at 3024x1800, because the director had the laptop panel on overnight
-/// instead of the external monitor, and the window landed on a smaller screen. Nothing said so.
-/// `benilla-visual` refused the pair with `image size mismatch` — the right outcome by luck, from a
-/// tool three steps downstream that could only report the symptom, and a full A/B cycle was spent
-/// getting there.
-///
-/// Measured, not assumed: `WOW_WIN=4000x3000` on this machine yields `1920x1048 logical` — clamped
-/// to the display the window happened to open on, minus its chrome.
-///
-/// **Fatal under a capture, a warning otherwise**, and the split is the point. Every visual
-/// regression diff in the tree is denominated in the window the scenario asks for
-/// ([`windowed_env`]'s doc says so), so a capture at the wrong size is not a worse capture, it is
-/// an invalid one that will be diffed against a valid one. A non-capture run with `$WOW_WIN` is
-/// somebody looking at something; a clamp there is surprising, not wrong, so it says so and
-/// carries on.
+/// Check the window got the size `$WOW_WIN` asked for: the window manager may clamp it to the
+/// display (macOS does). Fatal under a capture, whose diffs assume the scenario's size; a warning
+/// otherwise.
 fn check_window_pinned(
     windows: Query<&Window, With<PrimaryWindow>>,
     mut exit: MessageWriter<AppExit>,
@@ -606,10 +411,7 @@ fn check_window_pinned(
     let Ok(window) = windows.single() else {
         return;
     };
-    // `$WOW_DPI` re-denominates `$WOW_WIN` in PHYSICAL px (that knob's doc says so: the capture is
-    // the framebuffer that player's GPU would scan out), so the size this compares has to follow
-    // it. Comparing the logical size under an override refused every non-1× run outright — it read
-    // `want` against `want/dpi`.
+    // Under `$WOW_DPI`, `$WOW_WIN` is physical px, so compare the physical size.
     let res = &window.resolution;
     let got = match requested_dpi() {
         Some(_) => UVec2::new(res.physical_width(), res.physical_height()),
@@ -643,21 +445,8 @@ fn check_window_pinned(
     exit.write(AppExit::error());
 }
 
-/// One line at boot naming what the window actually got — and, on a Linux session, what it is
-/// talking to.
-///
-/// **The instrument half of 1627**, and it is not decoration. Every display and input report this
-/// client has had from a Linux player came from a machine nobody here can run: the Steam Deck
-/// perf reports behind 1624 and 1626, and the gamescope input report 1627 answers, were all
-/// diagnosed from prose. `bevy_winit` already logs the monitor, its scale factor and its refresh
-/// rate at creation; the two things it never says are which **backend** winit picked and whether a
-/// nested compositor is in the way — and a surprising amount hangs on the first of those.
-/// `CursorGrabMode::Locked`, which is what mouse-look asks for, is a real pointer lock on Wayland
-/// and is **rejected outright on X11** (`winit`'s x11 `set_cursor_grab` returns `NotSupported`),
-/// where `bevy_winit::attempt_grab` quietly falls back to `Confined`. "Which one am I on" should
-/// never again be a thing we reason about instead of read.
-///
-/// Not `#[cfg(feature = "dev")]`: the whole point is that it is in the log a *player* pastes.
+/// One boot line naming what the window got and, on Linux, the backend and any nested compositor
+/// (mouse-look's `CursorGrabMode::Locked` is rejected on X11). Not dev-only: players paste it.
 fn log_display_session(windows: Query<&Window, With<PrimaryWindow>>) {
     let Ok(window) = windows.single() else {
         return;
@@ -675,25 +464,20 @@ fn log_display_session(windows: Query<&Window, With<PrimaryWindow>>) {
     );
 }
 
-/// The display-server facts worth naming, as a trailing clause. Empty everywhere but a Linux/BSD
-/// session, where the same `cfg` the Wayland clipboard uses (decision 0702) marks the one platform
-/// whose windowing backend is a runtime choice rather than the only one there is.
+/// The display-server facts as a trailing clause; empty except on Linux/BSD, where the windowing
+/// backend is chosen at runtime.
 fn display_session() -> String {
     #[cfg(all(unix, not(any(target_os = "macos", target_os = "android"))))]
     {
         let set = |k: &str| std::env::var_os(k).is_some();
-        // Which backend winit took: it prefers Wayland when `WAYLAND_DISPLAY` names a socket and
-        // falls back to X11 (which, under a Wayland compositor, means XWayland). Both features are
-        // on — `bevy`'s `default_platform` carries `x11` *and* `wayland`, so this really is a
-        // runtime pick and not a build-time one.
+        // winit prefers Wayland when `WAYLAND_DISPLAY` is set, else X11 (XWayland under a
+        // Wayland compositor); `bevy`'s `default_platform` builds both.
         let backend = match (set("WAYLAND_DISPLAY"), set("DISPLAY")) {
             (true, _) => "wayland",
             (false, true) => "x11",
             (false, false) => "none",
         };
-        // gamescope exports its own socket name to children; the SteamOS session also stamps the
-        // Deck. Named because a nested compositor is the difference between "the window is wrong"
-        // and "the window is right and the compositor is scaling it".
+        // gamescope exports its socket name to children; the SteamOS session stamps the Deck.
         let nested = if set("GAMESCOPE_WAYLAND_DISPLAY") {
             ", gamescope"
         } else {
@@ -709,25 +493,15 @@ fn display_session() -> String {
     String::new()
 }
 
-/// Push the setting to the window **when the setting moves**, and only then.
-///
-/// `Res::is_changed()` is the honest signal since 2303: [`on_cvar`] writes this resource only
-/// when one of its own rows moved (before the registry, the CVar host's knob bundle deref-mutted
-/// every knob on every write, and this carried a value compare to work around it). The gate is
-/// load-bearing: re-asserting the setting every frame would fight the capture probes, which
-/// write `present_mode` on the window directly mid-run (`capture::mod`, `probes::live_fps`) to
-/// uncap a measurement — their override has to stick.
-///
-/// First sight deliberately does **not** just arm: an inserted resource reads as changed on its
-/// first frame, and `load_config` applies the saved value at `Startup`, after the window already
-/// exists at its boot mode — so the first run is the one that reconciles them.
+/// Push vsync to the window only when the setting moves or a `RestartGx()` asks: the capture
+/// probes write `present_mode` directly, and their override must stick.
 fn apply_present_mode(
     cfg: Res<VideoConfig>,
     restarts: Res<GxRestarts>,
     mut windows: Query<&mut Window, With<PrimaryWindow>>,
     mut last_restart: Local<u32>,
 ) {
-    // A `RestartGx()` re-asserts even when nothing moved — that is what the caller asked for.
+    // A `RestartGx()` re-asserts even when nothing moved.
     let forced = std::mem::replace(&mut *last_restart, restarts.0) != restarts.0;
     if !cfg.is_changed() && !forced {
         return;
@@ -736,8 +510,7 @@ fn apply_present_mode(
     let Ok(mut window) = windows.single_mut() else {
         return;
     };
-    // Guarded so an unchanged mode does not deref-mut `Window` — a spurious change there is a
-    // surface reconfigure.
+    // A spurious change to `Window` is a surface reconfigure.
     if window.present_mode != want {
         window.present_mode = want;
         info!(
@@ -747,23 +520,17 @@ fn apply_present_mode(
     }
 }
 
-/// The display-mode half, on the same change-gated shape as [`apply_present_mode`] and for the same
-/// two reasons — with one wrinkle of its own.
-///
-/// **The guard asks whether the window is fullscreen, never on which monitor.** Birth uses
-/// `MonitorSelection::Primary` (nothing else has an answer yet) and a live toggle uses `Current`
-/// (fill the monitor the window is actually on), so the two `WindowMode`s that both mean
-/// "fullscreen" are not equal values, and a `!=` compare would re-assert fullscreen on the first
-/// frame of every launch. Matching on the variant is the honest question.
+/// Push the display mode to the window, gated as [`apply_present_mode`] is. The guard matches the
+/// variant, not the monitor: birth uses `Primary` and a live toggle `Current`, so a `!=` compare
+/// would re-assert fullscreen on every launch.
 fn apply_window_mode(
     cfg: Res<VideoConfig>,
     restarts: Res<GxRestarts>,
     mut windows: Query<&mut Window, With<PrimaryWindow>>,
     mut last_restart: Local<u32>,
 ) {
-    // A `RestartGx()` re-asserts even when nothing moved, and that includes re-applying
-    // `gxResolution` to a window already in windowed mode — the one video setting whose value can
-    // have moved without the MODE moving, and therefore the one this verb is most useful for.
+    // A `RestartGx()` re-asserts even when nothing moved, re-applying `gxResolution` to a window
+    // that is already windowed.
     let forced = std::mem::replace(&mut *last_restart, restarts.0) != restarts.0;
     if !cfg.is_changed() && !forced {
         return;
@@ -783,13 +550,9 @@ fn apply_window_mode(
     if already && !forced {
         return;
     }
-    // Leaving fullscreen has to hand the size back, because entering it **overwrote**
-    // `window.resolution` with the monitor's — `bevy_window`'s own documented behaviour for
-    // `BorderlessFullscreen` — so a bare mode flip returns a monitor-sized "window". `gxResolution`
-    // is the record of what windowed means, which is exactly why it persists.
-    //
-    // Both writes land in one frame on purpose: `bevy_winit::changed_windows` applies `mode` before
-    // `resolution` in the same pass, so the inner size is set after the window has left fullscreen.
+    // Leaving fullscreen hands the size back: entering it overwrote `window.resolution` with the
+    // monitor's (`bevy_window`'s documented behaviour). Both writes land in one frame, as
+    // `bevy_winit::changed_windows` applies `mode` before `resolution`.
     if cfg.display == DisplayMode::Windowed {
         window
             .resolution
@@ -803,9 +566,7 @@ fn apply_window_mode(
 mod tests {
     use super::*;
 
-    /// The shipped default is synced, and "synced" is the engine default 0294 chose — `Fifo`, not
-    /// `AutoVsync`. Written as an assertion because the two are easy to conflate and are not the
-    /// same: `AutoVsync` resolves to `FifoRelaxed` where available, which tears on a late frame.
+    /// Synced is `Fifo`, not `AutoVsync` (`FifoRelaxed`, which tears on a late frame).
     #[test]
     fn the_default_is_synced_like_the_window_literal() {
         assert!(VideoConfig::default().vsync);
@@ -813,16 +574,13 @@ mod tests {
         assert_eq!(present_mode(true), PresentMode::Fifo);
     }
 
-    /// Uncapped is `AutoNoVsync` and never `Immediate` — the Metal finding this module exists to
-    /// hold (`Immediate` rails and takes ~1 s `nextDrawable` stalls).
+    /// On Metal `Immediate` takes ~1 s `nextDrawable` stalls.
     #[test]
     fn uncapped_is_autonovsync_not_immediate() {
         assert_eq!(present_mode(false), PresentMode::AutoNoVsync);
     }
 
-    /// The shipped display mode is fullscreen, and fullscreen is **borderless** — the whole point
-    /// of 1627. Welded as an assertion because `WindowMode::Fullscreen` is one word away and is the
-    /// mode that is ignored on Wayland and panics without a monitor.
+    /// `WindowMode::Fullscreen` is ignored on Wayland and panics without a monitor.
     #[test]
     fn the_default_is_borderless_fullscreen_not_exclusive() {
         assert_eq!(DisplayMode::default(), DisplayMode::Fullscreen);
@@ -836,24 +594,15 @@ mod tests {
         );
     }
 
-    /// `gxWindow` reads like every other 0/1 CVar in the tree: int + `!= 0`, with `"1"` the
-    /// *windowed* state — the reference's polarity, which is why the row is "Windowed Mode" and
-    /// not "Fullscreen".
+    /// The reference's polarity: the row is "Windowed Mode".
     #[test]
     fn gxwindow_one_is_windowed() {
         assert_eq!(display_from_flag(0.0), DisplayMode::Fullscreen);
         assert_eq!(display_from_flag(1.0), DisplayMode::Windowed);
     }
 
-    /// The mode round-trip, driven through the **real system** rather than around it — because the
-    /// two things that are easy to get wrong here are both invisible to a single live run.
-    ///
-    /// 1. A window born fullscreen must not be re-asserted on the first frame. Birth carries
-    ///    `MonitorSelection::Primary` and a live toggle carries `Current`, so the two `WindowMode`s
-    ///    that both mean "fullscreen" are unequal *values*; a `!=` guard would fire every launch.
-    /// 2. Leaving fullscreen must hand `gxResolution` back. Entering it overwrote
-    ///    `window.resolution` with the monitor's, so a bare mode flip returns a monitor-sized
-    ///    "window" — and on the 3440-wide panel B242/1619 came from, that is not a subtle miss.
+    /// A window born fullscreen is not re-asserted on the first frame, and leaving fullscreen
+    /// hands `gxResolution` back rather than the monitor's size.
     #[test]
     fn the_fullscreen_round_trip_keeps_the_monitor_out_of_the_windowed_size() {
         let mut app = App::new();
@@ -862,15 +611,14 @@ mod tests {
             display: DisplayMode::Fullscreen,
             windowed: UVec2::new(1024, 768),
         })
-        // The plugin's resource, seated by hand because this test runs the one system rather than
-        // the plugin — `apply_window_mode` reads it to know a `RestartGx()` asked for a re-assert.
+        // Seated by hand: this test runs the one system, not the plugin.
         .init_resource::<GxRestarts>()
         .add_systems(Update, apply_window_mode);
         let win = app
             .world_mut()
             .spawn((Window::default(), PrimaryWindow))
             .id();
-        // Born the way `lib.rs` builds it: already fullscreen, on the boot monitor selection.
+        // Born as `lib.rs` builds it: fullscreen, on the boot monitor selection.
         app.world_mut()
             .entity_mut(win)
             .get_mut::<Window>()
@@ -886,8 +634,7 @@ mod tests {
             "an already-fullscreen window must not be re-asserted onto another monitor selection"
         );
 
-        // Stand in for the compositor's half of being fullscreen — `bevy_window` documents that
-        // the resolution becomes the monitor's — then leave.
+        // Stand in for the compositor: fullscreen makes the resolution the monitor's. Then leave.
         app.world_mut()
             .entity_mut(win)
             .get_mut::<Window>()
@@ -904,8 +651,7 @@ mod tests {
             "leaving fullscreen restores gxResolution, never the monitor's size"
         );
 
-        // And back in, which must reach `Current` — the monitor the window is on by then, not the
-        // one it was born on.
+        // Back in, on `Current`: the monitor the window is on by now.
         app.world_mut().resource_mut::<VideoConfig>().display = DisplayMode::Fullscreen;
         app.update();
         assert!(matches!(
@@ -914,8 +660,6 @@ mod tests {
         ));
     }
 
-    /// `gxResolution` is the reference's `"WxH"` string, and a value that cannot be a window is
-    /// refused rather than passed on.
     #[test]
     fn gxresolution_parses_the_reference_spelling() {
         assert_eq!(parse_resolution("1280x800"), Some(UVec2::new(1280, 800)));
diff --git a/crates/benilla-app/src/vplates.rs b/crates/benilla-app/src/vplates.rs
index ec703c9e..7bd4cabd 100644
--- a/crates/benilla-app/src/vplates.rs
+++ b/crates/benilla-app/src/vplates.rs
@@ -1,64 +1,22 @@
-//! **V-key nameplates** — `CGNamePlateFrame` (ctor `0x7cb250`): the toggled health-bar plates
-//! over units' heads, a **2-D overlay** distinct from the world-pass overhead *names*
-//! (`crate::nameplates`) they replace.
+//! V-key nameplates, `CGNamePlateFrame` (ctor `0x7cb250`): health-bar plates drawn as a 2-D
+//! overlay that replaces a unit's overhead name. This file owns the world side (gate, anchor,
+//! projection, seat, basis); the widgets live in [`benilla_ui::script::nameplate`].
 //!
-//! The pinned law, transcribed:
-//! - **Master toggles** (`[0xc4da34]` bit 0 enemy / bit 3 friendly; real-client boot default
-//!   **OFF for both**, and since 1804 ours too — [`VPlateMode::default`]): the
-//!   `ShowNameplates`/`ShowFriendNameplates` script pairs —
-//!   bound to **V / Shift-V** by FrameXML `Bindings.xml` (asset-sourced default, like TAB).
-//! - **Gate**: never the own unit; never `NOT_SELECTABLE` (UNIT_FIELD_FLAGS bit 25); the
-//!   enemy/friendly split is **`CanAttack(localPlayer → unit)`**, NOT a reaction threshold
-//!   ([`crate::target::ring::plate_is_friendly`], `0x606980` — this file shipped `rank >= 4` for
-//!   a year and 1530 corrects it) —
-//!   and a **player** subject must additionally pass `CanCooperate`, which is nothing but the two
-//!   `FactionTemplate` faction-group masks being equal, so a player whose row carries neither
-//!   side's mask (a vmangos `.gm on` character is template 35, mask 0) is enemy-category no matter
-//!   how friendly they read; **max 20 yd**, hardcoded; **no
-//!   occlusion** (a 2-D overlay — plates draw through walls); snap, no smoothing. Anti-overlap
-//!   there *is*, since 0367 found the shared solver ([`crate::smart_rect`]) — this file's older
-//!   "no anti-overlap" missed it. And the sphere is bounded by the frustum:
-//!   the unit must be **in view** ([`crate::ui_pass::project_overlay`]) or the reference
-//!   **destroys** the plate outright (`0x60f600`, before the 20-yard cull); it is never clamped
-//!   in from off-screen, which is what ours did (1341/1344).
-//!   (The friendly-totem exclusion waits on totems existing.)
-//! - **Anchor**: the same overhead head point (`0x608640`, [`overhead_anchor`]) **+ 2/3 yd**
-//!   (`[0x80abfc]`), projected per frame (`0x483ee0`); the plate's **TOP-CENTER** lands on the
-//!   point (it hangs below — `0x509ec0`) and is edge-clamped half a plate inside the screen;
-//!   **constant screen size**: the geometry globals `[0x87d9cc]=0.1` × `[0x87d9d0]=0.025` in gx
-//!   screencoord units, where one unit = the screen **diagonal** `√(W²+H²)` (`0x41ad10` — and never
-//!   uiScale: plates live outside the UIParent cascade). **Our basis is growth-damped** past
-//!   [`PLATE_DIAG_KNEE`] — a director-pinned deviation (0185/0186): the real client grows
-//!   plates diagonal-linear without limit (`0x7705b0`) and the director rejected that
-//!   look; past 1024×768 the plate grows at half the real rate (midway between faithful and
-//!   the native size).
-//! - **Anatomy — not here any more.** The plate's six regions, its health-bar child, their
-//!   layers and the anchors between them live with the widgets that carry them
-//!   ([`benilla_ui::script::nameplate`], decision 2148): the plate is a real `Button` under the
-//!   `WorldFrame` and the shared frame→quad path draws it. What stays this file's is everything
-//!   about the WORLD — the gate above, the anchor, the projection, the seat, and the damped
-//!   basis the geometry is computed in ([`plate_basis`], [`gx_px`], [`text_px`]).
-//! - **Highlight = the mouseover unit ∪ the target** (the watcher `0x606f20 → 0x607080` reads
-//!   both globals): the bar's own colour brightens — a uniform [`LIT_BOOST`] lift of the fill
-//!   tint, gradient untouched, nothing else changes (director-pinned form, 0184; the recorded
-//!   ADD `Nameplate-Glow` rim read as hard edge lines on our linear-blending pipeline and is
-//!   not drawn). The plate is itself mouse-enabled UI: hovering it makes its unit the mouseover
-//!   (OnEnter `0x7cb850` → `[0xb4e2c8]` — [`PlateHover`], read straight off the widget the
-//!   pointer landed on since 2159), which also lifts the model emissive, and a completed click
-//!   selects through the plate ([`PlateClicks`]); the hover additionally turns the name yellow
-//!   `0xFFFFFF00` (OnEnter, name-only).
-//!   All decoupled from the target dim below.
-//! - **Target highlight**: relative alpha — with a target, the target's plate is opaque and
-//!   every other plate drops to `0x7F`; with no target all are opaque.
-//! - **Mutually exclusive with the overhead name** (ShouldShowName): a unit with a live plate
-//!   never also draws its floating name — [`VPlates`] is that verdict, read by the name driver.
-//!   (The questgiver marker raises for a live plate too — a director-pinned DEVIATION: the
-//!   reference really does sit low under a plate (`0x6076c0` arms anim 0) and the director
-//!   rejected that overlap; rationale on `quest_markers::pose_markers`, 2274/2275.)
-//!
-//! (The skull's trivial-gray leg is the shared grey check, [`benilla_ui::script::unit_is_grey`]
-//! — `0x5f0700`, the same one the tooltip/quest-range APIs read; it is vacuous on a ≥ +10
-//! hostile and kept for transcription fidelity.)
+//! - Toggles: the `[0xc4da34]` bitmask, bit 0 enemy and bit 3 friendly, both off at boot.
+//! - Gate: never the own unit or a `NOT_SELECTABLE` one; enemy or friendly by `CanAttack` from the
+//!   player (`0x606980`), and a player subject must also pass `CanCooperate` (equal faction-group
+//!   masks); 20 yd; no occlusion; a unit not projected into view loses its plate (`0x60f600`).
+//! - Anchor: the overhead head point (`0x608640`) plus 2/3 yd (`[0x80abfc]`), projected every
+//!   frame (`0x483ee0`), the plate's top centre on it (`0x509ec0`), sized in gx units of the
+//!   screen diagonal (`0x41ad10`), outside uiScale. Deviation: the basis is damped past
+//!   [`PLATE_DIAG_KNEE`], because the reference's unbounded growth (`0x7705b0`) draws plates too
+//!   large and soft at high resolutions.
+//! - Highlight: the mouseover or the target (`0x606f20` into `0x607080`) lights the plate.
+//!   Deviation: the bar fill brightens by `LIT_BOOST` in place of the reference's ADD
+//!   `Nameplate-Glow` rim, which reads as hard edge lines under benilla's linear blending.
+//!   Hovering a plate makes its unit the mouseover (`0x7cb850`) and turns the name yellow; a
+//!   click on it selects.
+//! - With a target, every other plate dims ([`DIM_ALPHA`]).
 
 use bevy::ecs::entity::EntityHashSet;
 use bevy::ecs::system::SystemParam;
@@ -73,121 +31,78 @@ use crate::net::{Guid, NetCommands, NetEntity, ObjectStore, Reputations, SelfPla
 use crate::target::{ring_reaction, Factions, Hovered, Selection, TargetUpdate};
 use benilla_world::view::WorldCamera;
 
-/// Sharp-resampling the frame border ([`border::resample_sharp`]) so the 128×32 art reads crisp at
-/// the plate's larger size instead of bilinear-magnified soft (0188).
+/// The plate border, sharp-resampled so its 128x32 art stays crisp when magnified.
 pub(crate) mod border;
 
-/// The master bitmask (`[0xc4da34]`): bit 0 enemy plates, bit 3 friendly. **Both boot OFF, the
-/// real client's own state** — see the derivation below. Enemy plates booted ON here from the 0167
-/// director call (combat plates from the first frame) until 1804; friendly has been OFF since the
-/// 0599 call, which also gives friendly speech bubbles room, because the faithful
-/// plate-blocks-bubble gate would otherwise suppress them. Both stay V / Shift-V togglable.
-/// `pub(crate)` so the capture harness can force plates on for the `vplates` scenario.
-///
-/// **This resource is the truth; the CVars are its persistence** (the [`CVAR_ENEMIES`] /
-/// [`CVAR_FRIENDS`] pair, [`crate::cvars`]). That mirrors the reference's own two-store shape: the
-/// engine bitmask is what the gate reads, and FrameXML keeps `NAMEPLATES_ON`/`FRIENDNAMEPLATES_ON`
-/// beside it for saving (`RegisterForSave`, UIOptionsFrame.lua) — pushing changes back through
-/// `ShowNameplates()`/`HideNameplates()`. 1.12 registers **no** nameplate CVar (no such string
-/// exists in the binary), so the names are the LATER-era engine's, the same posture
-/// as `autoLootDefault` — benilla's persistence lives in the CVar store (0954), and a setting with
-/// no 1.12 CVar takes the era name rather than inventing one.
-///
-/// **Both boot OFF — the reference's own state**, and verified on both of its halves, because
-/// either alone would be half an answer: the engine bitmask `[0xc4da34]` starts clear, and
-/// FrameXML's `UIOptionsFrame_Init` sets `NAMEPLATES_ON = nil` / `FRIENDNAMEPLATES_ON = nil` and
-/// only calls `ShowNameplates()` when the SAVED value is truthy (the install's own
-/// `UIOptionsFrame.lua` l.180-183, l.769-775). So a fresh 1.12 client draws no plates until you
-/// press V. Enemy plates shipped ON here from 0167 until 1804 — the same class of call as the
-/// overhead-name pair (`nameplates::NameConfig`): useful while the feature was being built, never
-/// re-weighed as a default. The `Default` is derived now that the claim is "both false", and it is
-/// still a *claim*: `cvars::tests` welds it to the registered `nameplateShowEnemies`/`Friendly`
-/// defaults and asserts the pair is off in as many words, so the derive cannot drift quietly.
+/// The `[0xc4da34]` master bitmask: bit 0 enemy plates, bit 3 friendly, both clear at boot as in
+/// the reference (`UIOptionsFrame.lua:180-183` sets the saved globals nil). The gate reads this
+/// resource; [`CVAR_ENEMIES`] and [`CVAR_FRIENDS`] persist it. 1.12 registers no nameplate CVar,
+/// so those names are not 1.12's.
 #[derive(Resource, Default, Clone, Copy)]
 pub(crate) struct VPlateMode {
     pub(crate) enemies: bool,
     pub(crate) friends: bool,
 }
 
-/// The persisted names of the two toggles — see [`VPlateMode`]. Welded to [`crate::cvars`]'s
-/// registered table by its own test, so the spelling here and the row on the Nameplates page can
-/// never drift apart.
+/// The persisted names of the two toggles.
 pub(crate) const CVAR_ENEMIES: &str = benilla_ui::script::CVAR_NAMEPLATE_ENEMIES;
 pub(crate) const CVAR_FRIENDS: &str = benilla_ui::script::CVAR_NAMEPLATE_FRIENDS;
 
-/// The units carrying a live plate this frame — the ShouldShowName exclusivity verdict the
-/// overhead-name driver reads (a plated unit never also draws its floating name).
+/// The units carrying a live plate this frame; the overhead-name driver draws no name for them
+/// (the reference's ShouldShowName).
 #[derive(Resource, Default)]
 pub(crate) struct VPlates(pub(crate) EntityHashSet);
 
-/// **The unit whose plate the pointer is inside** — the plate's own OnEnter publishing the
-/// mouseover, from this side (`0x7cb850` → `[0xb4e2c8]`).
-///
-/// The plate is real mouse-enabled UI now (2148), so the UI pointer pass owns the cursor over it
-/// and `target::hover`'s world pick correctly stands down; this is how the unit still reaches
-/// [`crate::target::Hovered`]. Written by the plate driver from
-/// [`benilla_ui::script::UiScript::hovered_nameplate`] — last frame's layout, which is the
-/// reference's own input-vs-layout latency.
+/// The unit whose plate the pointer is inside, from last frame's layout: the plate's OnEnter
+/// publishing the mouseover (`0x7cb850` into `[0xb4e2c8]`), since the world pick stands down
+/// over UI.
 #[derive(Resource, Default)]
 pub(crate) struct PlateHover(pub(crate) Option<Entity>);
 
-/// Completed clicks on plates, waiting for the targeting chain — the reference's plate click slot
-/// (`0x7cb910`), which ends in the same `SetSelection` a click on the body does.
-///
-/// Both a physical click and an addon's `plate:Click("LeftButton")` land here: the engine records
-/// them at the one click funnel both go through.
+/// Completed plate clicks, physical or an addon's `plate:Click`, waiting for the targeting chain:
+/// the reference's click slot (`0x7cb910`) ends in the same `SetSelection` as a body click.
 #[derive(Resource, Default)]
 pub(crate) struct PlateClicks {
     pub(crate) left: Vec<Entity>,
     pub(crate) right: Vec<Entity>,
 }
 
-/// The plate frame, gx screen-height units (`[0x87d9cc]`/`[0x87d9d0]`): 0.1 × 0.025. The border
-/// SetAllPoints-fills it; everything else anchors inside it (offsets: `0x7cb250`, `0x7cb6d0`).
+/// The plate frame in gx units (`[0x87d9cc]`, `[0x87d9d0]`); child offsets from `0x7cb250` and
+/// `0x7cb6d0`.
 const PLATE_W: f32 = 0.1;
 const PLATE_H: f32 = 0.025;
-/// The health bar: BOTTOMLEFT ← plate BOTTOMLEFT + (0.0031, 0.003125), sized 0.0804 × 0.007025.
+/// The health bar: BOTTOMLEFT at the plate's BOTTOMLEFT plus the offset.
 const BAR_OFF_X: f32 = 0.0031;
 const BAR_OFF_Y: f32 = 0.003125;
 const BAR_W: f32 = 0.0804;
 const BAR_H: f32 = 0.007025;
-/// Name text height 0.01, its BOTTOM at the plate CENTER; level height 0.0086, its CENTER at
-/// plate BOTTOMRIGHT + (−0.0092, +0.0071); both carry the FontString's black drop shadow at
-/// ±0.001. The skull (0.01 × 0.01) overlays the level's anchor when it replaces the number.
-///
-/// `LEVEL_H` is a **director-pinned deviation** (2026-07-07) from the byte 0.009: one em smaller
-/// across the window range (em 11 vs 12 at the reference, −1 up through 1440p). TEXT ems compose
-/// through the same damped gx basis as the frame geometry ([`text_px`] — the client-side chain:
-/// live re-raster on resize (`0x5c2b50`), no fixed UI space, no staleness).
+/// The name's BOTTOM sits at the plate CENTER; the level's CENTER at plate BOTTOMRIGHT plus
+/// (-0.0092, +0.0071); the skull overlays the level. Deviation: `LEVEL_H` is 0.0086, one em under
+/// the reference's 0.009, because the level number read too large.
 const NAME_H: f32 = 0.01;
 const LEVEL_H: f32 = 0.0086;
 const LEVEL_OFF_X: f32 = 0.0092;
 const LEVEL_OFF_Y: f32 = 0.0071;
 const SKULL_SIZE: f32 = 0.01;
-/// The raid-target icon (`0x7cb250`): 0.02 × 0.02, RIGHT ← border.LEFT (0,0) — it hangs
-/// off the plate's left edge, vertically centered; the 4-column atlas cell is 0.25.
+/// The raid-target icon (`0x7cb250`): its RIGHT on the border's LEFT, hanging off the plate's
+/// left edge.
 const RAID_ICON_SIZE: f32 = 0.02;
-/// The plate's world lift above the overhead anchor: 2/3 yd (`[0x80abfc]`).
+/// `[0x80abfc]`.
 const PLATE_LIFT: f32 = 2.0 / 3.0;
-/// Max plate distance, hardcoded (no cvar): 20 yd.
+/// 20 yd, hardcoded in the reference.
 const MAX_DIST_SQ: f32 = 20.0 * 20.0;
-/// The non-target relative alpha while something is targeted — a **director-pinned deviation**
-/// (2026-07-07) from the faithful `0x7F` (0.5), which faded the other plates too hard; raised so
-/// non-target plates stay readable. Tunable: 0.5 = the byte law, 1.0 = no dim.
+/// Deviation: the reference dims non-target plates to `0x7F`; raised because that fades them too
+/// far to read.
 const DIM_ALPHA: f32 = 178.0 / 255.0;
 
-/// The bar-fill palette — the byte-confirmed dwords (`0xcf60d0/e8/c8/dc`): pure
-/// red/blue/yellow/green (NOT the ring's pale player-blue). Client-space sRGB, the [`UiQuads`]
-/// convention.
+/// The bar-fill palette, the dwords at `0xcf60d0`/`e8`/`c8`/`dc`, in sRGB.
 const PLATE_HOSTILE: [f32; 4] = [1.0, 0.0, 0.0, 1.0];
 const PLATE_NEUTRAL: [f32; 4] = [1.0, 1.0, 0.0, 1.0];
 const PLATE_FRIENDLY: [f32; 4] = [0.0, 1.0, 0.0, 1.0];
 const PLATE_PLAYER: [f32; 4] = [0.0, 0.0, 1.0, 1.0];
 
-/// The plate palette selector — `0x7cbaa0`'s exact test order: hostile
-/// (reaction ≤ 1) red, else a player pure blue, else friendly (≥ 4) green, else — reaction 2–3,
-/// unfriendly AND neutral — yellow. (Rank 2 is yellow, not red: an earlier transcription here
-/// painted it hostile.) The bar fill (and its lit brighten) tints through this.
+/// `0x7cbaa0`'s test order: reaction 1 or less red, else a player blue, else 4 or more green,
+/// else (2 and 3) yellow.
 fn plate_tint(rank: u8, is_player: bool) -> [f32; 4] {
     if rank <= 1 {
         PLATE_HOSTILE
@@ -200,23 +115,15 @@ fn plate_tint(rank: u8, is_player: bool) -> [f32; 4] {
     }
 }
 
-/// The level con palette — the client's EXACT dwords (`0x7cbd50`; the softened WoW colors, not the
-/// FrameXML QuestDifficultyColor approximations we shipped first): red `0xFFFF1919`, orange
-/// `0xFFFF7F3F`, yellow `0xFFFFFF00`, green `0xFF3FB23F`, gray `0xFF7F7F7F`.
+/// The level con palette, `0x7cbd50`'s dwords, not FrameXML's `QuestDifficultyColor`.
 const CON_RED: [f32; 4] = [1.0, 25.0 / 255.0, 25.0 / 255.0, 1.0];
 const CON_ORANGE: [f32; 4] = [1.0, 127.0 / 255.0, 63.0 / 255.0, 1.0];
 const CON_YELLOW: [f32; 4] = [1.0, 1.0, 0.0, 1.0];
 const CON_GREEN: [f32; 4] = [63.0 / 255.0, 178.0 / 255.0, 63.0 / 255.0, 1.0];
 const CON_GRAY: [f32; 4] = [127.0 / 255.0, 127.0 / 255.0, 127.0 / 255.0, 1.0];
 
-/// The client's own con-color law (`0x7cbd50` — thresholds AND the grayband table
-/// `[0x81dda8]`, indexed `playerLevel/5`; it agrees with vmangos' formula at every probed level
-/// but the table is the client's own): `diff = unit − player`; ≥ +5 red, +3/+4 orange,
-/// −2..+2 yellow, lower → green while within `grayband` levels below, gray past it. The
-/// grayband/grey test lives in ONE home ([`benilla_ui::script::unit_is_grey`], the byte-identical
-/// `0x80ae98`/`0x81dda8` twins) shared with the engine tooltip's "??"/CIVILIAN gates and the
-/// `GetQuestGreenRange` binding — so the plate, the tooltip, and the target frame can never
-/// disagree on where grey starts.
+/// The con colour (`0x7cbd50`): +5 or more red, +3/+4 orange, -2..+2 yellow, then green until
+/// the shared grey test ([`unit_is_grey`], table `[0x81dda8]`) says gray.
 fn con_color(pl_level: u32, unit_level: u32) -> [f32; 4] {
     let diff = i64::from(unit_level) - i64::from(pl_level);
     if diff >= 5 {
@@ -232,49 +139,22 @@ fn con_color(pl_level: u32, unit_level: u32) -> [f32; 4] {
     }
 }
 
-/// Snap a logical-pixel coordinate onto the **device** pixel grid — the plate's texel alignment
-/// (a benilla divergence: the reference draws at fractional device coords).
-///
-/// The plate rect is snapped so the sharp-resampled border art blits 1:1 and reads crisp instead
-/// of bilinear-smeared (0188). Alignment is a property of the **framebuffer**, though, and the
-/// quad lane is *logical* px ([`crate::ui_pass`]: 1 world unit = 1 logical px) — so the plain
-/// `round()` this shipped with quantized the plate to `scale_factor` PHYSICAL pixels: two pixels
-/// of stepping on the 2× display we develop and play on, against a world that slides continuously
-/// underneath. At a fractional scale (1.25/1.5, the Windows norm) it did not land on a texel
-/// boundary at all — the crispness it was bought for was an accident of an integer scale factor.
-///
-/// Snapping on the device grid keeps the 1:1 blit, is correct at any scale factor, and halves the
-/// stepping at 2×: measured over a Goldshire walk at 1440×810 (the `vpl` trace), the extra
-/// displacement the snap adds to a plate's glide fell from a median 0.33 / max 0.99 logical px per
-/// frame to 0.21 / 0.49. What is left is the ±½ device pixel every crisp UI pays.
-///
-/// **Shared with the chat bubble** ([`crate::chat_bubble`]), like [`plate_basis`]/[`gx_px`]: it is
-/// the same outside-UIParent overlay family sliding over the same world, so it is the same snap
-/// law. The bubble shipped on a plain logical `round()` — this function's own bug, at the one site
-/// that never got the fix — which is 1398's finding.
+/// Snap a logical-pixel coordinate onto the device pixel grid, so the sharp-resampled border
+/// blits 1:1 at any scale factor. Deviation: the reference draws at fractional device
+/// coordinates; the snap keeps the magnified border crisp. Shared with the chat bubble.
 pub(crate) fn device_snap(v: f32, scale: f32) -> f32 {
     (v * scale).round() / scale
 }
 
-/// The knee of the plate's gx basis — **a director-pinned DEVIATION from the byte law**
-/// (0185/0186). The real client's plates grow diagonal-linear without limit (`0x7705b0`:
-/// ~294 px plate + em-29 name at 2560×1440, bilinear-softened) — the director
-/// rejected that look as too big/thick/soft, and a hard cap at native (0185) as too small.
-/// 1280 is the diagonal where the 0.1 × 0.025 frame is EXACTLY the border art's native
-/// 128 × 32 px; past it the basis grows at [`PLATE_GROWTH_DAMP`] of the real rate — at every
-/// window the plate lands midway between the faithful size and the native pin.
+/// Deviation: the reference's plates grow with the diagonal without limit (`0x7705b0`), which
+/// reads too big and soft; past this diagonal, where the frame is the border art's native
+/// 128x32 px, the basis grows at [`PLATE_GROWTH_DAMP`] of that rate.
 const PLATE_DIAG_KNEE: f32 = 1280.0;
-/// The growth rate past the knee: ½ = the midpoint between the byte law and the 0185 native
-/// pin (the director's "between what it was and what it is now"). 0 restores the 0185 pin,
-/// 1 the faithful law.
+/// 0 pins the native size, 1 is the reference's rate.
 const PLATE_GROWTH_DAMP: f32 = 0.5;
 
-/// One gx screencoord unit = the screen **DIAGONAL** `√(W²+H²)` (`0x41ad10` — the device space
-/// spans `[0,G44]×[0,G48]`, the live aspect basis; uiScale never enters: plates anchor
-/// WorldFrame-side, outside the UIParent cascade) — growth damped past [`PLATE_DIAG_KNEE`] (the
-/// director's pin).
-/// Shared with the chat bubble ([`crate::chat_bubble`]) — the sibling outside-UIParent overlay,
-/// same basis law so bubble text and plate text hold the same em at every window.
+/// One gx unit in pixels: the screen diagonal (`0x41ad10`), never uiScale, damped past
+/// [`PLATE_DIAG_KNEE`]. Shared with the chat bubble so its text holds the plate's em.
 pub(crate) fn plate_basis(viewport: Vec2) -> f32 {
     let d = viewport.x.hypot(viewport.y);
     if d <= PLATE_DIAG_KNEE {
@@ -284,44 +164,24 @@ pub(crate) fn plate_basis(viewport: Vec2) -> f32 {
     }
 }
 
-/// gx screencoord units → pixels over the plate basis. Frame geometry only — text takes
-/// [`text_px`]. Shared with the chat bubble, like [`plate_basis`].
+/// gx units to pixels for frame geometry; text takes [`text_px`].
 pub(crate) fn gx_px(v: f32, basis: f32) -> f32 {
     (v * basis).round()
 }
 
-/// Plate FontString height → the FreeType em: `min(32, round(h · basis))`. The real client's
-/// law (the FontObject bridge `0x44d040` divides the gx height by G48 before `GxuFontCreate`,
-/// the raster `0x5ca030` multiplies by the viewport height — netting `h·√(W²+H²)`, re-rasterized
-/// live on resize, 32-capped at the atlas cell); our `basis` is that diagonal under the director's
-/// [`PLATE_DIAG_KNEE`] damping. Reference-pinned at its 1152×648 window: name em 13, level 12.
-/// Shared with the chat bubble (`NAMEPLATE_FONT` at the same 0.01 gx), like [`plate_basis`].
+/// A plate FontString height to its em, `min(32, round(h * basis))`: the reference's
+/// `0x44d040` and `0x5ca030` net `h` times the diagonal, capped at the 32 px atlas cell, and
+/// re-rasterize on every resize (`0x5c2b50`).
 pub(crate) fn text_px(h: f32, basis: f32) -> f32 {
     (h * basis).round().min(32.0)
 }
 
-/// **The FrameXML mirror of the two toggles** — `NAMEPLATES_ON` and `FRIENDNAMEPLATES_ON`
-/// (decision 2132), pushed into whichever VM is live.
-///
-/// The reference keeps the plate state in **two** levels: the engine bitmask `[0xc4da34]`, which
-/// is volatile and cleared on every `EnterWorld`, and those two FrameXML globals, which are the
-/// saved store. `UpdateNameplates` (`UIOptionsFrame.lua` l.768) replays the store into the
-/// bitmask, from `UIParent_OnEvent`'s VARIABLES_LOADED and PLAYER_ENTERING_WORLD arms
-/// (`UIParent.lua` l.234, l.367).
-///
-/// **benilla has only one level.** [`VPlateMode`] is the state and the [`CVAR_ENEMIES`] /
-/// [`CVAR_FRIENDS`] pair is its persistence, and nothing clears it at a world entry — so on this
-/// engine the replay has nothing to restore and everything to break. With the globals left nil
-/// (nothing here ever wrote them) `UpdateNameplates` took its else branch and called
-/// `HideNameplates()`, which writes the CVar, which IS the store: the player's setting was erased
-/// at every world entry and `config.toml` lost the line as "at default".
-///
-/// So the globals are kept TRUE, which makes the stock replay a value-preserving no-op — and is
-/// what a third-party addon reading `NAMEPLATES_ON` is owed anyway, which was 2115's whole
-/// argument for loading the stock window in the first place.
+/// Push the mode into FrameXML's `NAMEPLATES_ON`/`FRIENDNAMEPLATES_ON`. `UpdateNameplates`
+/// (`UIOptionsFrame.lua:768`) replays these globals into the engine on `VARIABLES_LOADED` and
+/// every `PLAYER_ENTERING_WORLD` (`UIParent.lua:234`, `:367`), so they must match the mode or
+/// the replay turns plates off and overwrites the persisted CVar.
 pub(crate) fn push_plate_globals(script: &benilla_ui::script::UiScript, mode: VPlateMode) {
-    // The reference's own truthiness for these two: the number `1`, or nil. Never `0` — a Lua
-    // `0` is truthy, so `NAMEPLATES_ON = 0` would read as ON in `UpdateNameplates`'s `if`.
+    // The number 1 or nil, never 0: a Lua 0 is truthy.
     let on = |b: bool| b.then_some(1i64);
     let g = script.lua().globals();
     if let Err(e) = g
@@ -332,12 +192,8 @@ pub(crate) fn push_plate_globals(script: &benilla_ui::script::UiScript, mode: VP
     }
 }
 
-/// The globals kept in step with the mode for the life of each VM ([`push_plate_globals`]).
-///
-/// Behind a [`crate::ui_script::VmMemo`] (1290) because "this VM has been told" is a fact about
-/// the VM, not about the process. The world-entry load seeds them earlier still — ahead of
-/// `VARIABLES_LOADED`, which no `Update` system can reach — so this is the steady-state half:
-/// a V press, an options checkbox, a `/console` write, an addon's `SetCVar`.
+/// Keep the globals in step with the mode, memoised per VM; the world-entry load seeds them
+/// before `VARIABLES_LOADED`, which no `Update` system can reach.
 fn feed_plate_globals(
     script: Option<NonSendMut<benilla_ui::script::UiScript>>,
     mode: Res<VPlateMode>,
@@ -354,19 +210,11 @@ fn feed_plate_globals(
     }
 }
 
-/// NAMEPLATES / FRIENDNAMEPLATES / ALLNAMEPLATES through the binding table (0997; defaults V /
-/// SHIFT-V / CTRL-V). The typing gate and 0585's modifier law live in the dispatch now.
+/// The NAMEPLATES, FRIENDNAMEPLATES and ALLNAMEPLATES bindings; ALLNAMEPLATES is 1.12's body,
+/// both on unless both already on. A press also writes the CVar, which persists it.
 ///
-/// The V and SHIFT-V halves stay benilla's **independent** toggles (the shipped behavior) rather
-/// than 1.12's exclusive dance (whose NAMEPLATES body also force-hides friendly plates — a
-/// recorded divergence, 0997 residue). ALLNAMEPLATES arrives with the table and takes the 1.12
-/// body's semantics as-is: both on unless both already on, else both off.
-///
-/// **A key press mirrors into the CVar table** ([`VPlateMode`]'s doc): `set_cvar_engine` is the
-/// minimap-zoom pattern — the engine's own value moved, so the table follows it AND queues the
-/// change, which is what dirties `config.toml` and what makes the Nameplates page's checkboxes
-/// read right the next time they are opened. The resource stays authoritative either way: with no
-/// UI VM (a capture, a bare test app) the mirror is a silent no-op and V still works.
+/// Deviation: V and Shift-V toggle their own bit independently, where 1.12's bodies
+/// (`Bindings.xml:516-537`) turn the other kind off.
 fn toggle_vplates(
     binds: Res<crate::bindings::BindingsState>,
     mut mode: ResMut<VPlateMode>,
@@ -403,9 +251,9 @@ fn toggle_vplates(
     }
 }
 
-/// The world/reaction inputs of the plate gate, bundled (the 16-param ceiling).
+/// The world and reaction inputs of the plate gate, bundled under the 16-param ceiling.
 #[derive(SystemParam)]
-#[allow(clippy::type_complexity)] // one bundled system param — the app's convention
+#[allow(clippy::type_complexity)] // one bundled system param
 struct PlateWorld<'w, 's> {
     units: Query<
         'w,
@@ -423,38 +271,29 @@ struct PlateWorld<'w, 's> {
     factions: Option<Res<'w, Factions>>,
     reputations: Res<'w, Reputations>,
     selection: Res<'w, Selection>,
-    // The mouseover unit (the 3-D pick ∪ last frame's plate rects) — with `selection`, the
-    // highlight's trigger pair (the watcher's two globals `[0xb4e2c8]`/`[0xb4e2d8]`).
+    // With `selection`, the highlight's pair: the watcher's globals `[0xb4e2c8]`/`[0xb4e2d8]`.
     hovered: Res<'w, Hovered>,
     camera: Query<'w, 's, (&'static Camera, &'static Transform), With<WorldCamera>>,
-    // The cursor, for the plate-rect hover (OnEnter — the yellow name, this frame's rects).
     window: Query<'w, 's, &'static Window, With<bevy::window::PrimaryWindow>>,
-    // The pending ground-target cast — the plate's `+0x3c` hit-test veto (`0x7cba30`).
+    // The pending ground-target cast, for the plate's hit-test veto (`0x7cba30`).
     targeting: Res<'w, crate::spell::SpellTargeting>,
 }
 
-/// Gate + draw, every frame: decide which units carry a plate (into [`VPlates`], the
-/// name-exclusivity verdict), seat each one, and hand the result to the widget layer as
-/// [`PlateState`] — at constant screen size over the projected anchor + 2/3 yd. Runs after
-/// the script extract), after the targeting chain (it reads the frame's selection verdict).
+/// Every frame: gate the units, seat each plate and hand the result to the widget layer as
+/// [`PlateState`]s. Runs after the targeting chain, whose selection it reads.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 fn drive_vplates(
     mode: Res<VPlateMode>,
     mut plates: ResMut<VPlates>,
     mut plate_hover: ResMut<PlateHover>,
     mut plate_clicks: ResMut<PlateClicks>,
-    // Camera freelook, for the mouselook toggle `0x60f830`: plates stop taking the mouse while
-    // the pointer is driving the camera.
     rig: Res<crate::player::CameraControl>,
     world: PlateWorld,
     names: Res<NameCache>,
     net_commands: Res<NetCommands>,
-    // The widget layer this drives (decision 2148). `None` in a VM-less run (a capture with the
-    // interface off, a bare test app) — the gate below then costs one early return.
+    // `None` in a run with no UI VM.
     script: Option<NonSendMut<benilla_ui::script::UiScript>>,
-    // The seam this frame's px↔unit conversion runs at (`windowH/768 × uiScale`).
     ui_scale: Res<crate::ui_script::UiScaleCvar>,
-    // The overhead-anchor inputs ([`overhead_anchor`]).
     anchor_q: (
         Query<&BoneAttach>,
         Query<&benilla_world::rig_anim::RigPose>,
@@ -462,23 +301,16 @@ fn drive_vplates(
         Query<&GlobalTransform>,
         Query<(), With<crate::entities::mount::MountChild>>,
     ),
-    // The frame's claim bucket 0 (nameplates) — cleared and rebuilt every pass; worldtext owns
-    // bucket 1 in `combat_text` and the two never interact (a plate never pushes a number).
+    // Claim bucket 0, the plates', rebuilt every frame; combat text owns bucket 1.
     mut bucket: Local<crate::smart_rect::SmartBucket>,
-    // The raid-target board (decision 0434 §6) — the plate's raid-icon child reads it.
     group: Res<crate::ui_party::GroupState>,
-    // Whether this VM's plates have been told about freelook (the `0x60f830` edge).
     mut mouse_told: Local<crate::ui_script::VmMemo<Option<bool>>>,
 ) {
     plates.0.clear();
     plate_hover.0 = None;
     bucket.clear();
-    // **Every early return has to RETIRE the plates first, and that is new with 2148.** A painter
-    // could stop drawing and the plates were gone with the frame's quads; widgets stay until they
-    // are hidden, so a V press that turns plates off — or a camera-less frame, or a world exit —
-    // would otherwise leave the last frame's plates standing on screen forever. `sync` with no
-    // states is exactly the reference's own answer: `0x608a10` on every live plate, hiding each and
-    // returning it to the pool.
+    // Every early return retires the plates first, or the widgets stay on screen; the reference
+    // hides each live plate and returns it to the pool (`0x608a10`).
     let retire_all = |script: Option<NonSendMut<benilla_ui::script::UiScript>>| {
         if let Some(mut script) = script {
             script.retire_nameplates();
@@ -505,28 +337,16 @@ fn drive_vplates(
     let basis = plate_basis(viewport);
     let gx = |v: f32| gx_px(v, basis);
     let window = world.window.single().ok();
-    // **The mouselook toggle** (`0x60f830`, called from `0x483e80`/`0x483e70`): plates stop taking
-    // the mouse while the camera is in freelook, so a right-drag that starts over a plate turns the
-    // camera instead of clicking the plate, and the plates are not holding a pointer that has left
-    // the screen. Written on the EDGE, not per frame — the reference's own is two call sites on the
-    // freelook transitions, and the memo is keyed to the VM because that is what it is memory about
-    // (1290). A fresh VM's plates are born with the bit, so the memo starting empty is right.
-    // Which unit's plate the pointer is inside (last frame's layout), and the completed clicks
-    // waiting on the targeting chain. Both come from the plate widgets themselves, which is the
-    // reference's own arrangement: the plate's OnEnter publishes the mouseover and its click slot
-    // ends in `SetSelection`.
+    // Plates stop taking the mouse in freelook (`0x60f830`, called from `0x483e80`/`0x483e70` on
+    // the transitions), written on the edge per VM.
     let looking = rig.is_looking();
     if *mouse_told.get(&script) != Some(looking) {
         *mouse_told.get(&script) = Some(looking);
         script.set_nameplate_mouse(!looking);
     }
-    // **The plate's OWN veto** (`0x7cba30`, the `+0x3c` override), which is a different mechanism
-    // from the freelook toggle above and has to stay one: while a ground-targeted spell is armed a
-    // plate refuses the hit test *before* the rect, so the reticle can be placed through it — and
-    // it does that without touching the mouse-enabled bit, so `IsMouseEnabled()` still answers
-    // truthfully to an addon. `TargetingWants::Location` is `0x6e6320`'s `flag & 0x60` verbatim.
-    // Written every frame rather than on an edge: it is a plain flag read at hit-test time, not a
-    // walk over the plate list, so there is no edge worth memoising.
+    // While a ground-targeted spell is armed (`0x6e6320`'s `flag & 0x60`), plates refuse the hit
+    // test (`0x7cba30`, the `+0x3c` override) without clearing the mouse-enabled bit, so
+    // `IsMouseEnabled()` is unchanged.
     script.set_nameplate_hit_test_veto(
         world
             .targeting
@@ -539,21 +359,15 @@ fn drive_vplates(
 
     let (pw, ph) = (gx(PLATE_W), gx(PLATE_H));
     let scale = window.map_or(1.0, |w| w.scale_factor());
-    // The px↔unit seam. Every number below is computed in window px exactly as it always was —
-    // the projection, the seat, the solve, the device snap — and divided through this once, at
-    // the boundary, because the widget layer speaks FrameXML units.
+    // Everything below is in window px, divided by this once for the widget layer's units.
     let seam = window.map_or(1.0, |w| {
         crate::ui_script::seam_scale(w.height(), ui_scale.0)
     });
     let mut states: Vec<PlateState> = Vec::new();
 
-    // The seat PRIORITY (`0x608870`/`0x6089a0` + the per-frame walk `0x608ce0`): plates seat in
-    // squared-distance order from the fixed gx point (0.4, 0.3) — the 4:3 screen center, a
-    // literal constant in the ref, converted here over the diagonal basis with the Y mirrored
-    // out of the ref's Y-up device space. The first-seated plate never moves; each later one is
-    // solved off the plates already claimed this frame (bucket 0) — the reference's bouncing,
-    // never-overlapping plates. Gate + project first, then seat in sorted order. The TRUE
-    // diagonal, not the 0185-damped `basis`: the point is positional law, not plate size.
+    // Plates seat in squared-distance order from the gx point (0.4, 0.3), Y mirrored from the
+    // reference's Y-up space (`0x608870`, `0x6089a0`, walked by `0x608ce0`); each later plate is
+    // solved off those already claimed. The undamped diagonal: this is position, not size.
     let diag = viewport.length();
     let sort_pt = Vec2::new(0.4 * diag, viewport.y - 0.3 * diag);
     let mut cands = Vec::new();
@@ -561,43 +375,27 @@ fn drive_vplates(
         if !matches!(net.kind, EntityKind::Unit | EntityKind::Player) {
             continue;
         }
-        // NOT_SELECTABLE never gets a plate — `0x60f600`'s gate 2 (`0x60f622 shr ecx,0x19` /
-        // `0x60f628 jne 0x60f740` → pool + hide + clear `[unit+0xe60]`), unconditional, and re-run
-        // every tick because `0x60f600`'s caller `0x607ef9` sits inside CGUnit's OnUpdate
-        // (`vtable+0x38` = `0x607ed0`). So the flag arriving on a plated unit takes its plate away
-        // on the next tick, which falls out of this per-frame gate for free.
-        //
-        // **This suppression is load-bearing, not cosmetic** (decision 2060): a plate hover
-        // publishes the mouseover *directly* — `0x7cb850 OnEnter` → `0x7cb869 call 0x492890`, with
-        // none of the `IsSelectable` grading the world hover gets at `0x482982`. If a flagged unit
-        // ever kept its plate, hovering that plate would hand it a name tooltip the reference never
-        // shows. The plate gate is the only thing standing there.
+        // `NOT_SELECTABLE` (flags bit 25) never gets a plate, re-tested every tick (`0x60f622`,
+        // from CGUnit's OnUpdate `0x607ed0`). A plate hover publishes the mouseover with no
+        // selectability check (`0x7cb869`, unlike the world hover at `0x482982`), so this gate is
+        // what keeps such a unit's tooltip away.
         if store.is_some_and(|s| s.0.unit_flags() & (1 << 25) != 0) {
             continue;
         }
-        // A DEAD unit shows no plate — the per-tick gate `0x60f600`'s FIRST, unconditional
-        // test: signed `UNIT_FIELD_HEALTH ≤ 0`, absent = 0 (the
-        // zero-init descriptor). A poll, not a death callback; the lootable bit is never
-        // consulted. Feign death keeps health > 0, so it clears THIS leg — the gate that takes a
-        // feigning body's plate away is the hostile-only one below (decision 1022).
+        // `0x60f600`'s first test: health 0 or less (absent reads 0) has no plate. Feign death
+        // keeps health, so it passes here.
         if store.is_none_or(|s| s.0.unit_health().unwrap_or(0) == 0) {
             continue;
         }
-        // …and the SAME per-tick gate's second leg (`0x60f62e` — corrects this file's older
-        // "ghost stays plated" note): `bytes_1 byte3 & 3` (ghost | creep) denies the plate — a
-        // released ghost (health 1) carries none.
+        // `0x60f62e`: `bytes_1` byte 3 `& 3` (ghost or creep) has no plate.
         if store.is_some_and(|s| s.0.unit_is_ghost_visual()) {
             continue;
         }
-        // 20 yd, hardcoded, from the player.
         if (tf.translation - self_tf.translation).length_squared() > MAX_DIST_SQ {
             continue;
         }
-        // A unit with a CREATEDBY owner but no SUMMONEDBY owner, carrying `UNIT_FIELD_FLAGS`
-        // bit 9 (`0x200`), gets no plate in EITHER category (`0x60f70b`–`0x60f72d`, byte-verified
-        // — the same CHARMEDBY→SUMMONEDBY→CREATEDBY triple the standalone owner accessor
-        // `0x611670` walks in the same order). The bit's vanilla NAME is unrecorded; the number
-        // is what the binary tests, so that is what we test.
+        // A CREATEDBY owner, no SUMMONEDBY owner and flags bit 9 (`0x200`): no plate in either
+        // category (`0x60f70b`-`0x60f72d`); the bit's 1.12 name is unknown.
         if store.is_some_and(|s| {
             s.0.unit_created_by().is_some_and(|g| g != 0)
                 && s.0.unit_summoned_by().is_none_or(|g| g == 0)
@@ -605,13 +403,9 @@ fn drive_vplates(
         }) {
             continue;
         }
-        // **The enemy/friendly split is `CanAttack`, run PLAYER → UNIT** — not a reaction-rank
-        // threshold, which is what this shipped with and what 1530 corrects. The two halves of a
-        // plate genuinely run the reaction in opposite directions: the CATEGORY here asks "can I
-        // attack it?" (and for a rep-slot faction that question is answered by the AT-WAR bit,
-        // never by the standing), while the bar COLOUR below asks the unit for its reaction toward
-        // us — where the standing IS the input. A not-at-war neutral-standing NPC is therefore a
-        // friendly-category plate with a yellow bar, exactly as the reference draws it.
+        // The category is `CanAttack` from the player (a rep faction answers by its at-war bit);
+        // the bar colour is the unit's reaction toward us (by standing). A not-at-war neutral NPC
+        // is a friendly plate with a yellow bar.
         let rank = ring_reaction(
             world.factions.as_deref(),
             &world.reputations,
@@ -629,24 +423,13 @@ fn drive_vplates(
         if friendly && !mode.friends || !friendly && !mode.enemies {
             continue;
         }
-        // The gate's dead-looking leg, which sits on the HOSTILE side of that same split
-        // (`0x60f72f test al,al; jne` → friendly goes to the creature-type check `0x60f750`;
-        // hostile falls into `0x60f733 shr eax,5; test al,1` → hide). So a feigning hunter's
-        // plate vanishes for the enemies he is hiding from, which is the point of the spell,
-        // while a friendly one keeps his (decision 1022).
+        // Only on the hostile side, a dead-looking unit has no plate (`0x60f733`): a feigning
+        // hunter's plate hides from enemies and stays for friends.
         if !friendly && store.is_some_and(|s| s.0.unit_reads_dead()) {
             continue;
         }
-        // Project the plate point: the overhead anchor + 2/3 yd, per frame, no smoothing — and
-        // honour the projector's ACCEPT verdict ([`crate::ui_pass::project_overlay`]): behind the
-        // camera or outside the viewport, there is no plate. That is the reference's own law, and
-        // a hard one — `0x60f600` **destroys** the plate frame on a false verdict, before it ever
-        // reaches the seat.
-        //
-        // Ours instead ran an off-screen point into the seat, whose clamp translates a rect from
-        // anywhere bodily onto the screen: **30% of every drawn plate** was a unit nobody could
-        // see, pinned to a border, claiming bucket space and shoving the plates of units you can
-        // (1341 — two thirds of them while standing still, and 90% of the reported jitter).
+        // Behind the camera or outside the viewport there is no plate: `0x60f600` destroys it
+        // before the seat, never clamping it in from off-screen.
         let anchor = overhead_anchor(
             entity,
             tf,
@@ -676,30 +459,17 @@ fn drive_vplates(
     for (_, screen, anchor, rank, is_player, entity, guid, store) in cands {
         plates.0.insert(entity);
 
-        // The target-highlight relative alpha: target (or nobody targeted) opaque, others 0x7F.
         let alpha = if !has_target || world.selection.target == Some(entity) {
             1.0
         } else {
             DIM_ALPHA
         };
-        // The bar tint: the NAMEPLATE palette in `0x7cbaa0`'s exact order.
         let tint = plate_tint(rank, is_player);
-        // The frame SEAT (`0x509ec0`): the plate's TOP-CENTER lands on the projected
-        // point — the plate HANGS BELOW head + 2/3 yd — and the point is edge-clamped half a
-        // plate inside every screen border (`SetPoint(TOP ← root.BOTTOMLEFT, clampedX/Y)`).
-        // The highlight is a 2-D hover over THIS rect (the frame's OnEnter — yellow name). `pw`/`ph`
-        // (the plate's logical size) are hoisted above the loop — the border resample keys off them.
-        // Geometry trace for the vplates capture (`WOW_VPLATE_TRACE=1`): the exact plate rects
-        // this frame, in logical px — the machine-side check the capture PNG can't give
-        // (fill/border/text hues overlap under zoom). The `vpl` lines of the shared trace below
-        // are read back by `scripts/vplsum.py`.
+        // `WOW_VPLATE_TRACE=1` prints each plate rect in logical px.
         static TRACE: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
         let trace = *TRACE.get_or_init(|| std::env::var("WOW_VPLATE_TRACE").as_deref() == Ok("1"));
-        // The full seat (`0x509ec0`): the desired rect TOP-anchored on the raw projected point
-        // (the plate hangs below head + 2/3 yd), then the bucket-0 seat law — normalize, SOLVE
-        // off the plates already claimed this frame, clamp the resolved center-X/top half a
-        // plate inside every border, rebuild ([`crate::smart_rect`]). The old bare edge-clamp
-        // was this law minus the solve.
+        // The seat (`0x509ec0`): the plate hangs from its top centre on the projected point, is
+        // solved off the plates already claimed, then clamped half a plate inside the screen.
         let desired = Rect::new(
             screen.x - pw * 0.5,
             screen.y,
@@ -707,20 +477,13 @@ fn drive_vplates(
             screen.y + ph,
         );
         let solved = bucket.resolve(desired, viewport);
-        // The rect snaps to the device pixel grid ([`device_snap`]) — the LEFT edge, not the
-        // centre: an odd width would put a snapped centre's edges back between texels. The CLAIM
-        // takes the snapped rect, so later plates dodge exactly what is drawn.
+        // Snap the left edge, not the centre, which an odd width would put between texels; the
+        // claim takes the snapped rect, so later plates dodge what is drawn.
         let top = device_snap(solved.min.y, scale);
         let left = device_snap(solved.min.x, scale);
         let plate = Rect::new(left, top, left + pw, top + ph);
-        // **The jitter decomposition** (`WOW_MOVE_TRACE` tag `vpl`, one line per plate per frame):
-        // the world anchor, the camera pose that projected it, the raw projected point, the
-        // solver's answer, and the snapped rect — so "the plates are jittery when moving" is
-        // attributed to one of the four (a moving anchor, a noisy camera, a flipping solve, the
-        // pixel snap) from numbers rather than from the eye. It rides the shared trace — tag-
-        // filtered, one line per plate — and not the `WOW_VPLATE_TRACE` eprintlns beside it, whose
-        // four unbuffered writes per plate per frame would distort the frame pacing the question
-        // is about (the 0880 lesson).
+        // Trace tag `vpl`, one line per plate per frame: anchor, camera, projected point, solve
+        // and snapped rect, so plate jitter can be attributed to one of them.
         if benilla_assets::trace::enabled_for("vpl") {
             let (cp, cf) = (cam_pose.translation, cam_pose.forward());
             benilla_assets::trace::line(
@@ -750,13 +513,9 @@ fn drive_vplates(
             );
         }
         bucket.claim(plate);
-        // The plate's own hover, from last frame's layout: the widget layer answers which unit's
-        // plate the pointer is inside, and the driver resolves it to this frame's entity below.
         let hover = hovered_key == Some(guid.0);
-        // The highlight trigger — the watcher's OR over the two globals: this unit is the
-        // MOUSEOVER (the 3-D body pick, or the plate's own hover — [`PlateHover`], which the
-        // widget layer answered above) or the current TARGET. `hover` joins in directly so the
-        // bar brighten never lags the yellow name by the frame the mouseover takes to publish.
+        // The mouseover or the target lights the bar; `hover` joins directly so the brighten does
+        // not lag the yellow name by the frame the mouseover takes to publish.
         let lit =
             hover || world.hovered.target == Some(entity) || world.selection.target == Some(entity);
         if trace {
@@ -765,22 +524,11 @@ fn drive_vplates(
                 screen.x, screen.y, plate.min.x, plate.min.y, plate.max.x, plate.max.y
             );
         }
-        // ── The plate's state, handed to the widget layer ─────────────────────────────────
+        // ── The plate's state, handed to the widget layer ──
         //
-        // Everything above is unchanged: the gate, the anchor, the projection's ACCEPT verdict,
-        // the distance-sorted seat and the bucket solve are all about the WORLD, and they stay
-        // the app's. What changed in decision 2148 is only what happens with the answer — it used
-        // to become six quads, and it now becomes one [`PlateState`] for a real widget, which the
-        // shared frame→quad path draws and an addon can read, hook, restyle or take over.
-        //
-        // The seam scale (`windowH/768 × uiScale`) converts our window px into the FrameXML units
-        // the widget layer speaks. Dividing it out here is deliberate and is a DIVERGENCE worth
-        // naming: the reference's plates are outside the `uiScale` cascade (uiScale is
-        // `UIParent`'s own frame scale there, and the WorldFrame is a sibling root), while
-        // benilla folds uiScale into one global seam (0582/0584). Until that seam grows a
-        // per-cascade answer, the driver compensates, so a plate's PIXELS stay uiScale-blind the
-        // way the reference's are.
-        // The raid-target board (decision 0434 §6): 1-based here, 0-based for the atlas cell.
+        // The reference's plates sit outside the uiScale cascade, but benilla folds uiScale into
+        // one global seam, so dividing by it here keeps plate pixels uiScale-blind.
+        // The raid-target index is 1-based here, 0-based for the atlas cell.
         let mark = group.raid_target_index(guid.0);
         let x_units = (plate.min.x + plate.max.x) * 0.5 / seam;
         let y_units = (viewport.y - plate.min.y) / seam;
@@ -796,13 +544,12 @@ fn drive_vplates(
             }
         }
         states.push(PlateState {
-            // The plate's identity is the UNIT's, for the life of the plate — the reference's
-            // `[unit+0xe60]` binding, which every addon's per-plate cache rests on.
+            // A plate stays bound to its unit for its life, as the reference's `[unit+0xe60]`;
+            // addons cache per plate on it.
             key: guid.0,
             top_centre: (x_units, y_units),
-            // RAW health and its max — `healthbar:GetValue()` is `[bar+0x320]`, not a fraction
-            // (`0x78f5d0`). pfUI and CustomNameplates both divide, and a fraction here would read
-            // as full health.
+            // Raw health, not a fraction: `healthbar:GetValue()` is `[bar+0x320]` (`0x78f5d0`),
+            // and addons divide it by the max.
             health: store.and_then(|s| s.0.unit_health()).unwrap_or(0) as f32,
             max_health: store
                 .and_then(|s| s.0.unit_max_health())
@@ -813,16 +560,9 @@ fn drive_vplates(
                 .resolve_unit(guid.0, store, &net_commands)
                 .map(str::to_owned)
                 .unwrap_or_default(),
-            // The skull's two legs (`0x7cbb40`): a WORLD BOSS — creature-
-            // classification rank 3, through the client's own getter (`gated_rank`, decision
-            // 0782, which is why a MIND-CONTROLLED boss shows its number) — unconditionally; or a
-            // hostile ≥ 10 levels up that isn't trivial-grey (`0x5f0700`, the shared check,
-            // vacuous on a ≥ +10 hostile and kept for transcription fidelity).
-            //
-            // **A unit with no level yet is not a boss.** The two facts travel separately, because
-            // folding them into one `Option` made a missing `UNIT_FIELD_LEVEL` read as a skull —
-            // the old painter kept the whole block inside `if let Some(level)`, so no level meant
-            // no number AND no skull, and that is the behaviour restored here.
+            // The skull (`0x7cbb40`): rank 3 through `gated_rank` (so a charmed boss shows its
+            // level), or a hostile 10 or more levels up that is not grey (`0x5f0700`, vacuous
+            // there but transcribed). A unit with no level yet shows neither.
             level: store.and_then(|s| s.0.unit_level()),
             skull: store.and_then(|s| s.0.unit_level()).is_some_and(|level| {
                 crate::names::gated_rank(
@@ -839,7 +579,7 @@ fn drive_vplates(
                     .map_or([1.0, 1.0, 1.0, 1.0], |level| con_color(my_level, level));
                 [c[0], c[1], c[2]]
             },
-            // The 0434 §6 board, 0-based for the atlas (`col = idx & 3`, `row = idx >> 2`).
+            // 0-based for the atlas: `col = idx & 3`, `row = idx >> 2`.
             raid_icon: (mark >= 1).then(|| mark - 1),
             alpha,
             lit,
@@ -847,9 +587,8 @@ fn drive_vplates(
         });
     }
 
-    // The window-derived half, once per frame — the widget layer rewrites the static anchors only
-    // when this actually moves, which is what keeps an addon's own re-anchoring alive between
-    // resizes (decision 2148 §5).
+    // The widget layer rewrites the static anchors only when this moves, so an addon's own
+    // re-anchoring survives between resizes.
     script.sync_nameplates(
         PlateGeometry {
             width: pw / seam,
@@ -864,26 +603,23 @@ fn drive_vplates(
             raid_size: gx(RAID_ICON_SIZE) / seam,
             name_height: text_px(NAME_H, basis) / seam,
             level_height: text_px(LEVEL_H, basis) / seam,
-            // A constant ONE LOGICAL PIXEL of drop shadow, in the widget layer's units — the
-            // director's 2026-07-07 tuning, which the shared text arm would otherwise scale by
-            // this same seam and draw 2 px thick from a 1152-tall window up.
+            // Deviation: a constant one-logical-pixel shadow, not the reference's 0.001 gx, which
+            // draws 2 px thick and too heavy at larger windows. Divided by the seam, which the
+            // shared text arm would otherwise scale it by.
             shadow_offset: 1.0 / seam,
         },
         &states,
     );
 }
 
-/// The set the plate drive runs in — the overhead-name driver orders after it (the
-/// ShouldShowName exclusivity: a plated unit draws no floating name).
+/// The plate driver's set; the overhead-name driver runs after it.
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub(crate) struct VPlateSet;
 
-/// V-key nameplates: the toggles + the per-frame gate/draw.
+/// V-key nameplates: the toggles and the per-frame gate and draw.
 pub(crate) struct VPlatesPlugin;
 
-/// The two V-plate toggles' change callback (decision 2303) — the bitmask's two bits, flags
-/// like every other checkbox. Lowercased here like every arm; the consts carry the registered
-/// spelling.
+/// Apply a change to either toggle CVar to the bitmask.
 pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut mode: ResMut<VPlateMode>) {
     if ev.is(CVAR_ENEMIES) {
         mode.enemies = ev.flag();
@@ -903,30 +639,17 @@ impl Plugin for VPlatesPlugin {
                 Update,
                 (
                     toggle_vplates,
-                    // After the targeting chain (selection/hover verdicts) — which is
-                    // `.after(WorldStage::Input)`, so the camera this projects through is THIS
-                    // frame's, the freshest data a plate can be built from.
-                    //
-                    // **And the paint is this frame's too, since decision 2168.** The UI pass is
-                    // two systems: the tick/resolve half stays ahead of `WorldStage::Input`
-                    // (the hit test feeds `PointerOverUi`, which the camera reads), and the QUAD
-                    // half — `ui_script::extract::paint_script` — runs after this driver. 2148
-                    // shipped with the whole pass ahead of the camera, so the anchors written here
-                    // were drawn by the NEXT frame's extract: the seat reached the paint 16 ms
-                    // late, every frame, which is the director's "way more jittered when the
-                    // creature is moving" (measured both ways on the `vpl` trace, 2026-09-10 —
-                    // median driver→paint gap 16.0 ms before, 0.0 ms after).
+                    // After the targeting chain, itself after `WorldStage::Input`, so this projects
+                    // through this frame's camera; `ui_script::extract::paint_script` runs after
+                    // it, so the plates paint the same frame.
                     drive_vplates.after(TargetUpdate),
                 )
                     .chain()
                     .in_set(VPlateSet),
             )
-            // **Outside [`VPlateSet`] deliberately.** Its only ordering need is to be ahead of the
-            // script tick, and three sets order *after* `VPlateSet` while `drive_vplates` runs
-            // after the targeting chain — pulling the whole set in front of `UiInput` to carry one
-            // system would rewire all of that. A V press can therefore reach the globals a frame late,
-            // which costs nothing: their only readers are `UpdateNameplates` at the two world-entry
-            // events and an addon that calls it, never a per-frame path.
+            // Outside `VPlateSet`, which runs after the targeting chain: it only needs to precede
+            // the script tick, and a frame's lag is harmless since the globals are read only at
+            // world entry.
             .add_systems(Update, feed_plate_globals.in_set(crate::ui_script::UiFeed));
     }
 }
@@ -935,9 +658,7 @@ impl Plugin for VPlatesPlugin {
 mod tests {
     use super::*;
 
-    /// The client's own con law (`0x7cbd50`): thresholds at level 30 (grayband[6] = 7 → green
-    /// down to 23, gray at 22), the exact softened dwords, and the low-level edge (grayband[0] =
-    /// 4, so a level-1 never grays anything).
+    /// `0x7cbd50` at level 30 (grayband[6] = 7: green down to 23, gray at 22) and the low edge.
     #[test]
     fn con_color_matches_the_byte_table() {
         assert_eq!(con_color(30, 35), CON_RED);
@@ -955,39 +676,28 @@ mod tests {
             CON_GRAY,
             "grayband[1] = 4 ≥ the max gap at 5"
         );
-        // The exact dwords (0xFFFF1919 / 0xFFFF7F3F / 0xFF3FB23F): byte-pinned, not the
-        // FrameXML QuestDifficultyColor approximations.
+        // 0xFFFF1919, 0xFFFF7F3F, 0xFF3FB23F.
         assert_eq!(CON_RED[1], 25.0 / 255.0);
         assert_eq!(CON_ORANGE[2], 63.0 / 255.0);
         assert_eq!(CON_GREEN[1], 178.0 / 255.0);
     }
 
-    /// The snap is on the DEVICE grid, not the logical one. At the 2× scale we develop on, a
-    /// logical `round()` moved the plate two physical pixels at a time; this moves it one, which
-    /// is the smallest step that still lands the border blit on a texel boundary. Pinned so the
-    /// `scale` argument can't be "simplified" away back into `round()`.
     #[test]
     fn the_plate_snaps_on_the_device_grid_not_the_logical_one() {
-        // 2× display: the grid is every half logical pixel, and every snapped value is a whole
-        // number of PHYSICAL pixels.
+        // At 2x every snapped value is a whole number of physical pixels.
         for (v, want) in [(10.0, 10.0), (10.2, 10.0), (10.3, 10.5), (10.6, 10.5)] {
             let got = device_snap(v, 2.0);
             assert_eq!(got, want, "{v} at 2×");
             assert_eq!((got * 2.0).fract(), 0.0, "{got} is a whole physical pixel");
         }
-        // 1×: unchanged from the old law.
         assert_eq!(device_snap(10.4, 1.0), 10.0);
         assert_eq!(device_snap(10.6, 1.0), 11.0);
-        // 1.5× (the Windows norm), where a logical round() was never texel-aligned at all.
         assert_eq!((device_snap(10.4, 1.5) * 1.5).fract(), 0.0);
         assert_eq!((device_snap(10.9, 1.5) * 1.5).fract(), 0.0);
     }
 
-    /// Plate text ems ride the gx DIAGONAL like the frame geometry, growth-damped past the
-    /// director's [`PLATE_DIAG_KNEE`] — name em 13 at the reference's 1152×648 window (measured),
-    /// level em 11 (director-pinned one under the byte 0.009); at larger windows the em lands midway
-    /// between the byte law and the 0185 native pin (2560×1440: byte law 29, pin 13 → ours 21). The
-    /// raw em still carries the client's 32 atlas-cell cap.
+    /// Name em 13 at 1152x648 as measured in the reference; at 2560x1440 the reference's 29 and
+    /// the native 13 damp to 21.
     #[test]
     fn plate_text_sizes_take_the_damped_diagonal_basis() {
         let ref43 = plate_basis(Vec2::new(1024.0, 768.0));
@@ -1001,16 +711,7 @@ mod tests {
         assert_eq!(text_px(NAME_H, 10_000.0), 32.0, "atlas-cell cap, raw law");
     }
 
-    /// **A key press moves the CVar too** — the half a settings page cannot see for itself. V
-    /// flips the resource (the bitmask) AND mirrors into the table as an ENGINE write, which is
-    /// what dirties `config.toml` and what the Nameplates page's checkbox reads next time it
-    /// opens. Without the mirror, plates toggled by key would silently revert at every launch and
-    /// the window would show the wrong state.
-    ///
-    /// The table is seeded at `"0"/"0"` because that is what the app seeds it with: both plate
-    /// CVars boot at the reference's OFF since 1804 ([`VPlateMode::default`]), so the first V of a
-    /// session turns plates ON. The mirror is direction-blind, and the second press below is here
-    /// to say so.
+    /// Without the CVar write, a key-toggled plate would revert at every launch.
     #[test]
     fn the_v_key_mirrors_into_the_cvar_table() {
         use crate::bindings::{cmd, BindingsState};
@@ -1041,7 +742,6 @@ mod tests {
             "untouched"
         );
 
-        // And back: the same key mirrors the OFF as a host write too.
         app.world_mut()
             .insert_resource(BindingsState::test_fired(&[cmd::NAMEPLATES]));
         app.update();
@@ -1051,7 +751,7 @@ mod tests {
             vec![(CVAR_ENEMIES.to_string(), "0".to_string())]
         );
 
-        // Shift-V is the other bit, and only the other bit.
+        // Shift-V moves only the other bit.
         app.world_mut()
             .insert_resource(BindingsState::test_fired(&[cmd::FRIEND_NAMEPLATES]));
         app.update();
@@ -1061,15 +761,11 @@ mod tests {
             vec![(CVAR_FRIENDS.to_string(), "1".to_string())]
         );
 
-        // A frame with nothing fired writes nothing at all.
         app.world_mut().insert_resource(BindingsState::default());
         app.update();
         assert!(moved(&mut app).is_empty());
     }
 
-    /// **The FrameXML mirror is owed to every VM** (decision 2132) — the mode's two bits reach
-    /// `NAMEPLATES_ON`/`FRIENDNAMEPLATES_ON` as the reference's `1`-or-nil, follow a change, and
-    /// are handed to a rebuilt VM (a `/reload`) without one.
     #[test]
     fn the_plate_globals_follow_the_mode_and_survive_a_rebuilt_vm() {
         let read = |app: &mut App| {
@@ -1100,8 +796,7 @@ mod tests {
             "the reference's own truthiness: the NUMBER 1, never a truthy `0`"
         );
 
-        // `ReloadUI()`: a fresh VM, and the mode did not move. The memo is keyed on the VM's
-        // session (1290), so the new one is told again rather than inheriting the old one's claim.
+        // `ReloadUI()`: a fresh VM with the mode unchanged is told again.
         app.insert_non_send_resource(benilla_ui::script::UiScript::new().unwrap());
         assert_eq!(
             read(&mut app),
@@ -1116,9 +811,6 @@ mod tests {
         );
     }
 
-    /// The palette selector follows `0x7cbaa0`'s exact test order — notably reaction 2
-    /// (unfriendly) is YELLOW with 3, not hostile red, and a hostile player is red before the
-    /// player-blue test.
     #[test]
     fn plate_tint_matches_the_byte_order() {
         assert_eq!(plate_tint(1, false), PLATE_HOSTILE);
@@ -1130,12 +822,8 @@ mod tests {
         assert_eq!(plate_tint(6, true), PLATE_PLAYER, "player beats friendly");
     }
 
-    /// The plate geometry law through the gx DIAGONAL unit, growth-damped past
-    /// [`PLATE_DIAG_KNEE`]: at 1024×768 (diag exactly 1280) the 0.1 × 0.025 frame = 128 × 32 px
-    /// — the border texture's native size, the bar ≈ 103 × 9 px. Past the knee the frame lands
-    /// midway between the byte law and native (1080p: byte law 220, native 128 → ours 174).
-    /// Below the knee the diagonal rules unchanged (a smaller window shrinks the plate,
-    /// `0x41ad10`).
+    /// At 1024x768 (diagonal 1280) the frame is the border's native 128x32 px; at 1080p the
+    /// reference's 220 and the native 128 damp to 174.
     #[test]
     fn plate_geometry_damps_past_the_native_knee() {
         let ref43 = plate_basis(Vec2::new(1024.0, 768.0));
diff --git a/crates/benilla-app/src/vplates/border.rs b/crates/benilla-app/src/vplates/border.rs
index 17a8ae86..eaebeb75 100644
--- a/crates/benilla-app/src/vplates/border.rs
+++ b/crates/benilla-app/src/vplates/border.rs
@@ -1,28 +1,20 @@
-//! Sharpening the V-plate frame border (decision 0188).
+//! The V-plate frame border, resampled sharp.
 //!
-//! The frame art `Interface\Tooltips\Nameplate-Border` is a **128 × 32** BLP. The plate frame is
-//! `0.1 × 0.025` gx; past the 1024×768 knee (and always on a retina framebuffer) it is drawn
-//! *larger* than 128 × 32, so the UI pass's bilinear sampler **magnifies** the bitmap — the 1 px
-//! gold bevel smears across several soft pixels (the director's "blurry border").
-//!
-//! The director's call (2026-07-07): keep the **exact same art**, just make it sharper — not a
-//! redraw. So we resample the BLP's own pixels to the plate's physical size with **sharp bilinear**:
-//! flat within each source texel, a ~1-output-pixel anti-aliased ramp at texel boundaries. Same
-//! colours, same proportions, same socket — but crisp edges instead of a full-texel gradient. The
-//! result is uploaded as the border texture and drawn 1:1 (see [`super::drive_vplates`], which
-//! regenerates it only when the plate's physical size changes).
+//! Deviation: the reference magnifies the 128 × 32 `Interface\Tooltips\Nameplate-Border` art with
+//! `GL_LINEAR` (`0x770200`, filter `[0x878cf0]` = 1), smearing its 1 px bevel once the plate is
+//! larger than native; we resample the same pixels to the plate's physical size with sharp
+//! bilinear and draw it 1:1, because the chosen look is the same art with a crisp bevel.
+//! [`super::drive_vplates`] regenerates it when the physical size changes.
 
-/// Resample `src` (an `sw × sh` sRGB RGBA8 image) to `dw × dh` with sharp bilinear. Interpolates in
-/// **premultiplied** sRGB so alpha edges don't dark-fringe. On magnification the per-axis boundary
-/// ramp is compressed to ~1 output pixel (crisp); on minification it falls back to plain bilinear
-/// (`sharpen = max(scale, 1)`), so a plate smaller than native still resolves cleanly.
+/// Resample `src` (an `sw × sh` sRGB RGBA8 image) to `dw × dh` with sharp bilinear, premultiplied
+/// so alpha edges do not fringe dark. Magnifying squeezes each texel boundary to about one output
+/// pixel; minifying is plain bilinear.
 pub(crate) fn resample_sharp(src: &[u8], sw: u32, sh: u32, dw: u32, dh: u32) -> Vec<u8> {
     let fetch = |x: i32, y: i32| -> [f32; 4] {
         let x = x.clamp(0, sw as i32 - 1) as u32;
         let y = y.clamp(0, sh as i32 - 1) as u32;
         let i = ((y * sw + x) * 4) as usize;
         let a = src[i + 3] as f32 / 255.0;
-        // Premultiplied: colour weighted by coverage, so blended edges stay clean.
         [
             src[i] as f32 / 255.0 * a,
             src[i + 1] as f32 / 255.0 * a,
@@ -35,12 +27,11 @@ pub(crate) fn resample_sharp(src: &[u8], sw: u32, sh: u32, dw: u32, dh: u32) ->
     let mut out = vec![0u8; (dw * dh * 4) as usize];
     for dy in 0..dh {
         for dx in 0..dw {
-            // Source coordinate at this output texel's centre (−0.5 = texel-centre convention).
+            // Source coordinate at this output texel's centre.
             let su = (dx as f32 + 0.5) * sw as f32 / dw as f32 - 0.5;
             let sv = (dy as f32 + 0.5) * sh as f32 / dh as f32 - 0.5;
             let (x0, y0) = (su.floor(), sv.floor());
-            // Sharpen the fractional part: steepen the ramp so the texel boundary spans ~1 output
-            // pixel instead of the whole magnified texel (1.0 = plain bilinear).
+            // Steepen the ramp so a texel boundary spans about one output pixel.
             let ru = (((su - x0) - 0.5) * sharpen_x + 0.5).clamp(0.0, 1.0);
             let rv = (((sv - y0) - 0.5) * sharpen_y + 0.5).clamp(0.0, 1.0);
             let (x0, y0) = (x0 as i32, y0 as i32);
@@ -74,12 +65,9 @@ pub(crate) fn resample_sharp(src: &[u8], sw: u32, sh: u32, dw: u32, dh: u32) ->
 mod tests {
     use super::*;
 
-    /// A 2×2 source (one opaque red texel, the rest transparent) upscaled 4× stays the same size and
-    /// colour, and the sharp ramp keeps the opaque quadrant's core fully opaque red — no bilinear
-    /// wash across the whole image.
+    /// A 2×2 source with one opaque red texel, upscaled 4×, keeps a solid red core.
     #[test]
     fn resample_sharp_keeps_the_texel_crisp() {
-        // src texel (0,0) opaque red; the other three transparent.
         let mut src = vec![0u8; 2 * 2 * 4];
         src[0] = 255; // r
         src[3] = 255; // a
@@ -90,14 +78,11 @@ mod tests {
             let i = ((y * dw + x) * 4) as usize;
             [out[i], out[i + 1], out[i + 2], out[i + 3]]
         };
-        // The top-left corner sits well inside the opaque red texel — solid red, full alpha.
         assert_eq!(px(0, 0), [255, 0, 0, 255], "crisp opaque red core");
-        // The far corner is inside the transparent texels — clear.
         assert_eq!(px(7, 7)[3], 0, "transparent quadrant stays clear");
     }
 
-    /// Round-trip identity: resampling to the same size returns the source unchanged (the ramp is a
-    /// no-op at scale 1). Opaque pixels, so premultiply is exact.
+    /// Opaque pixels, so premultiplication round-trips exactly.
     #[test]
     fn resample_sharp_identity_at_same_size() {
         let mut src = vec![0u8; 3 * 3 * 4];
diff --git a/crates/benilla-app/src/weapon_trail.rs b/crates/benilla-app/src/weapon_trail.rs
index b9926eb8..3742e47c 100644
--- a/crates/benilla-app/src/weapon_trail.rs
+++ b/crates/benilla-app/src/weapon_trail.rs
@@ -1,92 +1,37 @@
-//! The weapon **swing trail** — `SpellVisualKit` CharProc type **8**, the ribbon a melee ability
-//! smears behind its blade.
+//! The weapon swing trail: `SpellVisualKit` CharProc type 8, the ribbon a melee ability smears
+//! behind its blade, and the whole visual of 16 of the 27 trail kits a live spell reaches.
 //!
-//! For **16 of the 27 trail kits a live spell reaches, this is the entire visual**: kit 324
-//! (Heroic Strike / Overpower / Mortal Strike / Bloodthirst / Rend — 218 spells), 506
-//! (Revenge / Riposte / Mongoose Bite), 557 (Sunder Armor), 646 (Hamstring / Wing Clip), 399
-//! (Sinister Strike), 822 (Garrote), 823 (Feint / Disengage) name no emitter slot at all, so
-//! without this module those abilities render nothing beyond the swing animation.
-//!
-//! ## The mechanism
-//!
-//! The proc does not draw. It **latches two words on the unit** and the unit's *next* animation
-//! fires them:
+//! The proc latches two words on the unit and the unit's next animation fires them:
 //!
 //! ```text
 //! 0x60d80a  the type-8 dispatcher arm      unit+0xd1c = ftol(ParamZero) | (ftol(ParamThree) << 24)
 //!                                          unit+0xd20 = ftol(ParamTwo)          -- ms
 //! 0x5fe48e  CGUnit::PlayAnimation, the      if (unit+0xd20 != 0) 0x60e550(&colour, duration)
-//!           fields' ONLY reader             unit+0xd20 = 0                       -- one-shot
+//!           fields' only reader             unit+0xd20 = 0                       -- one-shot
 //! 0x60e550  fan out to CGUnit+0xd34[0..1]   one WTOBJECT per weapon hand
-//! 0x6c6750  arm a SWING on that object      re-arming a live one RESETS its ring, never stacks
+//! 0x6c6750  arm a SWING on that object      re-arming a live one resets its ring, never stacks
 //! 0x6c67f0  the weapon model's per-frame cb sample $WTB/$WTT -> 0x6c6560
 //! 0x6c6560  append / fade / draw / die      the arithmetic transcribed in [`Swing::step`]
 //! ```
 //!
-//! [`WeaponTrail`] is the WTOBJECT: one per spawned weapon prop whose model authors both markers,
-//! carrying the reference's nullable `SWING` as [`Swing`]. The prop's own despawn (a weapon swap,
-//! a shapeshift) is the teardown, exactly as `0x6c6970` frees the object with the model reference
-//! it holds.
-//!
-//! ## The light term — ambient only, and no `N·L` half
-//!
-//! The callback turns lighting **on** (EGxRs `0x0e = 1` at `0x6c6847`) over a vertex format that
-//! carries **no normal** (format 7 is position + colour, stride 16). That combination is not a
-//! contradiction and it is not a no-op — it selects a specific, reduced term:
+//! Lighting is on (`0x6c6847`) over a vertex format with no normal (format 7, position and
+//! colour), which leaves:
 //!
 //! ```text
-//! out = (Σ enabled lights' Ambient) × authoredColour  +  inherited material Emissive
+//! out = (Σ enabled lights' Ambient) × authoredColour
 //! ```
 //!
-//! - The vertex colour **is** the material: `0x5a1e30` sets both `DIFFUSEMATERIALSOURCE` and
-//!   `AMBIENTMATERIALSOURCE` to `D3DMCS_COLOR1` off the format's diffuse bit, which format 7 has.
-//! - The normal is **explicitly disabled**, not stale: `0x592a60` replaces the format mask rather
-//!   than OR-ing it, and `0x59c100` issues `glDisableClientState(GL_NORMAL_ARRAY)` when the bit is
-//!   clear (D3D's format-7 descriptor carries `−1` in the normal column). So there is no `N·L` to
-//!   compute and the **diffuse half contributes nothing** — which is why this does not simply take
-//!   [`benilla_world::particles::buffer::EffectLighting::Scene`], whose term is
-//!   `clamp(ambient + diffuse·max(N·L, 0))` against the world up axis. Applying that here would
-//!   add a sun term the reference does not have.
-//! - The global `D3DRS_AMBIENT` (EGxRs id 6) has **zero writers image-wide** and defaults to 0, so
-//!   the whole ambient contribution comes from the M2 lighting collector's own enabled lights —
-//!   the same lights our lit emitters take their `ambient` from.
+//! The vertex colour is the material (`0x5a1e30` sources diffuse and ambient from `COLOR1`). The
+//! normal array is disabled (`0x592a60`, `0x59c100`), so by the D3D9 lighting model, inferred
+//! rather than traced, the diffuse half contributes nothing. `D3DRS_AMBIENT` has no writers and
+//! stays 0, and the trail is a type-5 render record, for which `0x70c190` commits emissive 0
+//! (`SetState(2, 0)` at `0x70ca30`). The lights are the wearer's (`[item+0x3b8] =
+//! [wearer+0x3b8]`, `0x718960`): the day/night ambient outdoors (`0x69e770`), the light node's
+//! ramped word indoors (`0x69e4c0`). The ambient folds into the vertex colours on the CPU.
 //!
-//! So the trail **darkens with the scene** rather than burning at its authored colour — and the
-//! scene it darkens with is its **wearer's**, not the world's. The draw runs inside the weapon
-//! model's own per-frame callback during the wearer's model draw, so the enabled lights it
-//! inherits are the ones the M2 collector committed for that unit; the held weapon's light node is
-//! the wearer's own by aliasing (`[item+0x3b8] = [wearer+0x3b8]`, `0x718960`):
-//!
-//! - **outdoors** a unit's committed ambient IS the day/night ambient (`0x69e770`), so
-//!   [`benilla_world::lighting::WowLighting`] is exact, not an approximation;
-//! - **indoors** it is the light node's own ramped word, chasing `cap96(MOCV)` (`0x69e4c0`) — the
-//!   room's light, never the sky's ([`benilla_world::interior::NodeAmbient`], the ambient half of
-//!   the same committed words [`benilla_world::interior::ParticleLight`] folds whole). Its absence
-//!   is the exterior lane, which is why the fallback above is the right one and not a guess.
-//!
-//! One named approximation is left: the **emissive** term is not modelled. It is inherited
-//! material state whose value is not pinned, and `EMISSIVEMATERIALSOURCE` is set nowhere,
-//! so it is a constant we would be inventing rather than reproducing.
-//!
-//! The fold happens on the CPU, into the vertex colours, and the draw declares
-//! [`benilla_world::particles::buffer::EffectLighting::None`] — the ambient is a per-draw constant,
-//! and per-draw constants belong in the vertex stream on a lane whose whole design is one shared
-//! buffer of them (the effect lane's own rule; it is what the `Committed` variant exists for).
-//!
-//! ## What is deliberately NOT here
-//!
-//! - **No transport ride-frame.** A committed sample is stored in absolute world coordinates and
-//!   never re-projected. `0x6c67f0` takes `0x7131b0`'s world position straight into the ring and
-//!   neither it nor `0x6c6560` reads `[CM2Model+0x17c]` — unlike the particle and ribbon lanes,
-//!   whose birth sites (`0x7b5160`, `0x7b7bc0`) do (`crate` `benilla_world::ride_frame`, 1591).
-//!   A swing on a moving deck smears in the reference too; that is the mechanism, not a gap.
-//! - **No sheath gate, and no handedness test.** `0x608d60` resolves the weapon's attachment
-//!   through `0x47a070(SheatheType, isMainHand)` and hangs the object wherever the weapon
-//!   currently sits, so a stowed weapon is still trail-capable; and neither of `[vtbl+0x98]`'s two
-//!   bodies (`0x5ec240` for a player, `0x605e30` for a creature) contains an InventoryType or
-//!   handedness test. A two-hander gets one trail only because the server leaves the off-hand slot
-//!   empty — which is exactly what our own off-hand slot does. **Creatures get trails too**, off
-//!   `UNIT_VIRTUAL_ITEM_SLOT_DISPLAY`; this is not a player-only effect.
+//! The reference has no transport ride frame for a trail (`0x6c67f0` stores world positions, so a
+//! swing on a moving deck smears), no sheath gate and no handedness test (`0x608d60`); creatures
+//! trail too.
 
 use bevy::ecs::entity::EntityHashMap;
 use bevy::prelude::*;
@@ -97,65 +42,45 @@ use benilla_world::view::WorldCamera;
 
 use crate::entities::HeldAttached;
 
-/// The ring's slot count — `0x6c677c` zeroes `0x80` entries of 12 bytes, and `0x6c64a4`'s
-/// `and eax,0x7f` is the write mask. Two vertices are appended per frame, so this is **64 frames**
-/// of blade history.
+/// The ring's slot count (`0x6c677c`; write mask `and eax,0x7f` at `0x6c64a4`): two samples a
+/// frame, so 64 frames of blade.
 const RING_SLOTS: u32 = 0x80;
 
-/// The **reader's** modulus, and it is not [`RING_SLOTS`]: `0x6c64e5`/`0x6c64ea`
-/// (`mov ecx,0x7f; idiv ecx`) takes `i % 127` where the writer stored at `i & 127`. The two
-/// genuinely disagree in build 5875, so once the write counter passes 127 the reader picks up a
-/// neighbouring sample instead of the one it wants. See [`Swing::read`] for what that looks like
-/// and which kits reach it.
+/// The reader's modulus, not [`RING_SLOTS`]: `0x6c64e5` reads `i % 127` where the writer stored
+/// at `i & 127`, a shipped mismatch ([`Swing::read`]).
 const READ_MODULUS: u32 = 0x7f;
 
-/// `0x811278` in `.rdata` — `0x3b5a740e`, the nearest f32 to `1/300`, and the per-millisecond fade
-/// coefficient the step multiplies by.
+/// `0x811278`: `0x3b5a740e`, the nearest f32 to 1/300, the per-millisecond fade coefficient.
 const FADE_PER_MS: f32 = 0.0033333334;
 
-/// The type-8 dispatcher **arming** a unit — the two words `0x60d828`/`0x60d835` write to
-/// `unit+0xd1c` / `unit+0xd20`. Written for every kit play that carries the proc, at every stage,
-/// exactly where the beam case is written; consumed by [`fire_weapon_trails`].
+/// The type-8 dispatcher arming a unit (`0x60d828`/`0x60d835` write `unit+0xd1c`/`unit+0xd20`),
+/// at every stage of every kit play carrying the proc.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct TrailArm {
-    /// The unit the kit played on — the wielder, never the target.
+    /// The unit the kit played on: the wielder, never the target.
     pub(crate) entity: Entity,
     pub(crate) trail: TrailProc,
 }
 
-/// The per-unit **pending arm** — `unit+0xd1c` / `unit+0xd20` as a map, the same shape
-/// [`super::creature_anim::spell_visual::MorphLatch`] gives `[unit+0xd54]`.
-///
-/// One slot per unit, because the reference has one pair of fields: a second proc before the
-/// first has fired **overwrites** it rather than queueing. Consumed and cleared by the unit's next
-/// animation (`0x5fe4b1 mov [ebx+0xd20],edi`), and swept when the unit goes.
+/// The per-unit pending arm, `unit+0xd1c`/`unit+0xd20`: one slot, so a second proc before the
+/// first fires overwrites it; cleared by the unit's next animation (`0x5fe4b1`).
 #[derive(Resource, Default)]
 pub(crate) struct TrailLatch(EntityHashMap<TrailProc>);
 
-/// A spawned **weapon prop** whose model authors both `$WTB` and `$WTT` — the reference's
-/// `WTOBJECT` (pool `0xce86d8`), one per weapon hand, alive for as long as the weapon is.
-///
-/// A model missing either marker gets no component at all, which is `0x6c67f0`'s own
-/// `0x7130e0` presence gate (`je -> return`: absent ⇒ nothing is drawn).
+/// A weapon prop whose model authors both `$WTB` and `$WTT`: the reference's `WTOBJECT` (pool
+/// `0xce86d8`), one per hand. A model missing either marker gets none (`0x6c67f0`'s `0x7130e0`).
 #[derive(Component)]
 pub(crate) struct WeaponTrail {
-    /// `$WTT` — the blade tip, prop-local Bevy space (the prop root's frame, as
-    /// [`crate::bowstring`] uses the same pair).
-    ///
-    /// The reference's per-hand index (`CGUnit+0xd34[0..1]`) is not carried: our two objects are
-    /// two entities, reached through the wielder's own main/off slots, so the ordinal that
-    /// distinguishes them there is the query here.
+    /// `$WTT`, the blade tip, in the prop root's frame.
     top: Vec3,
-    /// `$WTB` — the blade base.
+    /// `$WTB`, the blade base.
     bottom: Vec3,
-    /// The live `SWING`, or `None` when this hand is not trailing. Boxed so an idle weapon costs
-    /// a pointer rather than the whole ring.
+    /// The live `SWING`, boxed so an idle weapon costs a pointer, not the ring.
     swing: Option<Box<Swing>>,
 }
 
 impl WeaponTrail {
-    /// The component a spawned weapon prop takes, given its model's baked `[top, bottom]`
-    /// anchors. Called from the held-item attach.
+    /// The component a spawned weapon prop takes, given its model's baked anchors.
     pub(crate) fn new(top: Vec3, bottom: Vec3) -> Self {
         Self {
             top,
@@ -164,9 +89,8 @@ impl WeaponTrail {
         }
     }
 
-    /// Arm this hand — `0x6c6750`. An already-live swing **resets its ring in place** rather than
-    /// allocating a second one (`0x6c675f: [eax+4] = 0 ; [eax] = 0`), so a second proc on the same
-    /// weapon restarts the trail instead of stacking one on top of it.
+    /// Arm this hand (`0x6c6750`): a live swing resets its ring in place (`0x6c675f`), so a second
+    /// proc restarts the trail rather than stacking one.
     pub(crate) fn arm(&mut self, trail: TrailProc, now_ms: u32) {
         let [r, g, b] = trail.rgb();
         let swing = self.swing.get_or_insert_with(|| {
@@ -195,81 +119,65 @@ impl WeaponTrail {
     }
 }
 
-/// The reference's `SWING` record (pool `0xce86ec`) — the ring of blade samples plus the colour,
-/// duration and clocks that fade it out. Layout, field for field:
-/// `+0x00` head · `+0x04` tail · `+0x08` the 128-slot ring · `+0x608` the packed colour
-/// (byte 3 = the live alpha) · `+0x60c` duration · `+0x610` start · `+0x614` last.
+/// The reference's `SWING` record (pool `0xce86ec`): the ring of blade samples, the packed colour
+/// at `+0x608` (byte 3 the live alpha) and the clocks that fade it.
 struct Swing {
-    /// `+0x08`. Written at `head & 0x7f`, read at `i % 127` — see [`READ_MODULUS`].
+    /// `+0x08`: written at `head & 0x7f`, read at `i % 127`.
     ring: [Vec3; RING_SLOTS as usize],
-    /// `+0x00` — the monotonic write cursor, never masked itself.
+    /// `+0x00`: the monotonic write cursor, never masked itself.
     head: u32,
-    /// `+0x04` — the floor: the oldest sample still retained.
+    /// `+0x04`: the oldest sample still retained.
     tail: u32,
-    /// The trail's colour, `0..=1` per channel. Constant for the swing's whole life; only the
-    /// alpha ramps.
+    /// The colour, `0..=1` per channel; only the alpha ramps.
     rgb: [f32; 3],
-    /// The **live** alpha byte (`+0x60b`). Not just an opacity — it is the clock: the fade rate,
-    /// the retained segment count and the termination test are all derived from it.
+    /// The live alpha byte (`+0x60b`), which also sets the fade rate, the retained segment count
+    /// and the end test.
     alpha: u8,
-    /// `+0x60c` — how long the ring keeps *appending*. The trail outlives it by the fade.
+    /// `+0x60c`: how long the ring appends; the fade outlasts it.
     duration_ms: u32,
     /// `+0x610`.
     start_ms: u32,
-    /// `+0x614` — the previous evaluation's timestamp. The step's first factor is the delta
-    /// against this, **not** the elapsed time (`0x6c65c1`: feeding elapsed makes `fadeStep`
-    /// explode and kills the trail after one or two frames).
+    /// `+0x614`: the previous evaluation's time; the step takes the delta against it, not the
+    /// elapsed time (`0x6c65c1`).
     last_ms: u32,
 }
 
 /// One evaluated frame of a swing: the strip to draw, or the verdict that it is over.
 enum Step {
-    /// `0x6c6560` returned 0 — the caller frees the SWING and unregisters the callback.
+    /// `0x6c6560` returned 0: the caller frees the SWING.
     Ended,
-    /// The retained samples, oldest first, as `(bottom, top, alpha 0..=1)` per appended frame.
-    /// The **oldest** pair carries the highest alpha and the pair at the weapon carries ≈ 0.
+    /// The retained samples, oldest first, as `(bottom, top, alpha 0..=1)`; the oldest pair is the
+    /// most opaque.
     Strip(Vec<(Vec3, Vec3, f32)>),
 }
 
 impl Swing {
-    /// `0x6c64a0` — push one sample. `slot = head & 0x7f`, then `head++`, then the floor follows
-    /// the head so the ring never reports more than its capacity.
+    /// `0x6c64a0`: store at `head & 0x7f`, advance the head, keep the floor within capacity.
     fn push(&mut self, p: Vec3) {
         self.ring[(self.head & (RING_SLOTS - 1)) as usize] = p;
         self.head += 1;
-        // `if (tail < head - 0x80) tail = head - 0x80`, on a counter that starts at 0: below the
-        // capacity the right-hand side is negative and the floor stays where it is.
+        // `if (tail < head - 0x80) tail = head - 0x80`; below capacity the floor stays put.
         self.tail = self.tail.max(self.head.saturating_sub(RING_SLOTS));
     }
 
-    /// `0x6c6540(n)` — raise the floor so at most `n` samples remain, and report how many do.
+    /// `0x6c6540(n)`: raise the floor so at most `n` samples remain, and report how many do.
     fn trim(&mut self, n: u32) -> u32 {
         self.tail = self.tail.max(self.head.saturating_sub(n));
         self.head - self.tail
     }
 
-    /// Read counter `i` back out — through the reader's **`% 127`**, which is the shipped
-    /// mismatch against the writer's `& 127`.
-    ///
-    /// For `i < 127` the two agree and the ring is exact. Past that the reader is offset: slot
-    /// `s` was last written by counter `s + 128k`, so a read at `i ∈ [128, 254]` lands on the
-    /// sample written **one counter later** — and since consecutive counters alternate
-    /// bottom/top, that swaps the ribbon's two edges. Only a trail that appends more than 127
-    /// samples reaches it: at 60 Hz that is 64 frames, so every 300–700 ms kit stops short of it
-    /// and **Whirlwind's 10 000 ms spin (kits 369/370/4213) is the one that lives there.**
+    /// Read counter `i` through the reader's `% 127`. Past 127 a read lands on the sample one
+    /// counter later, swapping the ribbon's two edges; only a trail appending over 127 samples
+    /// reaches it, such as Whirlwind's 10 s spin (kits 369, 370, 4213).
     fn read(&self, i: u32) -> Vec3 {
         self.ring[(i % READ_MODULUS) as usize]
     }
 
-    /// `0x6c6560` — one frame: append while the duration holds, compute the fade step, decide
-    /// whether the trail is over, trim to the segments the step affords, build the strip, then
-    /// decay the live alpha past the half-duration mark.
-    ///
-    /// Order matters and is the reference's: the strip is coloured from the **pre-decay** alpha,
-    /// and the decay happens after the draw (`0x6c669a` then `0x6c669f`).
+    /// `0x6c6560`, one frame: append while the duration holds, compute the fade step, end or trim,
+    /// build the strip, then decay the alpha; the strip takes the pre-decay alpha (`0x6c669a`,
+    /// then `0x6c669f`).
     fn step(&mut self, now_ms: u32, bottom: Vec3, top: Vec3) -> Step {
-        // `6c657c: eax = now - start` / `jae 0x6c65b9` — an unsigned test, so appending stops the
-        // moment the duration is reached and the ribbon freezes where the blade left it.
+        // `6c657c`: an unsigned test, so appending stops the moment the duration is reached.
         let elapsed = now_ms.wrapping_sub(self.start_ms);
         if elapsed < self.duration_ms {
             self.push(bottom); // `$WTB` first (0x6c6587) …
@@ -278,20 +186,18 @@ impl Swing {
         let dt = now_ms.wrapping_sub(self.last_ms);
         self.last_ms = now_ms;
         let step = fade_step(dt, self.alpha);
-        // `6c65fa: eax = alpha / fadeStep` then `cmp eax,1 ; jg` — one segment or fewer and the
-        // trail is over.
+        // `6c65fa`: one segment or fewer and the trail is over.
         let segments = u32::from(self.alpha) / step;
         if segments <= 1 {
             return Step::Ended;
         }
         let live = self.trim(2 * segments);
         if live == 0 {
-            // `6c6620 je -> return 0` — an empty ring ends the trail rather than drawing nothing.
+            // `6c6620`: an empty ring ends the trail.
             return Step::Ended;
         }
-        // `0x6c64d0`, tail → head. The alpha is decremented once per PAIR (`test bl,1`) BEFORE
-        // that pair's colour is stored, so the oldest retained pair is the opaque end and the
-        // pair at the weapon lands at ≈ 0. Counter-intuitive but byte-exact: do not invert it.
+        // `0x6c64d0`, tail to head: the alpha drops once per pair before that pair's colour is
+        // stored, so the oldest pair is the opaque end and the weapon's ≈ 0. Do not invert it.
         let mut alpha = i32::from(self.alpha);
         let mut strip = Vec::with_capacity((live as usize).div_ceil(2));
         let mut i = self.tail;
@@ -304,8 +210,7 @@ impl Swing {
             ));
             i += 2;
         }
-        // `6c669f: ecx = duration>>1 ; if (elapsed > duration/2) [esi+0x60b] -= fadeStep`. The
-        // trail holds full strength for its first half and only then begins to go.
+        // `6c669f`: full strength for the first half of the duration, then the decay.
         if elapsed > self.duration_ms / 2 {
             self.alpha = self
                 .alpha
@@ -315,17 +220,11 @@ impl Swing {
     }
 }
 
-/// `fadeStep = max(1, ftol(dt_ms · (1/300) · alpha))` — `0x6c65c6`–`0x6c65f8`.
-///
-/// The floor is applied through `cmp al,1 / jae`, comparing only the **low byte** of the
-/// truncated result: a value whose low byte is zero — 256, i.e. a ≈ 768 ms hitch at alpha 100 —
-/// takes the floor of 1 rather than its own huge value, and the trail survives the stall instead
-/// of ending on it. Transcribed as the byte comparison it is, not as `max(1, …)`.
+/// `fadeStep = max(1, ftol(dt_ms · (1/300) · alpha))` (`0x6c65c6`–`0x6c65f8`), the floor tested
+/// on the low byte only (`cmp al,1`): 256, a ≈ 768 ms hitch at alpha 100, takes 1.
 fn fade_step(dt_ms: u32, alpha: u8) -> u32 {
-    // `fild dt` → `fmul dword [0x811278]` → `fimul dword [alpha]` → `_ftol`. The constant is the
-    // nearest f32 to 1/300 and the x87 evaluates at PC_53 with it widened, so the product runs in
-    // **f64 with an f32 constant** — `dt · alpha / 300.0` is different arithmetic and is not what
-    // the binary does.
+    // `fild`, `fmul [0x811278]`, `fimul`, `_ftol` at PC_53: f64 with an f32 constant, which
+    // `dt · alpha / 300.0` is not.
     let raw = (f64::from(dt_ms) * f64::from(FADE_PER_MS) * f64::from(alpha)).trunc() as i64 as u32;
     if raw & 0xff >= 1 {
         raw
@@ -334,33 +233,14 @@ fn fade_step(dt_ms: u32, alpha: u8) -> u32 {
     }
 }
 
-/// Absorb this frame's arms into the latch, then fire the latch on every unit that started an
-/// animation — `0x5fe48e`'s read, `0x60e550`'s fan-out to both hands, and `0x5fe4b1`'s clear.
+/// Absorb this frame's arms into the latch, then fire it on every unit that started an animation:
+/// `0x5fe48e`'s read, `0x60e550`'s fan-out to both hands, `0x5fe4b1`'s clear.
 ///
-/// The drain precedes the consume so a kit carrying **both** a proc-8 and an anim id self-fires in
-/// the frame it plays, which is the reference's own ordering inside `0x60edf0` (dispatcher at
-/// `0x60f35c`, animation at `0x60f3c5`). A kit whose anim id is `-1` — Charge's kit 44, 38 spells —
-/// arms and waits: `0x60f366 jl` skips the animation leg outright, so the trail starts on whatever
-/// the unit plays next, and because `0x5fe2f0` is the image's **single** animation entry point
-/// that is the charge's own run, not the swing at the end of it.
-///
-/// **The combat fast path is honoured, and benilla got it for free.** `0x5fe43c` returns before
-/// the latch read when the unit is *already* playing a combat animation and requests another one —
-/// it re-times the current clip instead of restarting it — so the arm survives that call. Missing
-/// that would not have invented trails out of nothing, but it would have drawn trails from arms
-/// the reference **supersedes before firing** (`0x60d835` is a plain `mov` into a one-slot field,
-/// so a second proc overwrites the first), with the superseded colours and durations, on 23 of the
-/// 34 type-8 kits. We do not fire there because the driver's own request loop already models the
-/// fast path (decision 0406, `select::is_combat_anim` = `0x5fcc10`'s byte-decoded set): it
-/// `continue`s without playing, so neither `base_played` nor `masked_played` is raised and the
-/// edge stays low. Pinned by
-/// [`the fast path test`](crate::creature_anim::driver::tests).
-///
-/// There is **no per-frame recompute** in the reference (`0x5fd8b0` has one caller;
-/// `0x5fd9e0`'s 38 sites are all event-driven), so an arm on a unit that then changes nothing sits
-/// armed indefinitely and the trail starts late — at whatever event finally plays something. The
-/// arm can be spent on a footstep. [`crate::creature_anim::AnimDriver::started_anim`] is the same
-/// edge-triggered shape for the same reason.
+/// The drain comes first so a kit with both the proc and an anim fires in the frame it plays, as
+/// in `0x60edf0` (dispatcher `0x60f35c`, animation `0x60f3c5`); a kit with anim `-1` (Charge's kit
+/// 44) waits for whatever the unit plays next. A combat clip re-timing itself returns before the
+/// latch read (`0x5fe43c`), and the driver raises no started edge there either. Nothing recomputes
+/// per frame (`0x5fd8b0` has one caller), so an arm can wait for the next event, even a footstep.
 pub(crate) fn fire_weapon_trails(
     time: Res<Time>,
     mut arms: MessageReader<TrailArm>,
@@ -369,7 +249,7 @@ pub(crate) fn fire_weapon_trails(
     mut trails: Query<&mut WeaponTrail>,
 ) {
     for arm in arms.read() {
-        // One slot: a second arm before the first fires replaces it, as two writes to one field do.
+        // One slot: a second arm before the first fires replaces it.
         latch.0.insert(arm.entity, arm.trail);
     }
     let now_ms = time.elapsed().as_millis() as u32;
@@ -377,38 +257,31 @@ pub(crate) fn fire_weapon_trails(
         if !drv.started_anim() {
             continue;
         }
-        // `0x5fe4a0 je` — the read is gated on a nonzero duration, and `TrailProc` only decodes
-        // for one, so the latch's presence IS that test. Removed either way: the clear at
-        // `0x5fe4b1` is unconditional once the branch is taken.
+        // `0x5fe4a0`: gated on a nonzero duration, which `TrailProc` only decodes for; the clear
+        // at `0x5fe4b1` is unconditional.
         let Some(trail) = latch.0.remove(&entity) else {
             continue;
         };
-        // `0x60e550`: `lea esi,[ecx+0xd34]` over TWO slots, skipping a null handle. Ours are the
-        // main- and off-hand prop roots; a hand holding nothing, or a weapon whose model authors
-        // neither marker, simply has no component to arm.
+        // `0x60e550` walks two slots, skipping a null one: ours are the main- and off-hand props.
         for root in held.spawned_slots().iter().take(2).flatten() {
             if let Ok(mut t) = trails.get_mut(*root) {
                 t.arm(trail, now_ms);
             }
         }
     }
-    // Entries die with the unit (the reference drops the pending arm in the CGUnit teardown
-    // `0x5fbb60`, eight instructions after it destroys both trail objects).
+    // Entries die with the unit (`0x5fbb60`).
     latch.0.retain(|e, _| units.contains(*e));
 }
 
-/// Step every live swing and write its strip into the shared effect stream.
-///
-/// Runs post-propagation so the prop's `GlobalTransform` is *this* frame's blade pose — the
-/// anchors ride the prop root's frame exactly as [`crate::bowstring`]'s do.
+/// Step every live swing and write its strip into the shared effect stream, after propagation so
+/// the prop's `GlobalTransform` is this frame's blade pose.
 fn draw_weapon_trails(
     time: Res<Time>,
     mut draw: WorldEffectDraw,
     white: Res<TrailWhite>,
     lighting: Option<Res<benilla_world::lighting::WowLighting>>,
     world_cam: Query<Entity, With<WorldCamera>>,
-    // The wearer's committed ambient word, present only while its light node is on the interior
-    // bake lane — the trail takes its WEARER's light, not the scene's (see the module doc).
+    // The wearer's committed ambient word, present only while its light node is indoors.
     indoors: Query<&benilla_world::interior::NodeAmbient>,
     mut trails: Query<(
         Entity,
@@ -421,23 +294,17 @@ fn draw_weapon_trails(
     let Ok(cam) = world_cam.single() else {
         return;
     };
-    // The EXTERIOR ambient — the fallback, and the right answer outdoors: a unit's own committed
-    // ambient there is the day/night one (`0x69e4ad`'s exterior intensity leg). Absent before the
-    // first lighting resolve — burn at the authored colour rather than at black.
+    // The exterior ambient, a unit's own outdoors (`0x69e4ad`); before the first lighting
+    // resolve, the authored colour.
     let scene = lighting.as_deref().map_or([1.0; 3], |l| l.ambient);
     let now_ms = time.elapsed().as_millis() as u32;
     for (entity, mut trail, prop, vis, wearer) in &mut trails {
-        // No swing, no work — asked through `&` first: every drawn weapon carries a trail, and
-        // reaching the swing through `as_mut()` below marked each one changed every frame while
-        // paying the ambient lookup and two transforms for a strip that was never built.
+        // Checked through `&` first, so an idle weapon is not marked changed.
         if trail.swing.is_none() {
             continue;
         }
-        // Indoors the wearer's node carries a committed ambient word of its own — the ramped chase
-        // toward `cap96(MOCV)`, the room's own light rather than the sky's. Its ABSENCE is the
-        // exterior lane. A Goldshire-inn character's word is ≈ (0.30, 0.22, 0.14) warm against a
-        // night sky's ≈ (0.22, 0.26, 0.29) cool: similar in magnitude, opposite in hue, which is
-        // why taking the scene's outdoors-and-in tinted every indoor trail with the sky.
+        // Indoors, the node's own ramped ambient toward `cap96(MOCV)`: the room's light, not the
+        // sky's.
         let ambient = indoors
             .get(wearer.0)
             .map_or(scene, |a| a.0)
@@ -452,8 +319,8 @@ fn draw_weapon_trails(
             trail.swing = None;
             continue;
         };
-        // The vis chain is ours, not the reference's: a hidden prop has no blade on screen to
-        // trail from. The swing keeps ageing above so it does not resume mid-arc when shown.
+        // The visibility gate is benilla's, not the reference's: a hidden prop has no blade on
+        // screen. The swing keeps ageing so it does not resume mid-arc when shown.
         if !vis.get() || strip.len() < 2 {
             continue;
         }
@@ -461,22 +328,10 @@ fn draw_weapon_trails(
             let (b, t, _) = strip[strip.len() - 1];
             (b + t) * 0.5
         };
-        // The six render states the callback writes, byte for byte (`0x6c6825`–`0x6c686e`) —
-        // three of which contradict what a spell ribbon looks like it should be, and every one of
-        // the three is visible:
-        //
-        // | EGxRs | value | |
-        // |---|---|---|
-        // | `0x07` | **2** | ordinary `SRC_ALPHA / INV_SRC_ALPHA` — **not** additive (that is mode 3) |
-        // | `0x10` | **0** | depth test **OFF** — the arc is never eaten by the swinger's own shoulder |
-        // | `0x12` | 0 | depth write off — so it occludes nothing in turn |
-        // | `0x14` | 0 | two-sided (the lane never backface-culls) |
-        // | `0x0f` | 0 | unfogged (the lane's default) |
-        // | `0x0e` | 1 | lighting ON — see the module doc's named deviation |
-        //
-        // Setting `0x07` also cascades EGxRs `0x08` (`0x593741`–`0x593764`) to an alpha test of
-        // `GEQUAL 1/255`, which discards the ramp's zero-alpha end. Under alpha blending a
-        // zero-alpha fragment contributes nothing anyway, so it is reproduced by arithmetic.
+        // The callback's render states (`0x6c6825`–`0x6c686e`): blend mode 2, `SRC_ALPHA /
+        // INV_SRC_ALPHA`, not additive; depth test and write off, so the swinger's own shoulder
+        // never hides the arc; two-sided, unfogged, lit. Mode 2's alpha test (`GEQUAL 1/255`,
+        // `0x593741`) drops only what blending already makes invisible.
         let mut batch = draw
             .batch(cam, white.0.id())
             .alpha()
@@ -486,9 +341,8 @@ fn draw_weapon_trails(
         let verts = batch.verts_mut();
         for w in strip.windows(2) {
             let ((b0, t0, a0), (b1, t1, a1)) = (w[0], w[1]);
-            // The lane indexes a quad `[0,1,2, 0,2,3]`, so perimeter order `[b0, b1, t1, t0]`
-            // reproduces the strip triangles the reference's `primType 4` draws
-            // (`benilla_world::ribbons` converts its own strip the same way).
+            // The lane indexes a quad `[0,1,2, 0,2,3]`, so `[b0, b1, t1, t0]` reproduces the
+            // reference's strip (`primType 4`).
             for (pos, a) in [(b0, a0), (b1, a1), (t1, a1), (t0, a0)] {
                 verts.push(EffectVertex {
                     pos: pos.to_array(),
@@ -506,10 +360,8 @@ fn draw_weapon_trails(
     }
 }
 
-/// The 1×1 opaque-white texel the trail samples. The reference's trail vertex is **16 bytes** —
-/// a `C3Vector` and a packed colour, no texcoord (`0x6c6523 add esi,0x10`) — so the ribbon is
-/// pure vertex colour; the shared effect lane always samples a texture, and white is the
-/// identity for it.
+/// The 1×1 white texel the trail samples: the reference's 16-byte trail vertex has no texcoord
+/// (`0x6c6523`), so the ribbon is pure vertex colour.
 #[derive(Resource)]
 struct TrailWhite(Handle<Image>);
 
@@ -522,8 +374,8 @@ pub(crate) struct WeaponTrailPlugin;
 
 impl Plugin for WeaponTrailPlugin {
     fn build(&self, app: &mut App) {
-        // The arm edge and its latch register here; `fire_weapon_trails` itself is placed inside
-        // `creature_anim`'s own chain, immediately after the driver that sets the edge it reads.
+        // `fire_weapon_trails` runs in `creature_anim`'s chain, right after the driver that sets
+        // the edge it reads.
         app.add_message::<TrailArm>()
             .init_resource::<TrailLatch>()
             .add_systems(Startup, init_trail_white)
@@ -532,8 +384,7 @@ impl Plugin for WeaponTrailPlugin {
                 draw_weapon_trails
                     .in_set(benilla_world::billboard::BillboardPlace)
                     .after(benilla_world::rig_anim::finalize_rig_worlds)
-                    // B161's edge: a lane that writes before the frame's clear loses everything it
-                    // pushed, silently, with its arithmetic perfect.
+                    // A lane that writes before the frame's clear loses everything it pushed.
                     .after(benilla_world::particles::buffer::begin_effect_frame),
             );
     }
diff --git a/crates/benilla-app/src/weapon_trail/tests.rs b/crates/benilla-app/src/weapon_trail/tests.rs
index b6971751..b9cea152 100644
--- a/crates/benilla-app/src/weapon_trail/tests.rs
+++ b/crates/benilla-app/src/weapon_trail/tests.rs
@@ -2,7 +2,7 @@
 
 use super::*;
 
-/// A shipped proc: kit 324's — `#f82929`, alpha 100, 600 ms.
+/// A shipped proc, kit 324: `#f82929`, alpha 100, 600 ms.
 fn kit_324() -> TrailProc {
     TrailProc {
         packed: 0x64f8_2929,
@@ -16,8 +16,8 @@ fn armed(trail: TrailProc) -> WeaponTrail {
     t
 }
 
-/// `0x6c6560`'s arithmetic, worked: with the shipped `CharParamThree = 100` and a 16.7 ms frame,
-/// `fadeStep = 5`, so `nSegments = 20` — twenty appended frames ≈ 0.33 s of trail history.
+/// `0x6c6560` with the shipped `CharParamThree = 100` and a 16.7 ms frame: `fadeStep = 5`, so
+/// `nSegments = 20`, about 0.33 s of trail history.
 #[test]
 fn shipped_frame_gives_five_and_twenty() {
     for dt in [16, 17] {
@@ -26,8 +26,8 @@ fn shipped_frame_gives_five_and_twenty() {
     assert_eq!(100 / fade_step(16, 100), 20);
 }
 
-/// The floor is `cmp al,1` — a **low-byte** test, so a result of exactly 256 takes the floor
-/// rather than its own value, and a long hitch does not end the trail.
+/// The floor is `cmp al,1`, a low-byte test, so exactly 256 takes the floor and a long hitch does
+/// not end the trail.
 #[test]
 fn fade_step_floor_is_the_low_byte() {
     assert_eq!(fade_step(0, 100), 1, "a zero delta floors");
@@ -52,8 +52,8 @@ fn ring_read_and_write_diverge_past_127() {
     for i in 0..127u32 {
         assert_eq!(s.read(i), Vec3::splat(i as f32), "counter {i} is exact");
     }
-    // Counter 127 writes slot 127; counter 128 writes slot 0, and the reader's `128 % 127 = 1`
-    // picks up slot 1 — the sample written by counter 129, one AHEAD of the one it wants.
+    // Counter 128 writes slot 0, but the reader's `128 % 127 = 1` picks slot 1, the sample
+    // counter 129 writes, one ahead.
     for i in 127..135u32 {
         s.push(Vec3::splat(i as f32));
     }
@@ -77,7 +77,7 @@ fn push_bounds_the_ring_at_capacity() {
 }
 
 /// Re-arming a live swing resets its ring in place (`0x6c675f`) rather than stacking a second
-/// trail — the same creation-time law the effect nodes take (2057).
+/// trail.
 #[test]
 fn rearm_resets_rather_than_stacks() {
     let mut t = armed(kit_324());
@@ -113,33 +113,28 @@ fn kit_324_at_sixty_hz() {
         assert!(frame < 10_000, "the trail must terminate");
     };
     assert_eq!(appended, 35, "appends for the 600 ms duration at 60 Hz");
-    // The nominal is 20 pairs (alpha 100 / fadeStep 5), but `fadeStep` is a TRUNCATED product,
-    // so as the alpha decays the integer quotient drifts *above* it — alpha 68 at a 16 ms frame
-    // truncates to step 3 and asks for 22. The ring's 64 pairs is the real ceiling.
+    // Nominal 20 pairs, but `fadeStep` truncates, so as the alpha decays the quotient rises:
+    // alpha 68 at 16 ms gives step 3 and 22 pairs. The ring's 64 pairs is the ceiling.
     assert_eq!(
         longest, 22,
         "the retained history peaks just over the nominal 20 pairs"
     );
-    // Holding `fadeStep` constant puts the visible life at ≈ duration/2 + (alpha/fadeStep)·dt ≈
-    // duration. It is not constant — it is `trunc(dt·alpha/300)`, so it shrinks
-    // with the alpha it is decaying, and the truncation shaves it further (alpha 54 asks for 2.88
-    // and gets 2). The decay is therefore sub-exponential and a 600 ms kit is on screen for
-    // **twice** its duration.
+    // `fadeStep = trunc(dt·alpha/300)` shrinks with the alpha it decays (alpha 54 gives 2, not
+    // 2.88), so the decay is sub-exponential and a 600 ms kit is on screen for about twice that.
     assert_eq!(
         end, 1_250,
         "a 600 ms kit is visible for 1.25 s, not the constant-step ~0.6 s"
     );
 }
 
-/// The alpha ramp's DIRECTION — the one thing a re-implementation is most likely to invert.
-/// The oldest retained pair is the opaque end; the pair at the weapon is the transparent one,
-/// and once the ring holds its full `2·segments` the ramp reaches exactly 0 there.
+/// The oldest retained pair is the opaque end, the pair at the weapon the transparent one; once the
+/// ring holds its full `2·segments` the ramp reaches exactly 0 there.
 #[test]
 fn the_far_end_of_the_arc_is_the_opaque_end() {
     let mut t = armed(kit_324());
     let swing = t.swing.as_mut().expect("live");
     let mut strip = Vec::new();
-    // Twenty appended frames is where the ring first holds the full `alpha/fadeStep` segments.
+    // Twenty appended frames first fill the `alpha/fadeStep` segments.
     for frame in 1..=20u32 {
         let blade = Vec3::new(frame as f32, 0.0, 0.0);
         match swing.step(frame * 1000 / 60, blade, blade + Vec3::Y) {
@@ -153,8 +148,7 @@ fn the_far_end_of_the_arc_is_the_opaque_end() {
         alphas.windows(2).all(|w| w[0] > w[1]),
         "alpha must fall from the oldest sample to the weapon: {alphas:?}"
     );
-    // One `fadeStep` per pair, subtracted before the pair is stored — so the ramp is arithmetic
-    // and its last term is exactly zero.
+    // One `fadeStep` per pair, subtracted before the pair is stored, so the last term is zero.
     let drop = alphas[0] - alphas[1];
     assert!(
         alphas.windows(2).all(|w| (w[0] - w[1] - drop).abs() < 1e-6),
@@ -171,8 +165,7 @@ fn the_far_end_of_the_arc_is_the_opaque_end() {
     );
 }
 
-/// Before the ring fills, the oldest pair carries `alpha − fadeStep` outright — 95/255 at the
-/// shipped alpha of 100.
+/// Before the ring fills, the oldest pair carries `alpha − fadeStep`: 95/255 at alpha 100.
 #[test]
 fn the_oldest_pair_carries_alpha_minus_one_step() {
     let mut t = armed(kit_324());
@@ -206,8 +199,8 @@ fn alpha_holds_until_the_half_duration_mark() {
     assert!(swing.alpha < 100, "and decaying past the mark");
 }
 
-/// Whirlwind's 10 000 ms spin is the one shipped kit that outruns the ring, so it is the one the
-/// reader/writer modulus mismatch is visible on.
+/// Whirlwind's 10 000 ms spin is the one shipped kit that outruns the ring and shows the
+/// reader/writer modulus mismatch.
 #[test]
 fn only_whirlwind_outruns_the_ring() {
     let whirlwind = TrailProc {
@@ -283,8 +276,8 @@ fn play_anim(app: &mut App, unit: Entity) {
         .set_started_anim(true);
 }
 
-/// The proc ARMS; it does not draw. Nothing happens until the unit plays an animation — which is
-/// what makes Charge (kit 44, anim id −1) start its trail on the charge itself.
+/// The proc arms, it does not draw: the trail starts with the unit's next animation, which is how
+/// Charge (kit 44, anim id −1) starts its trail on the charge.
 #[test]
 fn an_arm_alone_fires_nothing() {
     let (mut app, unit, hands) = latch_app();
@@ -305,8 +298,7 @@ fn an_arm_alone_fires_nothing() {
     );
 }
 
-/// `0x5fe4b1 mov [ebx+0xd20],edi` — the duration is cleared the moment it is read, so one arm is
-/// one trail. A second animation must not restart it.
+/// `0x5fe4b1 mov [ebx+0xd20],edi` clears the duration as it is read, so one arm is one trail.
 #[test]
 fn the_latch_is_consumed_exactly_once() {
     let (mut app, unit, hands) = latch_app();
@@ -327,8 +319,7 @@ fn the_latch_is_consumed_exactly_once() {
     assert!(!trailing(&app, hands[0]), "the arm was one-shot");
 }
 
-/// One pair of fields on the unit means one pending arm: a second proc before the first fires
-/// OVERWRITES it rather than queueing behind it.
+/// One pair of fields on the unit is one pending arm: a second proc overwrites it, not queues.
 #[test]
 fn a_second_arm_replaces_the_pending_one() {
     let (mut app, unit, hands) = latch_app();
@@ -352,8 +343,8 @@ fn a_second_arm_replaces_the_pending_one() {
     assert_eq!(swing.duration_ms, 10_000, "the LAST arm wins");
 }
 
-/// A hand holding nothing — or a weapon whose model authors neither marker — has no object to
-/// arm, and the other hand is unaffected (`0x60e550`'s `test ecx,ecx ; je` per slot).
+/// A hand with nothing, or a weapon model with neither marker, has nothing to arm and leaves the
+/// other hand alone (`0x60e550`'s `test ecx,ecx ; je` per slot).
 #[test]
 fn an_empty_hand_is_skipped() {
     let (mut app, unit, hands) = latch_app();
@@ -367,8 +358,7 @@ fn an_empty_hand_is_skipped() {
     assert!(trailing(&app, hands[0]), "the armed hand still fires");
 }
 
-/// The pending arm dies with the unit — the reference drops it in the CGUnit teardown
-/// (`0x5fbcdc`), eight instructions after destroying both trail objects.
+/// The pending arm dies with the unit, in the CGUnit teardown (`0x5fbcdc`).
 #[test]
 fn the_latch_is_swept_when_the_unit_goes() {
     let (mut app, unit, _) = latch_app();
@@ -391,8 +381,7 @@ fn the_latch_is_swept_when_the_unit_goes() {
 
 use benilla_world::particles::buffer::{begin_effect_frame, EffectQuads};
 
-/// End to end through the render half: an armed swing on a moving blade commits vertices, they
-/// carry the kit's colour and the ramp, and the draw stops when the trail does.
+/// An armed swing on a moving blade commits vertices in the kit's colour and ramp.
 #[test]
 fn an_armed_trail_commits_a_strip_to_the_effect_stream() {
     let mut app = App::new();
@@ -416,9 +405,8 @@ fn an_armed_trail_commits_a_strip_to_the_effect_stream() {
             benilla_world::model_fade::ParentModel(wearer),
         ))
         .id();
-    // Frame 1 seeds one pair; a strip needs two, so the first commit is empty by construction.
+    // Frame 1 seeds one pair; a strip needs two.
     app.update();
-    // Sweep the blade so the samples are distinct, and let the ring fill.
     for f in 1..=8u32 {
         app.world_mut()
             .get_mut::<Transform>(hand)
@@ -443,14 +431,11 @@ fn an_armed_trail_commits_a_strip_to_the_effect_stream() {
     let verts = &quads.verts[draw.range.start as usize..draw.range.end as usize];
     assert!(verts.len() >= 8, "at least two quads: {}", verts.len());
     assert_eq!(verts.len() % 4, 0, "whole quads");
-    // Kit 324's #f82929, and an alpha ramp that actually varies across the strip.
     for v in verts {
         assert!((v.color[0] - 248.0 / 255.0).abs() < 1e-6, "{:?}", v.color);
         assert!((v.color[1] - 41.0 / 255.0).abs() < 1e-6, "{:?}", v.color);
     }
-    // Eight appended frames is short of the 20 the ring will hold, so the ramp has not yet
-    // reached 0 at the blade — but it must already fall, by one `fadeStep` per quad, from the
-    // opaque far end (alpha − fadeStep = 95/255) toward it.
+    // Eight frames do not fill the ring, so the ramp falls from 95/255 but has not reached 0.
     let alphas: Vec<f32> = verts.iter().map(|v| v.color[3]).collect();
     let (lo, hi) = (
         alphas.iter().cloned().fold(f32::MAX, f32::min),
@@ -458,7 +443,7 @@ fn an_armed_trail_commits_a_strip_to_the_effect_stream() {
     );
     assert!((hi - 95.0 / 255.0).abs() < 1e-6, "the opaque end: {hi}");
     assert!(hi - lo > 0.1, "a real ramp, not one flat alpha: {alphas:?}");
-    // Each quad is `[b0, b1, t1, t0]` — the two ends of one segment, so its corners pair up.
+    // Each quad is `[b0, b1, t1, t0]`, the two ends of one segment.
     for q in verts.as_chunks::<4>().0 {
         assert_eq!(
             q[0].color[3], q[3].color[3],
@@ -467,14 +452,13 @@ fn an_armed_trail_commits_a_strip_to_the_effect_stream() {
         assert_eq!(q[1].color[3], q[2].color[3], "and so does the newer");
         assert!(q[0].color[3] > q[1].color[3], "falling toward the weapon");
     }
-    // The blade swept along +X, so the strip must span more than a single blade's worth of it.
     let xs: Vec<f32> = verts.iter().map(|v| v.pos[0]).collect();
     let span =
         xs.iter().cloned().fold(f32::MIN, f32::max) - xs.iter().cloned().fold(f32::MAX, f32::min);
     assert!(span > 0.5, "the ribbon follows the blade's arc: {span}");
 }
 
-/// A hidden prop draws no trail — our own vis chain, the same gate [`crate::bowstring`] takes.
+/// A hidden prop draws no trail, the same visibility gate [`crate::bowstring`] takes.
 #[test]
 fn a_hidden_weapon_draws_nothing() {
     let mut app = App::new();
@@ -503,13 +487,9 @@ fn a_hidden_weapon_draws_nothing() {
     assert!(app.world().resource::<EffectQuads>().draws.is_empty());
 }
 
-/// **The trail takes its WEARER's light, not the scene's** (decision 2086).
-///
-/// The draw runs inside the weapon model's own per-frame callback, during the wearer's model draw,
-/// so the enabled lights it inherits are the ones the M2 collector committed for that unit —
-/// four-way byte-derived through `0x70d982 → 0x70ca50 → 0x70baf0` plus the held-weapon `[+0x3b8]`
-/// alias. Outdoors that is the day/night ambient, which is the fallback. Indoors it is the light
-/// node's own committed word, and taking the sky's instead tinted every indoor trail cool.
+/// The trail takes its wearer's light, not the scene's: it draws inside the wearer's model draw,
+/// so it inherits the lights committed for that unit (`0x70d982 → 0x70ca50 → 0x70baf0`, held
+/// weapon `[+0x3b8]`). Indoors that is the node's ambient, outdoors the day/night one.
 #[test]
 fn an_indoor_wearers_committed_ambient_wins_over_the_scenes() {
     fn strip_rgb(app: &App) -> [f32; 3] {
@@ -565,8 +545,8 @@ fn an_indoor_wearers_committed_ambient_wins_over_the_scenes() {
         }
         lit[i] = strip_rgb(&app);
     }
-    // Kit 324's #f82929 through each ambient. The two are close in magnitude and opposite in hue,
-    // so a channel RATIO is the assertion that would actually catch the wrong one being used.
+    // The two ambients are close in magnitude and opposite in hue, so a channel ratio tells them
+    // apart.
     let [out_r, out_g, _] = lit[0];
     let [in_r, in_g, _] = lit[1];
     assert!(
diff --git a/crates/benilla-app/src/world_backdrop.rs b/crates/benilla-app/src/world_backdrop.rs
index c1382b61..8316b42f 100644
--- a/crates/benilla-app/src/world_backdrop.rs
+++ b/crates/benilla-app/src/world_backdrop.rs
@@ -1,77 +1,20 @@
-//! The world as the UI's **backdrop quad** — the seam that put the UI-over-world blend back into
-//! gamma bytes (the third and last piece of the composite lane 0161 and 0254 built).
+//! The world as the UI's backdrop: the world's final pass, the FFXGlow combine ([`FfxBackdrop`]),
+//! is the first draw of the UI camera's main pass, straight into the UI's byte target.
 //!
-//! ## The seam that was left
+//! The reference's fixed-function device blends in gamma bytes. The world lane emits gamma bytes,
+//! and the UI lane blends in an `Rgba8UnormSrgb` target, so every UI blend is arithmetic on the
+//! gamma value (`alphaMode="ADD"` is `dst + texel·α`, clamped, as EGxBlend 3). Drawing the world
+//! inside that target keeps the UI-over-world blend in bytes too; composited through the sRGB
+//! swapchain it would run in linear and lighten every translucent UI pixel over the world (a docked
+//! chat tab, black at α 102/255, must leave the scene at 60 %; a linear blend leaves 77.5 %).
 //!
-//! Both halves of the frame already composite the way the reference's fixed-function device does,
-//! and each does it by the same trick. The world (0161): every world shader emits raw gamma bytes,
-//! the blur runs on them, and the FFXGlow combine takes the frame's one `srgb_to_linear` so the
-//! sRGB present-encode restores the byte. The UI (0254): `ui_quad.wgsl` emits gamma values into an
-//! `Rgba8UnormSrgb` target, so the store encodes, the blend's destination read decodes, and every
-//! hardware blend is therefore arithmetic on the gamma value — `alphaMode="ADD"` really is
-//! `dst + texel·α`, clamped, exactly as EGxBlend 3 does it.
+//! The world camera's own target is a size-carrier: a one-byte image at the world's render size
+//! that nothing writes, kept because Bevy sizes a view's main texture from its target and the
+//! camera's logical viewport rides it ([`retarget_world_camera`]).
 //!
-//! Two correct byte lanes, and **the UI-over-world blend fell in the seam between them.** The UI
-//! camera composited its finished image onto the swapchain through its output blit, and the
-//! swapchain view is sRGB, so that one blend — the only one that mixes UI with world — ran in
-//! linear. 0254 named it as a residual and described it as "a small deviation on antialiased UI
-//! edges over the world". It is not an edge artefact: it is every translucent UI pixel over the
-//! 3D world, at full area.
-//!
-//! Measured on the chat dock, which is the most translucent surface the client has.
-//! `ChatFrameTab`'s body is black at α = 102/255, so a docked tab must leave the scene at **60 %**
-//! of its brightness; the unselected tab (frame α 0.5) at 80 %. Against a bare-scene capture of
-//! the same pixels (`ui-chat-tabhover` at `$WOW_TABHOVER=9`) they measured **77.5 %** and **89 %** —
-//! and a linear composite predicts exactly that, to within a byte, at every point checked
-//! (scene 93 → 72 vs 72.5 predicted; 70 → 54 vs 53.9; 95 → 74 vs 74.1). The tab had almost no
-//! plate, so the hover glow — an ADD, at full strength — sat on nothing and read as a blue lozenge
-//! floating on grass, louder than the tab that was actually selected. That is what the director
-//! reported, and it was never a chat bug.
-//!
-//! ## The fix: put the world *inside* the UI's byte buffer
-//!
-//! Not a third lane. The world camera renders off-screen, and the **first draw of the UI
-//! camera's main pass** is the world's own final pass — the FFXGlow combine ([`FfxBackdrop`],
-//! decision 2234) — rendered straight into the UI's byte target as the ground everything else is
-//! painted on, inside the very pass that paints it (a pass of its own would cost a tile GPU a
-//! load and a store of the whole target). Every UI blend
-//! over the world is then the same blend as every UI blend over UI: the one 0254 already
-//! verified, in the target it already verified it in. The output blit stops blending entirely (it
-//! now carries an opaque frame), which retires the `rgb·a²` hazard 0254 had to patch
-//! `PREMULTIPLIED_ALPHA_BLENDING` around.
-//!
-//! **It was a picture first** (1603): the combine wrote a full-window un-encoded float image that
-//! this pass drew as its first quad, the quad re-encoding what it sampled back to the byte the
-//! combine had computed. That is one write and one read of every pixel at eight bytes each, and
-//! on a bandwidth-bound GPU it is a third of the full-screen chain (2234's rig). The combine now
-//! stores that byte itself, in the UI lane's own terms (`ui_quad.wgsl`'s premultiply, no decode),
-//! and the picture is gone. What the world camera still carries as a target is a **size-carrier**:
-//! a one-byte image at the world's render size that nothing writes, kept because bevy sizes a
-//! view's main texture from its target and the camera's logical viewport is held through it
-//! ([`retarget_world_camera`]).
-//!
-//! Nothing about the world lane's arithmetic changes: the combine's byte math is the same, the
-//! frame still holds exactly one decode — the UI lane's, at its end — and an opaque world pixel
-//! comes out the byte it came out before, minus the float image's own rounding on the way.
-//!
-//! ## …and that seam turned out to be a dial: **render scale** (decision 1639)
-//!
-//! Once the world is a picture the UI paints on, the picture does not have to be the window's size.
-//! [`RenderScale`] sizes it — the world renders at `window × scale`, the combine still covers the
-//! window, and **the UI is untouched at native resolution**, because the combine runs at the UI
-//! camera's own size and only *samples* the scaled world, and nothing here can move that. That is
-//! the whole reason this is worth having rather than "run the game in a smaller window": text,
-//! icons and frame art stay exactly as sharp as they were, and only the 3D pays.
-//!
-//! **Below 1 it buys frames; above 1 it is supersampling** — and above 1 is the half this machine
-//! can measure, since `gxMultisample` defaults to off (1629) and the client therefore ships with no
-//! antialiasing of any kind. At exactly 2.0 the combine's plain bilinear read of the scene *is* a
-//! 2×2 box average (the destination pixel centre lands on the corner four texels share, weighting
-//! each 0.25), so SSAA×2 needs no filter of its own.
-//!
-//! **The one number that must not move is the camera's LOGICAL viewport**, and
-//! [`render_target_for`] is built around holding it fixed — [`retarget_world_camera`] says what
-//! reads it (every pick ray in the client) and why getting it wrong is B169 over again.
+//! [`RenderScale`] renders the world at `window × scale` while the UI stays native. At exactly 2.0
+//! the combine's bilinear read is a 2×2 box average, so supersampling needs no filter of its own.
+//! The camera's logical viewport must not move with it ([`render_target_for`]).
 
 use bevy::asset::RenderAssetUsages;
 use bevy::camera::RenderTarget;
@@ -84,46 +27,21 @@ use crate::ui_pass::PlayerUiCamera;
 use benilla_world::ffx_glow::FfxBackdrop;
 use benilla_world::view::WorldCamera;
 
-/// The **render scale** — benilla's own CVar `renderScale`, no 1.12 counterpart.
-///
-/// The era's answer to "my machine is too slow" was `gxResolution`: drop the whole backbuffer, UI
-/// and all, and in fullscreen mode-set the display to match. We ship no exclusive mode at all
-/// (decision 1627) and our UI is a separate pass over an off-screen world, so we can offer the
-/// strictly better version of that trade — **shrink the 3D, keep the interface**. It is the same
-/// knob every engine since has grown (Godot's `scaling_3d_scale`, Unity URP's `renderScale`,
-/// Unreal's `r.ScreenPercentage`), and it is the standard lever for the one machine class we have a
-/// real measurement from: the Steam Deck sitting at 94 % GPU busy (B329).
-///
-/// **Default 1.0 — off, and it has to be**, so every visual golden in the tree keeps meaning what
-/// it meant: at 1.0 [`render_target_for`] returns the window's own physical size and the window's
-/// own scale factor, unrounded and unmultiplied, which is bit-for-bit the pre-1639 lane.
+/// The render scale, the `renderScale` CVar, not a 1.12 CVar: it scales the 3D and keeps the
+/// interface native. At the default 1.0 [`render_target_for`] returns the window's own numbers.
 #[derive(Resource, Clone, Copy, PartialEq, Debug)]
 pub(crate) struct RenderScale(pub(crate) f32);
 
-/// The settable range of [`RenderScale`], shared by the CVar apply and the `$WOW_RENDER_SCALE` env
-/// knob so the two cannot drift.
-///
-/// Wider than a settings row would offer (a slider belongs at 50–200 %, where every engine puts
-/// it): this is the clamp that stops an absurd *value*, not the one that shapes the UI. The upper
-/// end is deliberately past 2 because supersampling is also the instrument — the only way to price
-/// a pixel on a machine whose present is railed at the display's grant (0362, and `crate::video`'s
-/// note that macOS honours neither `AutoNoVsync` nor `Immediate`).
+/// The settable range of [`RenderScale`], shared by the CVar and `$WOW_RENDER_SCALE`. Past 2 on
+/// purpose: supersampling prices a pixel on a machine whose present is railed at vsync.
 pub(crate) const RENDER_SCALE_RANGE: std::ops::RangeInclusive<f32> = 0.25..=4.0;
 
-/// The per-axis ceiling on the backdrop, in physical px — `wgpu::Limits::default()`'s
-/// `max_texture_dimension_2d`, which is what Bevy asks the adapter for unless `WgpuSettings` says
-/// otherwise.
-///
-/// Not a render-scale concern in origin: a window wider than this has always been a texture wgpu
-/// refuses to create, and before 1639 nothing here looked. The ceiling is applied to the *ratio*
-/// rather than to each axis (see [`render_target_for`]) so hitting it shrinks the picture instead of
-/// reshaping it.
+/// The per-axis ceiling in physical px, `wgpu::Limits::default()`'s `max_texture_dimension_2d`,
+/// applied to the ratio ([`render_target_for`]) so the picture shrinks rather than reshapes.
 const MAX_RENDER_AXIS: u32 = 8192;
 
 impl Default for RenderScale {
-    /// `$WOW_RENDER_SCALE` overrides the default, **session-only** — the A/B lever, the same posture
-    /// as `$WOW_MSAA` and `$WOW_FARCLIP`: a value pinned into `config.toml` would make a
-    /// measurement sticky across relaunches.
+    /// `$WOW_RENDER_SCALE` overrides the default for the session only, never into `config.toml`.
     fn default() -> Self {
         let scale = std::env::var("WOW_RENDER_SCALE")
             .ok()
@@ -139,19 +57,13 @@ impl Default for RenderScale {
 /// The backdrop's size and the world camera's target scale factor, for a window of `px` physical
 /// pixels at `window_factor`, rendered at `scale`.
 ///
-/// **Two invariants, and the second is the load-bearing one.**
+/// 1. The ratio, never one axis, clamps to [`MAX_RENDER_AXIS`], so the image keeps the window's
+///    aspect.
+/// 2. `size.x / factor`, the camera's logical viewport width, is the window's logical width at any
+///    `scale`: the factor derives from the size built, after the `round()`, since every pick ray is
+///    denominated in it.
 ///
-/// 1. The image keeps the window's aspect, so the ratio — never an individual axis — is what gets
-///    clamped to [`MAX_RENDER_AXIS`]. Clamping the axes independently would letterbox the world
-///    inside a quad that is still the window's shape.
-/// 2. `size.x / factor` — the camera's LOGICAL viewport width — comes out the window's logical
-///    width, whatever `scale` is. That is why the factor is derived from the size actually built
-///    rather than from `scale`: the `round()` moves the true ratio by up to half a pixel, and it is
-///    the logical number every pick ray is denominated in (see [`retarget_world_camera`]).
-///
-/// At `scale == 1.0` both lines are exact identities in IEEE — `px × 1.0` is `px`, `size.x / px.x`
-/// is `1.0`, `window_factor × 1.0` is `window_factor` — so the pre-1639 numbers come back
-/// bit-for-bit and no golden can move. A test welds that.
+/// At `scale == 1.0` both are exact in IEEE, so the window's own numbers come back bit for bit.
 fn render_target_for(px: UVec2, window_factor: f32, scale: f32) -> (UVec2, f32) {
     let px = px.max(UVec2::ONE);
     let ceiling = |axis: u32| MAX_RENDER_AXIS as f32 / axis as f32;
@@ -166,63 +78,39 @@ fn render_target_for(px: UVec2, window_factor: f32, scale: f32) -> (UVec2, f32)
     (size, window_factor * size.x as f32 / px.x as f32)
 }
 
-/// The texture LOD bias a render at `effective` scale owes its mipmapped world textures.
+/// The texture LOD bias a render at `effective` scale owes its mipmapped textures: `log2(scale)`,
+/// clamped at 0 so supersampling keeps its sharper mips.
 ///
-/// Rendering smaller doubles every screen-space derivative, so every sampler picks a **coarser**
-/// mip — and that blur then gets stretched back up by the resolve, on top of the resolution loss.
-/// Every engine that ships a render scale compensates with `log2(scale)`, and every one of them has
-/// to do it in the shader, because WebGPU dropped the sampler's LOD bias: `wgpu::SamplerDescriptor`
-/// (27.0.1) carries `lod_min_clamp`, `lod_max_clamp` and `anisotropy_clamp`, and nothing else.
-///
-/// **Clamped at 0 — downscaling is compensated, upscaling is left alone.** Above 1.0 the smaller
-/// derivatives already pick a *sharper* mip, and that is not an artefact to correct: it is exactly
-/// what makes supersampling work, since the resolve then averages detail that a native-resolution
-/// frame could never have resolved. Feeding it `+log2(scale)` would hand back the blurrier mip and
-/// throw the win away.
-///
-/// Bevy carries the plumbing already: [`MipBias`] on the camera is extracted into the view uniform
-/// (`View::mip_bias`, defaulting 0.0 when absent), and `pbr_input_from_standard_material` applies it
-/// to every sample — so the whole M2/WMO/creature/doodad lane gets this for free and only our own
-/// hand-written samplers had to be taught (`terrain.wgsl`, `static_gx.wgsl`, `liquid.wgsl`, and the
+/// WebGPU samplers carry no LOD bias, so it rides [`MipBias`] into the view uniform, which the PBR
+/// lane applies and our own shaders must too (`terrain.wgsl`, `static_gx.wgsl`, `liquid.wgsl`, the
 /// coverage re-sample in `wow_model.wgsl`).
 fn mip_bias(effective: f32) -> f32 {
     effective.log2().min(0.0)
 }
 
-/// The world camera's target — the size-carrier (see the module doc) — and the claim that makes
-/// the world the first draw of the UI camera's main pass.
-///
-/// Sized in physical pixels **× [`RenderScale`]**; at the default 1.0 that matches the swapchain 1:1
-/// and the combine's read of the world is an identity resample, which is the property the
-/// composite lane was built on and the reason the scale ships off.
+/// The world camera's target, the size-carrier, in physical px × [`RenderScale`]; at 1.0 the
+/// combine's read of the world is an identity resample.
 #[derive(Resource)]
 pub(crate) struct WorldBackdrop {
-    /// The image the world camera targets. Nothing writes it (the camera runs `Skip`, its final
-    /// pass is the UI camera's — [`FfxBackdrop`]) and nothing samples it; it exists to give the
-    /// view its render size and its logical viewport.
+    /// The image the world camera targets. Nothing writes or samples it (the camera's final pass
+    /// is the UI camera's, [`FfxBackdrop`]); it gives the view its size and logical viewport.
     pub(crate) image: Handle<Image>,
-    /// The size the image was last built at, in physical px — the resize gate.
+    /// The size the image was last built at, in physical px: the resize gate.
     size: UVec2,
-    /// What the world camera's target was last stamped with: **which image**, and the scale factor
-    /// that went with it. Both halves gate the re-stamp — the factor because a stale one is B169,
-    /// the image because a rebuilt backdrop is a NEW asset (see [`track_render_size`]) and a camera
-    /// left aiming at the retired one renders into nothing. `None` until the first stamp.
+    /// The image and scale factor the camera was last stamped with. Both gate the re-stamp: a
+    /// rebuilt backdrop is a new asset ([`track_render_size`]). `None` until the first stamp.
     stamped: Option<(AssetId<Image>, f32)>,
 }
 
 impl WorldBackdrop {
-    /// The size the world is actually being rendered at, in physical px — the window's size times
-    /// [`RenderScale`], after the rounding and the axis ceiling. The number an FPS probe has to
-    /// print beside its frame time, since nothing else in the line can imply it.
+    /// The world's render size in physical px, after the rounding and the axis ceiling.
     pub(crate) fn render_size(&self) -> UVec2 {
         self.size
     }
 }
 
-/// A fresh world-camera target at `size` physical px: the size-carrier of the module doc. One
-/// byte a pixel and a render attachment only — nothing writes it and nothing samples it, so the
-/// cheapest format a camera target may have is the honest one, and the CPU copy is dropped once
-/// the render world has it.
+/// A fresh size-carrier at `size` physical px: one byte a pixel, a render attachment only, its CPU
+/// copy dropped once the render world has it.
 fn new_world_target(size: UVec2) -> Image {
     let mut image = Image::new_fill(
         Extent3d {
@@ -263,37 +151,16 @@ fn setup_backdrop(
     commands.insert_resource(WorldBackdrop {
         image,
         size,
-        // Nothing stamped yet, so `retarget_world_camera`'s first run always fires — before any
-        // camera exists to point at the image.
+        // Nothing stamped yet, so `retarget_world_camera`'s first run always fires.
         stamped: None,
     });
 }
 
-/// Keep the target at `window × `[`RenderScale`]. A stale-sized target would still *work* (the
-/// combine samples whatever size the world rendered at) — what it would break is the pairing: the
-/// size and the factor [`retarget_world_camera`] stamps are two halves of one number, and a size
-/// that moved without the factor following it is exactly the B169 defect with a different
-/// constant.
+/// Keep the target at `window × `[`RenderScale`]; runs before the stamp, whose factor must pair
+/// with this size.
 ///
-/// Runs before the stamp (the plugin's `.chain()`), so the factor is always computed against the
-/// image that now exists.
-///
-/// ## The rebuild publishes a NEW asset — it does not write through the old handle (decision 1647)
-///
-/// It used to do exactly that (`*images.get_mut(&handle) = new_backdrop_image(size)`), and **the
-/// world froze**: change any graphics setting or resize the window in the world and the 3D stopped
-/// dead at the frame of the change while the interface carried on — the director's report of
-/// 2026-08-27. Mutating an `Image` behind its handle makes a whole new GPU texture, and the UI
-/// pass's material cache, keyed on `AssetId<Image>`, kept its bind group on the texture just
-/// thrown away, sampling it forever.
-///
-/// Since 2234 no material samples this image at all, so that door is closed; the rule stays
-/// because it was never that cache's rule but the tree's: **`AssetId<Image>` is the name of a GPU
-/// texture, so a new GPU texture gets a new name.** Every consumer then reacts on its own — here
-/// [`retarget_world_camera`] re-points the camera — and nothing anywhere can hold a stale view by
-/// a name that did not change. The retired asset is **removed**, not merely dropped, for the same
-/// reason: a name that goes away is one nothing can keep by mistake, and `ui_pass`'s rebuild
-/// forgets materials on exactly that event.
+/// A rebuild publishes a new asset and removes the old one, never writing through the old handle:
+/// `AssetId<Image>` names a GPU texture, and anything keyed on it would keep the retired texture.
 fn track_render_size(
     mut backdrop: ResMut<WorldBackdrop>,
     mut images: ResMut<Assets<Image>>,
@@ -314,9 +181,7 @@ fn track_render_size(
     let retired = std::mem::replace(&mut backdrop.image, images.add(new_world_target(size)));
     images.remove(&retired);
     backdrop.size = size;
-    // Said out loud on every change, because a measurement taken at the wrong scale looks
-    // exactly like a measurement: the pixels the GPU is actually being asked for are the one
-    // term no probe line could infer from the window.
+    // Logged on every change: the rendered pixel count is the one term a probe cannot infer.
     info!(
         "render scale {:.3}: world renders at {}x{} into a {}x{} window",
         scale.0,
@@ -327,47 +192,14 @@ fn track_render_size(
     );
 }
 
-/// Point the world camera at the backdrop instead of the swapchain — **carrying the window's own
-/// scale factor**.
+/// Point the world camera at the backdrop instead of the swapchain, carrying the window's scale
+/// factor. A system, as the camera has two spawn sites; `benilla-worldview` keeps the swapchain.
 ///
-/// A system rather than a component on the spawn, because there are two spawn sites for the same
-/// camera (the real one and `player::setup`'s no-client-data fallback) and neither should have to
-/// know about the composite lane. `benilla-worldview` is unaffected — it links `benilla-world`, not
-/// this crate, and has no UI camera to composite with, so its world camera keeps the swapchain.
-///
-/// **The scale factor is the load-bearing half.** A camera's logical↔physical conversions all go
-/// through its target's `RenderTargetInfo`: a WINDOW target reports the window's physical size and
-/// the window's scale factor, so `logical_viewport_size` is the window's LOGICAL size — which is
-/// the space `Window::cursor_position` reports in, and the space every caller here works in
-/// (`capture::pick_probe`'s header says it outright: *"`viewport_to_world` works in logical units
-/// and a Retina capture is 2× the logical window"*). `From<Handle<Image>>` builds an
-/// `ImageRenderTarget` with `scale_factor: 1.0`, and this backdrop is sized in **physical** px — so
-/// the moment the world camera was retargeted at it, its logical viewport became the PHYSICAL size
-/// and every conversion silently gained a factor of the display's scale.
-///
-/// On a 2× display that aims every world pick ray at a quarter of the screen: the ray for a cursor
-/// at the centre goes to the upper-left quadrant. It hit the whole client at once — the GameObject
-/// pick (the cog that "barely appears" and the right-click that "does nothing half the time" —
-/// B169's fourth half), the unit pick and its occlusion ray, and the `world_to_viewport` side
-/// (chat bubbles, `target::scan`). Stamping the window's real scale factor restores the
-/// pre-composite semantics for all of them at once, which is why it lives here and not as a
-/// conversion at each of the eight call sites.
-///
-/// Re-stamped when the factor changes, not only on `Added`: dragging the window between a Retina
-/// and a non-Retina display changes it mid-session — and, since 1639, so does moving
-/// [`RenderScale`], which multiplies into exactly the same number.
-///
-/// **Render scale rides here rather than anywhere else precisely because of the paragraph above.**
-/// The camera's logical viewport is `image_size / scale_factor`; scaling both by the same ratio
-/// leaves it — and therefore the projection (`camera_system` feeds `logical_viewport_size` into
-/// `Projection::update`) and every pick ray (`viewport_to_ndc` and `world_to_viewport_core` read
-/// `logical_viewport_rect()` and nothing else) — **arithmetically unchanged**. Picking is not
-/// "still correct after render scale"; it cannot see render scale at all.
-///
-/// The camera also carries the [`MipBias`] that a scaled render owes its textures — see
-/// [`mip_bias`]. Absent, Bevy's view uniform reads 0.0, so the component is inserted every stamp
-/// rather than only when non-zero: a camera left holding last scale's bias is the same class of
-/// stale-pairing bug as a stale factor.
+/// `From<Handle<Image>>` stamps `scale_factor: 1.0`, which on a physical-px image makes the logical
+/// viewport the physical size and throws every pick ray and `world_to_viewport` off by the display
+/// scale. With the window's factor the logical viewport stays the window's, and render scale moves
+/// size and factor together, so projection and picking never see it. Re-stamped when the image or
+/// the factor changes, with the [`MipBias`] ([`mip_bias`]) inserted on every stamp.
 fn retarget_world_camera(
     mut commands: Commands,
     mut backdrop: ResMut<WorldBackdrop>,
@@ -378,12 +210,9 @@ fn retarget_world_camera(
     let (px, window_factor) = windows.single().map_or((UVec2::ONE, 1.0), |w| {
         (window_physical_size(w), w.resolution.scale_factor())
     });
-    // The image's real size, not the requested one: `track_render_size` ran first and may have
-    // clamped, and the factor must describe the texture that exists.
+    // The built size, not the requested one: `track_render_size` may have clamped.
     let scale_factor = window_factor * backdrop.size.x as f32 / px.x.max(1) as f32;
-    // **The image as well as the factor.** A rebuild retires the old asset and publishes a new one
-    // ([`track_render_size`]), and on a pure window resize the factor does NOT move — so a
-    // factor-only gate would leave every world camera aiming at an asset that no longer exists.
+    // The image as well as the factor: a pure window resize rebuilds without moving the factor.
     let want = (backdrop.image.id(), scale_factor);
     let moved = backdrop.stamped != Some(want);
     if !moved && added.is_empty() {
@@ -400,14 +229,8 @@ fn retarget_world_camera(
     }
 }
 
-/// Point the player-UI camera's ground pass at the world camera drawing this frame
-/// ([`FfxBackdrop`]): the active one, `None` when there is none.
-///
-/// With no world (the glue screens, the loading screen, a gated camera) the world view's main
-/// texture holds a stale or never-written frame, and grounding the interface on it would be
-/// worse than the transparent clear the UI camera falls back to. Whether the camera named here
-/// actually rendered this frame is the render world's to know, and it checks
-/// (`ffx_glow::prepare_backdrops`).
+/// Point the player-UI camera's ground pass ([`FfxBackdrop`]) at the active world camera; with
+/// none it is `None`, and the UI camera clears to transparent rather than show a stale world frame.
 fn claim_backdrop(
     cameras: Query<(Entity, &Camera), With<WorldCamera>>,
     mut ui: Query<&mut FfxBackdrop, With<PlayerUiCamera>>,
@@ -416,8 +239,7 @@ fn claim_backdrop(
         .iter()
         .find_map(|(entity, camera)| camera.is_active.then_some(entity));
     for mut backdrop in &mut ui {
-        // Compare first: the component is extracted every frame regardless, and a write here
-        // would trip change detection for nothing.
+        // Compare first: a write would trip change detection for nothing.
         if backdrop.source != source {
             backdrop.source = source;
         }
@@ -425,12 +247,10 @@ fn claim_backdrop(
 }
 
 /// Owns the world camera's target (the size-carrier) and the UI camera's claim on the world.
-/// See the module doc.
 pub(crate) struct WorldBackdropPlugin;
 
-/// Render scale's change callback (1639, 2303). Clamped at the knob's edge like every other
-/// numeric row; the backdrop re-sizes on the next frame and the world camera's target factor
-/// follows it in the same pass, which is what keeps the pick rays where they were.
+/// Render scale's change callback, clamped to [`RENDER_SCALE_RANGE`]; the backdrop and the
+/// camera's factor follow together on the next frame.
 pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut scale: ResMut<RenderScale>) {
     if ev.is("renderScale") {
         scale.0 = ev
@@ -456,11 +276,7 @@ mod tests {
     use super::*;
     use bevy::image::TextureFormatPixelInfo as _;
 
-    /// **The world camera's target is a size-carrier and nothing else** (decision 2234): one byte
-    /// a pixel, a render attachment because a camera target must be one, and NOT a texture —
-    /// nothing samples it. The float image this used to be (1603) carried the world to the UI
-    /// pass's first quad; the combine carries it now, straight into the UI target, and a future
-    /// "make the target samplable again" edit is a second copy of the world coming back.
+    /// One byte a pixel, a render attachment, never sampled.
     #[test]
     fn the_world_target_is_a_size_carrier_only() {
         let image = new_world_target(UVec2::new(320, 200));
@@ -479,8 +295,6 @@ mod tests {
         );
     }
 
-    /// The UI camera's ground pass follows the world camera that is drawing: the active one,
-    /// `None` while there is none.
     #[test]
     fn the_ui_camera_claims_the_drawing_world_camera() {
         let mut app = App::new();
@@ -511,20 +325,7 @@ mod tests {
         assert_eq!(source(&mut app), None, "gated: the claim goes with it");
     }
 
-    /// **The world camera's target carries the WINDOW's scale factor, not `1.0`** — the pick
-    /// regression of 2026-08-26 (B169's fourth half).
-    ///
-    /// `From<Handle<Image>>` builds an `ImageRenderTarget` with `scale_factor: 1.0`, and this
-    /// backdrop is sized in PHYSICAL px. A camera whose target says "physical size, scale 1"
-    /// reports that physical size as its LOGICAL viewport — but every caller works in logical
-    /// units, because that is what `Window::cursor_position` reports in. So on a 2× display the
-    /// world's pick ray for a centred cursor went to the upper-left quadrant, and the cog "barely
-    /// appeared" while right-click "did nothing half the time". It hit all eight
-    /// `viewport_to_world`/`world_to_viewport` sites at once, not just the GameObject pick.
-    ///
-    /// The scale factor is re-stamped when it CHANGES, not only on `Added`: dragging the window
-    /// from a Retina display to a non-Retina one changes it mid-session, and a stale factor is the
-    /// same defect with a different constant.
+    /// The window's factor, not `1.0`, re-stamped when the window moves to another display.
     #[test]
     fn the_world_cameras_target_carries_the_windows_scale_factor() {
         let mut app = App::new();
@@ -538,9 +339,7 @@ mod tests {
         app.world_mut().spawn((window(2.0), PrimaryWindow));
         app.init_resource::<RenderScale>()
             .add_systems(Startup, setup_backdrop)
-            // Chained exactly as the plugin chains them: since 1639 the stamp reads the size the
-            // resize pass settled on, so a test that ran the stamp alone would be testing a pairing
-            // that never happens.
+            // Chained as the plugin chains them: the stamp reads the size the resize pass settled.
             .add_systems(Update, (track_render_size, retarget_world_camera).chain());
         let cam = app
             .world_mut()
@@ -572,8 +371,7 @@ mod tests {
         );
     }
 
-    /// Physical, not logical: the target is the world's render size. A zero-size window (minimised
-    /// on some platforms) must still produce a legal texture rather than a device error.
+    /// A zero-size window (minimised on some platforms) still builds a legal texture.
     #[test]
     fn a_degenerate_size_still_builds_a_legal_texture() {
         let image = new_world_target(UVec2::ZERO);
@@ -585,16 +383,13 @@ mod tests {
         );
     }
 
-    /// **Scale 1.0 is bit-for-bit the pre-1639 lane** — the property every visual golden in the
-    /// tree rests on. Not "within a pixel": the same `UVec2` and the same `f32`, because
-    /// `px × 1.0`, `size.x / px.x` and `f × 1.0` are all exact in IEEE and a rounding introduced
-    /// here would move the whole world by a sub-pixel resample.
+    /// Scale 1.0 gives the window's own numbers exactly, which every visual golden rests on.
     #[test]
     fn scale_one_reproduces_the_windows_own_numbers_exactly() {
         for px in [
             UVec2::new(1280, 720),
             UVec2::new(3200, 1800),
-            UVec2::new(1601, 901), // odd on both axes — the case a `/ 2` would round
+            UVec2::new(1601, 901), // odd on both axes, the case a `/ 2` would round
         ] {
             for sf in [1.0, 1.5, 2.0] {
                 assert_eq!(render_target_for(px, sf, 1.0), (px, sf), "{px} at {sf}×");
@@ -602,13 +397,8 @@ mod tests {
         }
     }
 
-    /// **The camera's logical viewport does not move** — the whole design, and the invariant that
-    /// makes render scale invisible to picking. `logical = image_size / scale_factor`
-    /// (`bevy_camera`'s `to_logical`), and that is what `viewport_to_ndc` and
-    /// `world_to_viewport_core` read; if it drifts, B169 comes back at the drift's magnitude.
-    ///
-    /// Sub-pixel is the tolerance because the image is integer: the ratio is derived back out of
-    /// the size that was actually built, so x is exact and y carries at most one `round()`.
+    /// `logical = image_size / scale_factor` (`bevy_camera`'s `to_logical`) stays the window's at
+    /// every scale: x exact, y within one `round()`.
     #[test]
     fn every_scale_keeps_the_logical_viewport_the_windows_own() {
         for px in [UVec2::new(1280, 720), UVec2::new(3200, 1800)] {
@@ -630,10 +420,7 @@ mod tests {
         }
     }
 
-    /// The axis ceiling clamps the **ratio**, so the picture keeps the window's aspect instead of
-    /// being letterboxed inside a quad that is still the window's shape. It binds on an oversized
-    /// window at scale 1.0 too — a >8192 px window was a texture wgpu refuses to create long before
-    /// this dial existed, and nothing here used to look.
+    /// The ceiling clamps the ratio, keeping the aspect, and binds on a huge window at 1.0 too.
     #[test]
     fn the_axis_ceiling_shrinks_the_picture_it_does_not_reshape_it() {
         let px = UVec2::new(3840, 2160);
@@ -657,9 +444,6 @@ mod tests {
         );
     }
 
-    /// **The bias compensates downscaling and leaves supersampling alone.** A negative bias where a
-    /// scale is > 1 would hand back the coarser mip and throw away the only thing SSAA buys; a
-    /// missing one where it is < 1 is the double blur every engine's render scale corrects.
     #[test]
     fn the_mip_bias_is_log2_below_one_and_nothing_above_it() {
         assert!((mip_bias(0.5) - -1.0).abs() < 1e-6);
@@ -673,20 +457,7 @@ mod tests {
         assert_eq!(mip_bias(4.0), 0.0);
     }
 
-    /// **A rebuild publishes a NEW image, and the camera follows it onto the new one** — the
-    /// 2026-08-27 world-freeze (decision 1647).
-    ///
-    /// Writing the new size through the OLD handle is what froze the world: `ui_pass` keys its
-    /// material cache on `AssetId<Image>`, and Bevy prepares a material's bind group once, so the
-    /// same id handed back the same bind group — still holding the `TextureView` of the texture
-    /// that had just been thrown away. The world camera drew into the new texture; the UI kept
-    /// sampling the dead one, forever.
-    ///
-    /// Three assertions, because the fix has three halves and any one of them alone is still broken:
-    /// the id must MOVE (or the cache cannot tell), the old asset must be GONE (or the retired
-    /// image is pinned by whatever still names it), and the camera must be re-stamped onto the new
-    /// handle — that last one is the half a factor-only gate misses, since a pure window resize
-    /// does not move the scale factor at all.
+    /// The id moves, the old asset is removed, and the camera is re-stamped onto the new image.
     #[test]
     fn a_rebuilt_backdrop_is_a_new_asset_and_the_camera_follows_it() {
         let mut app = App::new();
@@ -705,7 +476,7 @@ mod tests {
         app.update();
         let first = app.world().resource::<WorldBackdrop>().image.id();
 
-        // The director's own path: move the render scale while the world is up.
+        // Move the render scale while the world is up.
         app.insert_resource(RenderScale(0.5));
         app.update();
 
@@ -730,8 +501,7 @@ mod tests {
         }
     }
 
-    /// A pure WINDOW resize moves the image without moving the scale factor — the case a
-    /// factor-only re-stamp gate silently misses, leaving the camera aimed at a removed asset.
+    /// A pure window resize moves the image without moving the scale factor.
     #[test]
     fn a_window_resize_restamps_the_camera_even_though_the_factor_does_not_move() {
         let mut app = App::new();
@@ -779,9 +549,7 @@ mod tests {
         );
     }
 
-    /// End to end on a live `App`: a half-scale world on a 2× display renders into a half-size
-    /// image, stamps a factor of 1.0 — `image / factor` is still the window's logical size — and
-    /// carries `MipBias(-1)`.
+    /// A half-scale world on a 2× display: a half-size image, a factor of 1.0, `MipBias(-1)`.
     #[test]
     fn a_half_scale_world_halves_the_image_the_factor_and_the_mip() {
         let mut app = App::new();
diff --git a/crates/benilla-app/src/world_state.rs b/crates/benilla-app/src/world_state.rs
index 18edc4df..7230e5cb 100644
--- a/crates/benilla-app/src/world_state.rs
+++ b/crates/benilla-app/src/world_state.rs
@@ -1,37 +1,22 @@
-//! The world-state table — the server's key/value scoreboard, fed by `SMSG_INIT_WORLD_STATES` and
-//! `SMSG_UPDATE_WORLD_STATE` ([`benilla_protocol::messages::world_state`] for both wires).
+//! The world-state table, the server's key/value scoreboard from `SMSG_INIT_WORLD_STATES` and
+//! `SMSG_UPDATE_WORLD_STATE`. Read by the NPC-text `$<n>w`/`$<n>e` tokens ([`crate::npc_text`])
+//! and by the world map's landmark pass ([`crate::ui_world_map`]), where an `AreaPOI.dbc` row with
+//! a `WorldStateID` shows only while that state is nonzero.
 //!
-//! Two readers:
+//! The reference keeps an open hash keyed by the raw wire dword (`[0xb71ec8]`, bucket
+//! `mask & key`, value at node `+0x18`); keys stay raw because `$<n>e` reads the negated key
+//! (`$2077e` looks up `0xFFFFF7E3`).
 //!
-//! - the NPC-text expander's `$<n>w` / `$<n>e` tokens ([`crate::npc_text`]) — the reference
-//!   renders a hit as `%d` and a **miss as `"0"`**, so every such token printed `"0"` until this
-//!   landed: faithful while the table was empty, wrong the moment a zone sent real states;
-//! - the **world map's landmark pass** ([`crate::ui_world_map`], decision 1586) — an `AreaPOI.dbc`
-//!   row carrying a `WorldStateID` shows only while that state reads non-zero, which is what makes
-//!   the Eastern Plaguelands tower icons and the capitals' "Under Attack" markers appear and
-//!   change side. [`WorldStates::generation`] is the edge it rebuilds on.
-//!
-//! Shape is the reference's, not a convenience: it keeps an open hash keyed by the **raw wire
-//! dword** (`[0xb71ec8]`, bucket `mask & key`, value at node `+0x18`, miss → `0` at `0x4c5867`).
-//! Raw matters because `$<n>e` reads the table at the *negated* key — `$2077e` looks up
-//! `0xFFFFF7E3`, which only resolves if nothing re-interpreted the id on the way in.
-//!
-//! **An init CLEARS the table first**, correcting the assumption this module shipped with.
-//! `0x4c5650(ecx = map, edx = area)`, the function `SMSG_INIT_WORLD_STATES`' two leading dwords go
-//! to before the pair loop runs, does four things in order: it drains every entry (the all-entries
-//! list, then every bucket), stores the pair as the **display filter** `[0xb71e84]`/`[0xb71ea8]`,
-//! rebuilds the world-state UI list against that filter, and only then does the handler apply the
-//! packet's pairs. The bucket array itself survives; only entries are freed.
-//!
-//! That filter pair is [`WorldStates::scope`], and it is the reference's own notion of "where the
-//! player is" for this UI — **the server's last init, never the avatar's position**. Its only two
-//! writers image-wide are this clear and the logout reset.
+//! An init first runs `0x4c5650(ecx = map, edx = area)`: it frees every entry, stores the pair as
+//! the display filter `[0xb71e84]`/`[0xb71ea8]` ([`WorldStates::scope`]) and rebuilds the
+//! world-state UI list, and only then are the packet's pairs applied. The filter is the server's
+//! last init, never the avatar's position; only this clear and the logout reset write it.
 
 use std::collections::HashMap;
 
 use bevy::prelude::*;
 
-/// The live world-state table. Keys and values are raw wire dwords; see the module doc.
+/// The live world-state table, keyed and valued by raw wire dwords.
 #[derive(Resource, Default)]
 pub(crate) struct WorldStates {
     values: HashMap<u32, u32>,
@@ -40,60 +25,41 @@ pub(crate) struct WorldStates {
 }
 
 impl WorldStates {
-    /// Bumped on every [`Self::write`] — the "the table moved" edge a reader rebuilds on.
-    ///
-    /// This is the reference's own trigger shape, not a cache trick bolted on: the bulk
-    /// world-state handler re-runs the world-map landmark builder from *inside itself*
-    /// (`0x48fa0d` → `0x4a67a0`), so a landmark list is
-    /// rebuilt **because a world state arrived**, never once a frame. Counted per `write` rather
-    /// than per changed value for the same reason: the handler re-runs the builder once for the
-    /// whole packet, not once per pair.
+    /// Bumped per write and per init, not per pair, the edge readers rebuild on: the reference's
+    /// handler re-runs the world-map landmark builder once per packet (`0x48fa0d` to `0x4a67a0`).
     pub(crate) fn generation(&self) -> u64 {
         self.generation
     }
 
-    /// The reference's getter `0x4c5810`, including its miss leg: an absent key reads **0**, which
-    /// is why an un-received world state renders `"0"` rather than blank or the literal token.
-    ///
-    /// Returned as `i32` because that is the width the one caller formats — the reference prints
-    /// the dword through `"%d"`, so a value with the top bit set shows as negative.
+    /// The reference's getter (`0x4c5810`): a missing key reads 0 (`0x4c5867`). Signed, as the
+    /// reference prints it through `"%d"`.
     pub(crate) fn get(&self, key: u32) -> i32 {
         self.values.get(&key).copied().unwrap_or(0) as i32
     }
 
-    /// Every `(key, value)` currently in the table, in no particular order — the instrument
-    /// read, and only that. No reference function enumerates this hash: the client's own readers
-    /// are the point getter above and the `WorldStateUI.dbc` walk, both of which ask for a key
-    /// they already know. A battleground's whole score lives here as raw dwords nobody has a name
-    /// for yet, so a probe that cannot dump it cannot say what arrived (`capture::ProbeBgPlugin`).
+    /// Every pair, unordered, for instruments only (`capture::ProbeBgPlugin`); the reference
+    /// never enumerates the table.
     pub(crate) fn pairs(&self) -> impl Iterator<Item = (u32, i32)> + '_ {
         self.values.iter().map(|(&k, &v)| (k, v as i32))
     }
 
-    /// The `(map, area)` the last `SMSG_INIT_WORLD_STATES` scoped the table to — the reference's
-    /// `[0xb71e84]`/`[0xb71ea8]`, and the filter its world-state UI list is built against. `None`
-    /// before any init has arrived, which is the reference's `-1` (its rebuild trigger refuses to
-    /// run until an init has been seen).
+    /// The `(map, area)` of the last init, `[0xb71e84]`/`[0xb71ea8]`; `None` before any init, the
+    /// reference's `-1`.
     pub(crate) fn scope(&self) -> Option<(u32, u32)> {
         self.scope
     }
 
-    /// `SMSG_INIT_WORLD_STATES`' leading half — the reference's `0x4c5650`: **drop every entry**,
-    /// then record the `(map, area)` filter. The caller applies the packet's pairs after; the
-    /// order is the reference's, and it is what makes a zone change forget the previous zone's
-    /// keys rather than leaving them readable.
+    /// An init's leading half (`0x4c5650`): drops every entry, then records the filter. The caller
+    /// applies the pairs after.
     pub(crate) fn init_scope(&mut self, map: u32, area: u32) {
         self.values.clear();
         self.scope = Some((map, area));
         self.generation = self.generation.wrapping_add(1);
     }
 
-    /// Apply a run of `(id, value)` writes — the reference's setter `0x4c5870`, which both opcodes
-    /// funnel into. Init's trailing `(0, 0)` terminator is written like any other pair, exactly as
-    /// the reference's count loop does; it is data, not a sentinel — and `Set(k, 0)` **stores**
-    /// rather than deleting (`edx` is never tested across `[0x4c5870, 0x4c5a31)`), which is why a
-    /// state that goes to zero stays a present key reading `0`. A repeated key overwrites in place
-    /// (`0x4c58bb`); there is never a second node.
+    /// Writes `(id, value)` pairs, the reference's setter (`0x4c5870`) for both opcodes. Init's
+    /// trailing `(0, 0)` is written as data; a zero value is stored, not deleted (`edx` is never
+    /// tested in `[0x4c5870, 0x4c5a31)`); a repeated key overwrites in place (`0x4c58bb`).
     pub(crate) fn write(&mut self, states: &[(u32, u32)]) {
         self.values.extend(states.iter().copied());
         self.generation = self.generation.wrapping_add(1);
@@ -104,8 +70,6 @@ impl WorldStates {
 mod tests {
     use super::*;
 
-    /// The getter's miss leg and the `%d` width: an unknown key is 0 (not blank), a known one is
-    /// its value, and the top bit reads through as a negative — the three things `$<n>w` depends on.
     #[test]
     fn a_miss_reads_zero_and_a_value_keeps_its_sign() {
         let mut table = WorldStates::default();
@@ -116,8 +80,6 @@ mod tests {
         assert_eq!(table.get(9999), 0, "still a miss");
     }
 
-    /// `$<n>e`'s negated key is a *different* entry, not the same one — the whole reason ids stay
-    /// raw dwords. Writing id 2077 must not make `$2077e` (key `0xFFFFF7E3`) resolve.
     #[test]
     fn the_negated_key_is_a_separate_entry() {
         let mut table = WorldStates::default();
@@ -128,8 +90,6 @@ mod tests {
         assert_eq!(table.get(2077), 7, "the positive key is untouched");
     }
 
-    /// A later write to a live key replaces it (`SMSG_UPDATE_WORLD_STATE`'s whole job), and an
-    /// init's terminator lands as the ordinary entry it is.
     #[test]
     fn a_write_replaces_and_the_terminator_is_just_data() {
         let mut table = WorldStates::default();
diff --git a/crates/benilla-app/src/world_state_ui.rs b/crates/benilla-app/src/world_state_ui.rs
index 490b53d7..111717b2 100644
--- a/crates/benilla-app/src/world_state_ui.rs
+++ b/crates/benilla-app/src/world_state_ui.rs
@@ -1,43 +1,17 @@
-//! The always-up world-state readout (`WorldStateFrame`) — the app half behind
-//! stock `Interface\FrameXML\WorldStateFrame.xml` and benilla-ui's `script/worldstate.rs` bindings.
+//! The always-up world-state readout behind stock `WorldStateFrame.xml`: joins the rows
+//! `WorldStateUI.dbc` displays with the states the server sent ([`crate::world_state`]).
 //!
-//! This is report **B190**'s second half: the alliance↔horde progress UI. `WorldStateUI.dbc` says
-//! which world states are *displayed*, where, and with what label; [`crate::world_state`] holds
-//! what the server actually sent; this module joins them and pushes the result.
+//! The list builder (`0x4c56e0`) walks the whole DBC and admits a row when:
+//! 1. `MapID` is -1 or the scope's map;
+//! 2. `AreaID` is 0 or the scope's area;
+//! 3. `Type` is 0, or 1 while [`defense_channel_joined`]; 2 (battleground scoreboard columns)
+//!    never.
 //!
-//! Everything below is the reference's.
+//! The scope is the server's last `SMSG_INIT_WORLD_STATES`, not the player's position: the
+//! reference's two scope globals are written only by that init and by the logout reset.
 //!
-//! ## The list builder (`0x4c56e0`)
-//!
-//! Walks the whole DBC and admits a row on three gates, each failure skipping the row rather than
-//! aborting the walk:
-//!
-//! 1. **Map** — `MapID == -1` (a wildcard with *zero* shipped rows) or `MapID` equals the scope's
-//!    map;
-//! 2. **Area** — `AreaID == 0` (wildcard) or equal to the scope's area;
-//! 3. **Type** — `0` accepts unconditionally, `1` accepts only while [`defense_channel_joined`],
-//!    `2` (the battleground scoreboard columns) always rejects.
-//!
-//! **The scope is the server's last `SMSG_INIT_WORLD_STATES`, not the player's position**
-//! ([`crate::world_state::WorldStates::scope`]). That is not a simplification: the two globals it
-//! mirrors have exactly two writers each image-wide, the init clear and the logout reset, so a
-//! plain zone change moves nothing here. It matters — walk into Eastern Plaguelands and the readout
-//! appears when the *server* says so, which is also when the states it would read arrive.
-//!
-//! ## Why the towers need a chat channel
-//!
-//! The `Type == 1` gate is the surprising one, and it is the whole of what the world-PvP rows
-//! (Eastern Plaguelands' three, Silithus's two) hang on. The reference recomputes a flag by
-//! scanning the channels the player has **joined** and asking whether any of their
-//! `ChatChannels.dbc` rows carries **both** `ZONE_DEP` and `DEFENSE` — which in the shipped table
-//! is row 22 alone, the zone-scoped defense channel. Leave that channel and the tower readout
-//! disappears; the map icons, which are gated on the world states themselves, stay.
-//!
-//! ## The text (`0x508560`)
-//!
-//! Exactly one of the ten returned values is expanded, and by an expander that is **not** the
-//! NPC-text one — different function, different grammar, sharing only the table getter. See
-//! [`expand`].
+//! The world-PvP rows (Eastern Plaguelands, Silithus) are all `Type` 1, so leaving the zone
+//! defense channel hides them; the map icons, gated on the states themselves, stay.
 
 use bevy::ecs::system::NonSendMut;
 use bevy::prelude::*;
@@ -49,12 +23,10 @@ use benilla_assets::{AssetSet, LockRecover, WorldAssets};
 
 use crate::world_state::WorldStates;
 
-/// The shared `WorldStateUI.dbc` catalog. Absent if the DBC failed to read, which degrades to an
-/// empty readout rather than an error.
+/// The shared `WorldStateUI.dbc` catalog; absent, the readout is empty.
 #[derive(Resource)]
 pub(crate) struct WorldStateUiRes(pub(crate) WorldStateUiCatalog);
 
-/// Startup: load the table off the patch chain.
 fn load_world_state_ui(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
     let Some(assets) = assets else { return };
     let loaded = {
@@ -70,13 +42,8 @@ fn load_world_state_ui(mut commands: Commands, assets: Option<Res<WorldAssets>>)
     }
 }
 
-/// The `Type == 1` gate: has the player joined a **zone-dependent defense** channel?
-///
-/// The reference scans its joined-channel array and tests each channel's `ChatChannels.dbc`
-/// `Flags` for `0x2 | 0x10000` (`0x49bd9b`/`0x49bda2`) — both bits, not either. Exactly one shipped
-/// row qualifies: id 22, flags `0x010003`. Our joined list is names, so each resolves back to its
-/// row the same way the server resolves it (`row_for_name`); a custom channel resolves to nothing
-/// and cannot open the gate, which is right.
+/// The `Type == 1` gate: a joined channel whose `ChatChannels.dbc` flags carry both `ZONE_DEP` and
+/// `DEFENSE` (`0x49bd9b`, `0x49bda2`), which is row 22 alone. A custom channel resolves to no row.
 fn defense_channel_joined(channels: &crate::ui_chat::ChannelState) -> bool {
     const REQUIRED: u32 = chan::ZONE_DEP | chan::DEFENSE;
     channels
@@ -85,23 +52,12 @@ fn defense_channel_joined(channels: &crate::ui_chat::ChannelState) -> bool {
         .any(|row| row.flags & REQUIRED == REQUIRED)
 }
 
-/// Expand a `WorldStateUI` label — the reference's `0x508560`, and **not** the NPC-text expander
-/// ([`crate::npc_text`]). The two share only the world-state getter: every `call` in this one
-/// resolves to a CRT helper, the getter, or the string primitives, and the quest-text token
-/// handler `0x5070a0` is not among them.
-///
-/// The grammar is `%<digits>W|w` **and nothing else** — no `$` sigil, and no `e` (negated-key)
-/// form. A hit reads the table at the parsed id and prints the value through `"%d"`. Anything else
-/// after a `%` emits a literal `"%"`, sets an error flag the caller ignores, and **leaves the
-/// offending character unconsumed** so it falls through as ordinary text — the digits scanned ahead
-/// of it are consumed either way. No shipped row reaches that leg (all nine macro-bearing rows are
-/// well-formed), so it is reproduced rather than relied upon.
-///
-/// The reference writes into a 260-byte buffer with a 256-byte limit, so a label longer than that
-/// is truncated. Kept, because a UI string silently growing past what the reference would show is
-/// a difference the frame would render.
+/// Expands a `WorldStateUI` label (`0x508560`), a different expander from [`crate::npc_text`]'s,
+/// sharing only the world-state getter. The grammar is `%<digits>W|w` alone, printed `%d`; any
+/// other `%` emits a literal `%`, consumes its digits and leaves the next character as text.
+/// Output is truncated at the reference's 256-byte limit.
 fn expand(text: &str, states: &WorldStates) -> String {
-    /// The reference's `strncat` bound — `0x508560`'s caller passes `0x100`.
+    /// The `strncat` bound: `0x508560`'s caller passes `0x100`.
     const LIMIT: usize = 0x100 - 1;
 
     fn push(s: &str, out: &mut String) {
@@ -130,12 +86,11 @@ fn expand(text: &str, states: &WorldStates) -> String {
         }
         match bytes.get(j) {
             Some(b'w' | b'W') => {
-                // `atoi` over the run — an empty run is 0, which reads the table at key 0.
+                // `atoi`: an empty run is key 0.
                 let id: u32 = text[digits_at..j].parse().unwrap_or(0);
                 push(&states.get(id).to_string(), &mut out);
                 i = j + 1;
             }
-            // The error leg: a literal `%`, and the letter is left for the next pass.
             _ => {
                 push("%", &mut out);
                 i = j;
@@ -145,16 +100,14 @@ fn expand(text: &str, states: &WorldStates) -> String {
     out
 }
 
-/// Build the rows for one scope — the builder's gates, then `GetWorldStateUIInfo`'s resolution of
-/// each admitted row into the ten values it answers with.
+/// The admitted rows for the current scope, resolved as `GetWorldStateUIInfo` answers them.
 fn build(
     catalog: &WorldStateUiCatalog,
     states: &WorldStates,
     defense_channel: bool,
 ) -> Vec<WorldStateUiView> {
     let Some((map, area)) = states.scope() else {
-        // No init seen. The reference's rebuild trigger refuses to run before one arrives, and its
-        // filter globals read `-1`, which no row matches.
+        // Before an init the reference never rebuilds, and its scope globals read -1.
         return Vec::new();
     };
     catalog
@@ -164,7 +117,6 @@ fn build(
         .collect()
 }
 
-/// The three gates, in the builder's order (see the module doc).
 fn admits(row: &WorldStateUiRow, map: u32, area: u32, defense_channel: bool) -> bool {
     let map_ok = row.map_id == u32::MAX || row.map_id == map;
     let area_ok = row.area_id == 0 || row.area_id == area;
@@ -176,13 +128,11 @@ fn admits(row: &WorldStateUiRow, map: u32, area: u32, defense_channel: bool) ->
     map_ok && area_ok && type_ok
 }
 
-/// `GetWorldStateUIInfo`'s ten values for one row (`0x4c5a70`). Only [`WorldStateUiRow::text`] is
-/// expanded; every other string is the DBC column verbatim, and the three extended ids answer
-/// their *resolved values*.
+/// `GetWorldStateUIInfo` for one row (`0x4c5a70`): only the text is expanded, and the extended
+/// ids answer their states' values.
 fn resolve(row: &WorldStateUiRow, states: &WorldStates) -> WorldStateUiView {
     WorldStateUiView {
-        // A row with no `StateVariable` answers the constant 1, not 0 — the miss leg is a literal
-        // `1.0` at `0x4c5ad8`, so "no state of its own" reads as on.
+        // No `StateVariable` answers 1 (`0x4c5ad8`).
         ui_state: match row.state_variable {
             0 => 1,
             id => states.get(id),
@@ -197,8 +147,8 @@ fn resolve(row: &WorldStateUiRow, states: &WorldStates) -> WorldStateUiView {
     }
 }
 
-/// Push the readout when any of its inputs moves. The setter diffs before firing
-/// `UPDATE_WORLD_STATES`, so a frame in which nothing changed costs one table walk and no event.
+/// Pushes the readout when a world-state packet arrives or the defense-channel flag flips, the
+/// reference's two rebuild triggers.
 fn feed_world_state_ui(
     script: Option<NonSendMut<UiScript>>,
     catalog: Option<Res<WorldStateUiRes>>,
@@ -207,9 +157,7 @@ fn feed_world_state_ui(
     mut defense_channel: Local<bool>,
     mut last: Local<crate::ui_script::VmMemo<Option<(u64, bool)>>>,
 ) {
-    // Recomputed only when the roster moves. The scan resolves each joined NAME back to its DBC
-    // row, which allocates per row — cheap once a login, wasteful sixty times a second. A system
-    // that has never run sees every resource as changed, so the first frame computes it.
+    // Only when the roster moves; a first run sees it changed.
     if channels.is_changed() {
         *defense_channel = defense_channel_joined(&channels);
     }
@@ -217,8 +165,6 @@ fn feed_world_state_ui(
     let (Some(mut script), Some(catalog)) = (script, catalog) else {
         return;
     };
-    // The reference's own two rebuild triggers: a world-state packet (which is also the only thing
-    // that moves the scope) and the defense-channel flag flipping.
     let key = (states.generation(), defense_channel);
     if *last.get(&script) == Some(key) {
         return;
@@ -232,7 +178,6 @@ pub(crate) struct WorldStateUiPlugin;
 impl Plugin for WorldStateUiPlugin {
     fn build(&self, app: &mut App) {
         app.add_systems(Startup, load_world_state_ui.after(AssetSet::Open))
-            // After the script tick, like every other feed: the queued event dispatches next tick.
             .add_systems(Update, feed_world_state_ui.after(crate::ui_script::UiInput));
     }
 }
@@ -257,8 +202,6 @@ mod tests {
         }
     }
 
-    /// The `%<digits>w` grammar: a hit prints the table value through `%d`, a miss prints `0`
-    /// (the getter's own miss leg), and case does not matter.
     #[test]
     fn the_macro_expands_world_state_values() {
         let mut states = WorldStates::default();
@@ -280,7 +223,6 @@ mod tests {
         assert_eq!(expand("", &states), "");
     }
 
-    /// A value with the top bit set prints negative — the `%d` width, same as `$<n>w`.
     #[test]
     fn a_top_bit_value_prints_negative() {
         let mut states = WorldStates::default();
@@ -288,9 +230,7 @@ mod tests {
         assert_eq!(expand("%2327w", &states), "-1");
     }
 
-    /// The error leg: a `%` not followed by an optional digit run and a `w` emits a literal `%`
-    /// and leaves the offending character to fall through as text. It is unreachable on shipped
-    /// data; it is here so the behaviour is decided rather than accidental.
+    /// Unreachable on shipped data.
     #[test]
     fn a_malformed_macro_emits_a_literal_percent() {
         let states = WorldStates::default();
@@ -304,7 +244,6 @@ mod tests {
         );
     }
 
-    /// The reference's 256-byte buffer bound.
     #[test]
     fn the_output_is_capped_at_the_reference_buffer() {
         let states = WorldStates::default();
@@ -312,8 +251,6 @@ mod tests {
         assert_eq!(expand(&long, &states).len(), 0xFF);
     }
 
-    /// The three builder gates. Map `-1` and area `0` are wildcards; `Type` 2 never enters this
-    /// list at all, and `Type` 1 waits for the defense channel.
     #[test]
     fn the_builder_gates_admit_the_right_rows() {
         // Eastern Plaguelands: map 0, area 139.
@@ -326,7 +263,6 @@ mod tests {
             "map -1 is a wildcard"
         );
 
-        // Type: 0 unconditional, 1 on the channel, 2 never.
         assert!(admits(&row(0, 139, 1), 0, 139, true));
         assert!(
             !admits(&row(0, 139, 1), 0, 139, false),
@@ -340,8 +276,6 @@ mod tests {
         }
     }
 
-    /// Before any `SMSG_INIT_WORLD_STATES` the readout is empty — the reference's filter globals
-    /// read `-1` and its rebuild trigger will not run at all.
     #[test]
     fn nothing_shows_before_the_first_init() {
         let catalog = WorldStateUiCatalog::from_rows(vec![(136, row(0, 139, 0))]);
@@ -349,8 +283,6 @@ mod tests {
         assert!(build(&catalog, &states, true).is_empty());
     }
 
-    /// A row with no `StateVariable` answers `uiState = 1`, not `0` — the miss leg is a literal
-    /// `1.0`, so "no state of its own" reads as on rather than off.
     #[test]
     fn a_row_without_a_state_variable_reads_one() {
         let states = WorldStates::default();
@@ -368,7 +300,6 @@ mod tests {
         assert_eq!(resolve(&with_state, &states).ui_state, 1);
     }
 
-    /// The extended-UI ids are answered as resolved *values*, not as the ids the DBC holds.
     #[test]
     fn the_extended_ui_ids_are_resolved_to_values() {
         let mut states = WorldStates::default();
@@ -379,10 +310,7 @@ mod tests {
         assert_eq!(resolve(&r, &states).extended_ui_state, [42, 7, 0]);
     }
 
-    /// The whole join, against the REAL table: in Eastern Plaguelands, with the zone-defense
-    /// channel joined and the server's tower counts in, the readout is the two labelled tower rows
-    /// plus the capture-point progress row — and without the channel it is empty. Skips without
-    /// client data.
+    /// Against the install's table: Eastern Plaguelands with and without the defense channel.
     #[test]
     fn the_real_table_builds_the_eastern_plaguelands_readout() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -417,18 +345,17 @@ mod tests {
         assert_eq!(rows[2].extended_ui_state, [60, 40, 0]);
         assert_eq!(rows[2].ui_state, 1, "state 2426 reads 1");
 
-        // The server flips a tower: the same rows, new numbers, no rebuild needed.
+        // The server flips a tower.
         states.write(&[(2327, 2), (2328, 2)]);
         let rows = build(&catalog, &states, true);
         assert_eq!(rows[0].text, "Towers Controlled: 2");
         assert_eq!(rows[1].text, "Towers Controlled: 2");
 
-        // Elsewhere on the same continent, nothing — the area gate.
         let mut elsewhere = WorldStates::default();
         elsewhere.init_scope(0, 12); // Elwynn Forest
         assert!(build(&catalog, &elsewhere, true).is_empty());
 
-        // Warsong Gulch: Type 0, so no channel needed, and its rows carry the dynamic flag icons.
+        // Warsong Gulch: `Type` 0, with dynamic flag icons.
         let mut wsg = WorldStates::default();
         wsg.init_scope(489, 0);
         wsg.write(&[(1581, 2), (1582, 1), (1601, 3), (2339, 1)]);
@@ -444,12 +371,8 @@ mod tests {
         assert_eq!(rows[1].ui_state, 0, "state 2338 — the Alliance flag is not");
     }
 
-    /// The `Type == 1` gate is only worth building if the channel it waits on is one the client
-    /// actually joins — otherwise the whole Eastern Plaguelands readout ships dead. Against the
-    /// real `ChatChannels.dbc`: exactly one row carries both `ZONE_DEP` and `DEFENSE`, it is
-    /// `LocalDefense - %s`, and it is an auto-join row. `WorldDefense` is the control that could
-    /// have made this pass for the wrong reason — it carries `DEFENSE` without `ZONE_DEP`, and
-    /// must not open the gate. Skips without client data.
+    /// Against the install's `ChatChannels.dbc`: the one qualifying row is auto-joined, and
+    /// `WorldDefense` (`DEFENSE` without `ZONE_DEP`) is the control.
     #[test]
     fn the_gates_channel_is_one_the_client_joins_by_itself() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -486,8 +409,7 @@ mod tests {
         );
     }
 
-    /// An init CLEARS the table (the C2 correction): a state received in the previous zone must
-    /// not still read through after the server re-scopes us.
+    /// An init clears the table.
     #[test]
     fn an_init_forgets_the_previous_zone() {
         let mut states = WorldStates::default();
diff --git a/crates/benilla-app/tests/auction_frame.rs b/crates/benilla-app/tests/auction_frame.rs
index 207a0faf..0f0e3c06 100644
--- a/crates/benilla-app/tests/auction_frame.rs
+++ b/crates/benilla-app/tests/auction_frame.rs
@@ -1,11 +1,5 @@
-//! Drives the reference's own `Blizzard_AuctionUI` addon through the engine (decision 1511; 1971
-//! put it on the player's chain) — the auction
-//! twin of `mail_frame.rs`: it loads the same file chain the app does (cut to the auction window's
-//! dependency prefix), pushes a synthetic `AuctionState`, opens the window with the app's own
-//! `AUCTION_HOUSE_SHOW`/`AUCTION_ITEM_LIST_UPDATE` events, and asserts the transcribed Lua actually
-//! paints — the named regions exist, the Browse rows populate from the fed snapshot, a row past the
-//! batch is hidden, and the bid/buyout gates open for an affordable row and stay shut for one the
-//! player cannot pay for.
+//! Drives the stock `Blizzard_AuctionUI` addon off the player's chain with a synthetic
+//! `AuctionState` and the app's own show and list events, and asserts what it paints and queues.
 
 use benilla_ui::script::{
     AuctionCategory, AuctionItemRow, AuctionListState, AuctionState, AuctionSubCategory, UiScript,
@@ -14,49 +8,40 @@ use benilla_ui::script::{
 
 mod common;
 
-/// The auction window's load prefix — the app's own order (`assets/ui/benilla.toc`), members only.
-/// Every one of these is a real dependency: UiPanels for the panel manager + tab kit + StaticPopup
-/// engine, ScrollTemplates for the faux lists, UIPanelTemplates for the button/input/checkbox
-/// templates, UIDropDownMenu for the rarity capsule, MoneyFrame for `SmallMoneyFrameTemplate` +
-/// the `MoneyTypeInfo` table this window registers `AUCTION_DEPOSIT` into, The `MoneyInputFrame_*` money-entry
-/// helpers used to mean loading MerchantFrame.xml as well; 1751 moved that kit to MoneyFrame.xml
-/// on its way to the chain, so the dependency is gone.
+/// The auction window's load prefix, in the app's order (`assets/ui/benilla.toc`): UIParent for
+/// `ShowUIPanel`, UIPanelTemplates for the tab kit and widget templates, StaticPopup for the
+/// dialogs, MoneyFrame for `SmallMoneyFrameTemplate` and `MoneyTypeInfo`, MoneyInputFrame for
+/// the price entry, UIDropDownMenu for the rarity menu, ScrollTemplates for the faux lists.
 const FILES: &[&str] = &[
     "Interface\\FrameXML\\Fonts.xml",
     r"Interface\FrameXML\MoneyFrame.lua",
     r"Interface\FrameXML\MoneyFrame.xml",
-    // The four money-entry frames come off the chain since 1882 — `MoneyInputFrameTemplate` and
-    // the `MoneyInputFrame_*` verbs, replacing our own verbatim copy of both.
+    // `MoneyInputFrameTemplate` and the `MoneyInputFrame_*` verbs.
     r"Interface\FrameXML\MoneyInputFrame.lua",
     r"Interface\FrameXML\MoneyInputFrame.xml",
     r"Interface\FrameXML\UIParent.xml",
-    // `auctionRowName` colours each row from ITEM_QUALITY_COLORS, whose declarer is
-    // UIParent (ref UIParent.lua:65) since 1888 put the font registry on the chain.
+    // UIParent declares `ITEM_QUALITY_COLORS` (`UIParent.lua:65`), which colours each row name.
     "Interface\\FrameXML\\GameTooltip.xml",
     "Interface\\FrameXML\\UIDropDownMenu.xml",
     "ScrollTemplates.xml",
     r"Interface\FrameXML\UIPanelTemplates.lua",
     r"Interface\FrameXML\UIPanelTemplates.xml",
-    // `AuctionTabTemplate` inherits `CharacterFrameTabButtonTemplate`, and `inherits=`
-    // resolves at LOAD (1993).
+    // `AuctionTabTemplate` inherits `CharacterFrameTabButtonTemplate`; `inherits=` resolves at
+    // load, so it comes first.
     r"Interface\FrameXML\CharacterFrameTemplates.xml",
     "Interface\\FrameXML\\GlobalStrings.lua",
     "Interface\\FrameXML\\BasicControls.xml",
     "Interface\\FrameXML\\LocaleProperties.lua",
-    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine (1960)
-    // The reference's own addon (1971), its toc order: the window (which <Include>s its
-    // templates) and the embedded dress-up pane. An integration test has no addon registry, so
-    // the files load as chain files, the way the manifest's own entries do.
-    // The embedded dress-up pane's OnLoad calls the dressing room's own `DressUpTexturePath`
-    // (stock DressUpFrame.lua, on the chain since 1969) — the manifest seats that window above.
+    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine
+    // The dress-up pane's OnLoad calls `DressUpTexturePath` (`DressUpFrame.lua`).
     "Interface\\FrameXML\\DressUpFrame.xml",
+    // The addon in its toc order, loaded as chain files: a test has no addon registry.
     "Interface\\AddOns\\Blizzard_AuctionUI\\Blizzard_AuctionUI.xml",
     "Interface\\AddOns\\Blizzard_AuctionUI\\Blizzard_AuctionDressUp.xml",
 ];
 
-/// [`load_ui`] with the Browse tab's class tree seated first: the stock addon reads
-/// `GetAuctionItemClasses()` at its LOAD (`AuctionFrameBrowse_OnLoad`), before any session, so
-/// the classes are login-scoped and must be there before the files are (1971).
+/// [`load_ui`] with the class tree seated first: `AuctionFrameBrowse_OnLoad` reads
+/// `GetAuctionItemClasses()` at load, before any session.
 fn load_ui_with_classes(s: &mut UiScript) {
     s.set_auction_item_classes(vec![AuctionCategory {
         class_id: 4,
@@ -72,9 +57,8 @@ fn load_ui_with_classes(s: &mut UiScript) {
 }
 
 fn load_ui(script: &UiScript) {
-    // `common::load_ui`, not a local read: a manifest entry carrying a path separator is the
-    // REFERENCE's own file and has to come off the player's chain, which `std::fs::read` under
-    // `assets/ui` cannot do. This kit gained such an entry when the dropdown migrated (1751).
+    // `common::load_ui`: an entry with a path separator is a stock file read off the player's
+    // chain, not from `assets/ui`.
     for file in FILES {
         common::load_ui(script, file);
     }
@@ -102,11 +86,8 @@ fn row(name: &str, min_bid: u32, buyout: u32, bid: u32, owner: &str) -> AuctionI
     }
 }
 
-/// A session snapshot: `rows` on the Browse list, nothing on the other two, one category.
-///
-/// Each row gets a DISTINCT `auction_id` here, standing in for the app's own resolve: the engine
-/// remembers a selection by wire id rather than by row position (auction.rs), so rows sharing an id
-/// would all resolve back to the first of them.
+/// A session snapshot: `rows` on the Browse list, nothing on the other two.
+/// Each row gets a distinct `auction_id`: the engine remembers a selection by wire id, not row.
 fn state(mut rows: Vec<AuctionItemRow>) -> AuctionState {
     for (i, r) in rows.iter_mut().enumerate() {
         r.auction_id = i as u32 + 1;
@@ -126,8 +107,7 @@ fn state(mut rows: Vec<AuctionItemRow>) -> AuctionState {
     }
 }
 
-/// The player: a name (the Browse bid gate compares it against the row's owner), a level (the row
-/// level colours off it) and a purse.
+/// The player: a name (the bid gate compares it to the owner), a level and a purse.
 fn seat_player(s: &mut UiScript, money: u64) {
     s.set_unit(
         "player",
@@ -186,8 +166,7 @@ fn auction_frame_loads_and_key_regions_exist() {
     assert!(s.errors().is_empty(), "load errors: {:?}", s.errors());
 }
 
-/// The window is registered `doublewide`, which is the one row of its kind in all of 1.12 — without
-/// it ShowUIPanel takes its unregistered branch and the window flips `IsShown()` without landing.
+/// `doublewide` is the only such `UIPanelWindows` row in 1.12 (`Blizzard_AuctionUI.lua:14`).
 #[test]
 fn the_window_is_registered_doublewide() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -257,21 +236,9 @@ fn auction_house_show_opens_the_window_on_the_browse_tab() {
     assert!(s.errors().is_empty(), "clean open: {:?}", s.errors());
 }
 
-/// **The bug the per-list fires were made for** (decision 2308), in the stock addon's own Lua.
-///
-/// `AuctionFrameAuctions_Update` computes `offset + i + (NUM_AUCTION_ITEMS_PER_PAGE *
-/// AuctionFrameAuctions.page)` on its very first line of loop body, and `AuctionFrameAuctions.page`
-/// is assigned in exactly one place in the whole addon: that tab's `OnShow`, three lines below its
-/// `GetOwnerAuctionItems()`. So the event is only safe to fire *after* the Auctions tab has been
-/// shown at least once — which the reference guarantees structurally, because every caller of
-/// `GetOwnerAuctionItems` lives *inside* that pane (the `OnShow`, and the two page-turner buttons,
-/// which pass `AuctionFrameAuctions.page` as their argument).
-///
-/// The feed used to fire all three list events on any change, so the first browse result of the
-/// session ran this repaint on a tab nobody had opened and put
-/// `attempt to perform arithmetic on field 'page' (a nil value)` on the player's screen. This test
-/// is the hazard itself, pinned: it fails the day the stock Lua stops caring, and `ui_auction`'s
-/// own `a_result_owes_only_its_own_lists_event` is the guarantee that we never hand it that event.
+/// `AuctionFrameAuctions_Update` does arithmetic on `AuctionFrameAuctions.page`, which only that
+/// pane's `OnShow` assigns, so `AUCTION_OWNED_LIST_UPDATE` is safe only once the tab has shown.
+/// The reference never sends it earlier: every `GetOwnerAuctionItems` caller lives in that pane.
 #[test]
 fn the_auctions_tab_cannot_repaint_before_it_has_been_shown() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -286,7 +253,7 @@ fn the_auctions_tab_cannot_repaint_before_it_has_been_shown() {
         "Seller",
     )])));
 
-    // Open, and land a browse result — the whole of what a search does. Clean.
+    // Open, and land a browse result: the whole of a search.
     s.fire_event("AUCTION_HOUSE_SHOW", vec![]);
     s.fire_event("AUCTION_ITEM_LIST_UPDATE", vec![]);
     assert!(
@@ -294,8 +261,7 @@ fn the_auctions_tab_cannot_repaint_before_it_has_been_shown() {
         "a browse result on the Browse tab is clean"
     );
 
-    // The same result also announcing the *owned* list is what crashed: the Auctions tab has never
-    // been shown, so its `page` is nil and the repaint does arithmetic on it.
+    // The owned-list event before the Auctions tab has shown: its `page` is nil.
     s.fire_event("AUCTION_OWNED_LIST_UPDATE", vec![]);
     let errors = s.take_errors();
     assert!(
@@ -303,8 +269,7 @@ fn the_auctions_tab_cannot_repaint_before_it_has_been_shown() {
         "the never-shown Auctions tab raises the nil-page error: {errors:?}"
     );
 
-    // And the same event is harmless the moment the tab has been shown once — which is the only
-    // state the app can now produce it in, since the owned list is only ever asked for from there.
+    // Harmless once the tab has shown, the only state the app sends it in.
     s.run("AuctionFrameTab_OnClick(3)").unwrap();
     assert!(s.take_errors().is_empty(), "opening the tab is clean");
     s.fire_event("AUCTION_OWNED_LIST_UPDATE", vec![]);
@@ -314,19 +279,9 @@ fn the_auctions_tab_cannot_repaint_before_it_has_been_shown() {
     );
 }
 
-/// Why only the Auctions tab was in the screenshot — and why that is an accident of the XML.
-///
-/// All three panes read their `page` field in `_Update`, and each assigns it in exactly one place:
-/// its own `OnShow`. What differs is *when* that `OnShow` first runs, and it is decided by one
-/// attribute in the stock file — `AuctionFrameBrowse` and `AuctionFrameAuctions` are declared
-/// `hidden="true"`, `AuctionFrameBid` is declared **`hidden="false"`**. So the Bids pane becomes
-/// visible with the window itself, its `OnShow` runs on the very first `AUCTION_HOUSE_SHOW` —
-/// before `AuctionFrameTab_OnClick(1)` hides it again — and `AuctionFrameBid.page` is `0` while
-/// the player is still looking at Browse. The Auctions pane gets nothing at all until tab 3.
-///
-/// That is the whole reason a mis-aimed `AUCTION_OWNED_LIST_UPDATE` crashed and a mis-aimed
-/// `AUCTION_BIDDER_LIST_UPDATE` did not — and the reason the fix is the rule (an event names one
-/// list) rather than a guard on the one tab that happened to be reported.
+/// Each pane assigns `page` only in its `OnShow`. `AuctionFrameBid` alone is declared
+/// `hidden="false"` (`Blizzard_AuctionUI.xml:960`), so it shows with the window on the first
+/// `AUCTION_HOUSE_SHOW` before tab 1 hides it; the Auctions pane has no `page` until tab 3.
 #[test]
 fn only_the_bids_pane_gets_its_page_without_being_opened() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -347,8 +302,8 @@ fn only_the_bids_pane_gets_its_page_without_being_opened() {
         assert_eq!(page(&s, pane), "nil", "{pane} before the window opens");
     }
 
-    // The window opens on tab 1. Browse is shown by the tab click; Bid is shown by the window
-    // itself and hidden again a moment later, keeping the page its OnShow assigned.
+    // Browse is shown by the tab click; Bid is shown with the window and hidden again, keeping
+    // the page its OnShow assigned.
     seat_player(&mut s, 500_000);
     s.set_auction(Some(state(vec![row(
         "Linen Cloth",
@@ -376,23 +331,10 @@ fn only_the_bids_pane_gets_its_page_without_being_opened() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The show cascade, against the reference's own order — the mechanism the Bids pane's `page`
-/// rests on, checked rather than assumed. **Every outcome matches; the order does not** (2317).
-///
-/// The reference's `0x76ae10` is **post-order**: a frame marks itself visible (`0x76ae7b`), walks
-/// its children, and fires its **own** `OnShow` last (`0x76aef5`, past both child loops), with no
-/// snapshot anywhere — each loop re-reads the live links, so a `Hide()` issued from a sibling's
-/// handler suppresses a later sibling by clearing its shown flag before the walk reaches it.
-///
-/// benilla fires the parent's own handler **first** and still notifies the descendant the parent's
-/// handler just hid. For this window the two routes land on the same state, which is why the
-/// assertions below are the reference's outcomes and only the order line is ours: the
-/// `hidden="false"` Bids pane gets exactly one `OnShow`, on the first open, taking the `page` its
-/// repaint needs and sending the one `GetBidderAuctionItems()` that pane's handler owes — and the
-/// reopen notifies neither, because the tab click left its own shown flag clear.
-///
-/// If the cascade is ever made post-order, the `ShowOrder` assertions are what should change here;
-/// nothing else in this test should have to.
+/// The reference's show cascade `0x76ae10` is post-order: a frame marks itself visible
+/// (`0x76ae7b`), walks its children re-reading live links, and fires its own `OnShow` last
+/// (`0x76aef5`). benilla's is pre-order, a gap in the engine; for this window both orders reach
+/// the same state, so only the `ShowOrder` assertions are benilla's order.
 #[test]
 fn the_show_cascade_notifies_the_bids_pane_once_and_keeps_its_page() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -407,8 +349,8 @@ fn the_show_cascade_notifies_the_bids_pane_once_and_keeps_its_page() {
         "Seller",
     )])));
 
-    // Both handlers are called by global name from their `<OnShow>`, so wrapping the globals
-    // records the order the cascade actually fired them in.
+    // Both `<OnShow>`s call their handler by global name, so wrapping the globals records the
+    // order.
     s.run(
         "ShowOrder = {}          local pane, window = AuctionFrameBid_OnShow, AuctionFrame_OnShow          AuctionFrameBid_OnShow = function() table.insert(ShowOrder, \"pane\") pane() end          AuctionFrame_OnShow = function() table.insert(ShowOrder, \"window\") window() end",
     )
@@ -440,8 +382,7 @@ fn the_show_cascade_notifies_the_bids_pane_once_and_keeps_its_page() {
         "and that OnShow is what asks for the bids list"
     );
 
-    // Close and reopen. The tab click left the pane's own shown flag clear, so it is skipped:
-    // the page is kept from the first open rather than re-assigned, and nothing new goes out.
+    // Reopen: the tab click left the pane's shown flag clear, so it is skipped and keeps its page.
     s.run("HideUIPanel(AuctionFrame)").unwrap();
     let _ = s.take_auction_close();
     s.fire_event("AUCTION_HOUSE_SHOW", vec![]);
@@ -459,7 +400,7 @@ fn the_show_cascade_notifies_the_bids_pane_once_and_keeps_its_page() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The part that proves it works: a fed snapshot paints the Browse rows.
+/// A fed snapshot paints the Browse rows.
 #[test]
 fn the_browse_list_populates_from_the_fed_snapshot() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -491,7 +432,7 @@ fn the_browse_list_populates_from_the_fed_snapshot() {
             .unwrap(),
         "Wool Cloth"
     );
-    // The seller column shows the OWNER (the reference's `HighBidder` region name notwithstanding).
+    // The `HighBidder` region shows the owner.
     assert_eq!(
         s.eval::<String>("return BrowseButton1HighBidder:GetText()")
             .unwrap(),
@@ -511,11 +452,7 @@ fn the_browse_list_populates_from_the_fed_snapshot() {
         "25",
         "a bid-on row paints the live bid, not the minimum"
     );
-    // …and the ZERO coins below it stay on. This is the `MoneyTypeInfo["AUCTION"]` collapse rule
-    // — `showSmallerCoins`, which drops only the LEADING zeros — and it is the whole reason this
-    // window is laid out on `SmallMoneyFrameTemplate` rather than the three-slot kit the rest of
-    // benilla uses: that kit drops every zero denomination, so 10s 0c read as a lone "10 🥈" and a
-    // 1g buyout as a lone "1 🥇" (director's report, 2026-08-22).
+    // `MoneyTypeInfo["AUCTION"]` sets `showSmallerCoins`: only leading zero coins collapse.
     assert!(
         !s.eval::<bool>("return BrowseButton1MoneyFrameGoldButton:IsShown()")
             .unwrap(),
@@ -542,8 +479,7 @@ fn the_browse_list_populates_from_the_fed_snapshot() {
     assert!(s
         .eval::<bool>("return BrowseButton1ItemCount:IsShown()")
         .unwrap());
-    // The closing-time bucket resolved to a row word plus a hover detail (both GlobalStrings, so
-    // both are blank without the string table — what matters is that the tooltip field is set).
+    // The closing-time bucket sets a hover tooltip (its GlobalStrings text may be blank here).
     assert!(s
         .eval::<bool>("return BrowseButton1ClosingTime.tooltip ~= nil")
         .unwrap());
@@ -558,14 +494,13 @@ fn the_browse_list_populates_from_the_fed_snapshot() {
     assert!(s.errors().is_empty(), "clean repaint: {:?}", s.errors());
 }
 
-/// The bid/buyout gates: both start shut on every repaint and open only for the SELECTED row, and
-/// only when the purse can actually cover it.
+/// The bid and buyout gates open only for the selected row, and only when the purse covers it.
 #[test]
 fn the_bid_and_buyout_gates_read_the_purse() {
     let _data = benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     load_ui_with_classes(&mut s);
-    // 2 gold. Row 1 costs 10s to bid and 50s to buy out — affordable. Row 2 wants 5 gold.
+    // 2 gold. Row 1 costs 10s to bid and 50s to buy out; row 2 wants 5 gold.
     seat_player(&mut s, 20_000);
     s.set_auction(Some(state(vec![
         row("Linen Cloth", 1000, 5000, 0, "Seller"),
@@ -642,8 +577,7 @@ fn the_bid_and_buyout_gates_read_the_purse() {
     assert!(s.errors().is_empty(), "clean gating: {:?}", s.errors());
 }
 
-/// You cannot bid on your own auction, however much money you have — the one leg of the Browse gate
-/// that is not about affordability.
+/// The one leg of the Browse bid gate that is not about money.
 #[test]
 fn you_cannot_bid_on_your_own_auction() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -666,15 +600,14 @@ fn you_cannot_bid_on_your_own_auction() {
             .unwrap(),
         "the row's owner is the player"
     );
-    // The buyout gate has no such leg — the reference lets you buy out your own listing.
+    // The buyout gate has no such leg: the reference lets you buy out your own listing.
     assert!(s
         .eval::<bool>("return BrowseBuyoutButton:IsEnabled() ~= 0")
         .unwrap());
     assert!(s.errors().is_empty());
 }
 
-/// A search reads every filter at once, and nothing before the button is pressed: typing a name,
-/// setting a level band and clicking a class row queue no query at all until Search fires.
+/// A search reads every filter at once; nothing before Search queues a query.
 #[test]
 fn search_reads_the_filters_and_nothing_queries_before_it() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -693,7 +626,7 @@ fn search_reads_the_filters_and_nothing_queries_before_it() {
             .unwrap(),
         "Armor"
     );
-    // Clicking it expands the subclass beneath it and queries NOTHING.
+    // Clicking it expands the subclass beneath it and queries nothing.
     s.run("AuctionFilterButton1:Click()").unwrap();
     assert!(
         s.eval::<String>("return AuctionFilterButton2:GetText()")
@@ -717,7 +650,7 @@ fn search_reads_the_filters_and_nothing_queries_before_it() {
     assert_eq!(query.name, "linen");
     assert_eq!(query.min_level, 10);
     assert_eq!(query.max_level, 20);
-    // The stock Lua hands over the class row's POSITION (1); the wire carries its item class id.
+    // The stock Lua hands over the class row's position (1); the wire carries its item class id.
     assert_eq!(
         query.class,
         Some(4),
@@ -728,8 +661,8 @@ fn search_reads_the_filters_and_nothing_queries_before_it() {
     assert!(s.errors().is_empty(), "clean search: {:?}", s.errors());
 }
 
-/// The create form's gate, and the two triggers that move the deposit. The deposit is the client's
-/// own arithmetic over the stack's vendor value and the RUN TIME — never over what you ask for.
+/// The create form's gate and the deposit, which the client computes from the stack's vendor
+/// value and the run time, never the asking price.
 #[test]
 fn the_create_gate_and_the_deposit() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -765,7 +698,7 @@ fn the_create_gate_and_the_deposit() {
         1440
     );
 
-    // With no item, the form does not even reach the price checks — the buyout error stays hidden.
+    // With no item the form never reaches the price checks: the buyout error stays hidden.
     s.run("MoneyInputFrame_SetCopper(StartPrice, 10000)")
         .unwrap();
     s.run("MoneyInputFrame_SetCopper(BuyoutPrice, 5000)")
@@ -778,8 +711,8 @@ fn the_create_gate_and_the_deposit() {
         .eval::<bool>("return AuctionsBuyoutErrorText:IsShown()")
         .unwrap());
 
-    // Now put something in the slot, through the real cursor path: pick a bag item up and click
-    // the slot, which is `ClickAuctionSellItemButton` exactly as a drag or a drop would be.
+    // Fill the slot through the cursor: pick a bag item up and click the slot
+    // (`ClickAuctionSellItemButton`, as a drop would).
     s.set_container(
         0,
         Some(benilla_ui::script::ContainerState {
@@ -806,16 +739,11 @@ fn the_create_gate_and_the_deposit() {
             ..Default::default()
         },
     );
-    // A SPLIT pickup, deliberately. A whole-stack `PickupContainerItem` records `count: None`
-    // ("None = the whole stack", cursor.rs), and `GetAuctionSellItemInfo` then answers a count of
-    // ONE for it — so the slot would show no stack count and the deposit would be computed on a
-    // single unit. That is an ENGINE gap in `script/auction.rs`'s `sell_item_info`, not this
-    // window's: the window shows the count whenever the API reports more than one, which is what
-    // this exercises.
+    // A split pickup: after a whole-stack pickup (`count: None`) `GetAuctionSellItemInfo`
+    // answers a count of 1, an engine gap in `script/auction.rs`'s `sell_item_info`.
     s.run("SplitContainerItem(0, 1, 2)").unwrap();
     s.run("AuctionsItemButton:Click()").unwrap();
-    // The stock create pane paints the slot on NEW_AUCTION_UPDATE, which the app fires the frame
-    // the sell slot changes (`ui_auction`'s feed); a harness with no app fires it itself.
+    // The create pane paints on NEW_AUCTION_UPDATE, which the app fires when the slot changes.
     s.fire_event("NEW_AUCTION_UPDATE", vec![]);
     assert_eq!(
         s.eval::<String>("return AuctionsItemButtonName:GetText()")
@@ -832,14 +760,13 @@ fn the_create_gate_and_the_deposit() {
         .eval::<bool>("return AuctionsItemButtonCount:IsShown()")
         .unwrap());
 
-    // Dropping an item RESETS the form — the stock handler seeds the start price from the item's
-    // sell price and zeroes the buyout (`AuctionSellItemButton_OnEvent`) — so the prices are typed
-    // after the drop, as a player types them.
+    // A drop resets the form (`AuctionSellItemButton_OnEvent` seeds the start price and zeroes
+    // the buyout), so the prices are typed after it.
     s.run("MoneyInputFrame_SetCopper(StartPrice, 10000)")
         .unwrap();
     s.run("MoneyInputFrame_SetCopper(BuyoutPrice, 5000)")
         .unwrap();
-    // With an item in the slot, the buyout-under-start error is the one the form explains out loud.
+    // With an item in the slot, a buyout under the start price shows its error.
     s.run("AuctionsFrameAuctions_ValidateAuction()").unwrap();
     assert!(
         s.eval::<bool>("return AuctionsBuyoutErrorText:IsShown()")
@@ -858,9 +785,7 @@ fn the_create_gate_and_the_deposit() {
             .unwrap(),
         "an item, a 1g start price and no buyout is a valid auction"
     );
-    // The deposit is the CLIENT's own arithmetic (auction.rs §7): 5% of the carried stack's vendor
-    // value (2 x 25c = 50c) floors to 2c, and 24h is twelve two-hour units, so 24c. Two hours would
-    // be 2c — the duration is what moves this, never the asking price.
+    // 5% of the stack's vendor value (2 x 25c = 50c) floors to 2c, per two-hour unit: 24h is 24c.
     assert_eq!(
         s.eval::<i64>("return CalculateAuctionDeposit(1440)")
             .unwrap(),
@@ -908,9 +833,8 @@ fn hiding_the_window_closes_the_session() {
     assert!(s.errors().is_empty(), "clean close: {:?}", s.errors());
 }
 
-/// Paging: with more matches than the server's 50-row page, the turners appear only when the bar is
-/// at the very bottom, and the list is fed one extra row so the bar can travel there. A 50-row
-/// batch out of 120 fills all 8 slots, so the turners stay hidden until the list is scrolled down.
+/// With more matches than the 50-row page, the turners appear only with the list scrolled to the
+/// bottom; the list is fed one extra row so the bar can get there.
 #[test]
 fn paging_shows_the_turners_only_at_the_end_of_the_list() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -933,8 +857,7 @@ fn paging_shows_the_turners_only_at_the_end_of_the_list() {
         "at the top of a full page the turners stay out of the way"
     );
 
-    // Scroll to the very bottom. The list was fed 51 rows for 8 slots, so the last offset is 43 —
-    // which leaves row slot 8 empty and reveals the turners.
+    // 51 rows over 8 slots: offset 43 leaves slot 8 empty, which reveals the turners.
     s.run("FauxScrollFrame_SetOffset(BrowseScrollFrame, 43)")
         .unwrap();
     s.run("AuctionFrameBrowse_Update()").unwrap();
@@ -961,12 +884,8 @@ fn paging_shows_the_turners_only_at_the_end_of_the_list() {
     assert!(s.errors().is_empty(), "clean paging: {:?}", s.errors());
 }
 
-/// The row and sell-slot hovers go through the reference's own tooltip verbs (decision 1511).
-///
-/// Both used `SetHyperlink` while `GameTooltip:SetAuctionItem` / `SetAuctionSellItem` had no
-/// bindings. The rendered tooltip was the same either way — what changes is that an addon hooking
-/// either verb now sees the call it expects, which is the whole point of shipping the reference's
-/// API surface rather than an equivalent one.
+/// The row and sell-slot hovers call `GameTooltip:SetAuctionItem` and `SetAuctionSellItem`, so an
+/// addon hooking either sees the call.
 #[test]
 fn a_row_hover_goes_through_the_reference_tooltip_verb() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -976,7 +895,7 @@ fn a_row_hover_goes_through_the_reference_tooltip_verb() {
     s.fire_event("AUCTION_HOUSE_SHOW", vec![]);
     s.fire_event("AUCTION_ITEM_LIST_UPDATE", vec![]);
 
-    // The verbs exist as tooltip methods at all — the thing that was missing.
+    // Both verbs are tooltip methods.
     assert!(
         s.eval::<bool>("return type(GameTooltip.SetAuctionItem) == 'function'")
             .unwrap(),
@@ -988,11 +907,8 @@ fn a_row_hover_goes_through_the_reference_tooltip_verb() {
         "SetAuctionSellItem is bound"
     );
 
-    // And the row hover drives one without erroring. The tooltip body itself depends on the item
-    // template store, which a bare harness has not been fed — the assertion here is the call path,
-    // not the rendered text.
-    // `this` is what the event dispatcher binds before it calls a handler; a direct call from a
-    // chunk has to bind it the same way or `SetOwner(this, ...)` gets a nil frame.
+    // The row hover runs clean; the harness has no item templates, so this checks the call path.
+    // A direct call binds `this` as the dispatcher would, or `SetOwner(this, ...)` gets nil.
     s.run("this = BrowseButton1Item AuctionFrameItem_OnEnter('list', 1)")
         .unwrap();
     assert!(
@@ -1000,8 +916,7 @@ fn a_row_hover_goes_through_the_reference_tooltip_verb() {
         "the row hover raised no script error"
     );
 
-    // An empty sell slot is a no-op rather than a throw, which is how the window's own OnEnter
-    // gate calls it.
+    // An empty sell slot is a no-op, not an error.
     s.run("GameTooltip:SetAuctionSellItem()").unwrap();
     assert!(s.take_errors().is_empty());
 }
diff --git a/crates/benilla-app/tests/character_stats.rs b/crates/benilla-app/tests/character_stats.rs
index 372ba71d..68a742f5 100644
--- a/crates/benilla-app/tests/character_stats.rs
+++ b/crates/benilla-app/tests/character_stats.rs
@@ -1,59 +1,31 @@
-//! Drives the REAL `Interface\FrameXML\PaperDollFrame.xml` stat rows through the engine — the
-//! first test that executes the paper doll's own `PaperDollFrame_Set*` Lua at all, and since
-//! decision 1751 that Lua is the reference's own rather than a transcription of it.
-//!
-//! That gap is why this file exists. The character sheet's whole buff-decomposition surface — the
-//! green number, the red number, the `(base +x -y)` tooltip — sat broken from the day it shipped
-//! (B165, B251) because the four `POSSTAT`/`NEGSTAT`/`RESISTANCEBUFFMODS*` descriptor arrays were
-//! decoded as f32 when the wire carries INT, so every real buff arrived as a rounded `0` and every
-//! row took its "nothing is modifying this" leg. Both gates were green throughout: the bindings'
-//! own unit tests fed the snapshot directly, and nothing ever ran the Lua that colours the row.
-//!
-//! So the assertions here are deliberately at the *rendered string*: what `CharacterStatFrameNStatText`
-//! and `MagicResTextN` actually carry after a repaint, colour escapes included. Three shapes per
-//! family — untouched (plain), buffed (green), debuffed (red) — plus the tooltip's base arithmetic,
-//! which is the guard for `UnitStat`'s first return being the RAW field rather than a pre-subtracted
-//! one (decision 1397: the ref Lua subtracts `posBuff`/`negBuff` itself, so a pre-subtracted first
-//! return deducts the buff twice — a defect the f32 bug was hiding).
+//! Drives the stock `PaperDollFrame.xml` stat rows through the engine and asserts the rendered
+//! strings, colour escapes included: untouched (plain), buffed (green) and debuffed (red), plus the
+//! tooltip's base, which the stock Lua computes by subtracting both buff halves from `UnitStat`'s
+//! raw first return.
 
 mod common;
 
 use benilla_ui::script::{UiScript, UnitCombatStats, UnitState};
 
-/// The paper doll's load prefix, in `assets/ui/benilla.toc` order.
-///
-/// **`CharacterFrame.xml` is deliberately not here.** These tests repaint the stat rows directly;
-/// they never open the window, and `PaperDollFrame`'s only tie to its container is a `parent=`
-/// name, which the loader warns about and falls back from. Pulling the container in would drag
-/// `CharacterFrame_OnLoad`'s four external dependencies (the unit frames, the XP bar,
-/// `TextStatusBar.lua`, the panel-tab kit — see `ui_script::test_ui::CHARACTER_UI`) into a test
-/// about arithmetic.
-///
-/// `GlobalStrings.lua` and `BasicControls.xml` are not scenery either: the stock file has no
-/// `X = X or "…"` fallbacks, and every row here formats a real string — `SPELL_STAT0_NAME`..`4`
-/// through `TEXT()` (`PaperDollFrame.lua:143`), `RESISTANCE<n>_NAME` and
-/// `RESISTANCE_TOOLTIP_SUBTEXT` (`:184`/`:224`), `ARMOR` and `ARMOR_TOOLTIP` (`:236`/`:249`).
+/// The paper doll's load prefix, in `assets/ui/benilla.toc` order. `CharacterFrame.xml` is left
+/// out: the rows are repainted directly and the window never opens. Every row formats a global
+/// string: `SPELL_STAT<n>_NAME` (`PaperDollFrame.lua:140`), `RESISTANCE<n>_NAME` and
+/// `RESISTANCE_TOOLTIP_SUBTEXT` (`:187`/`:226`), `ARMOR` and `ARMOR_TOOLTIP` (`:244`/`:249`).
 const FILES: &[&str] = &[
     "Interface\\FrameXML\\GlobalStrings.lua",
     "Interface\\FrameXML\\Fonts.xml",
     "Interface\\FrameXML\\BasicControls.xml",
-    // The reference's own since 1751 window 24 — `common::load_ui` speaks both stores.
     "Interface\\FrameXML\\ItemButtonTemplate.xml",
     r"Interface\FrameXML\MoneyFrame.lua",
     r"Interface\FrameXML\MoneyFrame.xml",
-    // `Model_OnLoad` — the model pane's `<OnLoad>` calls it, so this is a LOAD-time dependency of
-    // the paper doll, not of the window. The reference declares it in `UIParent.lua`; ours lives
-    // in our counterpart of that file.
+    // `Model_OnLoad` (`UIParent.lua:1421`), which the model pane's `<OnLoad>` calls at load.
     r"Interface\FrameXML\UIParent.xml",
     r"Interface\FrameXML\UIPanelTemplates.lua",
     r"Interface\FrameXML\UIPanelTemplates.xml",
     "Interface\\FrameXML\\LocaleProperties.lua",
-    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine (1960)
+    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine
     "Interface\\FrameXML\\GameTooltip.xml",
-    // `CooldownFrameTemplate` and `CooldownFrame_SetTimer`. Not scenery: every one of the 20 slot
-    // buttons runs `PaperDollItemSlotButton_Update` from its own OnLoad, which calls
-    // `CooldownFrame_SetTimer` on `$parentCooldown` unconditionally (`PaperDollFrame.lua:692`) —
-    // so leaving this out is 20 loader errors before the first assertion.
+    // Each slot button's OnLoad calls `CooldownFrame_SetTimer` (`PaperDollFrame.lua:692`).
     "Interface\\FrameXML\\Cooldown.xml",
     "Interface\\FrameXML\\PaperDollFrame.xml",
 ];
@@ -64,17 +36,13 @@ fn load_ui(script: &UiScript) {
     }
 }
 
-/// The two colour escapes the sheet writes, as `Fonts.xml` defines them — asserted against the
-/// rendered string rather than re-derived, so a palette change fails here loudly instead of
-/// silently agreeing with itself.
+/// The sheet's two colour escapes, as `Fonts.xml` defines them.
 const GREEN: &str = "|cff20ff20";
 const RED: &str = "|cffff2020";
 
-/// A level-60 body carrying one of each case: strength heavily geared (+105), agility cursed
-/// (−12), stamina untouched, and the same three shapes across the resistance schools. The negative
-/// halves are the wire words an **x86**-hosted server sends; an arm64 host saturates a debuff to a
-/// flat `0` on the way out (decision 1397), which is exactly why the red leg has to be exercised
-/// here and cannot be exercised against the local deploy.
+/// A level-60 body with a geared (+105), a cursed (−12) and an untouched stat, and the same three
+/// shapes across the resistances. The negative halves are what an x86-hosted server sends; an
+/// arm64 host saturates a debuff to 0.
 fn stats() -> UnitCombatStats {
     UnitCombatStats {
         stats: [225, 68, 178, 34, 51],
@@ -99,7 +67,7 @@ fn player() -> UnitState {
     }
 }
 
-/// Repaint the sheet the way an in-world `UNIT_STATS` does and read a row's rendered text back.
+/// Repaint the sheet as an in-world `UNIT_STATS` does.
 fn painted(script: &mut UiScript) {
     script
         .run("PaperDollFrame_SetStats() PaperDollFrame_SetResistances() PaperDollFrame_SetArmor()")
@@ -138,8 +106,7 @@ fn a_geared_stat_renders_green_and_its_tooltip_names_the_unbuffed_base() {
     let mut s = seated();
     painted(&mut s);
 
-    // Strength: 225 total off a 120 base, +105 from gear. Green number, and the tooltip's
-    // parenthesised base is the ONE subtraction the ref Lua performs (225 − 105 − 0 = 120).
+    // Strength 225 = 120 base + 105 gear; the stock Lua subtracts the buff once for the base.
     let text = text_of(&mut s, "CharacterStatFrame1StatText");
     assert!(
         text.starts_with(GREEN) && text.contains("225"),
@@ -168,15 +135,13 @@ fn a_debuffed_stat_renders_red_and_an_untouched_one_stays_plain() {
         agility.starts_with(RED) && agility.contains("68"),
         "a cursed agility must render red, got {agility:?}"
     );
-    // Stamina has neither half — the ref's `posBuff == 0 and negBuff == 0` leg: a bare number with
-    // no escape at all. This is the assertion the shipped bug would have PASSED, and it is here so
-    // a future over-correction that colours everything is caught.
+    // Stamina has neither half: the stock `posBuff == 0 and negBuff == 0` leg, no escape.
     let stamina = text_of(&mut s, "CharacterStatFrame3StatText");
     assert_eq!(
         stamina, "178",
         "an unmodified stat carries no colour escape at all"
     );
-    // Red wins over green when both halves are in play — the ref colours on `negBuff < 0` first.
+    // Red wins over green: the stock Lua tests `negBuff < 0` first.
     s.set_player_combat_stats(Some(UnitCombatStats {
         stat_pos: [105, 30, 0, 4, 0],
         ..stats()
@@ -195,12 +160,8 @@ fn resistance_rows_colour_by_which_half_is_bigger() {
     let mut s = seated();
     painted(&mut s);
 
-    // Resolve each row's school from the FRAME's own `id=`, never from a table: that is exactly
-    // what the reference's `PaperDollFrame_SetResistances` does (`UnitResistance("player",
-    // frame:GetID())`), and it means a row-order change cannot silently re-point these assertions.
-    // It used to read our deleted file's `BENILLA_MAGICRES_IDS`; the stock XML carries the same
-    // mapping on the frames themselves (`MagicResFrame1 id="6"` arcane, then 2..5 fire/nature/
-    // frost/shadow — `PaperDollFrame.xml:654-758`).
+    // A row's school is its frame's `id=`, as `PaperDollFrame_SetResistances` reads it:
+    // `MagicResFrame1` is 6 (arcane), then 2..5 (`PaperDollFrame.xml:654-738`).
     let row_of = |s: &mut UiScript, school: i64| -> usize {
         s.eval::<i64>(&format!(
             "for i = 1, NUM_RESISTANCE_TYPES do \
@@ -226,27 +187,14 @@ fn resistance_rows_colour_by_which_half_is_bigger() {
     );
 }
 
-/// **The melee block: the seven-value `UnitDamage` unpacked positionally by the reference's own
-/// Lua**, and the arithmetic it does with the last three.
-///
-/// The stat rows above pin `UnitStat`/`UnitResistance`/`UnitArmor`. This one pins the family
-/// decision 1793 warns about hardest, because its consumer is arithmetic rather than a lookup:
-/// `PaperDollFrame_SetDamage` destructures **seven** values and immediately divides by the
-/// seventh. One value short and `percent` is nil — `(minDamage / nil)` raises; one value long and
-/// every term after it is off by a slot and the numbers come out plausible and wrong. Asserting
-/// the rendered strings is what tells those two apart from correct.
-///
-/// The numbers below are the reference's own formula, not ours: `displayMin`/`displayMax` are the
-/// raw range floored/ceiled, while the TOOLTIP range is the same numbers with the multiplier
-/// divided out and the flat bonuses subtracted (`PaperDollFrame.lua:279-283`) — which is why
-/// "40 - 62" and "27 - 47" are both right and different.
+/// `PaperDollFrame_SetDamage` unpacks `UnitDamage`'s seven values by position and divides by the
+/// seventh. The row shows the raw range floored and ceiled; the tooltip range has the multiplier
+/// divided out and the flat bonuses subtracted (`PaperDollFrame.lua:295-299`).
 #[test]
 fn the_melee_block_unpacks_seven_values_and_does_the_references_arithmetic() {
     let _data = benilla_formats::wow_data_or_skip!();
     let mut s = seated();
-    // 40.5-61.5 at 2.6 s, +12/-3 flat and a x1.1 multiplier: every one of the seven slots is
-    // distinct and non-zero, so a slot read from the wrong position cannot coincide with the
-    // right answer.
+    // Every one of the seven slots is distinct and non-zero, so a misplaced slot cannot pass.
     s.set_player_combat_stats(Some(UnitCombatStats {
         main_attack_time_ms: 2600,
         min_damage: 40.5,
@@ -262,13 +210,12 @@ fn the_melee_block_unpacks_seven_values_and_does_the_references_arithmetic() {
     s.run("PaperDollFrame_SetDamage() PaperDollFrame_SetAttackPower()")
         .expect("the melee rows repaint");
 
-    // The ROW: the raw range, green because the bonuses are net positive.
+    // The row: the raw range, green because the bonuses are net positive.
     assert_eq!(
         text_of(&mut s, "CharacterDamageFrameStatText"),
         format!("{GREEN}40 - 62|r")
     );
-    // The TOOLTIP: the same range with the multiplier divided out and the flat bonuses removed,
-    // then each modifier appended in the reference's own order and colours.
+    // The tooltip: the base range, then each modifier in the stock order and colours.
     assert_eq!(
         tooltip_of_field(&mut s, "CharacterDamageFrame", "damage"),
         format!("27 - 47{GREEN} +12|r{RED} -3|r{GREEN} x110%|r")
@@ -280,14 +227,13 @@ fn the_melee_block_unpacks_seven_values_and_does_the_references_arithmetic() {
     // dps = fullDamage / speed, fullDamage = (base + pos + neg) * percent = 51.0.
     let dps: f64 = s.eval("return CharacterDamageFrame.dps").expect("the dps");
     assert!((dps - 51.0 / 2.6).abs() < 0.01, "got {dps}");
-    // No offhand weapon: the reference NILS the offhand speed, which is what its hover branches on.
+    // No offhand weapon: the offhand speed is nil, which the hover branches on.
     assert!(s
         .eval::<Option<f64>>("return CharacterDamageFrame.offhandAttackSpeed")
         .unwrap()
         .is_none());
 
-    // Attack power goes through `PaperDollFormatStat`, whose colour law is "red if anything is
-    // negative, green otherwise" — so a mixed pair is RED even though the net is positive.
+    // `PaperDollFormatStat` colours red if anything is negative, so a mixed pair is red.
     assert_eq!(
         text_of(&mut s, "CharacterAttackPowerFrameStatText"),
         format!("{RED}800|r")
@@ -298,8 +244,7 @@ fn the_melee_block_unpacks_seven_values_and_does_the_references_arithmetic() {
         "the AP tooltip names the effective, the base and the buff, got {ap_tip:?}"
     );
 
-    // The plain leg: no bonuses and no multiplier, so `totalBonus == 0` and the row carries no
-    // colour escape at all — the branch a wrong `percent` would silently take.
+    // No bonuses and no multiplier: `totalBonus == 0`, no colour escape.
     s.set_player_combat_stats(Some(UnitCombatStats {
         main_attack_time_ms: 2600,
         min_damage: 40.5,
@@ -311,12 +256,8 @@ fn the_melee_block_unpacks_seven_values_and_does_the_references_arithmetic() {
     assert_eq!(text_of(&mut s, "CharacterDamageFrameStatText"), "40 - 62");
 }
 
-/// **The ranged block with nothing in the ranged slot** — the `NOT_APPLICABLE` fallback all three
-/// ranged rows share, and the `PaperDollFrame.noRanged` latch that carries it between them.
-///
-/// It is the reachable state for eight of nine classes at level 1, and it is the branch that
-/// decides whether `PaperDollFrame_SetRangedDamage` unpacks `UnitRangedDamage`'s six values at
-/// all — so it has to be pinned before the numbers are worth anything.
+/// With the ranged slot empty, all three ranged rows read `NOT_APPLICABLE`, carried between them
+/// by the `PaperDollFrame.noRanged` latch (`PaperDollFrame.lua:436-441`).
 #[test]
 fn the_ranged_rows_fall_back_to_not_applicable_with_an_empty_ranged_slot() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -336,17 +277,14 @@ fn the_ranged_rows_fall_back_to_not_applicable_with_an_empty_ranged_slot() {
     ] {
         assert_eq!(text_of(&mut s, row), na, "{row}");
     }
-    // …and the hover has nothing to show, which is the guard
-    // `CharacterRangedDamageFrame_OnEnter` opens with.
+    // The guard `CharacterRangedDamageFrame_OnEnter` opens with.
     assert!(s
         .eval::<Option<String>>("return CharacterRangedDamageFrame.damage")
         .unwrap()
         .is_none());
 }
 
-/// Armor is the one row of this family the local server never decomposes — item armor lands in
-/// `UNIT_FIELD_RESISTANCES[0]` itself, not in the buff split — so its plain-number leg is the live
-/// shape and worth pinning as such.
+/// Item armor lands in `UNIT_FIELD_RESISTANCES[0]` itself, not in the buff split.
 #[test]
 fn armor_with_no_buff_split_renders_plain() {
     let _data = benilla_formats::wow_data_or_skip!();
diff --git a/crates/benilla-app/tests/common/mod.rs b/crates/benilla-app/tests/common/mod.rs
index 14ce592c..9a765afb 100644
--- a/crates/benilla-app/tests/common/mod.rs
+++ b/crates/benilla-app/tests/common/mod.rs
@@ -1,29 +1,13 @@
-//! **The integration tests' interface loader — one copy, both stores** (decision 1751).
-//!
-//! The in-crate sibling of `ui_script::test_ui::load_ui`, which integration tests cannot reach:
-//! they link this crate as a library, so its `#[cfg(test)]` items are not compiled for them. Each
-//! `tests/*.rs` therefore grew its own reader off `assets/ui`, and every one of them broke the
-//! first time a file it names became the reference's own.
-//!
-//! The rule is the manifest's, verbatim: **a bare filename is a file we ship, a path is the
-//! reference's own off the player's installed chain.** Our shipped tree is flat, so a separator
-//! decides, and nothing here needs to know which windows have migrated.
-//!
-//! The provider half matters as much as the loop. A sourced document pulls its Lua through its own
-//! `<Script file="X.lua"/>`, which the loader resolves against the *including document's*
-//! directory — `Interface\FrameXML\X.lua`, a chain path. A disk-only provider leaves every one of
-//! those globals nil and the failures land nowhere near the cause.
-//!
-//! **A chain entry needs client data**, so a test that names one opens with
-//! `benilla_formats::wow_data_or_skip!()`, like every other archive-backed test.
+//! The integration tests' interface loader: integration tests cannot reach
+//! `ui_script::test_ui::load_ui`, which is `#[cfg(test)]`. A bare filename is a file we ship
+//! under `assets/ui`, a path is the reference's own off the installed chain, and `<Script file>`
+//! includes resolve through the same provider. A test that names a chain entry opens with
+//! `benilla_formats::wow_data_or_skip!()`.
 
 use benilla_ui::script::UiScript;
 
-/// Load one manifest entry into `script`, panicking on any loader error.
-///
-/// A `.lua` entry is run as a chunk rather than parsed as a document — `GlobalStrings.lua` and
-/// `LocaleProperties.lua` are entries of that shape in the real manifest too. Bytes, not text: a
-/// chunk goes to Lua as it sits in the archive and only an XML parse decodes (1193).
+/// Load one manifest entry into `script`, panicking on any loader error. A `.lua` entry runs as a
+/// chunk of raw bytes, as `GlobalStrings.lua` does in the real manifest; only XML is decoded.
 pub fn load_ui(script: &UiScript, entry: &str) {
     let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("assets/ui");
     let chain = |req: &str| -> Option<Vec<u8>> {
@@ -65,11 +49,8 @@ pub fn load_ui(script: &UiScript, entry: &str) {
     }
 }
 
-/// The stock micro-button row's unguarded reads, stood in for on the row's first call — one copy
-/// per store, like the loader itself. `ui_script::test_ui::MICRO_BUTTON_STAND_INS` is the
-/// original and carries the why (decision 1987).
-/// The stock `UIParent.xml`'s unguarded callees, stood in for at load — see
-/// `ui_script::test_ui::UIPARENT_STAND_INS` (decision 1988).
+/// The stock `UIParent.xml`'s unguarded callees, stood in for at load; the copy of
+/// `ui_script::test_ui::UIPARENT_STAND_INS`.
 const UIPARENT_STAND_INS: &str = r#"
     -- Callees of the stock UIParent.xml's <OnUpdate> and of UIParent_OnEvent's arms that live in
     -- files a kit may stop short of, plus the bag verbs the stock ShowUIPanel calls and the two
@@ -164,6 +145,8 @@ const UIPARENT_STAND_INS: &str = r#"
     end
 "#;
 
+/// The stock micro-button row's unguarded reads, stood in for on the row's first call; the copy of
+/// `ui_script::test_ui::MICRO_BUTTON_STAND_INS`.
 const MICRO_BUTTON_STAND_INS: &str = r#"
     local real = UpdateMicroButtons
     function UpdateMicroButtons()
diff --git a/crates/benilla-app/tests/cover_input_wall.rs b/crates/benilla-app/tests/cover_input_wall.rs
index b8ae4502..51a756f4 100644
--- a/crates/benilla-app/tests/cover_input_wall.rs
+++ b/crates/benilla-app/tests/cover_input_wall.rs
@@ -1,33 +1,17 @@
-//! **The cover-input wall** — the loading screen's input rule, counted from source on every
-//! `cargo test`, so the swallow list can never quietly fall behind what the client actually reads.
+//! The cover-input wall: every input channel the workspace names must carry a verdict in
+//! [`VERDICTS`], because the loading cover (`loading_screen/input.rs`) swallows input at the source
+//! only for the channels it names.
 //!
-//! `loading_screen/input.rs` takes the whole input plane while the cover is up, at the source, in
-//! `PreUpdate`. That cut is what makes the rule survive a consumer nobody remembered — the world
-//! pick chain, which hovered units and changed the hardware cursor *through* the loading screen
-//! until the director noticed. But a source cut only covers the channels it names, and bevy has
-//! more channels than we currently read: touch, IME, gamepads, the trackpad gestures. The day
-//! someone reads one of those, the cover has to grow a line — and nothing in the compiler will say
-//! so.
-//!
-//! This is that "nothing". It scans every workspace source for the input channels the client
-//! reaches for and requires each to carry a **verdict** in [`VERDICTS`] below:
-//!
-//! - **`Swallowed`** — the cover empties it. Cross-checked: the name must literally appear in the
-//!   gate's own source, so the table cannot claim coverage the gate does not implement.
-//! - **`Open`** — deliberately *not* swallowed, with the reason written down. Window lifecycle is
-//!   the whole of this class today: a close request, a focus change and an occlusion change must
-//!   still land while a load is running.
-//! - **`Plumbing`** — a type, enum, plugin or system-set name that carries no player input at all.
-//!
-//! An unclassified name fails the test with the question it wants answered: *does the cover
-//! swallow this?* Answering it is one line here and, when the answer is yes, one line in the gate.
+//! - `Swallowed`: the cover empties it; the name must appear in the gate's source.
+//! - `Open`: deliberately not swallowed, with the reason.
+//! - `Plumbing`: a type, plugin or set name that carries no player input.
 
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 enum Verdict {
-    /// The cover empties this channel — see `loading_screen/input.rs`.
+    /// The cover empties this channel.
     Swallowed,
     /// Deliberately left open under the cover. The `&str` is the reason.
     Open(&'static str),
@@ -36,8 +20,8 @@ enum Verdict {
 }
 use Verdict::{Open, Plumbing, Swallowed};
 
-/// Every `bevy::input::…` / `bevy::window::…` leaf the workspace names, plus the prelude-sourced
-/// input items, each with its verdict. **The wall itself.**
+/// Every `bevy::input::…` / `bevy::window::…` leaf the workspace names, plus the prelude input
+/// items, each with its verdict.
 const VERDICTS: &[(&str, Verdict)] = &[
     // ── The channels the cover takes ────────────────────────────────────────────────────────
     ("ButtonInput", Swallowed),
@@ -48,8 +32,7 @@ const VERDICTS: &[(&str, Verdict)] = &[
     ("CursorMoved", Swallowed),
     ("AccumulatedMouseMotion", Swallowed),
     ("AccumulatedMouseScroll", Swallowed),
-    // The pointer position is a *field*, not a message; the cover blanks it, which is why every
-    // hit-test in the client goes quiet without knowing the cover exists.
+    // The pointer position is a field, not a message; the cover blanks it.
     ("cursor_position", Swallowed),
     ("physical_cursor_position", Swallowed),
     // ── Deliberately open under the cover ───────────────────────────────────────────────────
@@ -80,8 +63,7 @@ const VERDICTS: &[(&str, Verdict)] = &[
     ),
     // ── Not input at all ────────────────────────────────────────────────────────────────────
     ("ButtonState", Plumbing),
-    // The cursor OUTPUTS — the art and the grab mode benilla *writes*. Nothing arrives through
-    // them, so there is nothing for the cover to take.
+    // Cursor outputs benilla writes; nothing arrives through them.
     ("CursorGrabMode", Plumbing),
     ("CursorIcon", Plumbing),
     ("CustomCursor", Plumbing),
@@ -107,11 +89,10 @@ const VERDICTS: &[(&str, Verdict)] = &[
     ("WindowResolution", Plumbing),
 ];
 
-/// The gate's own source — the cross-check target for every `Swallowed` row.
+/// The gate's source, which every `Swallowed` row must name.
 const GATE: &str = "crates/benilla-app/src/loading_screen/input.rs";
 
-/// The prelude re-exports these, so a source can name them with no `bevy::input::` path in sight.
-/// Scanned for by bare identifier; anything matched still has to carry a verdict above.
+/// Prelude re-exports, scanned for by bare identifier since no `bevy::input::` path names them.
 const PRELUDE_INPUT_NAMES: &[&str] = &[
     "ButtonInput",
     "AccumulatedMouseMotion",
@@ -125,7 +106,7 @@ fn every_input_channel_the_client_reads_has_a_verdict_under_the_cover() {
     let root = workspace_root();
     let mut found: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
     for file in workspace_sources(&root) {
-        // The wall names every channel in its own prose; scanning it would only find itself.
+        // The wall names every channel itself.
         if file.ends_with("tests/cover_input_wall.rs") {
             continue;
         }
@@ -162,8 +143,7 @@ fn every_input_channel_the_client_reads_has_a_verdict_under_the_cover() {
             .join("\n")
     );
 
-    // A `Swallowed` verdict is a claim about the gate's source; hold it to it. (The reverse is not
-    // asserted: the gate may name a channel nothing reads yet — that is the cover being ahead.)
+    // A `Swallowed` row must be named by the gate; the gate may name channels nothing reads yet.
     let gate = std::fs::read_to_string(root.join(GATE)).expect("the gate's source");
     let unbacked: Vec<&str> = VERDICTS
         .iter()
@@ -175,8 +155,7 @@ fn every_input_channel_the_client_reads_has_a_verdict_under_the_cover() {
         "VERDICTS claims the cover swallows these, but {GATE} never names them: {unbacked:?}"
     );
 
-    // And the table itself must not rot: a row nothing in the workspace names any more is a row to
-    // delete, not to keep as decoration. (`Plumbing` rows are exempt — they exist to absorb noise.)
+    // A non-`Plumbing` row nothing names is stale.
     let stale: Vec<&str> = VERDICTS
         .iter()
         .filter(|(name, v)| *v != Plumbing && !found.contains_key(*name))
@@ -188,15 +167,15 @@ fn every_input_channel_the_client_reads_has_a_verdict_under_the_cover() {
     );
 }
 
-/// Every input-ish identifier `text` names: the leaf of any `bevy::input::…`/`bevy::window::…`
-/// path (grouped `use` braces expanded), plus the prelude-sourced names.
+/// Every input identifier `text` names: the leaf of any `bevy::input::…`/`bevy::window::…` path
+/// (grouped `use` braces expanded), plus the prelude names.
 fn input_names(text: &str) -> BTreeSet<String> {
     let mut out = BTreeSet::new();
     for prefix in ["bevy::input::", "bevy::window::"] {
         let mut rest = text;
         while let Some(at) = rest.find(prefix) {
             rest = &rest[at + prefix.len()..];
-            // `use bevy::input::mouse::{A, B};` — take the braced group whole.
+            // `use bevy::input::mouse::{A, B};`: take the braced group whole.
             let path: String = rest
                 .chars()
                 .take_while(|c| c.is_alphanumeric() || *c == '_' || *c == ':')
@@ -208,8 +187,7 @@ fn input_names(text: &str) -> BTreeSet<String> {
                 path.clone()
             };
             for item in leaf_source.split(',') {
-                // `keyboard::KeyboardInput`, `KeyCode::Space`, `self` → the first segment that is
-                // a type-shaped name (upper-case initial) wins; a module segment is skipped.
+                // The first segment with an upper-case initial wins; module segments are skipped.
                 if let Some(name) = item
                     .split("::")
                     .map(str::trim)
@@ -237,9 +215,7 @@ fn workspace_root() -> PathBuf {
         .to_path_buf()
 }
 
-/// Every `.rs` under each crate's `src/` and `examples/` — the client's own code. Test files are
-/// included on purpose: a test that reaches for a new input channel is still a signal that the
-/// channel exists, and the verdict costs one line.
+/// Every `.rs` under each crate's `src/`, `examples/` and `tests/`.
 fn workspace_sources(root: &Path) -> Vec<PathBuf> {
     let mut out = Vec::new();
     for crate_dir in std::fs::read_dir(root.join("crates"))
diff --git a/crates/benilla-app/tests/create_frame_template.rs b/crates/benilla-app/tests/create_frame_template.rs
index 98f088cf..27bfd1fc 100644
--- a/crates/benilla-app/tests/create_frame_template.rs
+++ b/crates/benilla-app/tests/create_frame_template.rs
@@ -1,45 +1,18 @@
-//! `CreateFrame`'s fourth argument against the **real** `assets/ui` templates — the corpus idiom,
-//! end to end.
-//!
-//! The unit tests for the runtime template path live in
-//! `benilla-ui/src/script/tests/create_frame_template.rs` and drive synthetic templates. This one
-//! exists because the thing an addon actually types is
-//!
-//! ```lua
-//! local tab = CreateFrame("Button", "MyTab", UIParent, "TabButtonTemplate")
-//! getglobal("MyTab".."Text"):SetText("Hi")
-//! ```
-//!
-//! against a template *we* wrote, loaded the way the client loads it — six hundred lines of real
-//! FrameXML above it, a font registry, an anchor graph — not a four-line fixture. Every assertion
-//! below is a global an addon would reach for.
+//! `CreateFrame`'s fourth argument against real FrameXML templates, loaded the way the client
+//! loads them: the addon idiom `CreateFrame("Button", "MyTab", UIParent, "TabButtonTemplate")`
+//! then `getglobal("MyTab".."Text")`.
 
 mod common;
 
 use benilla_ui::script::UiScript;
 
-/// The prefix of `benilla.toc`'s load order these templates need: the font registry, the panel kit,
-/// UIParent (the parent every addon passes), and the faux-scroll kit.
-///
-/// **Two of the templates under test are the REFERENCE's since 1860** — `FauxScrollFrameTemplate`
-/// and `TabButtonTemplate` were ours until the dead-copy sweep, and both now come off the player's
-/// chain from `Interface\FrameXML\UIPanelTemplates.xml`, seated below `UIParent.xml` exactly as
-/// the manifest seats it. So this list carries the chain pair and the loader below has to be able
-/// to READ a chain entry, which a disk-only provider under `assets/ui` cannot.
+/// The prefix of `benilla.toc`'s load order these templates need. `FauxScrollFrameTemplate` and
+/// `TabButtonTemplate` are the stock ones, from `UIPanelTemplates.xml` on the player's chain.
 const FILES: &[&str] = &[
     "Interface\\FrameXML\\Fonts.xml",
-    // A REGRESSION GUARD, not a dependency (1923). FadingFrame.xml's entire body is a single
-    // `<Script file="FadingFrame.lua"/>`, so it loads correctly ONLY if that relative reference
-    // resolves against the document's own directory. Load it through the path-less `loader::load`
-    // and the base is "", the ref stays bare, the provider misses, and the assert below fires —
-    // which is exactly what it did before this file passed the path.
-    //
-    // It is self-contained on BOTH axes, and both had to be checked: zero `inherits=`, AND its Lua
-    // has no file-scope statements at all — only function definitions. The first guard tried here
-    // was CombatFeedback.xml, which also has zero `inherits=` but whose Lua calls `TEXT()` at file
-    // scope (l.7); that global is BasicControls.xml's, so it needed a dependency after all.
-    // `UnitFrame.lua` fails the same way (`TEXT(MANA)`). Structural dependencies are not the only
-    // kind.
+    // A guard, not a dependency: its whole body is `<Script file="FadingFrame.lua"/>`, which loads
+    // only if resolved against the document's own directory. It has no `inherits=` and its Lua
+    // has no file-scope statements, so it needs nothing before it.
     "Interface\\FrameXML\\FadingFrame.xml",
     r"Interface\FrameXML\MoneyFrame.lua",
     r"Interface\FrameXML\MoneyFrame.xml",
@@ -49,7 +22,7 @@ const FILES: &[&str] = &[
     "Interface\\FrameXML\\GlobalStrings.lua",
     "Interface\\FrameXML\\BasicControls.xml", // `TEXT`, which StaticPopup.lua reads at file scope
     "Interface\\FrameXML\\LocaleProperties.lua",
-    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine (1960)
+    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine
     "ScrollTemplates.xml",
 ];
 
@@ -59,20 +32,15 @@ fn load_ui(script: &UiScript) {
     }
 }
 
-/// The line an addon writes, and the globals it reads on the next one.
-///
-/// `TabButtonTemplate` (`UIPanelTemplates.xml`) is a `<Button>` carrying a `<Size>`, six `<Layers>`
-/// slices, a `<ButtonText name="$parentText">`, a `<HighlightTexture
-/// name="$parentHighlightTexture">`, the three state fonts and an `<OnUpdate>` — i.e. every
-/// decoration pass at once. Instantiating it as `BenillaTemplateProbeTab` must publish
-/// `BenillaTemplateProbeTab*`, and must publish nothing named after the template.
+/// `TabButtonTemplate` (`UIPanelTemplates.xml:303`) exercises every decoration pass at once; an
+/// instance publishes its parts under its own name and nothing under the template's.
 #[test]
 fn a_real_template_reaches_an_addon_through_create_frame() {
     let _data = benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_ui(&s);
-    // Clear anything the UI load itself had to say; what follows is this call's alone.
+    // Clear what the UI load itself reported.
     let _ = s.take_warnings();
     let _ = s.take_errors();
 
@@ -81,11 +49,8 @@ fn a_real_template_reaches_an_addon_through_create_frame() {
     )
     .expect("the corpus idiom must not error");
 
-    // The template's authored `<Size>` is 115x32 in BOTH our retired copy and the reference's, but
-    // the reference's `<OnLoad>` calls `PanelTemplates_TabResize(0)` — it FITS the tab to its text
-    // on load, and a freshly created tab has none, so what survives is the two end caps. Ours left
-    // the fit to an OnUpdate settle (1004), which is why this used to read the pre-fit 115. The
-    // height is untouched by the fit and still the template's (1860).
+    // The authored `<Size>` is 115x32, but the `<OnLoad>` calls `PanelTemplates_TabResize(0)`
+    // (`UIPanelTemplates.xml:371`), fitting an empty tab to its end caps; the height is untouched.
     let (w, h) = s
         .eval::<(f32, f32)>("return ProbeTab:GetWidth(), ProbeTab:GetHeight()")
         .unwrap();
@@ -93,8 +58,7 @@ fn a_real_template_reaches_an_addon_through_create_frame() {
     let caps = s
         .eval::<f32>("return 2 * BenillaTemplateProbeTabLeft:GetWidth()")
         .unwrap();
-    // `caps` plus the empty label's one-unit floor (`FONTSTRING_MIN_SPAN`) — the point is that it
-    // collapsed to its end caps, nowhere near the authored 115.
+    // `caps` plus the empty label's one-unit floor (`FONTSTRING_MIN_SPAN`).
     assert!(
         w >= caps && w <= caps + 1.5,
         "an unlabelled tab fits down to its two end caps: {w} vs {caps}"
@@ -106,8 +70,7 @@ fn a_real_template_reaches_an_addon_through_create_frame() {
         "the parent argument, not the template's idea of one"
     );
 
-    // The globals an addon addresses the parts by — every one named against the INSTANCE. The
-    // reference's own kit does exactly this (`getglobal(tabName.."Text")` in PanelTemplates).
+    // The part globals, named for the instance, as `UIPanelTemplates.lua:42` reads them.
     for suffix in [
         "Text",             // <ButtonText name="$parentText">
         "HighlightTexture", // <HighlightTexture name="$parentHighlightTexture">
@@ -141,10 +104,7 @@ fn a_real_template_reaches_an_addon_through_create_frame() {
         "Hi"
     );
 
-    // The template's <Scripts> reached the frame. **`OnLoad`, not `OnUpdate`, since 1860** — the
-    // OnUpdate was our own text-fit settle (1004), and the reference's `TabButtonTemplate` declares
-    // exactly one handler: an `<OnLoad>` that calls `PanelTemplates_TabResize(0)` and sizes the
-    // highlight. That it ran is what the collapsed width above already proves.
+    // The stock template declares one handler, the `<OnLoad>`.
     assert!(
         s.eval::<bool>(r#"return ProbeTab:GetScript("OnLoad") ~= nil"#)
             .unwrap(),
@@ -159,21 +119,9 @@ fn a_real_template_reaches_an_addon_through_create_frame() {
     );
 }
 
-/// The template the corpus actually asks for, and the handler that proves the naming rule.
-///
-/// `FauxScrollFrameTemplate` is the most-instantiated template in the 218-addon vanilla corpus that
-/// benilla declares at all — 15 `CreateFrame` call sites across AckisRecipeList, FonzAppraiser,
-/// Leader, Optional and oRA2. Its `<OnLoad>` is `ScrollFrame_OnLoad`, whose very first line is
-///
-/// ```lua
-/// getglobal(this:GetName() .. "ScrollBarScrollDownButton"):Disable()
-/// ```
-///
-/// so the handler **dies on a nil index** unless the caller's own name won all the way down: the
-/// template's nested `<Slider name="$parentScrollBar">` had to become `<caller>ScrollBar`, and
-/// *that* slider's own inherited `$parentScrollDownButton` had to become
-/// `<caller>ScrollBarScrollDownButton`. Two levels of `$parent`, composed through a runtime
-/// template, checked by shipped code rather than by an assertion we wrote to match.
+/// `FauxScrollFrameTemplate`, the addon corpus's most-instantiated template, runs
+/// `ScrollFrame_OnLoad` (`UIPanelTemplates.lua:244`), which indexes
+/// `<name>ScrollBarScrollDownButton` first: two levels of `$parent` through a runtime template.
 #[test]
 fn the_corpus_favourite_template_composes_parent_two_levels_deep() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -184,18 +132,13 @@ fn the_corpus_favourite_template_composes_parent_two_levels_deep() {
     let _ = s.take_errors();
 
     s.run(
-        // **A `ScrollFrame`, not a `Frame`, since 1860.** `FauxScrollFrameTemplate` is now the
-        // reference's own and the reference declares it as a `<ScrollFrame>` carrying a
-        // `<ScrollChild>`; `framexml::merge` takes the OVERRIDING node's tag, so asking for a
-        // "Frame" keeps the frame a Frame and the ScrollFrame-only parts — the scroll child among
-        // them — cannot apply. Our retired copy was a plain `<Frame>`, which is why the corpus
-        // idiom used to read that way here.
+        // The stock template is a `<ScrollFrame>` with a `<ScrollChild>`, and `framexml::merge`
+        // takes the overriding node's tag, so a "Frame" would drop the scroll-only parts.
         r#"Scroller = CreateFrame("ScrollFrame", "BenillaTemplateProbeScroll", UIParent, "FauxScrollFrameTemplate")"#,
     )
     .expect("the corpus's most-used template must not error");
 
-    // `ScrollFrame_OnLoad` ran to completion — it set `this.offset`, its last statement, which it
-    // cannot reach if either getglobal above returned nil.
+    // `this.offset` is `ScrollFrame_OnLoad`'s last statement.
     assert_eq!(
         s.eval::<f32>("return Scroller.offset").unwrap(),
         0.0,
diff --git a/crates/benilla-app/tests/item_text_frame.rs b/crates/benilla-app/tests/item_text_frame.rs
index f7f01b5f..55e32853 100644
--- a/crates/benilla-app/tests/item_text_frame.rs
+++ b/crates/benilla-app/tests/item_text_frame.rs
@@ -1,12 +1,6 @@
-//! Drives the REAL reader window through the engine — bag letters (mail-made permanent copies)
-//! and, later, books. Loads the same file chain the app does (cut to the reader's dependency
-//! prefix), pushes an `ItemTextState`, fires the reference event flow `ITEM_TEXT_BEGIN` →
-//! `ITEM_TEXT_READY` → `ITEM_TEXT_CLOSED`, and asserts the Lua actually paints (title, the "From,"
-//! creator tail, page-button visibility, the close intent).
-//!
-//! The window itself is `Interface\FrameXML\ItemTextFrame.xml`, off the player's own patch chain
-//! since 1751's ninth window — so every test here gates on the install, as every chain-backed
-//! test does.
+//! Drives the stock reader window (`ItemTextFrame.xml`, off the player's chain) through the
+//! engine: pushes an `ItemTextState`, fires `ITEM_TEXT_BEGIN`, `ITEM_TEXT_READY` and
+//! `ITEM_TEXT_CLOSED`, and asserts what the Lua paints.
 
 use benilla_ui::script::{ItemTextState, UiScript};
 
@@ -15,38 +9,29 @@ mod common;
 
 const UI_DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/assets/ui");
 
-/// The reader's dependency prefix, in the manifest's own order. `ScrollTemplates.xml` and
-/// `UIPanelTemplates.xml` joined it with decisions 1337/1338: the page sits in a real ScrollFrame
-/// now, whose template is in the second and whose `ScrollFrame_OnLoad` is in the first.
+/// The reader's dependency prefix, in the manifest's order; the page's scroll frame inherits
+/// `UIPanelScrollFrameTemplate` (`UIPanelTemplates.xml`).
 const FILES: &[&str] = &[
-    // `ITEM_TEXT_FROM`, which the reference's READY arm concatenates into the creator tail — and
-    // `attempt to concatenate a nil value` kills the handler before it reaches its `ShowUIPanel`,
-    // so the window simply never opens. Our deleted copy carried the string as a local fallback.
+    // `ITEM_TEXT_FROM`, concatenated into the creator tail (`ItemTextFrame.lua:41`); nil, it
+    // kills the handler before `ShowUIPanel`.
     "Interface\\FrameXML\\GlobalStrings.lua",
     "Interface\\FrameXML\\Fonts.xml",
     r"Interface\FrameXML\MoneyFrame.lua",
     r"Interface\FrameXML\MoneyFrame.xml",
+    // `GetMaterialTextColors` (`UIParent.lua:1880`), which picks the page and title ink.
     r"Interface\FrameXML\UIParent.xml",
-    // `GetMaterialTextColors`, which the reference's own `ItemTextFrame_OnEvent` calls to pick the
-    // page and title ink. 1.12 keeps it in UIParent.lua and ours does the same (1751 window 9).
     "ScrollTemplates.xml",
     r"Interface\FrameXML\UIPanelTemplates.lua",
     r"Interface\FrameXML\UIPanelTemplates.xml",
     "Interface\\FrameXML\\BasicControls.xml",
     "Interface\\FrameXML\\LocaleProperties.lua",
-    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine (1960)
+    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine
     "Interface\\FrameXML\\ItemTextFrame.xml",
 ];
 
-/// **Both stores, told apart the manifest's own way** — a bare filename is a file we ship, a path
-/// is the reference's own off the player's install (`ui_script::reference_ui::is_chain_entry`,
-/// re-expressed here because that module is crate-private and this is an integration test).
-///
-/// The provider half matters as much as the loop: the reference's `ItemTextFrame.xml` pulls its
-/// Lua through `<Script file="ItemTextFrame.lua"/>`, which the loader resolves against the
-/// document's own directory — `Interface\FrameXML\ItemTextFrame.lua`, a chain path — so a
-/// disk-only provider would leave every one of its globals nil and every test below red for a
-/// reason that looks nothing like the cause.
+/// Loads `FILES`: a bare filename from `assets/ui`, a path off the player's chain. The provider
+/// also serves chain paths, since `ItemTextFrame.xml` pulls its Lua through a relative
+/// `<Script file=…>` resolved against its own directory.
 fn load_ui(script: &UiScript) {
     let dir = std::path::Path::new(UI_DIR);
     let chain = benilla_formats::wow_data()
@@ -60,9 +45,7 @@ fn load_ui(script: &UiScript) {
     };
     for file in FILES {
         let bytes = read(file).unwrap_or_else(|| panic!("reading {file}"));
-        // A `.lua` entry is a chunk, not a document — `GlobalStrings.lua` is one, exactly as it is
-        // in the reference's own TOC. Bytes, not text: a chunk goes to Lua as it sits in the
-        // archive and only an XML parse decodes (1193).
+        // A `.lua` entry is a chunk, passed as raw bytes; only an XML parse decodes.
         if file.to_ascii_lowercase().ends_with(".lua") {
             script
                 .run_chunk_named(&bytes, &format!("@{file}"))
@@ -80,13 +63,8 @@ fn load_ui(script: &UiScript) {
     }
 }
 
-/// The page body as the reader actually DRAWS it, one string per block.
-///
-/// `ItemTextPageText` is a `SimpleHTML` since decisions 1337/1338, and 5875's SimpleHTML has no
-/// `GetText` — its Lua table is 19 entries and none of them is a text getter (`0x87ba80`; later
-/// clients grew one, this one has not). So the page is read the way it is seen: off the render
-/// list. A plain body is one block through the engine's raw-text fallback, which is what every
-/// letter here is.
+/// The page body as drawn, one string per block, read off the render list: `ItemTextPageText` is
+/// a `SimpleHTML`, which has no text getter in 1.12 (`0x87ba80`). A plain body is one block.
 fn page_blocks(s: &UiScript) -> Vec<String> {
     use benilla_ui::script::QuadContent;
     s.extract()
@@ -109,8 +87,8 @@ fn letter() -> ItemTextState {
     }
 }
 
-/// The letter flow: BEGIN paints the title, READY paints the body with the reference "From," tail
-/// and shows the window; a single page shows no page number and no page-turn buttons.
+/// BEGIN paints the title, READY paints the body with the "From," tail and shows the window; a
+/// single page shows no page number and no page-turn buttons.
 #[test]
 fn a_letter_reads_with_the_creator_tail() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -147,17 +125,10 @@ fn a_letter_reads_with_the_creator_tail() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The scrollbar track (the ref's black `$parentMiddle` strip) belongs in the scrollbar column,
-/// right of the page — regression for the black bar over the parchment: the ref declares the
-/// ARTWORK layer before BACKGROUND because `Middle` anchors to `Top` by name and anchors resolve
-/// at SetPoint time; a reordered transcription silently fell back to the parent.
-///
-/// **The tripwire beside it is the whole stock chain's, and it moved with decision 2176.** An
-/// unresolvable `relativeTo` used to anchor to the parent and warn; a *Lua* one now raises
-/// (`0x87ccd4`) and an *XML* one is reported and skipped the way `0x767800` reports and skips it
-/// (`"Couldn't find relative frame: %s"`, `0x878440`). So the assertion is on the new spelling —
-/// zero of those over every file the player's own chain loads — and the raise's own tripwire is
-/// `take_errors()` at the end, which a raise inside any `OnLoad` would land in.
+/// The black `$parentMiddle` track sits right of the page: the stock XML declares ARTWORK before
+/// BACKGROUND because `Middle` anchors to `Top` by name, resolved at SetPoint time. Also, no
+/// anchor in the chain is unresolved: an XML one is reported and skipped (`0x767800`,
+/// `"Couldn't find relative frame: %s"` at `0x878440`) and a Lua one raises (`0x87ccd4`).
 #[test]
 fn the_scrollbar_track_sits_right_of_the_page() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -188,8 +159,7 @@ fn the_scrollbar_track_sits_right_of_the_page() {
     assert!(s.take_errors().is_empty());
 }
 
-/// An authorless multi-page text (a book): no "From," tail, the page number and the page-turn
-/// buttons show per the reference visibility rules (page 1 with a next → Next only).
+/// A book: no "From," tail; page 1 with a next shows the page number and Next only.
 #[test]
 fn a_book_page_shows_the_paging_chrome() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -226,8 +196,8 @@ fn a_book_page_shows_the_paging_chrome() {
     assert!(s.take_errors().is_empty());
 }
 
-/// Closing: the X hides the panel, the OnHide queues the `CloseItemText` intent (the app then
-/// clears the session and fires `ITEM_TEXT_CLOSED` — which hides again, harmlessly).
+/// The X hides the panel and its OnHide queues `CloseItemText`; the app then clears the session
+/// and fires `ITEM_TEXT_CLOSED`, which hides again harmlessly.
 #[test]
 fn closing_queues_the_close_intent() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -242,23 +212,14 @@ fn closing_queues_the_close_intent() {
     assert!(!s.eval::<bool>("return ItemTextFrame:IsShown()").unwrap());
     assert!(s.take_item_text_close(), "OnHide queued the close intent");
 
-    // The app's answer: session cleared + ITEM_TEXT_CLOSED (stays hidden, no errors).
     s.set_item_text(None);
     s.fire_event("ITEM_TEXT_CLOSED", vec![]);
     assert!(!s.eval::<bool>("return ItemTextFrame:IsShown()").unwrap());
     assert!(s.take_errors().is_empty());
 }
 
-/// **B240's render half, on the reported page.** The plaque body (`page_text` 2676, the
-/// *Alliance Military Ranks* wall plaque in Stormwind's Old Town) went through the reader and came
-/// out as its own source — `<HTML><BODY><H1 align="center">…` drawn literally, and cut off with
-/// "..." partway down. Both were the page being a plain FontString where the reference has a
-/// `SimpleHTML` (decisions 1337/1338).
-///
-/// What this pins is the whole path the report exercises: the app's page feed → the reader's
-/// `"\n" .. body .. "\n"` padding → the markup parse → the drawn blocks. The falsification is
-/// stated at the bottom: if the parse ever regresses to the raw-text fallback, the page draws as
-/// one block that still has angle brackets in it, which is exactly what was reported.
+/// The Stormwind Old Town plaque (`page_text` 2676) draws as HTML blocks, not as its own markup,
+/// and is not truncated: the page is a `SimpleHTML`, not a FontString.
 #[test]
 fn the_reported_html_page_draws_as_blocks_not_as_its_own_markup() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -298,37 +259,22 @@ fn the_reported_html_page_draws_as_blocks_not_as_its_own_markup() {
             "{line:?} should draw as its own block; drawn: {drawn:?}"
         );
     }
-    // The reported symptom, stated as the thing that must not come back.
     assert!(
         !drawn
             .iter()
             .any(|b| b.contains("<HTML>") || b.contains("<P align")),
         "the markup itself must never reach the page — that is what was photographed: {drawn:?}"
     );
-    // And the second half of the same symptom: the body is no longer a height-pinned FontString,
-    // so decision 1332's ellipsis seam cannot cut a long page short. No block ends in the
-    // truncation marker.
+    // A height-pinned FontString would end a long page in an ellipsis.
     assert!(
         !drawn.iter().any(|b| b.ends_with("...")),
         "a block was truncated — the page is height-pinned again: {drawn:?}"
     );
 }
 
-/// **B342, on the reported page, through the real archives.** The symptom: the Alliance crest
-/// on *A Treatise on Military Ranks* draws several times the reference's size, with the page's own
-/// text over it.
-///
-/// The body is `page_text` 2654, quoted verbatim below, and its one `<IMG>` carries **no `width=`
-/// and no `height=`**. In the reference that is the CONTENT-derived span: the resolver's size call
-/// is virtual, and `CSimpleTexture`'s override answers an authored `0.0` with the loaded texture's
-/// texel extent, one texel to one FrameXML unit (`0x770720`, decision 1349).
-/// `Interface\PvPRankBadges\PvPRankAlliance` is a 128×128 BLP, so the crest is a 128-unit
-/// square inside a 270-wide page.
-///
-/// The engine half is pinned in `benilla-ui`'s own `simplehtml` tests against a stub oracle; what
-/// this adds is the two ends only the app has — the **real** reader XML the report was
-/// photographed against, and the **real** file, measured by the same decoder the renderer draws
-/// with. It skips on a machine with no client data, like every other archive-backed sweep.
+/// An unsized `<IMG>` draws at its texture's texel extent, one texel to one FrameXML unit
+/// (`CSimpleTexture`, `0x770720`): the crest on `page_text` 2654, quoted below, is a 128×128 BLP
+/// inside a 270-wide page.
 #[test]
 fn the_reported_book_crest_draws_at_the_blps_own_size() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -336,8 +282,7 @@ fn the_reported_book_crest_draws_at_the_blps_own_size() {
     let chain = std::sync::Mutex::new(benilla_formats::open_chain(&data).expect("open chain"));
 
     let mut s = UiScript::new().unwrap();
-    // The host oracle, wired exactly as `ui_script::lifecycle::install_addon_asset_resolvers` wires the
-    // live one: the same decoder, so the size the layout resolves with is the size the screen shows.
+    // Wired as `ui_script::lifecycle::install_addon_asset_resolvers` wires the live one.
     s.set_texture_size_probe(Box::new(move |path| {
         benilla_assets::sprite_dimensions(&chain, None, path)
     }));
@@ -382,20 +327,14 @@ fn the_reported_book_crest_draws_at_the_blps_own_size() {
         (128.0, 128.0),
         "the crest draws at the BLP's own 128x128 — a texel is a FrameXML unit"
     );
-    // The reported symptom, stated as the thing that must not come back: the page is 270 units
-    // wide, and the crest used to be stretched across all of it with the text over the top.
+    // The page is 270 units wide.
     assert!(
         r.right - r.left < 270.0,
         "the crest spans the whole page again — that is the photograph"
     );
 
-    // **The adjacent state**: page 2 of the same book (`page_text` 2655) is five unsized `<IMG>`s,
-    // one rank badge per officer rank, and every one of them is a 32x32 BLP. Under the reported
-    // defect all five were page-wide slabs stacked over each other's text; each is now its own
-    // 32-unit square. (What separates them vertically is the `<BR/>`/`<P>` blocks between them —
-    // a floated image reserves nothing — so their spacing is the font engine's business and this VM
-    // has none: every text block measures zero here and the five land on one line. The SIZES are
-    // the claim.)
+    // Page 2 (`page_text` 2655): five unsized `<IMG>`s, each a 32x32 BLP. This VM has no font
+    // engine, so text measures zero and only the sizes are checked, not the spacing.
     s.set_item_text(Some(ItemTextState {
         item: "A Treatise on Military Ranks".into(),
         creator: None,
@@ -442,12 +381,9 @@ fn the_reported_book_crest_draws_at_the_blps_own_size() {
     }
 }
 
-/// **B288, closed at the reported symptom** (decision 1507): the Verdant Note open from
-/// the bag, then a quest giver's gossip — both frames drew at the same TOPLEFT 0,-104 anchor,
-/// page text and greeting interleaved. The cause was the reader's missing `UIPanelWindows` row:
-/// registered (the ref's own `{ area = "left", pushable = 0 }`, UIParent.lua l.20), the two are
-/// left-slot rivals and showing one replaces the other — in BOTH orders, each displaced window's
-/// OnHide ending its own session exactly as the merchant/gossip pair already does.
+/// The reader's `UIPanelWindows` row (`{ area = "left", pushable = 0 }`, `UIParent.lua:20`) makes
+/// it and gossip left-slot rivals: showing one replaces the other in both orders, and each
+/// displaced window's OnHide ends its own session.
 #[test]
 fn a_quest_givers_gossip_displaces_the_open_reader() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -455,13 +391,9 @@ fn a_quest_givers_gossip_displaces_the_open_reader() {
 
     let mut s = UiScript::new().unwrap();
     load_ui(&s);
-    // The other rival — the reference's own window since 1751, so it goes through the shared
-    // both-stores loader rather than a disk read off `assets/ui`. A hand-rolled reader here is
-    // exactly what `tests/common` exists to replace: it broke the moment this file became the
-    // player's own, and a disk-only provider would leave `GossipFrame.lua`'s globals nil besides.
+    // The stock gossip window, off the chain.
     common::load_ui(&s, "Interface\\FrameXML\\GossipFrame.xml");
 
-    // The note is open and holding the left slot.
     s.set_item_text(Some(letter()));
     s.fire_event("ITEM_TEXT_BEGIN", vec![]);
     s.fire_event("ITEM_TEXT_READY", vec![]);
@@ -473,7 +405,6 @@ fn a_quest_givers_gossip_displaces_the_open_reader() {
     );
     let _ = s.take_item_text_close();
 
-    // The quest giver's gossip opens: one window, not two — the reported stack cannot form.
     s.set_gossip(Some(GossipMenu {
         greeting: "What can I do for you?".into(),
         quests: Vec::new(),
@@ -492,7 +423,7 @@ fn a_quest_givers_gossip_displaces_the_open_reader() {
         s.take_item_text_close(),
         "the displaced reader's OnHide ended the read session (CloseItemText)"
     );
-    // The app's answer to that close must not disturb the gossip that displaced it.
+    // The app's close must not disturb the gossip that displaced it.
     s.set_item_text(None);
     s.fire_event("ITEM_TEXT_CLOSED", vec![]);
     assert!(s.eval::<bool>("return GossipFrame:IsShown()").unwrap());
diff --git a/crates/benilla-app/tests/mail_frame.rs b/crates/benilla-app/tests/mail_frame.rs
index ea041dd7..095a42e8 100644
--- a/crates/benilla-app/tests/mail_frame.rs
+++ b/crates/benilla-app/tests/mail_frame.rs
@@ -1,23 +1,16 @@
-//! Drives the stock `Interface\FrameXML\MailFrame.xml` through the engine (decision 0544 P1/P2) —
-//! the mail twin of `tradeskill_frame.rs`: it loads the same file chain the app does (cut to the
-//! mail window's dependency prefix), pushes a synthetic inbox, opens the window with the app's own
-//! `MAIL_SHOW`/`MAIL_INBOX_UPDATE` events, and asserts the transcribed Lua actually paints — the
-//! named regions exist, the rows populate from a fed `MailState`, the paging math is right, and the
-//! unread/read row state tracks the wire `wasRead` flag.
+//! Drives the stock `MailFrame.xml` off the player's chain with a synthetic inbox and the app's
+//! own `MAIL_SHOW`/`MAIL_INBOX_UPDATE` events, and asserts what it paints and queues.
 
 mod common;
 
 use benilla_ui::script::{MailInboxRow, MailInvoice, MailState, UiScript};
 
-/// The mail window's load prefix — the app's own order (`ui_script/mod.rs`), members only.
-/// MerchantFrame.xml rides along because MailFrame.xml reuses its global `BenillaMoney_*` coin
-/// helpers (postage display), so a load error in either fails here.
+/// The mail window's load prefix, in the app's order.
 const FILES: &[&str] = &[
     "Interface\\FrameXML\\Fonts.xml",
     r"Interface\FrameXML\MoneyFrame.lua",
     r"Interface\FrameXML\MoneyFrame.xml",
-    // The send tab's money entry comes off the chain since 1882 — `MoneyInputFrameTemplate` and
-    // the `MoneyInputFrame_*` verbs. Seated straight after MoneyFrame.xml, benilla.toc's order.
+    // The send tab's money entry: `MoneyInputFrameTemplate` and the `MoneyInputFrame_*` verbs.
     r"Interface\FrameXML\MoneyInputFrame.lua",
     r"Interface\FrameXML\MoneyInputFrame.xml",
     "Interface\\FrameXML\\GlobalStrings.lua",
@@ -27,11 +20,11 @@ const FILES: &[&str] = &[
     r"Interface\FrameXML\UIPanelTemplates.xml",
     "Interface\\FrameXML\\BasicControls.xml",
     "Interface\\FrameXML\\LocaleProperties.lua",
-    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine (1960)
+    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine
     "Interface\\FrameXML\\GameTooltip.xml",
     r"Interface\FrameXML\ItemButtonTemplate.xml", // the send tab's attachment slot inherits it
-    // The stock tabs inherit `FriendsFrameTabTemplate`, and `inherits=` resolves at load — so the
-    // social window and the kit it needs come first, as the reference's toc has them (1970).
+    // The tabs inherit `FriendsFrameTabTemplate` and `inherits=` resolves at load, so the social
+    // window and its kit come first, as in the stock toc.
     "Interface\\FrameXML\\UIDropDownMenu.xml",
     "Interface\\FrameXML\\CharacterFrameTemplates.xml",
     "Interface\\FrameXML\\FriendsFrame.xml",
@@ -74,9 +67,8 @@ fn row(sender: &str, subject: &str, was_read: bool, item_id: u32, cod: u32) -> M
     }
 }
 
-/// One Linen Cloth in the backpack — the send tab's attachment fixture. `ClickSendMailItemButton`
-/// reads the cursor, and `GetSendMailItem` answers off the bag slot it came from, so the row needs
-/// a real name and texture for the stock tab to title the letter with.
+/// A Linen Cloth stack in the backpack, the send tab's attachment: `GetSendMailItem` answers off
+/// its bag slot, so it needs a real name and texture.
 fn one_linen_backpack() -> benilla_ui::script::ContainerState {
     let mut slots = std::collections::HashMap::new();
     slots.insert(
@@ -164,8 +156,8 @@ fn mail_show_opens_and_inbox_populates() {
             .unwrap(),
         "Warchief's orders"
     );
-    // The row's clickable child button is shown for a populated row, hidden past the 2 mails (the
-    // reference row FRAME stays shown — only $parentButton toggles; ref InboxFrame_Update l.120/180).
+    // Only the row's `$parentButton` toggles; the row frame stays shown (`MailFrame.lua:120`,
+    // `:180`).
     assert!(s.eval::<bool>("return MailItem1Button:IsShown()").unwrap());
     assert!(!s.eval::<bool>("return MailItem3Button:IsShown()").unwrap());
 
@@ -204,9 +196,6 @@ fn paging_math_enables_next_only_when_overflowing() {
         .unwrap());
 }
 
-/// The unread/read row *coloring* (SetTextColor / SetVertexColor) has no engine getter to assert
-/// against, so the harness verifies the other observable per-row state the same Update paints: the
-/// COD tag shows on a COD mail and hides on a plain one, and the plain row's money field is nil.
 #[test]
 fn cod_tag_shows_on_a_cod_mail() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -244,7 +233,6 @@ fn opening_a_letter_shows_the_open_frame_and_queues_the_body() {
     s.fire_event("MAIL_INBOX_UPDATE", vec![]);
     let _ = s.take_mail_opens();
 
-    // Click row 1: the check button toggles on → open the letter.
     // A programmatic click toggles the check button on, then fires OnClick (this = the button).
     s.run("MailItem1Button:Click()").unwrap();
     assert!(
@@ -260,14 +248,9 @@ fn opening_a_letter_shows_the_open_frame_and_queues_the_body() {
     assert!(s.take_errors().is_empty());
 }
 
-/// **The letter and the centre seat exclude each other, in BOTH arrival orders** (decision 1520,
-/// director-reported and ref-checked): with the mailbox at the left slot and the character sheet
-/// pushed to centre beside it (its pushable=2 row), clicking a mail item must EVICT the sheet —
-/// the letter's OnShow is the ref's own (`if GetCenterFrame() then HideUIPanel(...)`, ref
-/// MailFrame.xml l.1903-1907) — not open underneath it, which is what a bare Show did. The
-/// reverse order is 1507's child-window loop: a frame arriving at centre puts the letter away.
-/// Whichever comes second wins the space; they can never stack. A bare stand-in carries the
-/// CharacterFrame row (the real file isn't in this harness's chain).
+/// The open letter and the centre panel exclude each other in both orders: the letter's OnShow
+/// hides the centre frame (`MailFrame.xml:1903-1907`), and a frame arriving at centre hides the
+/// letter. A bare stand-in carries the `CharacterFrame` row.
 #[test]
 fn a_letter_and_the_centre_occupant_evict_each_other() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -278,7 +261,7 @@ fn a_letter_and_the_centre_occupant_evict_each_other() {
     s.fire_event("MAIL_INBOX_UPDATE", vec![]);
     let _ = s.take_mail_opens();
 
-    // The director's setup: mailbox left, character sheet pushed to centre beside it.
+    // Mailbox left, character sheet pushed to centre beside it.
     s.run(
         r#"local c = CreateFrame("Frame", "CharacterFrame") c:SetWidth(50); c:SetHeight(50) c:Hide()
            ShowUIPanel(CharacterFrame)"#,
@@ -293,7 +276,7 @@ fn a_letter_and_the_centre_occupant_evict_each_other() {
         "mail holds left, the sheet was pushed to centre"
     );
 
-    // Click a mail item: the letter opens AND the sheet is evicted — one thing beside the mailbox.
+    // Click a mail item: the letter opens and the sheet is evicted.
     s.run("MailItem1Button:Click()").unwrap();
     assert!(s.take_errors().is_empty());
     assert!(
@@ -314,8 +297,7 @@ fn a_letter_and_the_centre_occupant_evict_each_other() {
         "the mailbox itself is untouched"
     );
 
-    // The reverse arrival: re-opening the sheet over the open letter puts the LETTER away
-    // (1507's child-window loop) — the same exclusion, other direction.
+    // The reverse: re-opening the sheet over the open letter puts the letter away.
     s.run("ShowUIPanel(CharacterFrame)").unwrap();
     assert!(s.take_errors().is_empty());
     assert!(
@@ -351,8 +333,8 @@ fn reply_switches_to_send_tab_prefilled() {
     );
 }
 
-/// Closing an ordinary letter (no money, no item, textCreated=false) must NOT delete it — the
-/// reference OnHide rule (MailFrame.lua l.256-272) only purges a fully-taken husk.
+/// `OpenMailFrame_OnHide` deletes only a mail with no money, no item and `textCreated`
+/// (`MailFrame.lua:256-272`).
 #[test]
 fn closing_a_plain_letter_does_not_delete_it() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -377,12 +359,9 @@ fn closing_a_plain_letter_does_not_delete_it() {
     );
 }
 
-/// Closing a fully-taken husk (no money, no item, textCreated=TRUE) deletes it — the reference
-/// OnHide purge. This is also the live "mail vanished on close" moment against vmangos: the server
-/// stamps an EMPTY-BODY player mail MAIL_CHECK_MASK_COPIED (`MailHandler.cpp` l.421,
-/// `req->body.empty() ? MAIL_CHECK_MASK_COPIED : MAIL_CHECK_MASK_HAS_BODY`), which IS the wire's
-/// textCreated bit — so a subject-only letter with nothing attached auto-purges when closed, in
-/// the real 1.12 client exactly as here.
+/// A mail with no money, no item and `textCreated` is deleted on close. vmangos marks an
+/// empty-body player mail COPIED, the wire's `textCreated` bit (`MailHandler.cpp:421`), so a
+/// subject-only letter with nothing attached is deleted when closed.
 #[test]
 fn closing_a_taken_husk_deletes_it() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -406,8 +385,8 @@ fn closing_a_taken_husk_deletes_it() {
     );
 }
 
-/// The expiry text pluralizes like the reference (`GetText("DAYS_ABBR", nil, n)`: "Day"/"Days") —
-/// and carries the reference's own trailing space before the colour close (MailFrame.lua l.144).
+/// The expiry text pluralizes via `GetText("DAYS_ABBR", nil, n)` and keeps a trailing space before
+/// the colour close (`MailFrame.lua:144`).
 #[test]
 fn expiry_text_pluralizes_days() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -433,10 +412,8 @@ fn expiry_text_pluralizes_days() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The letter button — "make a permanent copy" (ref OpenMail_Update l.364-376): a mail whose body
-/// is takeable (`item_text_id != 0`) and not yet copied shows it; clicking queues the
-/// `TakeInboxTextItem` intent (→ `CMSG_MAIL_CREATE_TEXT_ITEM`). With money enclosed too, both
-/// buttons show and the caption reads "Take Attachments:".
+/// The permanent-copy letter button shows for a takeable, not yet copied body
+/// (`MailFrame.lua:364-376`); a click queues `TakeInboxTextItem` (`CMSG_MAIL_CREATE_TEXT_ITEM`).
 #[test]
 fn letter_button_shows_for_a_body_letter_and_click_queues_the_copy() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -471,8 +448,7 @@ fn letter_button_shows_for_a_body_letter_and_click_queues_the_copy() {
     assert!(s.take_errors().is_empty());
 }
 
-/// Once the body is copied (`textCreated`, the wire COPIED bit) the letter button hides — the same
-/// flag whose OnHide purge then deletes the husk on close.
+/// Once the body is copied (`textCreated`, the wire COPIED bit) the letter button hides.
 #[test]
 fn letter_button_hides_once_copied() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -495,7 +471,7 @@ fn letter_button_hides_once_copied() {
     assert!(s.take_errors().is_empty());
 }
 
-/// Hovering the coins shows the plain money tooltip (ref OpenMailMoneyButton OnEnter l.1823-1829).
+/// Hovering the coins shows the money tooltip (`MailFrame.xml:1823-1829`).
 #[test]
 fn money_button_hover_shows_the_amount_tooltip() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -508,7 +484,7 @@ fn money_button_hover_shows_the_amount_tooltip() {
     s.fire_event("MAIL_INBOX_UPDATE", vec![]);
     s.run("MailItem1Button:Click()").unwrap();
 
-    // The hover is the button's own inline handler (stock MailFrame.xml), reading `this`.
+    // The hover is the button's inline handler, which reads `this`.
     s.run("this = OpenMailMoneyButton OpenMailMoneyButton:GetScript(\"OnEnter\")()")
         .unwrap();
     assert!(
@@ -523,9 +499,7 @@ fn money_button_hover_shows_the_amount_tooltip() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The inbox page label stays EMPTY: the ref XML declares InboxCurrentPage (l.329) but no
-/// reference Lua ever writes it — the real 1.12 window shows nothing there ("Page 1" was our
-/// invention, now removed).
+/// `InboxCurrentPage` is declared (`MailFrame.xml:329`) but no stock Lua writes it.
 #[test]
 fn inbox_page_label_stays_empty_like_the_reference() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -543,13 +517,8 @@ fn inbox_page_label_stays_empty_like_the_reference() {
     );
 }
 
-/// A runtime-shown child `<Frame>` renders its own `<Layers>` FontStrings (decision 1517).
-///
-/// This pins a fact three window files spent months asserting the opposite of. `SendMailFrame`
-/// ships `hidden="true"` and is shown by the tab click; its title lives in its OWN Layers, not on
-/// the window root. The "flat layout" those windows adopted was a workaround for a constraint that
-/// never existed — and it produced no symptom precisely because it was always obeyed, which is why
-/// the claim needed a test rather than a header comment.
+/// A runtime-shown child `<Frame>` renders its own `<Layers>` FontStrings: `SendMailFrame` ships
+/// `hidden="true"` and holds its title in its own Layers.
 #[test]
 fn a_runtime_shown_pane_renders_its_own_layers() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -568,22 +537,13 @@ fn a_runtime_shown_pane_renders_its_own_layers() {
     );
 }
 
-/// The auction house's mail is a RECEIPT, not a letter (decision 1522). Before this the window
-/// showed exactly what the server wrote — `From: Unknown / Subject: 5529:0:2` over a body of
-/// `6C:10000:10000:25:500` — because nothing parsed it. The subject rewrite is the engine's
-/// (`ui_mail::invoice`); this is the pane, and it comes in two shapes off one set of seven values.
-///
-/// (`From: Unknown` is NOT part of the bug and is not fixed here: an auction mail carries no
-/// player sender guid, so the reference's own `if ( not sender ) then sender = UNKNOWN` is what
-/// puts that word there — MailFrame.lua l.286-288.)
-///
-/// The body text assertion is the 1527 fold-back: `GetInboxText` returns **nil** for an invoice by
-/// an explicit carve-out in the reference, so `SetText(nil)` leaves the page genuinely empty.
+/// An auction mail opens as a receipt, in a seller and a buyer shape; its subject is rewritten
+/// by `ui_mail::invoice`. It has no player sender, so the stock Lua shows `UNKNOWN`
+/// (`MailFrame.lua:286-288`), and `GetInboxText` returns nil for an invoice.
 #[test]
 fn an_auction_invoice_renders_as_a_receipt() {
     let _data = benilla_formats::wow_data_or_skip!();
-    /// The pane reads the player's own GlobalStrings, which a bare-XML harness has none of. Stand
-    /// in synthetic ones: what is under test is that each reaches the right region, never their text.
+    /// Synthetic GlobalStrings: the test checks each reaches the right region, not the text.
     fn strings(s: &UiScript) {
         s.run(concat!(
             "ITEM_SOLD_COLON = 'SOLD:' PURCHASED_BY_COLON = 'BY:' AMOUNT_RECEIVED_COLON = 'GOT:' ",
@@ -614,7 +574,7 @@ fn an_auction_invoice_renders_as_a_receipt() {
             .unwrap()
     };
 
-    // ── The seller's: the full sum. 1g sale + 25c deposit back − 5c the house takes. ──────────
+    // ── The seller's: 1g sale + 25c deposit back - 5c house cut. ──────────────────────────────
     let mut s = open_with(MailInvoice {
         seller: true,
         item_name: "Linen Cloth".into(),
@@ -631,7 +591,7 @@ fn an_auction_invoice_renders_as_a_receipt() {
     );
     assert_eq!(text(&s, "OpenMailInvoiceItemLabel"), "SOLD: Linen Cloth");
     assert_eq!(text(&s, "OpenMailInvoicePurchaser"), "BY: Twowarrior");
-    // bid == buyout, so it was bought outright rather than won on a bid.
+    // bid == buyout: bought outright.
     assert_eq!(text(&s, "OpenMailInvoiceBuyMode"), "(Buyout)");
     assert_eq!(money(&s, "OpenMailSalePriceMoneyFrame"), "10000");
     assert_eq!(money(&s, "OpenMailDepositMoneyFrame"), "25");
@@ -652,7 +612,7 @@ fn an_auction_invoice_renders_as_a_receipt() {
     );
     assert!(s.take_errors().is_empty());
 
-    // ── The buyer's: one line, and the seller-only rows gone. Won on a bid, not bought out. ───
+    // ── The buyer's: one line, the seller-only rows hidden, won on a bid. ────────────────────
     let mut s = open_with(MailInvoice {
         seller: false,
         item_name: "Small Blue Pouch".into(),
@@ -694,8 +654,7 @@ fn an_auction_invoice_renders_as_a_receipt() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A mail that is NOT an auction invoice keeps its letter: the pane stays hidden and the body text
-/// survives. The blanking above is aimed at one kind of mail and must not reach any other.
+/// A mail that is not an invoice keeps its body and shows no receipt.
 #[test]
 fn a_plain_letter_keeps_its_body_and_shows_no_receipt() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -716,14 +675,8 @@ fn a_plain_letter_keeps_its_body_and_shows_no_receipt() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The open letter's ring holds an ordinary **item** icon (`INV_Misc_Note_01`), so it has to go
-/// through the PORTRAIT verb and not a bare `SetTexture` — which is exactly what the reference
-/// reaches for here, and nowhere else in the file (`MailFrame.lua` l.174).
-///
-/// Set raw, the icon's square dark border shows through the ring's transparent corners as four
-/// little squares around the circle (director's report, 2026-08-22). The INBOX window's ring is the
-/// control: it holds `Mail-Icon`, purpose-drawn art that needs no mask, and the reference leaves
-/// that one at its `file=` (ref l.258) — so a blanket "mask every ring" would be wrong too.
+/// The open letter's ring takes an item icon through `SetPortraitToTexture` (`MailFrame.lua:174`),
+/// so it draws masked; the inbox ring's `Mail-Icon` stays a plain `file=` (`MailFrame.xml:258`).
 #[test]
 fn the_open_letters_ring_icon_is_masked_but_the_inboxs_is_not() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -770,19 +723,9 @@ fn the_open_letters_ring_icon_is_masked_but_the_inboxs_is_not() {
     );
 }
 
-/// **"I can't even type anything in the mailbox window"** — the director's report, at its cause.
-///
-/// The send tab has five edit boxes, and exactly one of them — `SendMailNameEditBox` — carries an
-/// XML `<OnChar>` (`SendMailFrame_SendeeAutocomplete`). That handler auto-enables the box for the
-/// keyboard walk, and the box is the first-registered keyboard frame in the window, so on every
-/// keystroke the walk reached it first and the **base** `CSimpleFrame::OnChar` gate consumed:
-/// script present → fire → stop. Nothing downstream of it ever saw a character. The reference
-/// cannot do that — `CSimpleEditBox` replaces slot `+0x5c` with `0x77a900`, which asks about focus
-/// and declines (`0x77a956`) when another box owns it, and never chains to the base gate at all
-/// ([`benilla_ui`]'s `script::keyboard::is_editbox`, decision 2145).
-///
-/// The one box that DID work is the assertion's control: the autocomplete box types, once per
-/// character, and the four that were dead now type too.
+/// Only `SendMailNameEditBox` has an `<OnChar>`, which puts it in the keyboard walk first. An edit
+/// box's `OnChar` slot `+0x5c` is `0x77a900`, which declines (`0x77a956`) when another box has
+/// focus and never chains to the base `CSimpleFrame` gate (`script::keyboard::is_editbox`).
 #[test]
 fn every_send_tab_box_takes_a_keystroke_not_just_the_one_with_an_onchar() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -794,8 +737,7 @@ fn every_send_tab_box_takes_a_keystroke_not_just_the_one_with_an_onchar() {
     s.resolve();
     assert!(s.eval::<bool>("return SendMailFrame:IsVisible()").unwrap());
 
-    // The box whose handler was eating everyone else's keys: it still types, and its OnChar still
-    // fires exactly once per character (the insert path's fire — never the walk's).
+    // The `<OnChar>` box types, and its OnChar fires once per character, from the insert.
     s.run("SendMailNameEditBox:SetText('') SendMailNameEditBox:SetFocus()")
         .unwrap();
     s.run("SendMailChars = 0 \
@@ -815,7 +757,7 @@ fn every_send_tab_box_takes_a_keystroke_not_just_the_one_with_an_onchar() {
         "OnChar fires once per character, from the insert — not a second time from the walk"
     );
 
-    // …and the four that took nothing at all. The money boxes are `numeric`, so they get digits.
+    // The other four boxes; the money boxes are `numeric`.
     for (box_name, typed, expect) in [
         ("SendMailSubjectEditBox", ["H", "e", "y"], "Hey"),
         ("SendMailBodyEditBox", ["o", "d", "d"], "odd"),
@@ -837,13 +779,8 @@ fn every_send_tab_box_takes_a_keystroke_not_just_the_one_with_an_onchar() {
     assert!(s.take_errors().is_empty(), "and nothing raised on the way");
 }
 
-/// **"Sending an item still leaves the subject and the item image in the input"** — the director's
-/// second report, at its cause: the compose-tab reset used to fire `MAIL_SEND_SUCCESS` *before* it
-/// dropped the attachment, so the stock `SendMailFrame_Reset`'s own tail
-/// (`SendMailFrame_Update` → `GetSendMailItem`) painted the just-sent item straight back into the
-/// form it had blanked one line earlier. `UiScript::reset_compose_tab` is now `0x4acdc0(1)` whole —
-/// zero the globals, THEN tail-fire the three events — so there is no window in which the two
-/// disagree (decision 2145).
+/// `UiScript::reset_compose_tab` is `0x4acdc0(1)`: it clears the attachment before firing the
+/// events, since `SendMailFrame_Reset` ends in `SendMailFrame_Update`, reading `GetSendMailItem`.
 #[test]
 fn the_compose_reset_clears_the_subject_and_the_attachment_together() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -854,8 +791,7 @@ fn the_compose_reset_clears_the_subject_and_the_attachment_together() {
     s.fire_event("MAIL_SHOW", vec![]);
     s.run("MailFrameTab_OnClick(2)").unwrap();
 
-    // Attach the item the way the player does: pick it up, click the send slot. The stock tab
-    // names the letter after it, which is the text that used to survive the send.
+    // Pick the item up and click the send slot; the stock tab names the letter after it.
     s.run("PickupContainerItem(0, 1) ClickSendMailItemButton()")
         .unwrap();
     s.fire_event("MAIL_SEND_INFO_UPDATE", vec![]);
@@ -866,8 +802,7 @@ fn the_compose_reset_clears_the_subject_and_the_attachment_together() {
         "the stock tab titles the letter after its attachment"
     );
 
-    // The send lands. This is the whole edge: one call, and the form is clean when the FrameXML
-    // handler reads it.
+    // The send lands.
     s.reset_compose_tab();
     assert_eq!(
         s.eval::<String>("return SendMailSubjectEditBox:GetText()")
diff --git a/crates/benilla-app/tests/message_keys.rs b/crates/benilla-app/tests/message_keys.rs
index 06d070b5..88a90717 100644
--- a/crates/benilla-app/tests/message_keys.rs
+++ b/crates/benilla-app/tests/message_keys.rs
@@ -1,31 +1,15 @@
-//! Every `ERR_*` key this workspace names must be a real row of the client's message catalog.
-//!
-//! benilla writes these keys as string literals at ~160 call sites, and each one used to arrive by
-//! hand-tracing a `push <id>; call CGGameUI::DisplayError` in the binary. A typo, a key from a
-//! later expansion, or a plausible-looking invention would all have been invisible: the string
-//! simply would not resolve in `GlobalStrings.lua`, and the reference's own data-suppression rule
-//! means benilla shows *nothing* for an unresolvable key. Silence is the failure mode, which is the
-//! worst kind — nobody files a bug about a toast they never saw.
-//!
-//! Since decision 1770 the surface those keys are shown on is read from
-//! [`benilla_ui::messages`] rather than carried beside them, so a key that is not in the catalog
-//! also silently takes the fallback. This walk is what keeps that fallback unreachable: it is the
-//! tripwire that turns "we believe these are message ids" into a checked claim.
-//!
-//! It reads source text rather than any registry the code keeps, deliberately — a registry could
-//! only contain what somebody remembered to register.
+//! Every `ERR_*` key this workspace names must be a real row of the client's message catalog: an
+//! unresolvable key shows nothing, and [`benilla_ui::messages`] reads the display surface from the
+//! row. Source text is scanned, not a registry, so an unregistered key is still caught.
 
 use std::collections::BTreeSet;
 use std::path::Path;
 
-/// Not message ids, and not meant to be — both are fixtures for the unknown-key *fallback*, which
-/// needs a key the client does not have in order to be tested at all: `ui_petition::lines`'
-/// degrade-to-generic arm, and `benilla_ui::messages`' own proof that `kind_of` answers for a key
-/// it has never heard of. Anything else appearing here is a defect, not an entry to add.
+/// Fixtures for the unknown-key fallback (`ui_petition::lines` and `benilla_ui::messages`'
+/// `kind_of`), which need a key the client does not have.
 const NOT_A_MESSAGE: &[&str] = &["ERR_SOMETHING_UNCARVED", "ERR_NOT_A_REAL_MESSAGE"];
 
-/// The generated table itself, which is the answer and not a question — walking it would make
-/// every key trivially present and the check vacuous.
+/// The generated catalog, skipped: walking it would make every key trivially present.
 const GENERATED: &str = "catalog.rs";
 
 fn walk(dir: &Path, into: &mut Vec<String>) {
@@ -41,7 +25,7 @@ fn walk(dir: &Path, into: &mut Vec<String>) {
     }
 }
 
-/// Pull every `"ERR_…"` string literal out of a source file, the way the call sites write them.
+/// Every `"ERR_…"` string literal in a source file.
 fn err_keys(src: &str) -> impl Iterator<Item = String> + '_ {
     src.match_indices("\"ERR_").filter_map(|(i, _)| {
         let rest = &src[i + 1..];
@@ -61,8 +45,7 @@ fn every_error_key_in_the_source_is_a_catalog_row() {
     assert!(sources.len() > 100, "the walk found almost nothing to read");
 
     let keys: BTreeSet<String> = sources.iter().flat_map(|s| err_keys(s)).collect();
-    // 163 at the time of writing — the point is only that the walk found the vocabulary and not
-    // a handful of files, so this is a floor and not a ledger to keep updated.
+    // A floor proving the walk found the vocabulary, not a count to keep updated.
     assert!(
         keys.len() > 150,
         "expected the hand-written `ERR_*` vocabulary, found {}",
@@ -81,30 +64,14 @@ fn every_error_key_in_the_source_is_a_catalog_row() {
     );
 }
 
-/// **The claim this file's own doc has always made, finally checked** (decision 1821): a key the
-/// source names must not only be a catalog row, it must **resolve to text**.
-///
-/// The two are not the same, and the difference is the failure this file exists to catch. A row's
-/// `key` is a `GlobalStrings.lua` *lookup*, and the shipped file has no entry for a good many of
-/// them — that absence is the reference's own data-suppression face, and a raise site that picks
-/// one of those rows is silent for good. The walk above would pass it.
-///
-/// Worth closing now because 1821 moved four more windows' refusals onto keys (the vendor's two
-/// tables, the banker's, the mailbox's), where a superseded or mistyped key costs a whole window's
-/// worth of lines rather than one toast. Skips without client data.
+/// A named key must also resolve to text: a row's key is a `GlobalStrings.lua` lookup, and the
+/// shipped file has no entry for many rows, which the reference then never shows.
 #[test]
 fn every_error_key_in_the_source_resolves_to_real_text() {
-    /// Keys whose row the shipped `GlobalStrings.lua` has **no string for**, so the reference
-    /// itself shows nothing when it raises them. Each is documented where it is raised —
-    /// `ui_items::equip_error` (errorId 362), `ui_action::cast_fail` (the pet-happiness arm), and
-    /// `ui_pet::net` (errorId 337, both pet handlers' NOPATH arm). A fourth entry here is a
-    /// defect until someone proves otherwise.
-    ///
-    /// `ERR_PET_SPELL_NOPATH` is the one worth reading twice, because it is a trap: 5875 *does*
-    /// ship a `PET_SPELL_NOPATH` ("No path available for your pet"), one letter-group away and
-    /// perfectly plausible on screen — but it is not row 337's key and no code path in the client
-    /// raises it. benilla named it for months and showed the wrong string for the wrong byte
-    /// (decision 2033). Silence here is the reference's behaviour, not a gap.
+    /// Keys the shipped `GlobalStrings.lua` has no string for, so the reference shows nothing:
+    /// raised by `ui_items::equip_error` (errorId 362), `ui_action::cast_fail` (pet happiness)
+    /// and `ui_pet::net` (errorId 337). `PET_SPELL_NOPATH` exists but is not row 337's key and
+    /// nothing in the client raises it.
     const SILENT_IN_5875: &[&str] = &[
         "ERR_CANT_BE_DISENCHANTED",
         "ERR_NOT_HAPPY_ENOUGH",
@@ -140,36 +107,25 @@ fn every_error_key_in_the_source_resolves_to_real_text() {
         "these keys are catalog rows but resolve to NOTHING in the shipped GlobalStrings.lua, so \
          every line raised through them is invisible: {silent:?}"
     );
-    // A floor, not a ledger: the point is that the VM really loaded the file, so an empty `vm`
-    // cannot make the sweep above vacuously green.
+    // A floor proving the VM loaded the file.
     assert!(
         resolved > 150,
         "only {resolved} keys resolved — did GlobalStrings load?"
     );
 }
 
-/// **The other half of the same claim, on real data: a key that carries a VOICE line can actually
-/// be spoken** (decision 1815).
-///
-/// 56 catalog rows put an error-speech id in `+0x0c` instead of a cue name, and the client says
-/// those aloud in the player's own race and gender. The join runs
-/// `key → MessageRecord::type_tag → VocalUISounds.dbc(race, line) → SoundEntries(sex)`, across
-/// four tables and two crates, and every link is a lookup that can come back empty *silently* —
-/// the same failure mode the walk above exists for, one layer deeper.
-///
-/// So: for every voice-tagged key this workspace raises, every playable race must have a row, and
-/// that row must resolve real audio for both sexes. The two exceptions are exceptions **in the
-/// shipped data**, named here so a regression cannot hide behind them. Skips without client data.
+/// 56 catalog rows carry an error-speech id at `+0x0c` instead of a cue name, spoken in the
+/// player's race and sex through `type_tag`, `VocalUISounds.dbc(race, line)` and
+/// `SoundEntries(sex)`. Every voiced key raised here must resolve audio for every playable race
+/// and both sexes, except the gaps in the shipped data listed below.
 #[test]
 fn every_voiced_key_the_source_raises_has_audio_for_every_playable_race() {
     use benilla_formats::VOCAL_UI_LINES;
 
-    /// Lines the 5875 data ships no audio for, in any race: `0x07` (`ERR_FOOD_COOLDOWN`) and
-    /// `0x20` (`ERR_LOOT_BAD_FACING`). Both have a `VocalUISounds` row per race whose kit ids are
-    /// `-1` — the file's own "no line recorded" — so the client is silent for them by data.
+    /// Lines with no audio in any race, `0x07` (`ERR_FOOD_COOLDOWN`) and `0x20`
+    /// (`ERR_LOOT_BAD_FACING`): every race's `VocalUISounds` row has kit id -1.
     const NO_AUDIO_IN_5875: &[u8] = &[0x07, 0x20];
-    /// Single `(race, sex)` gaps in the shipped file — one voice actor's line that never got
-    /// recorded. Listed rather than tolerated wholesale, so a *new* hole fails the test.
+    /// Single `(line, race, sex)` gaps in the shipped file.
     const RACE_SEX_GAPS: &[(u8, u32, u32)] = &[
         (0x21, 3, 0), // ERR_LOOT_LOCKED, Dwarf male
         (0x21, 4, 0), // ERR_LOOT_LOCKED, Night Elf male
@@ -223,24 +179,17 @@ fn every_voiced_key_the_source_raises_has_audio_for_every_playable_race() {
             }
         }
     }
-    // benilla raises a good share of the 45 distinct voiced lines — a floor, so a refactor that
-    // quietly stopped routing refusals through the catalog fails here instead of going silent.
+    // A floor over the 45 distinct voiced lines, so raise sites that stop naming them fail here.
     assert!(
         voiced >= 30,
         "only {voiced} voice-tagged keys reached the catalog — the raise sites stopped naming them"
     );
 }
 
-/// **Why benilla may hang a message's sound off its display, even though the reference does not.**
-///
-/// `CGGameUI::DisplayError 0x496720` sounds first (`0x49673d`) and only then guards on the row's
-/// key (`0x4967bd`/`0x4967c5`) and, in the sink, on the resolved text (`0x4945b4`) — so *there*, a
-/// message with no GlobalStrings string still makes its noise. benilla drops an empty line before
-/// it reaches `show_messages`, so it would not. That is a divergence with **no case in 5875's
-/// data**, and this is the measurement that says so: every row that sounds also has text.
-///
-/// If this ever fails, `sound::message` has to sound the row independently of the display rather
-/// than alongside it. Skips without client data.
+/// `CGGameUI::DisplayError` (`0x496720`) sounds (`0x49673d`) before it guards on the key
+/// (`0x4967bd`/`0x4967c5`) and the text (`0x4945b4`); benilla drops an empty line before it
+/// sounds, which matches only while every sounding row has text. If this fails,
+/// `sound::message` must sound independently of the display.
 #[test]
 fn every_sounding_catalog_row_also_has_text_to_show() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -271,17 +220,8 @@ fn every_sounding_catalog_row_also_has_text_to_show() {
     assert_eq!(sounding, 86, "56 voice lines + 30 named cues");
 }
 
-/// **The non-`ERR_` half of the same tripwire, for the one family that has one** (decision 2039):
-/// every string `pet_tame_failure_key` can return must be a real global of the 1.12 client.
-///
-/// The walk above collects `"ERR_…"` literals, which is every catalog row — and is therefore
-/// blind to a raise site that names something else. `SMSG_PET_TAME_FAILURE` is precisely that
-/// shape: the message it raises is `ERR_TAME_FAILED`, but the *text* comes from a second lookup
-/// of a `PETTAME_*` key, and an invented one there would fail exactly the way this file's header
-/// describes — silently, with no line shown and nobody to file it.
-///
-/// Checked against `reference/1.12-globals.tsv`, the running client's own `_G` (decision 1189),
-/// rather than against the install: it is in-tree, so this holds on a machine with no client.
+/// Every `PETTAME_*` key `pet_tame_failure_key` returns, the fill for `ERR_TAME_FAILED`, is a 1.12
+/// global, checked against the in-tree `reference/1.12-globals.tsv`.
 #[test]
 fn every_pettame_key_is_a_real_1_12_global() {
     let tsv = concat!(
@@ -295,8 +235,7 @@ fn every_pettame_key_is_a_real_1_12_global() {
         .filter_map(|l| l.split('\t').next())
         .collect();
 
-    // The whole reachable image of the table: 1..=11 index it, everything else is the default
-    // arm. `u8` is small enough to just walk.
+    // 1..=11 index the table; everything else is the default arm.
     let reachable: BTreeSet<&str> = (0..=u8::MAX)
         .map(benilla_protocol::messages::pet_tame_failure_key)
         .collect();
diff --git a/crates/benilla-app/tests/reference_strings.rs b/crates/benilla-app/tests/reference_strings.rs
index 73831730..e1ca293c 100644
--- a/crates/benilla-app/tests/reference_strings.rs
+++ b/crates/benilla-app/tests/reference_strings.rs
@@ -1,73 +1,19 @@
-//! **No user-facing sentence is written in Rust when the reference ships one.**
-//!
-//! The real client never composes display text: every sentence is a key into `GlobalStrings.lua`
-//! (in-game) or `GlueStrings.lua` (the login/character screens) — each with a `Localize()` patch
-//! file laid over it, which is where a good many of the sentences the player actually reads come
-//! from (decision 2052) — resolved at runtime from the player's own install. Writing the English in
-//! Rust throws away three things at once —
-//! localization, and, for anything that goes through the message catalog, the *surface* the
-//! message is shown on and the *voice line* it speaks with (decisions 1770, 1815, 2035).
-//!
-//! **Why a tripwire and not a review rule.** Decision 2035 found a loot-refusal table that had
-//! composed its own eight sentences, six of which said something 1.12 never says, under a comment
-//! asserting they were quoted from the reference. The comment was the only check there had ever
-//! been, and a comment cannot fail. What makes that class *findable* is that a re-typed string is
-//! byte-identical to the shipped one — so a walk that normalises both sides and compares them finds
-//! every instance mechanically, which is what this does.
-//!
-//! **What it cannot find, stated plainly.** Text that matches nothing is invisible here: an
-//! *invented* sentence (2035's "Those pockets are already empty.", for a code 1.12 has no string
-//! for) has no shipped counterpart to match against. This tripwire catches the re-typing class,
-//! which is the large one; the invention class needs a reader who checks the reference.
-//!
-//! **A literal beside a key lookup is correct and is not flagged** — a fallback for an install
-//! whose chain lacks the key is the reference's own `UNKNOWNOBJECT` shape. The walk only counts a
-//! literal whose enclosing function resolves nothing.
-//!
-//! [`ALLOWED`] is a **ratchet**: it records what was already drifted when the tripwire was built,
-//! per file, and the counts may only ever go **down**. Converting a file means lowering its number
-//! (or deleting the row); a file not listed may carry none at all. Skips without client data.
+//! No user-facing sentence is written in Rust when the reference ships one: the 1.12 client
+//! resolves display text by key from `GlobalStrings.lua` or `GlueStrings.lua` and their
+//! `Localize()` patches. A re-typed sentence is byte-identical to the shipped one, so this walk
+//! finds it; an invented sentence matches nothing and is invisible here. A literal in a function
+//! that also resolves a key is a fallback and is not flagged. Skips without client data.
 
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 
-/// **Empty, and that is the point.** This was decision 2045's ratchet — a per-file budget of
-/// re-typed sentences that might only ever go down — and it went down to nothing.
-///
-/// It stays as an empty list rather than being deleted with the machinery, because the walk below
-/// is still the guard: a row appearing here is a file that started re-typing again, and the
-/// argument for the rule holds whether or not anything is currently breaking it.
-///
-/// **The number went UP once before it went down, and that is the part worth remembering.** Two
-/// defects in the walk itself — a `RESOLVERS` entry that a `sort_by_key` call satisfied, and a
-/// `#[cfg(test)]` stripper blind to the out-of-line `mod tests;` — had it reporting 160 where the
-/// truth was 180, hiding 36 literals inside one function while double-counting a handful
-/// elsewhere. A ratchet is only ever as honest as the walk under it: a number that may only
-/// decrease is worthless if the number was never right.
-///
-/// **What this walk still cannot do**, unchanged from 2045 and worth keeping in view now that the
-/// count is zero: it finds *re-typed* strings, because those are byte-identical to the shipped
-/// ones. It cannot find *invented* ones — text matching nothing has nothing to match against —
-/// and it cannot see a one-word value, which collides with ordinary program text. Three invented
-/// slot words and a hand-typed `LockType` name were found in this arc by reading the reference,
-/// not by this test.
-///
-/// **Regenerate against a clean tree, never mid-edit.** The walk is deterministic on the sources
-/// plus the shipped tables (two consecutive runs agree exactly), but a baseline captured while
-/// other files are half-converted records counts no later tree will reproduce.
+/// Per-file budgets of re-typed sentences, which may only go down; empty, so no file may carry
+/// any. A one-word value is not checked: it collides with ordinary program text.
 const ALLOWED: &[(&str, usize)] = &[];
 
 /// Paths that are never player-facing: dev instruments, probes, capture harnesses and benches.
-/// A `.learn <spell>` GM command is not a UI string even when it collides with one.
-///
-/// **`resolve_bench` is the one entry that is not a *category* but a hole in the walk**, and it is
-/// named here rather than papered over. The file is `#[cfg(test)] mod resolve_bench;` — test-only
-/// code, exactly what [`strip_test_modules`] exists to drop — but that stripper works *within* a
-/// file, and this module's body lives in another one whose name does not contain "test", so the
-/// walk visits it as production source. Its three hits are Lua fixtures inside `#[ignore]`d
-/// release-only benches (`GameTooltip:AddLine("Main Hand", …)` — a line whose only job is to have
-/// a width). Skipping cfg(test)-only *files* properly would mean parsing the module tree; this is
-/// the honest one-line stand-in until something needs the general answer.
+/// `resolve_bench` is a `#[cfg(test)]` module in its own file, which [`strip_test_modules`] cannot
+/// see from its parent, so it is named here.
 fn is_instrument(rel: &str) -> bool {
     [
         "/capture/",
@@ -80,9 +26,8 @@ fn is_instrument(rel: &str) -> bool {
     .any(|p| rel.contains(p))
 }
 
-/// Collapse a shipped value and a Rust literal onto the same shape: every placeholder — the
-/// reference's `%s`/`%d`/`%1$s` and Rust's `{}`/`{name}` alike — becomes one marker, `\32` is the
-/// escaped space it stands for, runs of whitespace collapse, and case is dropped.
+/// Collapse a shipped value and a Rust literal onto one shape: every placeholder (`%s`, `%1$s`,
+/// `{}`, `{name}`) becomes one marker, `\32` becomes a space, whitespace collapses, case drops.
 fn normalize(s: &str) -> String {
     let s = s.replace("\\32", " ");
     let mut out = String::with_capacity(s.len());
@@ -165,13 +110,7 @@ fn walk(dir: &Path, into: &mut Vec<PathBuf>) {
     }
 }
 
-/// Does this function resolve a key at all? If so, a literal inside it is a fallback.
-///
-/// Matched on an **identifier boundary** for the bare-word entries, which is not fussiness:
-/// `by_key(` is a substring of `sort_by_key(`, and one `bonuses.sort_by_key(…)` was exempting the
-/// whole 530-line `render_view` — the largest literal-bearing function in the workspace — from
-/// this walk. A resolver list that can be satisfied by an unrelated method name is not a filter,
-/// it is a blindfold. Entries that begin with punctuation (`.text(`) are already delimited.
+/// Calls that resolve a key; a literal in a function containing one is a fallback.
 const RESOLVERS: &[&str] = &[
     "strings.get(",
     ".text(",
@@ -183,7 +122,8 @@ const RESOLVERS: &[&str] = &[
     "glue_strings",
 ];
 
-/// [`RESOLVERS`], on an identifier boundary for the bare-word entries.
+/// [`RESOLVERS`], on an identifier boundary for the bare-word entries (`by_key(` must not match
+/// `sort_by_key(`).
 fn resolves(body: &str) -> bool {
     RESOLVERS.iter().any(|r| {
         let word = r.starts_with(|c: char| c.is_alphanumeric() || c == '_');
@@ -202,9 +142,8 @@ fn no_user_facing_sentence_is_written_in_rust_when_the_reference_ships_one() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = benilla_formats::open_chain(&data).expect("open chain");
     let mut shipped: HashMap<String, Vec<String>> = HashMap::new();
-    // The base tables AND the locale patches laid over them (decision 2052): where `Localize()`
-    // redefines a key, its wording is the one the player actually reads, so a set that stopped at
-    // the base files would be grading against text this install never shows.
+    // The base tables and the locale patches: where `Localize()` redefines a key, its wording is
+    // the one the player reads.
     for file in [
         "Interface\\FrameXML\\GlobalStrings.lua",
         "Interface\\FrameXML\\Localization.lua",
@@ -220,22 +159,14 @@ fn no_user_facing_sentence_is_written_in_rust_when_the_reference_ships_one() {
             // A one-word or punctuation-only value ("Locked", "%s") is too weak a signal: it
             // collides with ordinary program text. Sentences are what this is after.
             if n.split(' ').count() >= 2 && n.chars().any(|c| c.is_ascii_lowercase()) {
-                // **Every** key with this wording, not the first one seen. A value maps to more
-                // than one key far more often than you would guess — `CHAT_IGNORED` and
-                // `ERR_IGNORING_YOU_S` are the same enUS sentence, and so are
-                // `INVTYPE_SHIELD`/`SECONDARYHANDSLOT`, `CHAR_CREATE_NAME_IN_USE`/
-                // `CHAR_NAME_RESERVED` — and naming one of them is how a reader converts a site
-                // to the wrong key. Which one belongs at a given call site is the *reference's
-                // code* to answer, never this table's; the report's job is to say that a choice
-                // exists (decision 2045, "assert the identifier, not the sentence").
+                // Every key with this wording: several keys share one enUS sentence
+                // (`CHAT_IGNORED`/`ERR_IGNORING_YOU_S`), and the call site decides which applies.
                 shipped.entry(n).or_default().push(k);
                 taken += 1;
             }
         }
-        // A file that reads fine but parses to nothing would make this whole test pass vacuously
-        // — and the two `Localize()` files wrap their assignments in a function, a shape the base
-        // tables never have. Every source has to contribute or the walk is grading against less
-        // than it claims.
+        // Every source must contribute: the `Localize()` files wrap their assignments in a
+        // function, a shape the base tables never have.
         assert!(taken > 0, "{file} contributed no sentences");
     }
 
@@ -248,8 +179,7 @@ fn no_user_facing_sentence_is_written_in_rust_when_the_reference_ships_one() {
     let mut found: HashMap<String, Vec<String>> = HashMap::new();
 
     for path in &sources {
-        // The walk starts at this crate's `src` and at the two sibling crates by relative path;
-        // name every hit `<crate>/src/...` so the ratchet rows read the same wherever it ran.
+        // Name every hit `<crate>/src/...`.
         let raw = path.to_string_lossy().to_string();
         let rel = match raw.strip_prefix("../") {
             Some(sibling) => sibling.to_string(),
@@ -280,10 +210,8 @@ fn no_user_facing_sentence_is_written_in_rust_when_the_reference_ships_one() {
         }
     }
 
-    // A ratchet says only whether a file got worse; converting one needs the list. `cargo test -p
-    // benilla-app --test reference_strings -- --nocapture` with `BENILLA_REFSTRINGS_REPORT=1`
-    // prints every hit — key, function, literal — biggest file first, so a conversion starts from
-    // what is actually there rather than from a count.
+    // `BENILLA_REFSTRINGS_REPORT=1` with `--nocapture` prints every hit (key, function, literal),
+    // biggest file first.
     if std::env::var_os("BENILLA_REFSTRINGS_REPORT").is_some() {
         let mut files: Vec<(&String, &Vec<String>)> = found.iter().collect();
         files.sort_by_key(|(f, h)| (std::cmp::Reverse(h.len()), (*f).clone()));
@@ -310,8 +238,7 @@ fn no_user_facing_sentence_is_written_in_rust_when_the_reference_ships_one() {
             ));
         }
     }
-    // The ratchet only bites downward if a *stale* row is an error too — otherwise a converted
-    // file's row lingers and silently re-permits the drift it was meant to retire.
+    // A stale row is an error too, or it would re-permit the drift it counted.
     for (file, budget) in ALLOWED {
         let actual = found.get(*file).map_or(0, |h| h.len());
         assert!(
@@ -330,18 +257,8 @@ fn no_user_facing_sentence_is_written_in_rust_when_the_reference_ships_one() {
     );
 }
 
-/// Cut every `#[cfg(test)]` item out of a source file before scanning it.
-///
-/// Without this the walk reads test fixtures as production text — `ui_action::cast_fail`'s unit
-/// tests build a *fake* GlobalStrings map whose 48 entries are, by construction, byte-identical to
-/// the shipped strings. Those are the test doing its job, not drift.
-///
-/// **The item's terminator is a brace OR a semicolon, whichever comes first**, and getting that
-/// wrong was silently corrupting this walk in both directions. `#[cfg(test)] mod tests;` — the
-/// out-of-line form, 28 files in this workspace — has no brace of its own, so a brace-only scan
-/// either ran off the end (re-appending the prefix it had already emitted, double-counting every
-/// literal above it: that is the whole of `unit/mod.rs`'s row of "2") or, when any later item had
-/// a brace, matched THAT one and deleted every line between — hiding real drift with no trace.
+/// Cut every `#[cfg(test)]` item out of a source file before scanning it, so test fixtures do not
+/// count. An item ends at its brace or its semicolon, whichever comes first (`mod tests;`).
 fn strip_test_modules(src: &str) -> String {
     let mut out = String::with_capacity(src.len());
     let mut rest = src;
@@ -352,8 +269,7 @@ fn strip_test_modules(src: &str) -> String {
             // A braced item: brace-match it away.
             (Some(open), None) => brace_match(after, open),
             (Some(open), Some(semi)) if open < semi => brace_match(after, open),
-            // `mod tests;` / `use …;` — the item ends at its semicolon and its body, if it has
-            // one, is another file's problem.
+            // `mod tests;` or `use …;`: the item ends at its semicolon.
             (_, Some(semi)) => Some(semi + 1),
             (None, None) => None,
         };
@@ -385,8 +301,8 @@ fn brace_match(src: &str, open: usize) -> Option<usize> {
     None
 }
 
-/// Split a source file into `(fn name, body)` pairs — crude but enough to ask "does the enclosing
-/// function resolve a key?", which is the only question here.
+/// Split a source file into `(fn name, body)` pairs, enough to ask whether the enclosing function
+/// resolves a key.
 fn split_fns(src: &str) -> Vec<(&str, &str)> {
     let mut out = Vec::new();
     let bytes = src.as_bytes();
diff --git a/crates/benilla-app/tests/talent_frame.rs b/crates/benilla-app/tests/talent_frame.rs
index 3e3a1152..e2a01997 100644
--- a/crates/benilla-app/tests/talent_frame.rs
+++ b/crates/benilla-app/tests/talent_frame.rs
@@ -1,13 +1,6 @@
-//! Drives the reference's own `Blizzard_TalentUI` addon through the engine — the first test that
-//! executes the transcribed talent Lua at all (before this, the window's machinery only ever
-//! ran inside a live client session; both of the director's day-one reports — no prereq branch
-//! lines, no tooltip on first hover — slipped through that gap).
-//!
-//! The harness loads the same file chain the app does (`ui_script/mod.rs`'s list, cut to the
-//! talent window's dependency prefix), pushes a synthetic two-talent page shaped like the
-//! warrior's Improved Rend → Deep Wounds column, opens the window, and asserts at three
-//! depths: the Lua-visible state (`TALENT_BRANCH_ARRAY`), the logical frame state (`IsShown`),
-//! and the extract the renderer actually draws (branch/arrow quads with their atlas coords).
+//! Drives the stock `Blizzard_TalentUI` addon through the engine with a synthetic two-talent page
+//! shaped like the warrior's Improved Rend and Deep Wounds column, asserting the Lua state
+//! (`TALENT_BRANCH_ARRAY`), the frame state (`IsShown`) and the quads the renderer draws.
 
 mod common;
 
@@ -16,41 +9,33 @@ use benilla_ui::script::{
     UiScript, UnitState,
 };
 
-/// The talent window's load prefix — the app's own order (`assets/ui/benilla.toc`), members only.
-/// `ItemButtonTemplate.xml` is the `SetItemButton*` family the talent buttons grey through (the
-/// reference's own verb; see TalentFrame.xml's header) — it sits at .toc line 32, above every
-/// other entry here bar `Fonts.xml`.
+/// The talent window's load prefix, in `assets/ui/benilla.toc` order.
 const FILES: &[&str] = &[
-    // `PLAYER_LEVEL` and the rest of the strings the stock file formats through.
+    // `PLAYER_LEVEL` and the other strings the stock file formats.
     "Interface\\FrameXML\\GlobalStrings.lua",
     "Interface\\FrameXML\\Fonts.xml",
     // `TEXT`.
     "Interface\\FrameXML\\BasicControls.xml",
+    // `SetItemButtonDesaturated`, which the talent buttons grey through.
     "Interface\\FrameXML\\ItemButtonTemplate.xml",
     r"Interface\FrameXML\MoneyFrame.lua",
     r"Interface\FrameXML\MoneyFrame.xml",
+    // `ToggleTalentFrame` (`UIParent.lua:205`).
     r"Interface\FrameXML\UIParent.xml",
-    // `ToggleTalentFrame` lives here now, not in the window's own file (decision 1833).
     "Interface\\FrameXML\\GameTooltip.xml",
-    // `UIPanelScrollFrameTemplate` — the stock scroll frame's whole substance: its `$parentScrollBar`
-    // Slider AND its `<OnMouseWheel>`. Nothing else in the tree declares it, and a missing template
-    // is a loader WARNING, not an error, so without this the window still built — just with no
-    // scrollbar and no wheel (decision 1833). `load_ui_strict` below is what makes that loud.
+    // `UIPanelScrollFrameTemplate`: the scroll bar and the `<OnMouseWheel>`. A missing template
+    // is only a loader warning, so the window would build without them.
     r"Interface\FrameXML\UIPanelTemplates.lua",
     r"Interface\FrameXML\UIPanelTemplates.xml",
     "Interface\\FrameXML\\LocaleProperties.lua",
-    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine (1960)
-    // `TalentTabTemplate` inherits `CharacterFrameTabButtonTemplate`, and `inherits=`
-    // resolves at LOAD (1993).
+    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine
+    // `TalentTabTemplate` inherits `CharacterFrameTabButtonTemplate`; `inherits=` resolves at load.
     r"Interface\FrameXML\CharacterFrameTemplates.xml",
     "ScrollTemplates.xml",
-    // Stock `TalentFrame_OnShow` opens with `SetButtonPulse(TalentMicroButton, 0, 1)` and then
-    // `UpdateMicroButtons()` — both live here, and a nil `TalentMicroButton` throws out of OnShow
-    // BEFORE `TalentFrame_Update()`, so the whole window comes up empty (decision 1833). Our
-    // retired file's OnShow called neither, which is why this was never a dependency before.
+    // `TalentFrame_OnShow` pulses `TalentMicroButton` and calls `UpdateMicroButtons()`
+    // (`Blizzard_TalentUI.lua:97-100`); a nil button throws before `TalentFrame_Update()`.
     r"Interface\FrameXML\MainMenuBarMicroButtons.xml",
-    // Five files behind one line: the `.xml` sources its own `.lua` and `<Include>`s the
-    // templates file that declares TalentButton/Branch/Arrow/TabTemplate.
+    // Sources its own `.lua` and `<Include>`s the templates file.
     "Interface\\AddOns\\Blizzard_TalentUI\\Blizzard_TalentUI.xml",
 ];
 
@@ -60,10 +45,8 @@ fn load_ui(script: &UiScript) {
     }
 }
 
-/// The Improved Rend → Deep Wounds shape: a rank-3 prereq two tiers straight up the same
-/// column, the empty cell between them carrying the vertical branch (the classic vanilla look).
-/// `points_spent` decides the line's color: ≥10 unlocks tier 3 (yellow, `1`); fewer leaves it
-/// locked (gray, `-1`) — the reference draws the branch EITHER way.
+/// A rank-3 prereq two tiers up the same column, the empty cell between carrying the branch.
+/// `points_spent` of 10 or more unlocks tier 3 (yellow, `1`); fewer draws it gray (`-1`).
 fn fixture(points_spent: u32) -> TalentUiState {
     let rend = TalentView {
         name: "Improved Rend".into(),
@@ -110,14 +93,8 @@ fn fixture(points_spent: u32) -> TalentUiState {
     }
 }
 
-/// [`fixture`] plus a talent on the LAST tier, so the tree is taller than the scroll frame.
-///
-/// The stock `TalentFrameScrollChildFrame` is 50px in XML and is never resized by Lua — the
-/// reference derives its extent from the buttons anchored into it via `UpdateScrollChildRect`
-/// (`Blizzard_TalentUI.lua:311`). So a two-talent tree genuinely does not scroll, and asking it to
-/// would be asserting our retired file's behaviour rather than the reference's: ours pinned the
-/// child to a fixed full-height rect, which made every tree scrollable regardless of content
-/// (decision 1833).
+/// [`fixture`] plus a last-tier talent, so the tree scrolls: the scroll child's extent comes from
+/// the buttons in it via `UpdateScrollChildRect` (`Blizzard_TalentUI.lua:311`).
 fn tall_fixture() -> TalentUiState {
     let mut state = fixture(10);
     let mut deep = state.talents[0][1].clone();
@@ -138,13 +115,8 @@ fn view(name: &str, desc: &str) -> SpellTooltipView {
     }
 }
 
-/// Hover a talent button the way a player does — the pointer, not a handler call.
-///
-/// The stock `Blizzard_TalentUITemplates.xml` writes the tooltip code INLINE in the button's
-/// `<OnEnter>` (`GameTooltip:SetOwner` + `GameTooltip:SetTalent`), so there is no named function to
-/// invoke the way our retired file's `BenillaTalentButton_OnEnter` could be (decision 1833). Moving
-/// the mouse is closer to the thing under test anyway: it drives the hit test as well as the
-/// handler.
+/// Hover a talent button with the pointer: the stock `<OnEnter>` is inline, with no named
+/// function to call.
 fn hover(script: &mut UiScript, frame: &str) {
     script.resolve();
     let (x, y): (f32, f32) = script
@@ -153,9 +125,7 @@ fn hover(script: &mut UiScript, frame: &str) {
     script.mouse_move(x, y);
 }
 
-/// A level-60 player. The reference's `ToggleTalentFrame` opens nothing below level 10 (decision
-/// 1833) — real behaviour, not a guard — so every opener here needs one. Our retired file had no
-/// such gate, which is why this fixture did not exist before.
+/// A level-60 player: `ToggleTalentFrame` opens nothing below level 10 (`UIParent.lua:206`).
 fn probe_player() -> UnitState {
     UnitState {
         exists: true,
@@ -171,9 +141,6 @@ fn open_window(points_spent: u32) -> UiScript {
     let mut script = UiScript::new().expect("engine");
     script.set_screen_size(1024.0, 768.0);
     load_ui(&script);
-    // The reference's `ToggleTalentFrame` opens nothing below level 10 (decision 1833) — that is
-    // real behaviour, not a guard, so the window needs a player who has talents at all. Our
-    // retired file had no such gate, which is why this fixture was never needed before.
     script.set_unit("player", Some(probe_player()));
     script.set_talents(fixture(points_spent));
     script.run("ToggleTalentFrame()").expect("toggle");
@@ -184,8 +151,7 @@ fn open_window(points_spent: u32) -> UiScript {
 fn branch_lines_draw_for_a_same_column_prereq() {
     let _data = benilla_formats::wow_data_or_skip!();
     let mut script = open_window(10);
-    // Depth 1 — the Lua machinery: Update ran, the branch array carries the vertical chain
-    // (tier 1's down-edge, the empty tier-2 cell's up+down, the button's own top arrow).
+    // The Lua state: tier 1's down edge, the empty tier-2 cell's up and down, tier 3's top arrow.
     script
         .run(
             r#"
@@ -198,7 +164,7 @@ fn branch_lines_draw_for_a_same_column_prereq() {
             "#,
         )
         .expect("branch array");
-    // Depth 2 — the pooled textures took the work: at least one branch + one arrow shown.
+    // The pooled textures: at least one branch and one arrow shown.
     script
         .run(
             r#"
@@ -207,8 +173,7 @@ fn branch_lines_draw_for_a_same_column_prereq() {
             "#,
         )
         .expect("pool state");
-    // Depth 3 — the renderer sees them: branch/arrow quads in the extract, cropped into the
-    // atlas (a full-sheet [0,1] crop means SetTexCoord never landed).
+    // The extract: atlas-cropped quads (a full-sheet crop means SetTexCoord never landed).
     script.resolve();
     let quads = script.extract();
     let branch = quads
@@ -242,9 +207,7 @@ fn branch_lines_draw_for_a_same_column_prereq() {
 fn tooltip_is_complete_on_the_first_hover() {
     let _data = benilla_formats::wow_data_or_skip!();
     let mut script = open_window(10);
-    // The app's feed owes the store every talent spell view up front (the spellbook's own
-    // arrival-driven contract) — with the views in place, the FIRST OnEnter must render the
-    // full tooltip: name line, description, the green hint.
+    // With the talent spell views stored up front, the first OnEnter renders the full tooltip.
     script.set_spell_tooltip(201, view("Improved Rend", "Bleed harder."));
     script.set_spell_tooltip(301, view("Deep Wounds", "Bleed on crit."));
     hover(&mut script, "TalentFrameTalent2");
@@ -263,8 +226,7 @@ fn tooltip_is_complete_on_the_first_hover() {
 fn tooltip_miss_still_shows_the_rank_line() {
     let _data = benilla_formats::wow_data_or_skip!();
     let mut script = open_window(10);
-    // The store is EMPTY (no views pushed): the ask-once fallback must still show a box with
-    // the talent head — never a blank hover — and record the ask for the app's resolver.
+    // An empty store: the fallback still shows the talent head and records the ask.
     hover(&mut script, "TalentFrameTalent2");
     script
         .run(
@@ -285,9 +247,7 @@ fn tooltip_miss_still_shows_the_rank_line() {
 #[test]
 fn a_locked_tier_still_draws_the_branch_gray() {
     let _data = benilla_formats::wow_data_or_skip!();
-    // The director's own day-one state: 2 points spent, tier 3 locked — the reference draws
-    // the chain anyway, gray (the `-1` keys of the texcoord tables; a typo'd negative key
-    // would error the draw loop and hide every line while the grid stays perfect).
+    // 2 points spent, tier 3 locked: the chain still draws, gray (the texcoord tables' `-1` keys).
     let script = open_window(2);
     script
         .run(
@@ -302,21 +262,8 @@ fn a_locked_tier_still_draws_the_branch_gray() {
         .expect("gray branch");
 }
 
-/// **B162 — an unavailable talent goes GREYSCALE, not merely dim.**
-///
-/// The reporter's own A/B: 1.12.1 at 0 talent points draws every unlearned icon in black and
-/// white; benilla drew them in full colour. The Lua was never wrong — it asked for the grey-out
-/// and the ask reached the region — but the engine had no `Texture:SetDesaturated`, so
-/// `SetItemButtonDesaturated`'s no-shader arm was the only one available and "greyed" meant a
-/// `SetVertexColor(0.65)` brightness multiply. On colourful art that reads as a slightly dimmer
-/// colourful icon, which is exactly what was reported.
-///
-/// So the assertion is on the DESATURATION FLAG reaching the renderer, not on the tint: the tint
-/// was always there and was never the thing that was missing. The fixture is the reporter's state
-/// — points spent, none left — and Deep Wounds' tier is locked besides.
-///
-/// The control is the same extract's learned talent: full colour, no flag. A regression that
-/// greys the whole tree passes the first assertion and fails this one.
+/// An unavailable talent reaches the renderer desaturated (`Texture:SetDesaturated`, via
+/// `SetItemButtonDesaturated`), not merely tinted; the learned talent is the control.
 #[test]
 fn an_unavailable_talent_reaches_the_renderer_desaturated() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -338,24 +285,20 @@ fn an_unavailable_talent_reaches_the_renderer_desaturated() {
     };
     let quads = script.extract();
 
-    // Deep Wounds: tier 3 with 2 points spent — locked, and the player has 2 points to spend, so
-    // this is the tier gate alone, not the no-points force-desaturate.
+    // Deep Wounds: locked by the tier gate alone, since the player still has points to spend.
     let (grey, tint) = icon(&quads, "Ability_BackStab");
     assert!(
         grey,
         "an unavailable talent's icon must carry the greyscale flag — the whole of B162"
     );
-    // The reference's own `(1, 0.65, 0.65, 0.65)` still SETS that tint, and on shader-capable
-    // hardware it has no effect on colour — the desaturated fragment discards the vertex RGB
-    // entirely (`Shaders\Pixel\Desaturate.bls`; decision 1330 corrected 1327 here). It is
-    // pinned anyway because the value must keep reaching the quad: it is what the no-shader arm
-    // would have drawn with, and its ALPHA is read on both paths.
+    // The stock 0.65 tint still reaches the quad: the desaturate shader
+    // (`Shaders\Pixel\Desaturate.bls`) discards its RGB, but its alpha is read on both paths.
     assert!(
         (tint[0] - 0.65).abs() < 1e-3,
         "the ref's 0.65 still lands on the quad (inert on RGB, live on alpha), got {tint:?}"
     );
 
-    // The control: Improved Rend is learned to max, so it is available — full colour, no flag.
+    // The control: Improved Rend, learned to max.
     let (grey, tint) = icon(&quads, "Ability_Gouge");
     assert!(!grey, "a learned talent must NOT be greyed");
     assert!(
@@ -367,11 +310,8 @@ fn an_unavailable_talent_reaches_the_renderer_desaturated() {
 #[test]
 fn a_wheel_spin_over_the_grid_scrolls_the_tree() {
     let _data = benilla_formats::wow_data_or_skip!();
-    // The wheel's whole chain, driven from the pointer entry point the app feeds: hit-test on
-    // a talent button, bubble to the ScrollFrame's OnMouseWheel, step the Slider, whose
-    // OnValueChanged pans the frame. This is the chain the 2051f4f8 rename broke silently —
-    // the handler called a helper by a name that no longer existed, and only a real spin (not
-    // a load) executes it.
+    // The whole chain: hit test on a talent button, bubble to the ScrollFrame's OnMouseWheel,
+    // step the Slider, whose OnValueChanged pans the frame.
     let mut script = UiScript::new().expect("engine");
     script.set_screen_size(1024.0, 768.0);
     load_ui(&script);
@@ -383,7 +323,7 @@ fn a_wheel_spin_over_the_grid_scrolls_the_tree() {
     let (x, y): (f32, f32) = script
         .eval("return TalentFrameTalent1:GetCenter()")
         .expect("talent 1 center");
-    // One notch DOWN (WoW convention: -1) — the handler steps the bar one valueStep forward.
+    // One notch down is -1; the handler steps the bar one valueStep forward.
     script.mouse_wheel(x, y, -1.0);
     script
         .run(
@@ -396,7 +336,6 @@ fn a_wheel_spin_over_the_grid_scrolls_the_tree() {
             "#,
         )
         .expect("wheel down");
-    // And the notch back up re-seats the top.
     script.mouse_wheel(x, y, 1.0);
     script
         .run(
diff --git a/crates/benilla-app/tests/trade_frame.rs b/crates/benilla-app/tests/trade_frame.rs
index 0ff05872..8e4292c5 100644
--- a/crates/benilla-app/tests/trade_frame.rs
+++ b/crates/benilla-app/tests/trade_frame.rs
@@ -1,25 +1,17 @@
-//! Drives the stock `Interface\FrameXML\TradeFrame.xml` through the engine (decision 0592 P1) — the
-//! trade twin of `mail_frame.rs`: it loads the same file chain the app does (cut to the trade
-//! window's dependency prefix), pushes a synthetic two-sided offer, opens the window with the app's
-//! own `TRADE_SHOW` event, and asserts the transcribed Lua actually paints — the named regions
-//! exist, both columns populate from a fed `TradeState`, the money coin trios render, and the
-//! accept glow tracks the `TRADE_ACCEPT_UPDATE(my, his)` args. This is the machine gate for the XML
-//! (a Lua error / missing global / wrong region name fails here); the director's eye judges only the *look*.
+//! Drives the stock `TradeFrame.xml` through the engine: pushes a synthetic two-sided offer, opens
+//! the window with `TRADE_SHOW`, and asserts the Lua paints both columns, the money and the accept
+//! glows that follow `TRADE_ACCEPT_UPDATE(my, his)`.
 
 mod common;
 
 use benilla_ui::script::{ScriptValue, TradeSideState, TradeSlotItem, TradeState, UiScript};
 
-/// The trade window's load prefix — the app's own order (`ui_script/mod.rs`), members only.
-/// MerchantFrame.xml rides along because TradeFrame.xml reuses its global `BenillaMoney_*` coin
-/// helpers (the two gold displays), so a load error in either fails here.
+/// The trade window's load prefix, in `assets/ui/benilla.toc` order.
 const FILES: &[&str] = &[
     "Interface\\FrameXML\\Fonts.xml",
     r"Interface\FrameXML\MoneyFrame.lua",
     r"Interface\FrameXML\MoneyFrame.xml",
-    // The money entry comes off the chain since 1882 — `MoneyInputFrameTemplate` and the
-    // `MoneyInputFrame_*` verbs the window's OnLoad calls. Seated straight after MoneyFrame.xml,
-    // which is benilla.toc's own order.
+    // `MoneyInputFrameTemplate` and the `MoneyInputFrame_*` functions the window calls.
     r"Interface\FrameXML\MoneyInputFrame.lua",
     r"Interface\FrameXML\MoneyInputFrame.xml",
     r"Interface\FrameXML\UIParent.xml",
@@ -28,9 +20,9 @@ const FILES: &[&str] = &[
     "Interface\\FrameXML\\GlobalStrings.lua",
     "Interface\\FrameXML\\BasicControls.xml",
     "Interface\\FrameXML\\LocaleProperties.lua",
-    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine (1960)
+    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine
     "Interface\\FrameXML\\GameTooltip.xml",
-    // The stock slot updates go through ItemButtonTemplate.lua's SetItemButton* helpers (1966).
+    // The slot updates go through `ItemButtonTemplate.lua`'s `SetItemButton*` helpers.
     r"Interface\FrameXML\ItemButtonTemplate.xml",
     "Interface\\FrameXML\\TradeFrame.xml",
 ];
@@ -53,7 +45,7 @@ fn item(item_id: u32, name: &str, count: u32, quality: u32) -> TradeSlotItem {
     }
 }
 
-/// A two-sided offer: we offer Linen Cloth ×5 + 1g23s45c; the partner offers Silk Cloth + 5s.
+/// We offer Linen Cloth ×5 and 1g 23s 45c; the partner offers Silk Cloth and 5s.
 fn state() -> TradeState {
     let mut player = TradeSideState {
         gold: 12_345,
@@ -86,7 +78,7 @@ fn trade_frame_loads_and_key_regions_exist() {
         "TradeRecipientItem7",
         "TradeFrameTradeButton",
         "TradeFrameCancelButton",
-        "TradePlayerInputMoneyFrameGold", // our gold is now the editable input (P2)
+        "TradePlayerInputMoneyFrameGold", // our gold is the editable input
         "TradeRecipientMoneyFrameCopperButton",
         "TradeHighlightPlayer",
         "TradeHighlightRecipientEnchant",
@@ -107,8 +99,8 @@ fn trade_show_opens_and_both_columns_populate() {
     let mut s = UiScript::new().unwrap();
     load_ui(&s);
     s.set_trade(Some(state()));
-    // The stock header reads `UnitName("NPC")` — the partner rides the shared "npc" booth the
-    // app's session feed points at them (1966).
+    // The stock header reads `UnitName("NPC")` (`TradeFrame.lua:43`); the app points the "npc"
+    // unit at the partner.
     s.set_unit(
         "npc",
         Some(benilla_ui::script::UnitState {
@@ -123,11 +115,8 @@ fn trade_show_opens_and_both_columns_populate() {
         s.eval::<bool>("return TradeFrame:IsShown()").unwrap(),
         "the window opens on TRADE_SHOW"
     );
-    // ...and it is SLOTTED into the left panel, not merely Show()n unpositioned. Without the
-    // UIPanelWindows["TradeFrame"] row, ShowUIPanel takes its unregistered branch — a bare
-    // frame:Show() with no SetLeftFrame placement — which still flips IsShown() but leaves the
-    // window off its panel slot, so it never lands on screen (the live "OPEN_WINDOW arrived on both
-    // clients, yet no window" bug). This is the assertion that catches that missing registration.
+    // Slotted into the left panel by its `UIPanelWindows` row (`UIParent.lua:27`); unregistered,
+    // `ShowUIPanel` only calls `Show()` and the window never lands on screen.
     assert_eq!(
         s.eval::<String>("return GetLeftFrame() and GetLeftFrame():GetName() or ''")
             .unwrap(),
@@ -135,7 +124,6 @@ fn trade_show_opens_and_both_columns_populate() {
         "TRADE_SHOW slots the window into the left panel"
     );
 
-    // Our slot 1 and the partner's slot 1 painted their names + icons from the fed state.
     assert_eq!(
         s.eval::<String>("return TradePlayerItem1Name:GetText()")
             .unwrap(),
@@ -151,7 +139,7 @@ fn trade_show_opens_and_both_columns_populate() {
             .unwrap(),
         "a filled slot shows its icon"
     );
-    // An empty slot clears its name (the stock's `SetText(nil)`) + hides its icon.
+    // An empty slot clears its name (`SetText(nil)`) and hides its icon.
     assert!(s
         .eval::<Option<String>>("return TradePlayerItem2Name:GetText()")
         .unwrap()
@@ -161,17 +149,14 @@ fn trade_show_opens_and_both_columns_populate() {
         .eval::<bool>("return TradePlayerItem2ItemButtonIconTexture:IsShown()")
         .unwrap());
 
-    // The partner's name paints from GetTradePartnerName().
+    // The partner's name paints from `UnitName("NPC")`, set up above.
     assert_eq!(
         s.eval::<String>("return TradeFrameRecipientNameText:GetText()")
             .unwrap(),
         "Thrall"
     );
 
-    // The partner's read-only money rendered exactly one coin for 5s: TARGET_TRADE is a COLLAPSING
-    // type (MoneyTypeInfo.collapse), so gold and copper hide and silver alone stands — the
-    // reference's own rule, and the one this fixture was written to show. Our own gold is the
-    // editable input, exercised in `player_money_input_reflects_then_offers`.
+    // `TARGET_TRADE` collapses (`MoneyFrame.lua:69`), so 5s shows the silver coin alone.
     assert!(s
         .eval::<bool>(
             "return TradeRecipientMoneyFrameSilverButton:IsShown() \
@@ -189,15 +174,14 @@ fn enchant_slot_shows_the_not_traded_note() {
     let mut s = UiScript::new().unwrap();
     load_ui(&s);
     let mut st = state();
-    // Park an item in our enchant slot (index 6 = slot 7).
+    // Our enchant slot: index 6, slot 7.
     st.player.slots[6] = Some(item(6217, "Copper Rod", 1, 1));
     s.set_trade(Some(st));
     s.fire_event("TRADE_SHOW", vec![]);
-    // Slot 7 with an item but no enchant shows the coloured "will not be traded" note.
     assert_eq!(
         s.eval::<String>("return TradePlayerItem7Name:GetText()")
             .unwrap(),
-        // The stock wording, TRADEFRAME_NOT_MODIFIED_TEXT (ours had read "Will Not Be Traded").
+        // `TRADEFRAME_NOT_MODIFIED_TEXT` (`TradeFrame.lua:64`).
         "|cffffffffItem not yet modified|r"
     );
     assert!(s.take_errors().is_empty());
@@ -210,12 +194,12 @@ fn accept_update_drives_the_column_glows() {
     load_ui(&s);
     s.set_trade(Some(state()));
     s.fire_event("TRADE_SHOW", vec![]);
-    // Highlights start hidden (TradeFrame_Update hides all four).
+    // `TradeFrame_Update` hides all four highlights.
     assert!(!s
         .eval::<bool>("return TradeHighlightRecipient:IsShown()")
         .unwrap());
 
-    // The partner accepts: their column + enchant glow show, ours stay hidden.
+    // The partner accepts: their column and enchant glow show, ours stay hidden.
     s.fire_event(
         "TRADE_ACCEPT_UPDATE",
         vec![ScriptValue::Int(0), ScriptValue::Int(1)],
@@ -230,7 +214,7 @@ fn accept_update_drives_the_column_glows() {
         .eval::<bool>("return TradeHighlightPlayer:IsShown()")
         .unwrap());
 
-    // We accept: our glow shows and the Trade button disables (the reference's own-accept lock).
+    // We accept: our glow shows and the Trade button disables.
     s.fire_event(
         "TRADE_ACCEPT_UPDATE",
         vec![ScriptValue::Int(1), ScriptValue::Int(0)],
@@ -253,13 +237,13 @@ fn closing_the_window_queues_the_cancel() {
     s.fire_event("TRADE_SHOW", vec![]);
     let _ = s.take_trade_close();
 
-    // The X button hides the window → OnHide → CloseTrade queues the local close/cancel verb.
+    // The X hides the window, and its OnHide's `CloseTrade` queues the close.
     s.run("TradeFrameCloseButton:Click()").unwrap();
     assert!(!s.eval::<bool>("return TradeFrame:IsShown()").unwrap());
     assert!(s.take_trade_close(), "closing queued the CloseTrade intent");
     assert!(s.take_errors().is_empty());
 
-    // TRADE_CLOSED from the server-driven path also hides it.
+    // A server-driven `TRADE_CLOSED` also hides it.
     s.fire_event("TRADE_SHOW", vec![]);
     assert!(s.eval::<bool>("return TradeFrame:IsShown()").unwrap());
     s.fire_event("TRADE_CLOSED", vec![]);
@@ -280,14 +264,15 @@ fn trade_button_click_queues_accept() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The editable player money input (decision 0592 P2): the server's PLAYER_TRADE_MONEY echo reflects
-/// the accepted gold into the three boxes without re-offering (the diff-guarded SetCopper), and a
-/// keystroke offers the running copper total through SetTradeMoney → the app's SET_TRADE_GOLD.
+/// `PLAYER_TRADE_MONEY` fills the three boxes from `GetPlayerTradeMoney()` without re-offering,
+/// and a keystroke offers the copper total through `SetTradeMoney`. vmangos never echoes our own
+/// gold (it sends it to the partner only, `TradeData.cpp:118`); the app sets it client-side and
+/// fires the event.
 #[test]
 fn player_money_input_reflects_then_offers() {
     let _data = benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
-    s.set_money(1_000_000); // SetTradeMoney is purse-gated (1965)
+    s.set_money(1_000_000); // SetTradeMoney is purse-gated
     load_ui(&s);
     s.set_trade(Some(state())); // state().player.gold == 12345 (1g 23s 45c)
     s.fire_event("TRADE_SHOW", vec![]);
@@ -303,8 +288,7 @@ fn player_money_input_reflects_then_offers() {
         );
     }
 
-    // Reflection: PLAYER_TRADE_MONEY fills the boxes from GetPlayerTradeMoney(), guarded so the
-    // programmatic fill does NOT re-offer (no spurious SET_TRADE_GOLD).
+    // The programmatic fill must not re-offer.
     let _ = s.take_trade_money();
     s.fire_event("PLAYER_TRADE_MONEY", vec![]);
     assert_eq!(
@@ -323,12 +307,11 @@ fn player_money_input_reflects_then_offers() {
         "the guarded reflect does not re-offer"
     );
 
-    // A genuine keystroke offers the running total (bypass the affordability clamp — a bare harness
-    // has no purse).
+    // Lift the affordability clamp (`TradeFrame.lua:164`) for a typed offer.
     s.run("GetMoney = function() return 100000000 end").unwrap();
     s.run("TradePlayerInputMoneyFrameGold:SetText('2')")
         .unwrap();
-    s.tick(0.0); // the deferred OnTextChanged drains here (decision 1831)
+    s.tick(0.0); // the deferred OnTextChanged drains here
     assert_eq!(
         s.take_trade_money(),
         Some(2 * 10000 + 23 * 100 + 45),
@@ -337,20 +320,17 @@ fn player_money_input_reflects_then_offers() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The trade slot buttons route through the shared drop handler (decision 0592 P2): clicking OUR
-/// filled slot clears it (ClickTradeButton → CLEAR_TRADE_ITEM), while the partner's column is inert
-/// (ClickTargetTradeButton). Exercises the real button OnClick → BenillaTradeSlot_OnClick →
-/// player/recipient name-dispatch, without needing a cursor payload (the empty-cursor clear path).
+/// With an empty cursor, clicking our filled slot clears it (`ClickTradeButton`), while the
+/// partner's column calls `ClickTargetTradeButton`, which queues nothing (`TradeFrame.xml:101`).
 #[test]
 fn slot_click_routes_player_to_clear_and_recipient_to_inert() {
     let _data = benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     load_ui(&s);
-    s.set_trade(Some(state())); // player slot 1 + recipient slot 1 are both filled
+    s.set_trade(Some(state())); // both slot 1s are filled
     s.fire_event("TRADE_SHOW", vec![]);
     let _ = s.take_trade_clear_items();
 
-    // Our filled slot 1 clicked with an empty cursor → a clear routed through ClickTradeButton.
     s.run("TradePlayerItem1ItemButton:Click()").unwrap();
     assert_eq!(
         s.take_trade_clear_items(),
@@ -358,8 +338,6 @@ fn slot_click_routes_player_to_clear_and_recipient_to_inert() {
         "clicking our filled slot clears it (ClickTradeButton)"
     );
 
-    // The partner's filled slot is read-only — the click hits ClickTargetTradeButton, which queues
-    // nothing on either channel.
     s.run("TradeRecipientItem1ItemButton:Click()").unwrap();
     assert!(
         s.take_trade_clear_items().is_empty() && s.take_trade_set_items().is_empty(),
diff --git a/crates/benilla-app/tests/tradeskill_frame.rs b/crates/benilla-app/tests/tradeskill_frame.rs
index 8adfc817..c13dee1a 100644
--- a/crates/benilla-app/tests/tradeskill_frame.rs
+++ b/crates/benilla-app/tests/tradeskill_frame.rs
@@ -1,14 +1,6 @@
-//! Drives the reference's own `Blizzard_TradeSkillUI` addon through the engine — the crafting-book
-//! twin of `talent_frame.rs`, and the first test that executes the transcribed tradeskill Lua at
-//! all (the polish pass's own discovery: no suite loaded this file, so a runtime bug in the
-//! Show/Update/dropdown code would only ever surface in a live session).
-//!
-//! The harness loads the same file chain the app does (`ui_script/mod.rs`'s list, cut to the
-//! tradeskill window's dependency prefix), pushes a synthetic two-group Blacksmithing book,
-//! opens the window with the app's own `TRADE_SKILL_SHOW`, and exercises the polish-pass
-//! surface end-to-end: the CollapseAll tab (text, fold-all round trip through the engine's
-//! touched-flag → `TRADE_SKILL_UPDATE` contract), and both filter dropdowns (capsule default
-//! text, a REAL menu-row click driving the exclusive filter, the "All" row restoring it).
+//! Drives the stock `Blizzard_TradeSkillUI` and `Blizzard_CraftUI` addons off the player's chain
+//! with a synthetic book and the app's own show events: the CollapseAll tab, the filter menus,
+//! the reagent slots and the list rows' selection and hover.
 
 use benilla_ui::script::{
     CraftRecipe, CraftState, CraftTooltip, TradeSkillDifficulty, TradeSkillReagent,
@@ -17,9 +9,7 @@ use benilla_ui::script::{
 
 mod common;
 
-/// The tradeskill window's load prefix — the app's own order (`ui_script/mod.rs`), members only.
-/// CraftFrame.xml rides along (it loads right after TradeSkillFrame.xml in the app and shares
-/// its guarded-global utilities) so a load error in EITHER window fails here.
+/// The load prefix of both windows, in the app's order.
 const FILES: &[&str] = &[
     "Interface\\FrameXML\\Fonts.xml",
     r"Interface\FrameXML\MoneyFrame.lua",
@@ -30,21 +20,17 @@ const FILES: &[&str] = &[
     "Interface\\FrameXML\\GlobalStrings.lua",
     "Interface\\FrameXML\\BasicControls.xml",
     "Interface\\FrameXML\\LocaleProperties.lua",
-    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine (1960)
+    "Interface\\FrameXML\\StaticPopup.xml", // the dialog engine
     "Interface\\FrameXML\\GameTooltip.xml",
     "Interface\\FrameXML\\UIDropDownMenu.xml",
     "ScrollTemplates.xml",
-    // The stock windows open from UIParent's own TRADE_SKILL_SHOW / CRAFT_SHOW arms (its
-    // `*_LoadUI` then `*_Show`), not from a registration of their own — so UIParent.xml is a
-    // dependency of the event path this suite drives (1973). With no addon registry here the
-    // load reports ADDON_LOAD_FAILED through `message`, which is a shown frame, not an error.
-    // The reference's own addons (1973), off the chain — both inherit the trainer window's
-    // list/detail kit, which the manifest seats above them. An integration test has no addon
-    // registry, so the files load as chain files, the way the manifest's own entries do.
+    // Both windows open from UIParent's TRADE_SKILL_SHOW / CRAFT_SHOW arms (`*_LoadUI`, then
+    // `*_Show`). With no addon registry the addons load as chain files, and `*_LoadUI` reports
+    // ADDON_LOAD_FAILED through `message`, a shown frame, not an error.
+    // Both addons inherit the trainer window's list and detail templates.
     r"Interface\FrameXML\ClassTrainerFrameTemplates.xml",
-    // The reagent slots inherit `QuestItemTemplate` (147x41) through the addons' own row templates,
-    // and the selection paints them with `SetItemButtonTexture`/`SetItemButtonCount`, which are
-    // ItemButtonTemplate.lua's — both chain files the manifest seats above the addons.
+    // The reagent slots inherit `QuestItemTemplate` and are painted with `SetItemButtonTexture`
+    // and `SetItemButtonCount` (`ItemButtonTemplate.lua`).
     r"Interface\FrameXML\ItemButtonTemplate.xml",
     r"Interface\FrameXML\QuestFrameTemplates.xml",
     r"Interface\AddOns\Blizzard_TradeSkillUI\Blizzard_TradeSkillUI.xml",
@@ -52,9 +38,8 @@ const FILES: &[&str] = &[
 ];
 
 fn load_ui(script: &UiScript) {
-    // `common::load_ui`, not a local read: a manifest entry carrying a path separator is the
-    // REFERENCE's own file and has to come off the player's chain, which `std::fs::read` under
-    // `assets/ui` cannot do. This kit gained such an entry when the dropdown migrated (1751).
+    // `common::load_ui`: an entry with a path separator is a stock file read off the player's
+    // chain, not from `assets/ui`.
     for file in FILES {
         common::load_ui(script, file);
     }
@@ -78,7 +63,7 @@ fn recipe(
         cooldown_secs: None,
         product_item: spell_id + 10_000,
         product_inv_type,
-        product_item_level: 0, // neutral — this file's order pins fall through to the name
+        product_item_level: 0, // neutral: ordering falls through to the name
         reagents: vec![TradeSkillReagent {
             item: 2840,
             name: Some("Copper Bar".into()),
@@ -90,8 +75,8 @@ fn recipe(
     }
 }
 
-/// A two-group Blacksmithing book: Mail (a chest + a legs product) and Trade Goods (a non-equip
-/// stone → the 0x800000 catch-all slot) — the director's own reference-screenshot shape.
+/// A two-group Blacksmithing book: Mail (a chest and a legs product) and Trade Goods (a stone,
+/// which lands in the 0x800000 not-equippable slot).
 fn state() -> TradeSkillState {
     TradeSkillState {
         line: 164,
@@ -107,8 +92,7 @@ fn state() -> TradeSkillState {
     }
 }
 
-/// The app-side contract the window's event-driven repaints ride on: after any engine-side list
-/// mutator, drain the touched flag and fire `TRADE_SKILL_UPDATE` (drain_trade_skill's own shape).
+/// What the app does after a list mutator: drain the touched flag and fire `TRADE_SKILL_UPDATE`.
 fn pump(script: &mut UiScript) {
     if script.take_trade_skill_touched() {
         script.fire_event("TRADE_SKILL_UPDATE", vec![]);
@@ -130,15 +114,14 @@ fn collapse_all_tab_and_filter_dropdowns_work_end_to_end() {
     // 2 headers + 3 recipes.
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 5);
 
-    // The CollapseAll tab carries its GlobalString text (a cross-chunk local would render nil).
+    // The CollapseAll tab carries its GlobalString text.
     assert_eq!(
         s.eval::<String>("return TradeSkillCollapseAllButton:GetText()")
             .unwrap(),
         "All"
     );
 
-    // Fold everything through the tab: the click never calls Update() itself — the engine's
-    // touched flag + TRADE_SKILL_UPDATE (pump) is the whole repaint path, the ref's own contract.
+    // The click never calls Update() itself: the repaint rides TRADE_SKILL_UPDATE (`pump`).
     s.run("TradeSkillCollapseAllButton:Click()").unwrap();
     pump(&mut s);
     assert_eq!(
@@ -150,7 +133,7 @@ fn collapse_all_tab_and_filter_dropdowns_work_end_to_end() {
     pump(&mut s);
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 5);
 
-    // The dropdown capsules default to the "All …" texts (the OnShow/Initialize dance).
+    // The dropdowns default to the "All …" texts.
     assert_eq!(
         s.eval::<String>("return TradeSkillSubClassDropDownText:GetText()")
             .unwrap(),
@@ -161,7 +144,7 @@ fn collapse_all_tab_and_filter_dropdowns_work_end_to_end() {
             .unwrap(),
         "All Slots"
     );
-    // The InvSlot vocabulary: Chest(5) → bit 4, Legs(7) → bit 6, stone(0) → the catch-all.
+    // Chest (5) is bit 4, Legs (7) bit 6, the stone (0) the not-equippable slot.
     assert_eq!(
         s.eval::<(String, String, String)>("return GetTradeSkillInvSlots()")
             .unwrap(),
@@ -172,7 +155,7 @@ fn collapse_all_tab_and_filter_dropdowns_work_end_to_end() {
         )
     );
 
-    // A REAL menu-row click: open the SubClass menu, click "Trade Goods" (row 3: All + 2 groups).
+    // A menu-row click: "Trade Goods" is row 3 (All, then the two groups).
     s.run("ToggleDropDownMenu(1, nil, TradeSkillSubClassDropDown)")
         .unwrap();
     s.run("DropDownList1Button3:Click()").unwrap();
@@ -187,7 +170,7 @@ fn collapse_all_tab_and_filter_dropdowns_work_end_to_end() {
             .unwrap(),
         "Trade Goods"
     );
-    // The capsule follows the picked row on the next initialize (OnShow re-runs it).
+    // The dropdown text follows the picked row on the next initialize (OnShow re-runs it).
     s.run("TradeSkillSubClassDropDown:Hide() TradeSkillSubClassDropDown:Show()")
         .unwrap();
     assert_eq!(
@@ -204,9 +187,8 @@ fn collapse_all_tab_and_filter_dropdowns_work_end_to_end() {
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 5);
 }
 
-/// The Craft window's own CollapseAll tab is faithful-but-inert (a 1.12 craft list is a single
-/// skill-line group, so the header scan always finds zero and hides the tab — the file's own
-/// deviation note); this pins the load + the text attribute + the hidden-in-practice state.
+/// A 1.12 craft list has no headers, so `Blizzard_CraftUI.lua:269-282` always hides the Craft
+/// window's CollapseAll tab.
 #[test]
 fn craft_collapse_tab_loads_with_text_and_stays_hidden_for_a_flat_list() {
     benilla_formats::wow_data_or_skip!();
@@ -230,27 +212,18 @@ fn craft_collapse_tab_loads_with_text_and_stays_hidden_for_a_flat_list() {
     );
 }
 
-/// **The reagent slot IS `QuestItemTemplate`** — B250's pin, in both windows.
-///
-/// The ref's `TradeSkillItemTemplate` (Blizzard_TradeSkillUI.xml l.11-35) and `CraftItemTemplate`
-/// (Blizzard_CraftUI.xml l.29-53) each inherit `QuestItemTemplate` and override **only scripts**, so
-/// the slot's whole visual is that template's: 147×41, a 39×39 icon, the `UI-QuestItemNameFrame`
-/// plate on the icon's right edge, the name centred ON the plate, and the count on the icon's own
-/// BOTTOMRIGHT.
-///
-/// Every assertion here is one the shape that shipped before B250 would fail — a 140×32 slot with a
-/// 28×28 icon, no plate at all, the name top-anchored right of the icon and the count *below* the
-/// name. It is written that way on purpose (decision 1107's "so the sibling law would fail it"): the
-/// numbers alone would let a future session drift the slot back toward a hand-rolled shape with no
-/// test going red.
+/// `TradeSkillItemTemplate` (`Blizzard_TradeSkillUI.xml:11-35`) and `CraftItemTemplate`
+/// (`Blizzard_CraftUI.xml:29-53`) inherit `QuestItemTemplate` and override only scripts: a 147×41
+/// slot, a 39×39 icon, the name plate on the icon's right edge with the name centred on it, and
+/// the count on the icon's bottom-right corner.
 #[test]
 fn reagent_slots_carry_the_questitemtemplate_shape_in_both_windows() {
     benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     load_ui(&s);
 
-    // Both windows open (a slot's anchors resolve against a laid-out parent), and the slots this
-    // test measures are shown — the ref's own SetSelection shows one per reagent.
+    // Both windows open so the anchors resolve against a laid-out parent; the slots are shown as
+    // SetSelection shows one per reagent.
     s.set_trade_skill(Some(state()));
     s.fire_event("TRADE_SKILL_SHOW", vec![]);
     s.fire_event("CRAFT_SHOW", vec![]);
@@ -266,7 +239,7 @@ fn reagent_slots_carry_the_questitemtemplate_shape_in_both_windows() {
                 .unwrap_or_else(|e| panic!("{expr}: {e}"))
         };
 
-        // The row box: 147×41, the ref's QuestItemTemplate <Size>.
+        // QuestItemTemplate's <Size>.
         assert_eq!(
             (
                 num(&format!("{w}1:GetWidth()")),
@@ -276,21 +249,20 @@ fn reagent_slots_carry_the_questitemtemplate_shape_in_both_windows() {
             "{w}1 row box"
         );
 
-        // The 2-column grid: column 2 opens exactly one row-width right (Reagent2 anchors
-        // LEFT→Reagent1's RIGHT with a zero offset, so the pitch IS the row width) …
+        // Reagent2 anchors LEFT to Reagent1's RIGHT at zero offset, so the pitch is the row width,
         assert_eq!(
             num(&format!("{w}2:GetLeft()")) - num(&format!("{w}1:GetLeft()")),
             147.0,
             "{w} column pitch"
         );
-        // … and row 2 drops one row height plus the ref's own 2px gutter.
+        // and row 2 drops one row height plus a 2px gutter.
         assert_eq!(
             num(&format!("{w}3:GetTop()")) - num(&format!("{w}1:GetTop()")),
             -43.0,
             "{w} row step"
         );
 
-        // The icon (`$parentIconTexture`, the reference's own region name): 39×39 flush in the row's TOPLEFT corner.
+        // `$parentIconTexture`: 39×39, flush in the row's TOPLEFT corner.
         assert_eq!(
             (
                 num(&format!("{w}1IconTexture:GetWidth()")),
@@ -310,8 +282,7 @@ fn reagent_slots_carry_the_questitemtemplate_shape_in_both_windows() {
             "{w}1 icon flush top"
         );
 
-        // The name plate — the piece that was missing entirely. Its 128×64 texture starts 10px
-        // inside the icon's right edge and is centred on the icon's own middle.
+        // The 128×64 name plate starts 10px inside the icon's right edge, centred on the icon.
         assert_eq!(
             s.eval::<String>(&format!("return {w}1NameFrame:GetTexture()"))
                 .unwrap(),
@@ -332,8 +303,7 @@ fn reagent_slots_carry_the_questitemtemplate_shape_in_both_windows() {
             "{w}1 plate rides the icon's right edge"
         );
 
-        // The name sits ON the plate (+15 from its left), vertically centred — not above-right of
-        // the icon, where the pre-B250 shape put it.
+        // The name sits on the plate, 15 from its left, vertically centred.
         assert_eq!(
             num(&format!("{w}1Name:GetLeft()")) - num(&format!("{w}1NameFrame:GetLeft()")),
             15.0,
@@ -350,7 +320,7 @@ fn reagent_slots_carry_the_questitemtemplate_shape_in_both_windows() {
             "{w}1 name is centred on the plate ({nc} vs {pc})"
         );
 
-        // The count rides the ICON's bottom-right corner (-4, +1) — not a line below the name.
+        // The count sits on the icon's bottom-right corner (-4, +1).
         assert_eq!(
             num(&format!("{w}1Count:GetRight()")) - num(&format!("{w}1IconTexture:GetRight()")),
             -4.0,
@@ -368,25 +338,10 @@ fn reagent_slots_carry_the_questitemtemplate_shape_in_both_windows() {
     }
 }
 
-/// **A row click paints the selection glow, and a row hover paints nothing** — the two things the
-/// director saw wrong in a live window, pinned in both directions (decision 1598).
-///
-/// Neither was subtle. Both survived because this suite drove the window's tabs, dropdowns and
-/// reagent slots without ever clicking or hovering a LIST ROW:
-///
-///   * `TradeSkillFrame_Update` addressed `TradeSkillHighlight` — the *texture* — for
-///     the Hide/SetPoint/Show that the reference does on `TradeSkillHighlightFrame`, the *frame*
-///     (Blizzard_TradeSkillUI.lua l.99/142-143; only l.200's `SetVertexColor` is the texture's).
-///     The frame is declared `hidden="true"`, so it never once became visible and no selection ever
-///     highlighted. `CraftFrame.xml`/`TrainerFrame.xml` both split the two correctly already.
-///   * The row template carried a `GameTooltip:SetTradeSkillItem` OnEnter that the reference has no
-///     trace of: `TradeSkillSkillButtonTemplate` overrides `OnClick` alone, and its base
-///     `ClassTrainerSkillButtonTemplate` (`Interface\FrameXML\ClassTrainerFrameTemplates.xml`) only
-///     recolours `$parentSubText` on hover. The real window's list is bare on hover.
-///
-/// The hover half asserts through the row's own script table rather than a synthetic mouse-over, so
-/// it fails on the *existence* of a hover handler — re-adding one "harmlessly" goes red here even if
-/// the tooltip it opens happens to be empty in a headless VM.
+/// The selection glow is `TradeSkillHighlightFrame`, a `hidden="true"` frame the update moves
+/// and shows (`Blizzard_TradeSkillUI.lua:99`, `:142-143`); only the vertex colour goes on the
+/// `TradeSkillHighlight` texture (`:200`). A list row has no tooltip: its template overrides
+/// `OnClick` alone, and `ClassTrainerSkillButtonTemplate` only recolours `$parentSubText` on hover.
 #[test]
 fn a_row_click_shows_the_selection_glow_and_a_row_hover_shows_nothing() {
     benilla_formats::wow_data_or_skip!();
@@ -395,7 +350,7 @@ fn a_row_click_shows_the_selection_glow_and_a_row_hover_shows_nothing() {
     s.set_trade_skill(Some(state()));
     s.fire_event("TRADE_SKILL_SHOW", vec![]);
 
-    // Row 1 is the "Mail" header, row 2 the first recipe (the two-group book `state()` builds).
+    // Row 1 is the "Mail" header, row 2 the first recipe.
     assert_eq!(
         s.eval::<String>("local _, t = GetTradeSkillInfo(2) return t")
             .unwrap(),
@@ -403,8 +358,7 @@ fn a_row_click_shows_the_selection_glow_and_a_row_hover_shows_nothing() {
         "row 2 is a recipe, not a header (state()'s own difficulty)"
     );
 
-    // Opening already selects `GetFirstTradeSkill()` (the OnEvent path), so the glow is up before
-    // any click — exactly what the director's screenshot should have shown and didn't.
+    // Opening selects `GetFirstTradeSkill()` (OnEvent), so the glow is up before any click.
     let glow_on_row = |s: &UiScript, n: i64| {
         let (glow, row) = (
             s.eval::<f64>("return TradeSkillHighlightFrame:GetTop()")
@@ -421,7 +375,7 @@ fn a_row_click_shows_the_selection_glow_and_a_row_hover_shows_nothing() {
     );
     assert!(glow_on_row(&s, 2), "and it is parked on the first recipe");
 
-    // A click on the OTHER Mail recipe moves it, rather than leaving it at the window's TOPLEFT.
+    // A click on the other Mail recipe moves it.
     s.run("TradeSkillSkill3:Click()").unwrap();
     pump(&mut s);
     assert_eq!(
@@ -437,7 +391,7 @@ fn a_row_click_shows_the_selection_glow_and_a_row_hover_shows_nothing() {
         "the glow followed the click to row 3"
     );
 
-    // Fold every group away and no recipe row is visible to carry it.
+    // With every group folded no recipe row is visible to carry it.
     s.run("TradeSkillCollapseAllButton:Click()").unwrap();
     pump(&mut s);
     assert!(
@@ -446,15 +400,13 @@ fn a_row_click_shows_the_selection_glow_and_a_row_hover_shows_nothing() {
         "no recipe row on screen → no glow (headers never take the selection)"
     );
 
-    // The hover half. Positive control first, so a `GetScript` that answered nil for everything
-    // could not quietly pass the real assertions below: the reagent slot DOES tooltip on hover.
+    // Control: a reagent slot has an OnEnter, so `GetScript` reports real handlers.
     assert!(
         s.eval::<bool>("return TradeSkillReagent1:GetScript(\"OnEnter\") ~= nil")
             .unwrap(),
         "control: a reagent slot has an OnEnter, so GetScript reports real handlers"
     );
-    // The list row's hover is the trainer template's own — it recolours `$parentSubText` and
-    // nothing else (ClassTrainerFrameTemplates.xml): driven with `this` set, it opens no tooltip.
+    // The list row's hover is the trainer template's, which opens no tooltip.
     s.run("GameTooltip:Hide() this = TradeSkillSkill2 TradeSkillSkill2:GetScript(\"OnEnter\")()")
         .unwrap();
     assert!(
@@ -465,24 +417,11 @@ fn a_row_click_shows_the_selection_glow_and_a_row_hover_shows_nothing() {
         .unwrap();
 }
 
-/// **The recipe list lights its rows white — under the cursor, and on the selected one.** The
-/// director put the real client's Blacksmithing window next to ours: there, the hovered row and the
-/// selected row are both white, while every other recipe wears its difficulty colour. Ours wore the
-/// difficulty colour everywhere, hover and selection included.
-///
-/// One mechanism does both, and it is the row BUTTON's, not a script's.
-/// `ClassTrainerSkillButtonTemplate` — the base under this window's rows, Craft's and the class
-/// trainer's — declares `<HighlightFont inherits="GameFontHighlight">` (white) beside its
-/// `<NormalFont>`, and `TradeSkillFrame_Update` paints each row with
-/// `skillButton:SetTextColor(difficulty)` and then calls `LockHighlight()` on the selected one
-/// (Blizzard_TradeSkillUI.lua l.113/144). A `SetTextColor` writes the NORMAL font instance only, so
-/// it cannot reach a highlighted label — which is exactly why the reference's rows still turn white.
-///
-/// Ours could not, for two reasons that had to be fixed together (decision 1605): the row's label
-/// was a child `$parentName` FontString rather than the button's own `<ButtonText>`, so no per-state
-/// font could reach it; and the engine's highlighted label fell back to the normal state's colour,
-/// so even a ButtonText would have stayed orange. This test is the end-to-end pin — it reads the
-/// colour off the extracted text quad, not off any Lua state, so it fails if either half regresses.
+/// The hovered and the selected recipe rows are white, the rest their difficulty colour:
+/// `ClassTrainerSkillButtonTemplate` declares a white `<HighlightFont>`, and
+/// `TradeSkillFrame_Update` sets the difficulty with `SetTextColor`, which writes the normal font
+/// only, then `LockHighlight`s the selection (`Blizzard_TradeSkillUI.lua:113`, `:144`). The colour
+/// is read off the extracted text quad.
 #[test]
 fn a_hovered_or_selected_recipe_row_paints_its_label_white() {
     benilla_formats::wow_data_or_skip!();
@@ -492,8 +431,7 @@ fn a_hovered_or_selected_recipe_row_paints_its_label_white() {
     s.set_trade_skill(Some(state()));
     s.fire_event("TRADE_SKILL_SHOW", vec![]);
 
-    // Row 1 is the "Mail" header; rows 2 and 3 are its two Medium recipes, and opening the window
-    // auto-selects the first of them.
+    // Row 1 is the "Mail" header; rows 2 and 3 are its Medium recipes, and opening selects row 2.
     assert_eq!(
         s.eval::<i64>("return GetTradeSkillSelectionIndex()")
             .unwrap(),
@@ -501,8 +439,7 @@ fn a_hovered_or_selected_recipe_row_paints_its_label_white() {
         "the show-time auto-selection landed on the first recipe"
     );
 
-    // The label really is the button's own ButtonText now — a child FontString would leave
-    // GetFontString() nil and take every per-state font with it.
+    // The label is the button's ButtonText, the only region per-state fonts reach.
     assert!(
         s.eval::<bool>("return TradeSkillSkill2:GetFontString() ~= nil")
             .unwrap(),
@@ -589,13 +526,8 @@ fn a_hovered_or_selected_recipe_row_paints_its_label_white() {
     );
 }
 
-/// **The craft list lights the same way, off the same base template.** `CraftButtonTemplate` and
-/// `TradeSkillSkillButtonTemplate` both inherit `ClassTrainerSkillButtonTemplate`, so its
-/// `<HighlightFont inherits="GameFontHighlight">` is one mechanism serving both windows — and
-/// `Craft_Update` locks its selected row exactly as the tradeskill one does (Blizzard_CraftUI.lua
-/// l.234). Ours had the same `$parentName`-FontString workaround in both files, so fixing only the
-/// window the director was looking at would have left the enchanting book wrong beside it
-/// (decision 1605).
+/// The craft list lights the same way: `CraftButtonTemplate` inherits the same base template, and
+/// the update locks the selected row (`Blizzard_CraftUI.lua:234`).
 #[test]
 fn a_hovered_or_selected_craft_row_paints_its_label_white() {
     benilla_formats::wow_data_or_skip!();
diff --git a/crates/benilla-app/tests/ui_script_wall.rs b/crates/benilla-app/tests/ui_script_wall.rs
index ada6b811..786cb4c3 100644
--- a/crates/benilla-app/tests/ui_script_wall.rs
+++ b/crates/benilla-app/tests/ui_script_wall.rs
@@ -1,43 +1,24 @@
-//! **The reverse wall of decision 1177, measured** — how many files in `benilla-app` outside the
-//! VM's own module name `UiScript`.
+//! A ratchet on how many `benilla-app` files outside `ui_script/` name the Lua VM's `UiScript`:
+//! only the feed layer should know the FrameXML VM exists, and everything else produces model
+//! values.
 //!
-//! 1177 (2026-08-10) drew the line: the feed layer becomes one module, the only legitimate caller
-//! of the Lua VM, and everything else produces model values. Its instrument was 1160's — a wall
-//! test in `tests/` whose number is ratcheted down by the work — and it named the number: **141
-//! files**. The instrument was never built, and with nothing failing the count went the other
-//! way: 164 files by 2026-09-16 (decision 2265 §A3). This file is the instrument. It does not
-//! decide whether the crate move happens — that stays the director's — it only makes the number
-//! visible on every test run and refuses to let it grow unnoticed.
+//! A file counts if it contains the identifier `UiScript` anywhere (a type, a `use`, a doc
+//! comment). `CEILING` is the standing count of gameplay files and `SLACK` how far under it the
+//! count may sit, as in `world_api_wall.rs`. `WOW_UISCRIPT_DUMP=1` prints the files.
 //!
-//! "Outside the VM's module" means any `.rs` under `crates/benilla-app/src` whose path does not
-//! start with `ui_script/`; 1177's "feed module" does not exist yet, and when it does the
-//! exclusion moves there. A file counts if it contains the identifier `UiScript` at all — a type
-//! in a parameter list, a `use`, a doc comment naming the seam: each is a place that knows the
-//! FrameXML VM exists, which is the coupling 1177 measures.
-//!
-//! Same shape as `world_api_wall.rs`: `CEILING` is the standing count, `SLACK` keeps a single
-//! closure from failing the gate while making it impossible to bank a whole stage of work without
-//! writing the new number down. `WOW_UISCRIPT_DUMP=1` prints the files.
-//!
-//! **Four families, one gated** (decision 2338). The `ui_*` window feeds are 1177's feed layer
-//! in a hundred modules (2265 §A3 makes them one); `capture/` probes read the stock binding on
-//! purpose; test modules test. None of those is what 1177 meant, so they are reported, and only
-//! the remaining gameplay files — the ones that can reach zero — are ratcheted.
+//! Window feeds (`ui_*`), `capture/` probes and test modules are reported; only gameplay files,
+//! the ones that can reach zero, are gated.
 
 use std::path::{Path, PathBuf};
 
-/// Where a file that names the VM stands under 1177 (decision 2338).
+/// What kind of file names the VM.
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
 enum Family {
-    /// Gameplay code that knows the FrameXML VM exists — the camera, targeting, the minimap,
-    /// the sound layer, bindings, the glue screens. **1177's number**: the one this wall
-    /// gates, and the one that can reach zero.
+    /// Gameplay code that knows the FrameXML VM exists: the one family this wall gates.
     Game,
-    /// `ui_*` — a window's feed. 1177 makes the feeds THE legitimate caller; that they are a
-    /// hundred modules and not one is 2265 §A3's refactor, not a leak. Reported, never gated.
+    /// `ui_*`, a window's feed: the legitimate caller. Reported, never gated.
     Feed,
-    /// `capture/` — a live probe that asks the STOCK binding on purpose (2283, 2290): fed a
-    /// model value it would prove nothing. Reported.
+    /// `capture/`, a live probe that asks the stock binding on purpose. Reported.
     Probe,
     /// A test module beside the code it tests. Reported.
     Test,
@@ -56,16 +37,8 @@ fn family(rel: &str) -> Family {
     }
 }
 
-/// The standing count of **`Game`** files — gameplay code outside the feeds that names the VM.
-///
-/// **2026-09-16, 164** was the whole outside-`ui_script/` count the day the instrument was
-/// built, against 1177's 141 five weeks earlier; it moved to 167 the same day (2279's
-/// structural test, 2283's and 2290's probes — each legitimate, each written down here, and
-/// two sessions colliding on this line instead of quietly passing each other). **Decision 2338
-/// split the count**: of those 167, 96 were the window feeds, 18 the probes, 8 tests — none of
-/// them what 1177 meant — and **45** were gameplay files that know the VM. The wall gates the
-/// 45 and reports the rest, so the number here is one that can actually reach 1177's zero.
-const CEILING: usize = 45;
+/// The standing count of `Game` files; raise it only with the reason written down.
+const CEILING: usize = 40;
 
 /// How far under [`CEILING`] the count may sit before the test asks for the ceiling to follow it.
 const SLACK: usize = 4;
diff --git a/crates/benilla-app/tests/world_api_wall.rs b/crates/benilla-app/tests/world_api_wall.rs
index 246c71ae..087fdf48 100644
--- a/crates/benilla-app/tests/world_api_wall.rs
+++ b/crates/benilla-app/tests/world_api_wall.rs
@@ -1,46 +1,16 @@
-//! **The world API wall** — the doorway of `benilla-world`, counted from source on every
-//! `cargo test`, so it can never be measured once and then quietly widen.
+//! The world API wall: every `benilla-world` item that `benilla-app` code names, counted from
+//! source. [`PUBLISHED`] is the designed API, [`SORTED_LEAKS`] the crossings filed to close and
+//! how, and anything else that crosses is an unsorted leak. Only the leak count is ratcheted,
+//! toward zero; a table row nothing names any more fails the test until it is deleted.
 //!
-//! Decision 1160 splits the world renderer out of `benilla-app` into `benilla-world`, and its
-//! *secondary* falsifier is a number: if the engine's public vocabulary is much larger than a
-//! designed API, the cut line is wrong. 1163 measured it — **214 distinct engine items named by
-//! gameplay code** — and set the gate at **forty**, with the sort into DOWN / PUBLISH / CLOSE as
-//! the work. 1164 is that sort.
-//!
-//! A number in a decision record is a number nobody re-measures. This is the same measurement as
-//! a test, so every commit that closes a leak shows up as [`CEILING`] going down, and every commit
-//! that opens a new one fails the gate the day it lands rather than three weeks later.
-//!
-//! **It has two lives, and it switches by itself.** Before the move, the boundary is a naming
-//! convention: gameplay files reaching `crate::<engine module>::…`. After the move it is a real
-//! crate, and the same count is `benilla_world::…` in `benilla-app`'s sources. The scan below
-//! looks for `crates/benilla-world` and measures whichever world exists — so the ratchet survives
-//! stage two instead of being deleted by it.
-//!
-//! What it deliberately does **not** count: `#[cfg(test)]` bodies (a test naming an internal is
-//! not an API consumer), doc comments (a `[`crate::x::Y`]` link is prose), and the composition
-//! root's plugin registrations are counted like anything else — 1164's plugin-group collapse has
-//! to actually happen for them to stop counting.
-//!
-//! **Since decision 2338 the number that gates is the LEAKS, not the surface.** For five weeks
-//! the one number went up twenty-seven times, every raise a paragraph saying "a PUBLISH", and
-//! never once down: the falsifier 1163 set at forty had fired, and the ratchet had become a
-//! diary. So the sort is data now. [`PUBLISHED`] is the designed API, each row with the record
-//! that published it; [`SORTED_LEAKS`] is what 1164 filed to close and how; anything else that
-//! crosses is an unsorted leak. The surface and the published count are reported; only the leak
-//! count is ratcheted, and it ratchets toward zero. Adding a `PUBLISHED` row is the act that
-//! raising the ceiling used to be — a claim made in review, with its record — and a row nothing
-//! names any more fails the test until it is deleted, so the tables cannot rot.
+//! Not counted: `#[cfg(test)]` bodies (a test naming an internal is not an API consumer) and
+//! comments. Plugin registrations in the composition root count like anything else.
 
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 
-/// The engine's module set inside `benilla-app` — the cut line of 1160, written down.
-///
-/// This list is the pre-move definition of "the world". It is load-bearing in exactly one way: an
-/// engine module missing from it makes its leaks invisible to this test. It goes away at stage
-/// two, when `crates/benilla-world/` becomes the definition and the scan switches to the crate
-/// path (see the module docs).
+/// The engine's module set when the world lives inside `benilla-app`: an engine module missing
+/// here hides its leaks. Unused once `crates/benilla-world` exists, which the scan checks.
 const ENGINE_ROOTS: &[&str] = &[
     "art_scope",
     "assets",
@@ -93,39 +63,13 @@ const ENGINE_ROOTS: &[&str] = &[
     "zfill",
 ];
 
-/// The instruments — `debug_panel`, `perf`, `pipe_warm`, `art_scope`. They live inside the engine
-/// module set today (the world viewer boots them), but 1160 puts instruments at the *top* of the
-/// stack, not the bottom: extracting them early would publish hundreds of internals as permanent
-/// API shaped by what a debugger wanted to poke. So they are not part of the doorway being
-/// measured, and gameplay reaching into them is a different problem with a different record.
+/// The instruments inside the engine module set: they sit above the engine, so they are not part
+/// of the doorway being measured.
 const INSTRUMENT_ROOTS: &[&str] = &["art_scope", "debug_panel", "perf", "pipe_warm"];
 
-/// The instruments that ended up **above** the engine — `benilla-app` modules that consume
-/// `benilla-world` like any other caller.
-///
-/// 1164's rule is that an instrument's surface is not the engine's designed API: "1160 puts
-/// instruments at the top of the stack, and their surface is a different record's problem".
-/// 1167 corrected the *geography* — the compiler proved these three read the game and cannot live
-/// inside the engine — but the rule it was attached to still holds, and for the reason 1163 gave:
-/// an API whose target is set by what a debugger wanted to poke is the same failure as an API
-/// shaped by whichever `use` statement got written first.
-///
-/// So they are excluded from the gated number and **counted separately**, because a rule that
-/// hides a number is worse than no rule. `art_scope` is not here: it is registered by
-/// `WorldPlugins` and lives inside the engine, so it never crosses.
-///
-/// `crash` (decision 2266 §B2) is the fourth: the panic hook that writes the crash report. It is
-/// `perf::stall`'s sibling — a diagnostic that writes into `Diagnostics/` and nothing gameplay
-/// reads — and the one engine item it names, `log_ring::recent`, is a diagnostic feed kept beside
-/// the engine's `LogPlugin` because that is where the layer has to be installed. An API shaped
-/// by what a crash report wanted to attach is 1163's failure exactly, so it is counted here, not
-/// in the doorway.
-///
-/// `capture` (decision 2338) is the fifth, and the oldest ruling of the five: 1164 §Measured
-/// already counted `capture/*` among the instruments outside the doorway (its "21 named only by
-/// instruments"), but this list never said so, and a probe's reach — `static_gx::StaticGx`,
-/// `liquid::FoamPatch`, `ride_frame::ride_matrix`, the water-effect fixtures — was gated as if
-/// the game had asked for it. A probe that reads the engine's own state is what a probe is for.
+/// The `benilla-app` instruments (probes, the crash hook, the dev panels) that consume
+/// `benilla-world` like any caller. An API shaped by what a debugger wanted to poke is not the
+/// designed API, so what only they name is counted separately, outside the gate.
 const INSTRUMENT_CONSUMERS: &[&str] = &["capture", "crash", "debug_panel", "perf", "pipe_warm"];
 
 /// Is this file one of the app-side instruments?
@@ -134,15 +78,8 @@ fn is_instrument_consumer(rel: &str) -> bool {
     INSTRUMENT_CONSUMERS.contains(&root)
 }
 
-/// **The designed API** — every engine item game code may name, and the record that published
-/// it (decision 2338). `1164` is the sort's own PUBLISH bucket and its facades; a four-digit
-/// number is the record whose paragraph in the raise log below said "a PUBLISH"; `wall` is a
-/// raise-log paragraph that published the item without naming a record (grep the name below);
-/// `1167` published the facades the crate move landed; `2338` is the boot seam — the process-level
-/// entries a binary needs to run the engine at all (`worldview::run`, `tuned_default_plugins`,
-/// `BuildId`, the background-window and thread-QoS helpers), the same class as the three plugins
-/// the log already published. **Adding a row is a claim made in review, with its record.** A row
-/// no game file names any more fails the test until it is deleted.
+/// The designed API: every engine item game code may name, with the record that published it
+/// (`wall`: published without one). Adding a row is a claim made in review, with its record.
 const PUBLISHED: &[(&str, &str)] = &[
     ("bgwin::BgWinPlugin", "wall"),
     ("bgwin::background_run", "2338"),
@@ -239,14 +176,10 @@ const PUBLISHED: &[(&str, &str)] = &[
     ("worldview::run", "2338"),
 ];
 
-/// **The sorted leaks** — items 1164 filed to close, still crossing today, with the bucket it
-/// filed them under (decision 2338 moved the sort here from prose). `CLOSE/absorb` means a facade
-/// takes the call, `CLOSE/invert` the engine publishes the fact instead of the game reaching in,
-/// `CLOSE/move-engine` mis-filed engine code moving engine-side (the twelve `terrain_stream::*`
-/// items are `entities/wmo_props.rs`, 1164's fourth candidate, invisible until 2338's scanner
-/// fix), `CLOSE/move-game` gameplay moving out of the engine. A leak that is in neither table is
-/// unsorted: it crossed after 1164 and no record has said what happens to it. A row no game
-/// file names any more fails the test until it is deleted — closing a leak is deleting its row.
+/// The sorted leaks: crossings filed to close, with how. `CLOSE/absorb`: a facade takes the call;
+/// `CLOSE/invert`: the engine publishes the fact instead of the game reaching in;
+/// `CLOSE/move-engine`: engine code in a game file moves engine-side; `CLOSE/move-game`: gameplay
+/// moves out of the engine. Closing a leak is deleting its row.
 const SORTED_LEAKS: &[(&str, &str)] = &[
     ("billboard::BillboardJointRig", "CLOSE/absorb"),
     ("billboard::BillboardPlace", "CLOSE/absorb"),
@@ -347,409 +280,22 @@ const SORTED_LEAKS: &[(&str, &str)] = &[
     ("wmo_portal::WmoPvsSet", "CLOSE/absorb"),
 ];
 
-/// The gate — on the **leaks**. 1163 set the surface at forty; 1164 sorted it; 2338 made the
-/// sort data and pointed the ratchet at what is left to close. The raise log below is the
-/// history of the surface count this constant gated until then, and the source of every
-/// `PUBLISHED` row that names a record or `wall`.
-///
-/// **Lower it when you close something.** The lower bound below exists so that a session which
-/// closes twenty leaks cannot leave the ceiling standing at the old number, which would silently
-/// hand the next twenty leaks a free pass.
-///
-/// It has been raised **twelve times**, and every reason is worth keeping. 138 → 139: `ground_fx`
-/// moved into the engine, where 1164 says it belongs ("326 lines of pure render"), and the game
-/// now names one entry point (`spawn_ground_fx_decal`) where before it named none — it was calling
-/// a module in its own crate. A structural correction that costs one item and buys the lane's
-/// ordering law back from its caller; `ModelEffects` absorbs the entry point when it is built.
-///
-/// **150 → 176: the crate
-/// exists, and the count switched to the thing it was always a proxy for.** Two reasons it went up,
-/// both of them the measurement getting more honest rather than the doorway widening:
-///
-/// - The module-name scan excluded the *instruments* (`debug_panel`, `perf`, `pipe_warm`) as
-///   namers, on the assumption they travel with the engine. The compiler refuted that the moment
-///   the move was attempted: all three read the game, so they stayed in `benilla-app` — and they
-///   consume the engine API like any other consumer, which they always did.
-/// - `crate::x::Y` had to be parsed out of a naming convention. `benilla_world::x::Y` is a real
-///   path the compiler agrees with, so nothing hides behind a form the parser did not anticipate.
-///
-/// The number to work down is this one. It is also the last time it can be argued with: from here
-/// every item on it is a `pub` in `benilla-world`, and closing one is a demotion the compiler
-/// checks.
-///
-/// 149 → 150: `SPAWN_XY`, the
-/// streamer's last-ditch focus, moved out of `lib.rs` and into `terrain_stream` where it is used —
-/// an engine that cannot answer "where do I stream from" with no game attached is not an engine.
-/// The two gameplay readers (the player's boot pose, the world viewer's start) name it across the
-/// line now; it bought the one reverse crossing that neither wall could see.
-///
-/// 155 → 156:
-/// `model_fade::ModelFade` — 1164's alpha inversion, in one component. The game declares how
-/// translucent a root should be; the engine owns the write, the chain composition and the material
-/// swap. One published name for two impossible dependencies, and it retires a gameplay writer of a
-/// channel the reference gives one owner.
-///
-/// 153 → 155:
-/// `world_unit::{WorldUnit, ViewerUnit}` — a body in the world and the viewer's own, replacing
-/// five engine lanes' filters on the game's wire record. Two published markers for three
-/// impossible dependencies (`net::NetEntity`, `net::SelfPlayer`, `entities::CollisionHeight`).
-///
-/// 152 → 153: `view::Viewer`
-/// — the avatar as a *body* (where, how fast, which way, how tall) rather than as the game's
-/// `Player` type. Three engine lanes were reading it behind the identical predicate. One published
-/// resource for two impossible dependencies.
-///
-/// 148 → 152: `creature_anim`
-/// split along 1163's line — the rig machinery (pose evaluation, world/palette composition, the
-/// global-sequence channels) became `rig_anim` and the game kept the policy. The four are the real
-/// "pose a rig" vocabulary (`RigPose`, `RigFrame`/`RigAnchor`, `PosePost`, `GlobalSeqDrive`), and
-/// they belong beside `RigPalettes` and `RigSkin` in 1164's *place* face — a second program that
-/// spawns a skinned model has to pose it. They bought three impossible dependencies.
-///
-/// 147 → 148: 1160's wire
-/// (b). The engine stopped reading the game's four-variant session enum to learn whether a world
-/// exists and started reading its own one-bit `schedule::WorldLive`, which the session writes.
-///
-/// 145 → 147: 1160's wire
-/// (a) inverted. The streamer stopped reading `player::Player` and started reading
-/// `terrain_stream::ViewFocus`, which the game writes; and `WorldLoadProgress` — the streamer's
-/// own residency fact, which had been living in `loading_screen` — came home, so its two readers
-/// (the bar, and the mover's post-snap hold) now name it across the line. Two published inputs
-/// bought four reverse crossings, and the enforcer stopped needing a stub avatar to boot.
-///
-/// 143 → 145: two capture
-/// fixtures that had been living inside engine modules (`water_fx::view`, the foam viewer, and
-/// `particles::census`, the draw-address probe) moved out to `capture`, where they belong — and
-/// an instrument on the game side naming engine internals is a forward crossing where an
-/// instrument *inside* the engine was not counted at all. Same shape as the 160 → 162 raise
-/// below: the doorway did not widen, the measurement got honest. It closed three reverse
-/// crossings, including an engine plugin that had to name `capture` to register a fixture.
-///
-/// 142 → 143: the depth-bias
-/// ladder came together in `sky_order` as one `Rung` type. That is a genuinely new forward
-/// crossing — gameplay lanes now name an engine rung where before each kept its own constant —
-/// and it bought three REVERSE crossings, the ones that cannot exist at all once the crate does.
-/// One published rung against three impossible dependencies is the trade, and the ladder is
-/// engine API by 1164's own spine (a second program orders against the engine's frame).
-///
-/// 133 → 154, and this is the one to read first: it is not a leak, it is the wall admitting it
-/// had been lying. `expand` stopped walking at a brace, so `use benilla_world::interact::{A, B}`
-/// — the ordinary Rust import — collapsed to the bare module path and was then discarded as a
-/// prefix. Only items written out fully qualified at a *usage* site were ever counted. Every
-/// number this test has printed since the crate landed was an undercount of the same kind, and
-/// the honest surface is 154. Found by disagreement: a second scanner put the total one item
-/// lower while naming items this one had never heard of, and neither error was visible from
-/// either side alone. `WOW_API_DUMP=1` exists because of this.
-///
-/// And 160 → 162, the first one: moving
-/// `StreamActivity` out of `perf` and `DebugState` out of `debug_panel` did not widen the doorway,
-/// it stopped two engine facts hiding inside instrument modules this test deliberately does not
-/// count. The items were always crossing; the measurement improved. That is the only kind of raise
-/// that is not a retreat — a raise for a NEW leak is the failure this number exists to catch.
-///
-/// And 158 → 159: `vis_chain::VisChainOnly`, a PUBLISH by 1164's test (decision 1441). The
-/// chain-only visibility idiom — keep `Visibility`+`InheritedVisibility` (hide-propagation),
-/// remove `ViewVisibility` (the per-camera sweep row) — is an ENGINE law about bevy's visibility
-/// pipeline, but half the never-rendering hierarchy nodes it applies to are spawned game-side
-/// (net-object roots, held-item and spell-fx wrappers, transports). Keeping it engine-private
-/// would mean every game spawner hand-rolling `.remove::<ViewVisibility>()` with its own copy of
-/// the why — the exact drift a named idiom exists to prevent; the trait is the smallest honest
-/// carrier of the law.
-///
-/// And 157 → 158: `collision::ColliderEpoch`, a PUBLISH by 1164's test (decision 1384). It is the
-/// stamp on the world's collider set — "the geometry you last asked has changed" — and the whole
-/// point of it is that a *cached* collision answer must not outlive the world it described. The
-/// engine owns the fact (the streamer's attach queue is what changes the set), the game owns two of
-/// the three parties: the creature ground clamp reads it, and the GameObject hull lane
-/// (`entities::attach`) is the one collider insert outside the streamer's queue, so it must be able
-/// to stamp. Keeping it engine-private would mean either a game-side collider that no cache can see
-/// arrive — which is B197's bug with a different collider class — or an engine system reaching into
-/// game components to invalidate them, which crosses this line the other way and worse.
-///
-/// And 156 → 157: `mat_anim_table::MatAnimTable`, a PUBLISH by 1164's test (decision 1381). The
-/// mat-anim delta table replaced per-frame material mutation, and registration must happen where
-/// materials are BUILT — which for WMO GameObject props (transport interiors) is a game-side
-/// spawner (`entities::wmo_props`) that already threads the two registries this table serves
-/// (`UvAnimMaterials`/`TintAnimMaterials`, published members of the same family). The resource
-/// that allocates the slots is the smallest honest addition beside them; hiding it would mean
-/// a game-side material registering without a slot and silently freezing at its seed.
-///
-/// And 155 → 156: `doodad_anim::DoodadAnimHost`, a PUBLISH by 1164's test (decision 1365). The
-/// doodad joint collapse put placed doodads on the collapsed-rig lane (`RigPose`), which made
-/// them visible to the game's animation-LOD gate — whose park marker the engine's own doodad
-/// draw gate already owns, on a different law (the composed draw verdict + fade sphere, not the
-/// unit frustum test). Two writers to one marker silently un-park hidden hosts, so the game's
-/// gate must be able to say "this population is not mine" — and the engine component that IS
-/// that population's name is the smallest honest way to say it. The instruments already named
-/// it; this makes the one gameplay filter explicit rather than inventing a second marker to
-/// carry the same fact.
-///
-/// And 154 → 155: `modkeys::SyntheticHold`, a PUBLISH by 1164's test rather than a leak. The
-/// engine owns the macOS stuck-modifier reconciler, and that reconciler decides by polling the
-/// **hardware** flag state — which by construction reads "up" for a key no hand is on. So a
-/// synthesized press (the probe harness's `WOW_PROBE_KEY`) was released the frame after it was
-/// made, and logged as a stuck-key correction: every chord binding was silently unreachable
-/// headlessly on the platform we develop on. "Something is deliberately holding this key" has
-/// exactly one reader — the reconciler, engine-side — and its writers are whoever synthesizes
-/// input, which is game-side; a one-field resource is the smallest honest expression of that. The
-/// alternative was ordering a game system against an engine system, which crosses this same line
-/// *and* publishes a schedule point to do it.
-/// And 159 → 160: `WorldLoadProgress::gx_pending`, a PUBLISH beside the two residency terms
-/// already through this door (`colliders_pending`, `merge_pending`). The retained pass (1429)
-/// moved the static world off the entity path, so a placement that has SPAWNED still draws
-/// nothing until its region bakes — and the game reads residency for two decisions the engine
-/// does not own: when the loading cover may lift, and when the post-snap physics hold may
-/// release (decision 0737's split). Both were answering "is the world there" with a fact that
-/// had stopped meaning it (decision 1498). The alternative was the game reaching into
-/// `StaticGx` itself, which is a whole engine subsystem through the door instead of one
-/// `usize` on the residency struct that exists to be read from outside.
-/// And 160 → 161: `mac_quit::MacQuitPlugin`, a PUBLISH in the exact class of the two engine
-/// plugins already through this door — `thread_qos::ThreadQosPlugin` and `bgwin::BgWinPlugin`.
-/// All three correct a *host platform default* at launch, both composition roots name all three,
-/// and they sit outside `WorldPlugins` because they are properties of the process and its window
-/// rather than of the world. This one re-points macOS's `Cmd+Q` (winit's default menu wires it
-/// straight to `terminate:`, which exits without ever running another frame) at the window close,
-/// so the client's shutdown tail gets the frame it needs — decision 1528, where that gesture was
-/// measured on the real client writing *nothing*: no saved variables, no addon files, no camera
-/// pose. The alternative was hiding it inside `WorldPlugins` to keep the count flat, which is
-/// gaming the instrument rather than paying for a name.
-/// And 161 → 162: `particles::ViewThrottled`, a PUBLISH of the same shape as
-/// `rig_anim::AnimParked` already through this door — a marker the ENGINE reads and the GAME
-/// writes, which is the 1160 line drawn exactly where 1163 drew it. Freezing an emitter with the
-/// view that stopped drawing it is machinery (the draw-set law lives in `particles::sim`);
-/// deciding that a particular booth camera is being *paced* rather than put to sleep is policy,
-/// and it is `portrait::gate_booth_cameras`'s, in the game. There is no engine-side way to tell
-/// the two apart — a camera's `is_active` bit says only that it did not draw — which is precisely
-/// the conflation that ran the body panes' item effects at half speed (decision 1559, B312). The
-/// alternative was passing a `Res<PaneRate>`-shaped opinion down into the engine's own sim, which
-/// puts the game's knob inside the renderer to keep a count flat.
-/// And 162 → 163: `rig_rider::RigRider`, a PUBLISH of the same shape as `rig_anim::AnimParked`
-/// and `particles::ViewThrottled` above — a component the ENGINE reads and the GAME writes.
-/// Placing an attached model's vertices in its wearer's rig frame rather than in absolute f32
-/// world space is machinery (the whole lane is `rig_rider` + the palette's row writer, and the
-/// reason is arithmetic: at Elwynn's ~9481 yards the absolute sum lands on an 0.98 mm grid and is
-/// rebuilt every frame). *Which* bone a helm hangs from, and what a sheath swap does to that, is
-/// policy, and it is `entities::equipment`'s, in the game — the same M2 attachment table that
-/// decides where a weapon is drawn versus stowed. There is no engine-side way to know it: the
-/// engine sees a scene-graph child, and a child is not an attachment. The alternative was passing
-/// the game's attach-slot table down into the renderer to keep a count flat (decision 1609).
-/// And 163 → 164: `instance_tint::InstanceTintMirrors`, the twin of `rig_palette::RigPaletteMirrors`
-/// already through this door and registered at exactly the same site — an off-world `wow_light`
-/// buffer the engine must also fill with the per-instance tint region, because the shader reads
-/// that region out of whichever buffer the draw binds. Uploading a region to the buffers that
-/// carry it is machinery. *Which* off-world buffers carry it is policy, and it has to be: a
-/// portrait bake must NOT (the reference builds a fresh CM2 with colour `(1,1,1)`, so a ghost's
-/// portrait shows the living face — `0x524f60`, report B49, decision 1481)
-/// while the glue scene MUST (it is the screen itself, and its character component is the very
-/// instance the reference tints). The engine cannot tell those two render targets apart — both are
-/// a camera writing to an image — and encoding "a bake standing in for a UI model widget" inside
-/// the uploader is exactly the game opinion the wall exists to keep out. The alternative was
-/// mirroring the region into every registered buffer to keep the count flat, which re-opens B49 in
-/// the tint lane (decision 1731).
-/// And 164 → 165: `ffx_glow::GlueFfx`, a PUBLISH of the same shape as `rig_anim::AnimParked` and
-/// the two above — a resource the ENGINE reads and the GAME writes, and exactly ONE bit wide.
-/// Running an FFX pass pair is machinery; *which* pair a screen installs is the screen's own, and
-/// the reference says so by building two pairs (WorldFrame `0x481c46`, CGlueMgr `0x46a723`) and
-/// selecting between them at two different sites. The world's selector is already inside the
-/// engine's reach — `PLAYER_FLAGS_GHOST` on the live player — but the glue's is not and cannot be:
-/// it is the ghost bit of the **selected roster row** (`0x472fd9 test dh,0x20`), a character
-/// nobody is standing in, on a screen the engine has no concept of. The alternative was handing the
-/// renderer a roster to read to keep a count flat (decision 1731). Note the direction of travel:
-/// this replaced `FfxGlow::state_scale`, a float that let a bake inherit a player-state lane by
-/// arithmetic — the enum that took its place makes report B49's invariant structural.
-/// And 165 → 166: `collision::MoverTraceExclusions`, a PUBLISH in the same class as the two
-/// one-bit resources above — a resource the ENGINE reads and the GAME writes. The reference's
-/// world trace carries a per-trace mask, and the local mover's gains bit `0x8000` when the body it
-/// drives is a player in ghost form; the GameObject collision-candidacy virtual `0x5f85f0` reads
-/// it and drops every `GAMEOBJECT_TYPE_ID == 0` object, so a ghost walks through closed doors
-/// (decision 1767). The engine cannot compute that set — "a DOOR GameObject, while the player is a
-/// ghost" names two gameplay concepts, which is precisely what the wall pointing the other way
-/// forbids an engine file from knowing. The alternatives were both worse: dropping or re-laning
-/// the door's collider makes it stop existing for the particle snap, the precipitation probe, the
-/// mouse pick and the creature conform, none of which the binary touches; and threading a filter
-/// through `step`/`grounded_step`/`airborne_step` puts a gameplay argument into the movement
-/// core's signature. An `EntityHashSet` that is empty on every living frame is the smallest honest
-/// expression, and it makes the living player's query provably the one it always was.
-/// And 166 -> 172: **not six crossings — one measurement correction.** Nothing moved through the
-/// doorway; the scan was blind to part of every file. A `#[cfg(test)]` was cleared only on
-/// `depth < d`, and a top-level test module is seen at depth 0, rises to 1 and returns to 0 —
-/// never below it, so the first test module in a file switched the scan off for the rest of that
-/// file. [`paths_in`] carries the fix and how it surfaced (2026-09-01, a change that only *moved*
-/// a test module out of `net.rs` and pushed the count up by one with no new reference in its
-/// diff). These six were named by gameplay code all along, below a test module, uncounted:
-/// `lighting::WorldTime`, `art_scope::ArtScope`, `art_scope::ArtSlot`,
-/// `billboard::billboard_joint_palette`, `rig_anim::finalize_rig_worlds`, `world_unit::ViewerUnit`.
-/// Raising the number is what keeps the ratchet honest — a ceiling measured through a hole is not
-/// a ceiling — and it is the ratchet's own instruction: a count that cannot see the whole file
-/// cannot report a widening either, which is the one thing this test exists to do. The six are
-/// **not** hereby blessed as PUBLISH: they are un-sorted 1164 work, now visible enough to sort.
-/// And 172 → 173: `model_render::lazy::realize`, a PUBLISH. A built `WowModelMaterial` is no
-/// longer an asset the moment a spawner builds it — the engine parks the value behind a
-/// reserved handle and inserts the asset the first frame something visible is bound to it
-/// (decision 1940: 9.9k materials, 20.7k buffers and 10.2k bind groups were alive at the
-/// Stormwind auction house for 36 drawn entity batches, the variant set every spawner is handed
-/// and never switches to). A game lane that CLONES a material before anything binds it — the
-/// portrait booth relighting a part's twins onto its own light buffer, a spell kit deriving its
-/// per-instance tinted copy from the shared steady — asks the engine to realize it first. That
-/// is the whole of the crossing: one function, "make this handle's asset exist now", the
-/// doorway's own rule about when a material is real. The alternative — eager materials for
-/// the two lanes that read early — would put the store's law in the caller's hands.
-/// And 173 → 174: `particles::render::EFFECT_DRAW_STATS`, an instrument PUBLISH — the effect
-/// lane's own per-frame draw census (items in the transparent phase, draws after the merge),
-/// the number the `FPS_PROBE` line prints as `fx=`. It is the reading that refuted the
-/// additive-window regroup on the crowd rig (decision 1955): a lane whose merge walk is the
-/// only place the count exists has to publish it or stay unmeasurable.
-/// And 174 → 175: `dev_state::STILL_INPUTS_CHANGED`, an instrument PUBLISH — how many frames
-/// each whole-scene input of the still-frame skips (1979) read as changed. Counted in the
-/// world crate so the probe names ONE static instead of the four resources the skips read; the
-/// reading is what says whether a gate ever engages.
-/// And 175 → 176: `mat_anim_table::affine_row`, a PUBLISH. The mat-anim table's second row
-/// kind (decision 2019): a texture transform's rotation and scale as deltas from the identity,
-/// `[cos − 1, sin, sx − 1, sy − 1]`, so that row 0 — the pinned zero every static material
-/// reads — IS the identity. That encoding is the table's own law (the same zero-is-identity
-/// rule its translation rows and the tint table run under), and the shader's fold is written
-/// against it; a lane that owns rows in the table — the UI model tiles, sampling the cooldown's
-/// quadrant rotations off the pane's play head — has to write them in the table's encoding,
-/// not one of its own. One function, "encode this affine the way the table reads it".
-/// And 176 → 177: `mat_anim_table::MatAnimMirrors`, a PUBLISH — the mat-anim table's twin of
-/// `instance_tint::InstanceTintMirrors` (decision 2023). A lane whose materials bind a light
-/// buffer of their own reads the table out of THAT buffer, so the UI model tiles' rows — the
-/// cooldown sweep's rotations, written every frame off the pane's play head — reached a region
-/// nothing in a tile ever sampled until the tile's buffer was on a mirror list. Registered once
-/// at the tile renderer's startup, the same shape and the same reason as the palette mirror
-/// beside it.
-/// And 177 → 178: `model_fade::UnitRenderAlpha`, a PUBLISH — one streamed unit's live render
-/// alpha, composed from the unit ROOT's own presentation state. `ModelAlphas` beside it is the
-/// read side for a consumer that can wait for `PostUpdate`'s publish; this is the read side for
-/// one that cannot — the blob shadow runs in `Update`, and on the frame a unit's presentation
-/// begins the published component does not exist yet. Published as a door rather than as its
-/// three inputs (`UnitAppearFade`, `DespawnFade`, `model_render_alpha`) precisely because the
-/// lane that reconstructed the answer from parts got it wrong the same way every time: it read
-/// "no part is fading" as opaque, which is false of a *pending* unit, and put a full-strength
-/// shadow on the ground under an invisible creature for the length of a load. A caller asking
-/// one question cannot make that mistake; a caller handed the inputs can.
-/// And 178 → 179: `interior::NodeAmbient`, a PUBLISH — one light node's committed **ambient word
-/// alone**, the ramped chase toward `cap96(MOCV)`. `ParticleLight` beside it is the same words
-/// folded into the whole fixed-function term (`ambient + 0.9·diffuse + Σ lamps`), which is what a
-/// lit particle quad receives; this is the read side for a draw whose vertex format carries **no
-/// normal**, so the normal array is disabled outright and its term is the ambient product and
-/// nothing else (the weapon swing trail, decisions 2079/2086). Published rather than reconstructed
-/// for the reason the entry above gives: the caller cannot rebuild it from `ParticleLight` — the
-/// diffuse lobe and the MOLT points are already summed in and cannot be subtracted back out — and
-/// a caller that reached for the *scene* ambient instead, which is what this replaces, tinted
-/// every indoor trail with the sky.
-/// And 179 → 180: `weather::WeatherState`, a PUBLISH — the weather driver's own state, reached by
-/// `crate::cvars` because one byte of it (`weather_density`) is a **player setting** and 2181 gave
-/// it its switch. It is the same shape as `clutter::ClutterConfig` two rows of that table up: a
-/// resource the engine owns and the options window writes exactly one field of, welded to its CVar
-/// by `registered_defaults_mirror_the_code_truths`. Published as the state rather than as a
-/// density-only door for the reason the two entries above give in reverse — there is no
-/// reconstruction to get wrong here, the field is a `u8` the engine reads directly, and a
-/// one-field wrapper would be a second name for the same byte that the weld test would then have
-/// to hold in step with both sides. It was already on the far side of the wall as an INSTRUMENT
-/// item (the `#[cfg(feature = "dev")]` weather panel is its only other namer); what changed is
-/// that a game module names it now, which is exactly the crossing this gate exists to make
-/// visible.
-/// And 180 → 181: `final_pass::FinalPassTarget`, a PUBLISH — where a colour lane's final pass
-/// lands, as one noun (decision 2206). The client has two colour lanes that end in a full-screen
-/// decode: the world's (the FFXGlow combine, engine-side) and the UI's (`crate::ui_gamma`'s,
-/// game-side since 0254 — the interface is the game's). Both used to write bevy's main texture
-/// and let its `upscaling` blit copy the result out; 2206 has each render straight into its
-/// camera's target when the camera's output mode is `Skip`, and the rule that turns an output
-/// mode into a destination, a format and a scissor is one rule, not two copies of it that drift.
-/// It could not go the other way: moving the UI decode into the engine would put the UI lane's
-/// colour law on the wrong side of the wall. So the engine publishes the rule as one type with
-/// two associated functions, and the game names it once.
-/// And 181 → 182: `ffx_glow::FfxBackdrop`, a PUBLISH — the component that makes the world's
-/// FFX combine the first draw of the player-UI camera's main pass (decision 2234). The combine is engine-side
-/// (the world lane's byte math, 0161); the camera it now runs on is the game's (the interface,
-/// 0254); so the engine publishes the claim as one component the game puts on its camera and
-/// points at the world camera it owns, and the two nodes behind it stay private. It retires a
-/// full-window float image that one camera wrote and the next read back — the seam 1603 built
-/// and 2215 measured — and it could not go the other way for 2206's reason: the UI camera cannot
-/// move into the engine.
-/// And 182 → 183: `doodad_anim::register_fx_uv`, a PUBLISH — put one spell-effect material clone
-/// on the per-instance UV-scroll lane (decision 2282). The clone is the GAME's: `entities::spell_fx`
-/// makes it because one cast is one phase (the same reason 0271's animated tint clones it), and
-/// nothing engine-side knows an effect instance exists. Everything after that is the engine's —
-/// which registry, which delta-table row, which of 1408's two baked loop spellings, and the
-/// instance-clock law that separates this lane from the shared one. Published as ONE verb rather
-/// than as its three pieces (`UvLoop`'s effect variant, `register_uv`, the row) precisely because
-/// this lane's recurring bug is a caller that takes some of the pieces and not the rest: 2038's
-/// marked-but-unregistered parts froze every waterfall in the game for three days, and a
-/// registration without a row, or a row without a registration, is that same shape. One verb
-/// cannot be half-taken. It is also why the three pieces went back to `pub(crate)` in the same
-/// commit, which is the rare crossing that *lowers* the surface it replaces.
-/// And 183 → 184: `doodad_anim::UvLoops`, the argument of the verb above. A texture transform is
-/// ONE authored record with four baked channels — 1408's two translation spellings plus 2019's
-/// per-slot rotation and scaling — and which of them a batch fills is not a thing the caller gets
-/// to reason about: a scale-only transform (`Spells\GroundingTotem_Impact.mdx`) and a
-/// dead-slot-0 translation both answer `None` to the channel you would check first. So the struct
-/// carries the record whole, and `any()`/`open_offset()` on it are the two questions the game
-/// asks — which keeps the "does this batch animate" predicate and the "what does it open on" seed
-/// in the engine, where the bake's rules live, instead of copied into the effect attach where they
-/// would drift. Four positional `Option`s would have been the alternative, and swapping two of
-/// them is a silent wrong-channel bug the compiler cannot see.
-/// And 184 → 186, both for the ENTITY lane (decision 2295), which is the same crossing 2282 made
-/// for the effect lane and made for the same reason.
-/// `doodad_anim::register_entity_uv` is the second PUBLISH verb on this lane: put a unit /
-/// GameObject / held-item batch material on the UV lane, picking the shared clock or the
-/// instance's play head from the authored record rather than making the caller reason about it.
-/// It is a separate verb from `register_fx_uv` and not a flag on it because the two lanes differ
-/// in the one thing a caller cannot get right by accident — an effect's clocks are measured from
-/// its own attach (0856/0858) and a resident entity's are the scene's — and a boolean spelling of
-/// that would read as a preference.
-/// `model_render::EntityUvLane` is the argument `entity_variants` grew, and the crossing it buys
-/// is the point of the decision: building an entity batch's material and putting it on the lane
-/// are ONE act, so the engine takes the registry and the delta table *in the same call* instead of
-/// handing back six handles and trusting the game to register them. That is 2038's law spelled in
-/// the signature — a `play_uv` flip without a registration freezes every entity batch at its first
-/// key instead of its identity, which is a different wrong frame and not a fix — and it is why the
-/// lane is a bundle rather than three arguments a caller can pass two of.
-/// And 186 → 189, the second half of 2295 — the ONE entity population that needs a material of
-/// its own rather than the batch's, which the dressing path clones and registers because the
-/// clone has to exist before the part's interior and fade records are built from it.
-/// `doodad_anim::AnimMatPart` is the draw-scan marker, and it crosses for the reason 1375 put it
-/// at the spawn site in the first place: the marker and the registration are one predicate, and
-/// the game is where an entity part is spawned. The engine cannot insert it — it does not know
-/// an entity part exists — and a lane that let the two drift is 2038's three frozen days.
-/// `doodad_anim::register_tint` and `doodad_anim::TintLoop` are the tint channel's twins of the
-/// UV verbs above, for the same five batches on three GameObject models: `G_FreezingTrap`'s glow
-/// card, `OrgrimmarPentagram`, `ScholomanceCrystalBall01` — four of whose five batches bake
-/// **nothing** in file slot 0, so a shared material can only ever seed white however faithfully it
-/// is ticked. They were already `pub` for the world streamer; what crosses here is the game naming
-/// them, and it is the same crossing the UV half makes one line up.
-/// And 189 → 190: `terrain_stream::CurrentArea`, taken by `capture/probe_bg.rs` (decision 2290).
-/// It is the engine's own area authority — the `AreaTable.dbc` leaf under the player's feet, which
-/// the engine already publishes for its own audio and zone-text consumers — and the probe reports
-/// it for one reason: a battleground census has to be able to say *where the body actually is*,
-/// and a map id alone cannot. "Map 489" is true of the pen, the field and the graveyard alike; the
-/// area id is what told this instrument that the port lands at Silverwing Hold and that the
-/// release lands at the graveyard. The alternative was to re-derive the leaf in the probe from
-/// tiles the engine already resolved, which is the copy-the-rule drift this wall exists to stop.
-///
-/// **190 → the leaks (decision 2338).** The surface stood at 190 published-and-leaked items
-/// together; the tables above split it, `capture` joined the instruments as 1164 always counted
-/// it, and the scanner learned to read a `use` group that spans lines (nine imports, twenty-one
-/// items counted nowhere until then — see [`logical_lines`]). What this constant gates from here
-/// is the leak count alone, measured on the tree that lands.
+/// The gate on the leak count. Lower it when a leak closes.
 const LEAK_CEILING: usize = 107;
 
-/// How far under [`LEAK_CEILING`] the real count may sit before this test asks for the ceiling
-/// to be lowered. Slack, not tolerance: it keeps a single closure from failing the gate, while
-/// making it impossible to bank a whole stage of work without writing the new number down.
+/// How far under [`LEAK_CEILING`] the count may sit before the test asks for the ceiling to be
+/// lowered: one closure does not fail the gate, a whole stage of work cannot go unrecorded.
 const LEAK_SLACK: usize = 10;
 
 #[test]
 fn the_world_api_doorway_stays_shut() {
     let all = measure();
-    // Partition one: an item only an instrument names is the instruments' surcharge, not the
-    // designed doorway (see `INSTRUMENT_CONSUMERS`). One a game module *also* names is the doorway's.
+    // An item only an instrument names is outside the doorway (`INSTRUMENT_CONSUMERS`); one a
+    // game module also names is inside it.
     let (probes, surface): (BTreeMap<_, _>, BTreeMap<_, _>) = all
         .into_iter()
         .partition(|(_, files)| files.iter().all(|f| is_instrument_consumer(f)));
-    // Partition two (decision 2338): the doorway is the published API plus the leaks, and only
-    // the leaks gate.
+    // The doorway is the published API plus the leaks; only the leaks gate.
     let published_by: BTreeMap<&str, &str> = PUBLISHED.iter().copied().collect();
     let sorted_by: BTreeMap<&str, &str> = SORTED_LEAKS.iter().copied().collect();
     let both: Vec<&str> = published_by
@@ -769,8 +315,7 @@ fn the_world_api_doorway_stays_shut() {
         .keys()
         .filter(|k| sorted_by.contains_key(k.as_str()))
         .count();
-    // Always say the numbers: `cargo test -p benilla-app --test world_api_wall -- --nocapture`
-    // is the one-command answer to "where is the wall now".
+    // Always print the numbers (`--nocapture` shows them).
     eprintln!(
         "world API surface: {} items — {n} leaks (ceiling {LEAK_CEILING}, slack {LEAK_SLACK}; \
          {sorted} sorted by 1164, {} unsorted), {} published; + {} named only by the instruments",
@@ -780,9 +325,8 @@ fn the_world_api_doorway_stays_shut() {
         probes.len()
     );
 
-    // The tables are the sort. A row no game file names any more is a row to delete — a stale
-    // published row would let the item cross again for free, and a stale leak row is a closure
-    // nobody wrote down.
+    // A row no game file names any more must go: a stale published row would let the item cross
+    // again for free.
     let stale: Vec<&str> = PUBLISHED
         .iter()
         .map(|(k, _)| *k)
@@ -801,10 +345,7 @@ fn the_world_api_doorway_stays_shut() {
         stale.join("\n  ")
     );
 
-    // `WOW_API_DUMP=1` prints the surface itself, most-named first, each item with what the
-    // tables say about it. The count alone answers "is the wall holding"; it cannot answer
-    // "which item did that unit actually retire", and a unit that reads as net-zero is exactly
-    // when you need the list.
+    // `WOW_API_DUMP=1` prints the surface itself, most-named first, each item with its table tag.
     if std::env::var("WOW_API_DUMP").is_ok() {
         let tagged = |m: &BTreeMap<String, BTreeSet<String>>, tag: &dyn Fn(&str) -> String| {
             let mut rows: Vec<_> = m
@@ -852,9 +393,8 @@ fn the_world_api_doorway_stays_shut() {
     );
 }
 
-/// **The wall that points the other way.** 1160 stage one's other half: an engine file naming a
-/// gameplay item is a dependency `benilla-world` cannot express, so every one of these has to go
-/// before the crate can exist at all. Ratcheted to zero, and then the crate graph keeps it there.
+/// The wall that points the other way: an engine file naming a gameplay item is a dependency
+/// `benilla-world` cannot express. Zero, and the crate graph keeps it there.
 #[test]
 fn the_engine_names_nothing_of_the_game() {
     let surface = measure_back();
@@ -892,8 +432,8 @@ fn measure() -> BTreeMap<String, BTreeSet<String>> {
             .unwrap()
             .to_string_lossy()
             .to_string();
-        // Pre-move, the caller's own module decides which side of the line it is on; post-move,
-        // every file in this crate is on the game side by construction.
+        // Without the world crate the file's module decides its side; with it, every file here
+        // is on the game side.
         if (!split && is_engine(&rel)) || tests.contains(&rel) {
             continue;
         }
@@ -905,17 +445,9 @@ fn measure() -> BTreeMap<String, BTreeSet<String>> {
     drop_module_paths(out)
 }
 
-/// Drop every entry that is only the **path to** another entry.
-///
-/// `use benilla_world::particles::buffer;` exists so the file can write `buffer::EffectQuads`
-/// below, and that second form is the one worth counting. There is no syntactic way to tell a
-/// module path from a free function — `particles::buffer` and `mesh_tag::spawn_tag` look
-/// identical — but there is a structural one: a module path is a **strict prefix of something
-/// else that was named**, and a function is a prefix of nothing.
-///
-/// This generalises a special case that only caught single-segment modules and so missed
-/// `particles::buffer` by one level. A rule that needs a list of exceptions is usually the wrong
-/// rule; this one needs none.
+/// Drop every entry that is only the path to another entry: `particles::buffer` and
+/// `mesh_tag::spawn_tag` look alike, but a module path is a strict prefix of another named item
+/// and a function is a prefix of nothing.
 fn drop_module_paths(
     all: BTreeMap<String, BTreeSet<String>>,
 ) -> BTreeMap<String, BTreeSet<String>> {
@@ -928,18 +460,15 @@ fn drop_module_paths(
         .collect()
 }
 
-/// Every **gameplay** item named by an ENGINE file — the wall that points the other way.
-///
-/// Empty by construction once the crate exists: `benilla-world` does not depend on `benilla-app`,
-/// so a name that crosses this way is not a lint, it is a compile error. Before the move it is
-/// only a convention, and this is what holds it.
+/// Every gameplay item named by an engine file. Empty once the world crate exists, where such a
+/// name is a compile error.
 fn measure_back() -> BTreeMap<String, BTreeSet<String>> {
     let app = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
     if app
         .parent()
         .is_some_and(|c| c.join("benilla-world").is_dir())
     {
-        return BTreeMap::new(); // the crate graph is the enforcement now
+        return BTreeMap::new(); // the crate graph enforces it
     }
     let mut out: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
     let src = app.join("src");
@@ -953,8 +482,7 @@ fn measure_back() -> BTreeMap<String, BTreeSet<String>> {
         if tests.contains(&rel) {
             continue;
         }
-        // Instruments are allowed to see both sides — 1160 puts them at the top of the stack, so
-        // they are not part of the engine being extracted and their reads are a later record's.
+        // Instruments may see both sides: they sit above the engine.
         let root = rel.split(['/', '.']).next().unwrap_or("");
         if !is_engine(&rel) || INSTRUMENT_ROOTS.contains(&root) {
             continue;
@@ -967,21 +495,13 @@ fn measure_back() -> BTreeMap<String, BTreeSet<String>> {
     out
 }
 
-/// Every source file that is a **test module in its own file** — declared `#[cfg(test)] mod x;`
-/// somewhere, with its body in `x.rs` or `x/mod.rs` beside its parent.
-///
-/// 1164's counting rule says `#[cfg(test)]` bodies do not count: a test naming an internal is not
-/// an API consumer. The scan honours that for an inline `#[cfg(test)] mod tests { … }` by tracking
-/// brace depth, and used to miss it entirely when the same module lives in its own file — so a
-/// test file inflated the wall with items no shipping code names. One item was hiding behind this
-/// (`mesh_tag::alpha_of`, read by `aura_visual/tests.rs` to assert a packed alpha round-trips);
-/// the rule, not the count, is why it is worth fixing.
+/// Every source file that is a test module in its own file: declared `#[cfg(test)] mod x;`,
+/// with its body in `x.rs` or `x/mod.rs` beside its parent. Its names do not count.
 fn test_module_files(src: &Path) -> BTreeSet<String> {
     let mut out = BTreeSet::new();
     for file in rs_files(src) {
         let text = std::fs::read_to_string(&file).unwrap();
-        // A module file's children live in a directory named after it — `a.rs`'s `mod b;` is
-        // `a/b.rs`; `a/mod.rs`'s is `a/b.rs` too.
+        // `a.rs`'s `mod b;` is `a/b.rs`; so is `a/mod.rs`'s.
         let dir = match file.file_name().and_then(|n| n.to_str()) {
             Some("mod.rs") | Some("lib.rs") | Some("main.rs") => {
                 file.parent().unwrap().to_path_buf()
@@ -1028,31 +548,15 @@ fn is_engine(rel: &str) -> bool {
 }
 
 /// Walk a source file and yield `(canonical item, line)` for every engine path it names in code.
-///
-/// Hand-rolled rather than a regex dependency, and deliberately literal: it follows `crate::root::`
-/// (or `benilla_world::` once the crate exists), expands a `use` brace group so
-/// `use crate::assets::{AssetSet, LockRecover}` counts as two items, and stops the path at its
-/// first capitalised segment so `crate::assets::WorldAssets::get` is one item and not two.
+/// It follows `crate::root::` (or `benilla_world::` with the crate), expands a `use` brace group
+/// into its items, and stops a path at its first capitalised segment (`WorldAssets::get` is one).
 fn paths_in(text: &str, split: bool, want_engine: bool) -> Vec<(String, usize)> {
     let prefix = if split { "benilla_world::" } else { "crate::" };
     let mut found = Vec::new();
     let mut depth: i32 = 0;
-    // **A `#[cfg(test)]` guards exactly the item that follows it, and the scan has to find that
-    // item's END.** It did not, and the miss was total: the guard was cleared only on `depth < d`,
-    // but a top-level `#[cfg(test)] mod tests { … }` is seen at depth 0, rises to 1 inside and
-    // returns to 0 — never *below* it. So the first test module in a file switched this scan off
-    // for the whole rest of that file, and every engine item named below it went uncounted. The
-    // wall's whole job is to be a number nobody has to re-measure, and it was measuring a prefix.
-    //
-    // Found on 2026-09-01 by a change that only *moved* a test module out of `net.rs`: the count
-    // rose by one with no new reference anywhere in the diff, because deleting the module handed
-    // the scan back the rest of the file. An instrument that moves when the code does not is
-    // reporting on itself.
-    //
-    // The extent, for both shapes that exist here: `test_at` arms on the attribute line at depth
-    // `d`; if the guarded item opens a brace (`mod tests {`, `impl X {`) the depth rises and the
-    // item ends when it comes back to `d`; if it opens none (`#[cfg(test)] mod tests;`,
-    // `#[cfg(test)] pub(crate) use …;`) it ends at that statement's semicolon.
+    // A `#[cfg(test)]` guards the item after it. `test_at` arms at the attribute's depth `d`: a
+    // braced item ends when the depth comes back to `d` (it never drops below), an unbraced one
+    // (`mod tests;`, `use …;`) at its semicolon.
     let mut test_at: Option<i32> = None;
     let mut test_open = false;
     for (n, line) in logical_lines(text).iter().map(|(n, l)| (*n, l.as_str())) {
@@ -1069,13 +573,8 @@ fn paths_in(text: &str, split: bool, want_engine: bool) -> Vec<(String, usize)>
                 let boundary = i == 0 || !is_ident(rest.as_bytes()[i - 1] as char);
                 let tail = &rest[i + prefix.len()..];
                 if boundary {
-                    // A **crate-root** item — `crate::SPAWN_XY`, no module segment — is neither
-                    // side's by module, and both walls were structurally blind to it: the parse
-                    // below wants a lowercase module root, so an uppercase first segment fell out
-                    // entirely. It belongs to the *game* by construction, because `lib.rs` is what
-                    // stays behind in `benilla-app` when the engine moves — so an engine file
-                    // naming one is a reverse crossing, and it took a hand-rolled grep over the
-                    // engine file set to find the one that was hiding (`SPAWN_XY`).
+                    // A crate-root item (`crate::SPAWN_XY`) belongs to the game, since `lib.rs`
+                    // stays in `benilla-app`; an engine file naming one is a reverse crossing.
                     let root_item = !split
                         && ident(tail).is_some_and(|(r, a)| {
                             r.starts_with(char::is_uppercase) && !a.starts_with("::")
@@ -1099,11 +598,8 @@ fn paths_in(text: &str, split: bool, want_engine: bool) -> Vec<(String, usize)>
                             _ => (String::new(), ""),
                         }
                     };
-                    // Three sides, not two. An INSTRUMENT is neither: it is excluded from the
-                    // doorway being measured (1160 puts instruments at the top of the stack), and
-                    // an engine file naming one is not a reverse dependency either — every
-                    // instrument module is registered by `WorldPlugins`, so it travels *with* the
-                    // engine into the crate.
+                    // An instrument is neither side: outside the doorway, and not a reverse
+                    // dependency either, since `WorldPlugins` registers it.
                     let instrument = !split && INSTRUMENT_ROOTS.contains(&root.as_str());
                     let engine = split || (!instrument && ENGINE_ROOTS.contains(&root.as_str()));
                     let keep = if want_engine {
@@ -1119,11 +615,8 @@ fn paths_in(text: &str, split: bool, want_engine: bool) -> Vec<(String, usize)>
                                 format!("{root}::{tail}")
                             };
                             let item = canon(&full);
-                            // A bare module name is not an item — `use benilla_world::interact;`
-                            // exists so the file can write `interact::WorldObject` below. Most of
-                            // these are caught structurally by `drop_module_paths`, but not the
-                            // ones whose member is only named where this scan does not look (a
-                            // `#[cfg(test)]` block, a macro body), so the parse drops them too.
+                            // A bare module name is not an item; `drop_module_paths` misses one
+                            // whose members are named only where the scan does not look.
                             let bare_module =
                                 !item.contains("::") && !item.starts_with(char::is_uppercase);
                             if !bare_module {
@@ -1148,13 +641,9 @@ fn paths_in(text: &str, split: bool, want_engine: bool) -> Vec<(String, usize)>
     found
 }
 
-/// The file's lines, with a `use` statement whose brace group spans several physical lines
-/// joined into one. The scan is line-based, and [`expand`] given a `{` with nothing after it
-/// yielded nothing — so every member of such a group was invisible to both walls: nine imports
-/// in game files, twenty-one items counted nowhere, among them a 1164 CLOSE row and the twelve
-/// `terrain_stream::*` names `entities/wmo_props.rs` reaches for (decision 2338). Each joined
-/// line keeps its first physical line's number; a `//` comment inside the group is cut at the
-/// comment (a `use` statement has no string literal a `//` could sit in).
+/// The file's lines, with a `use` brace group that spans several lines joined into one, since the
+/// scan is line-based. A joined line keeps its first line's number; a `//` inside it is cut (a
+/// `use` has no string literal for one to sit in).
 fn logical_lines(text: &str) -> Vec<(usize, String)> {
     fn open(s: &str) -> i32 {
         s.matches('{').count() as i32 - s.matches('}').count() as i32
@@ -1198,7 +687,7 @@ fn ident(s: &str) -> Option<(String, &str)> {
     (end > 0).then(|| (s[..end].to_string(), &s[end..]))
 }
 
-/// The dotted tails a path fragment names — one, or every leaf of a `use` brace group.
+/// The dotted tails a path fragment names: one, or every leaf of a `use` brace group.
 fn expand(s: &str) -> Vec<String> {
     let s = s.trim_start();
     if !s.starts_with('{') {
@@ -1213,11 +702,7 @@ fn expand(s: &str) -> Vec<String> {
                 break;
             }
             let tail = &after[2..];
-            // `interact::{WorldClick, WorldRightClick}` — a group hanging off a path we have
-            // already walked. Without this the walk stops dead at the brace and the whole group
-            // collapses to the bare module path, which `drop_module_paths` then discards: every
-            // item imported the ordinary Rust way was invisible to both walls. The brace arm
-            // below only ever saw a group that began the path, which in real code it never does.
+            // `interact::{WorldClick, WorldRightClick}`: a group hanging off a walked path.
             if tail.trim_start().starts_with('{') {
                 let head = out;
                 return expand(tail)
@@ -1322,8 +807,8 @@ fn render(items: &[(usize, &String)]) -> String {
         .join("\n")
 }
 
-/// A `use` group that spans lines counts every member — the blind spot 2338 closed. The
-/// comment inside the group is cut, and the closing line's `};` ends the statement.
+/// A `use` group that spans lines counts every member; the comment inside it is cut, and the
+/// closing `};` ends the statement.
 #[test]
 fn a_use_group_spanning_lines_counts_every_member() {
     let text =
diff --git a/crates/benilla-ui/src/script/unit/mod.rs b/crates/benilla-ui/src/script/unit/mod.rs
index 212898d1..de589077 100644
--- a/crates/benilla-ui/src/script/unit/mod.rs
+++ b/crates/benilla-ui/src/script/unit/mod.rs
@@ -224,8 +224,8 @@ pub fn grey_band(player_level: u32) -> u32 {
 }
 
 /// The reference's grey level test (`0x5f0700`): the unit is more than the band below the player,
-/// strictly, so a gap equal to the band is still green. The reference also requires the unit not
-/// be player-controlled; every caller here passes creatures.
+/// strictly, so a gap equal to the band is still green. The reference also returns false for a
+/// player (object type bit `0x10`, `0x5f0726`-`0x5f0732`); a pet takes the level test.
 pub fn unit_is_grey(player_level: u32, unit_level: u32) -> bool {
     player_level > unit_level && player_level - unit_level > grey_band(player_level)
 }